# Execution Intent Contract

Stable output from `capint route --json`. Package major bumps only on breaking changes to required fields.

## Required fields

| Field | Type | Values |
|-------|------|--------|
| `intent` | string | Original task text |
| `capability` | string | Resolved capability id |
| `resolution` | string | `provider/resource` e.g. `skill/localization-hub` |
| `memory` | string | `none` \| `optional` \| `required` |
| `plan` | string | `auto` \| `confirm` \| `override` |
| `confirm` | object | `{ enabled, mode, prompt, options, default_option }` |
| `confirm_question` | string \| null | Human prompt |
| `confirm_options` | array | `{ id, label }[]` |
| `confirm_default_option` | string \| null | e.g. `apply_now` |
| `fallback` | object \| null | `{ capability, override }` when ambiguous |

## Optional fields (v0.3+)

| Field | Description |
|-------|-------------|
| `verification_required` | boolean |
| `verification_hints` | string[] |
| `verification_profile` | string |
| `provider_activation` | memory/graph gating result |
| `context_pack` | local file snippets when memory active |
| `orchestration` | `{ pattern, execution_mode, chains[] }` |
| `route_explain` | verbose routing debug |
| `resolution_status` | `installed` \| `not_installed` |
| `resolution_hint` | string when not installed |
| `explanation` | Route explainability block (see below) |
| `workspace_boundary` | `{ violated, suspicious_paths, override_hint }` when cross-repo paths detected |
| `overlay_error` | `{ file, hint }` when `.capint/disabled-skills.json` is corrupt |
| `local_adapters` | optional; only when `CAPINT_LOCAL_CONTEXT=1` |

## Explanation block (v0.5+)

| Field | Description |
|-------|-------------|
| `task_type_id` | Matched matrix task type |
| `matched_keywords` | Keywords that matched |
| `winner` | `{ type, resource }` |
| `files_to_read` | SKILL.md / workflow paths agent should read |
| `files_intended` | Repo paths mentioned for edit (when `plan_first` or boundary) |
| `reason_summary` | Human-readable why |
| `alternatives_considered` | Other providers considered |
| `workspace_boundary` | Optional nested boundary info |

Schema: `schemas/explanation.v1.json`

## Plan modes

| `plan` | Confirm | Agent behavior |
|--------|---------|----------------|
| `auto` | disabled | Apply after Execution Intent (light tasks) |
| `confirm` | enabled | Wait for devam/plan/analiz |
| `override` | `mode: blocked` | Refuse apply until workspace override phrase (boundary violation) |

Undo: CapInt gates agent apply window only; git/IDE is real undo.

## Example: medium debug task

```json
{
  "intent": "debug login hatasi var",
  "capability": "systematic-debugging",
  "resolution": "skill/systematic-debugging",
  "memory": "optional",
  "plan": "confirm",
  "confirm": {
    "enabled": true,
    "mode": "adaptive",
    "default_option": "apply_now"
  },
  "verification_required": true,
  "orchestration": {
    "pattern": "producer_reviewer",
    "execution_mode": "pipeline",
    "chains": [{ "then_capability": "refactor-simplify", "when": "plan_first" }]
  }
}
```

## Example: memory lookup

```json
{
  "capability": "memory-retrieval",
  "memory": "required",
  "context_pack": {
    "source": "local",
    "snippets": [{ "source": "AGENT.md", "confidence": "verbatim" }]
  },
  "provider_activation": {
    "memory": { "activated": true, "default": "off" },
    "graph": { "activated": true, "default": "off" }
  }
}
```

## Confirm options

| Option | Agent behavior |
|--------|----------------|
| `apply_now` | Execute immediately (subagent mode) |
| `plan_first` | Short plan, then execute (pipeline mode) |
| `analyze_only` | Read-only analysis (explore mode) |
