@open-agent-toolkit/cli 0.1.54 → 0.1.59

package/assets/docs/contributing/smoke-testing.md

@@ -0,0 +1,284 @@
+---
+title: Smoke Testing
+description: 'Runbook for the OAT live workflow smoke runner: preflight, scenarios, evidence, cleanup, and fixture maintenance.'
+---
+
+# Smoke Testing
+
+The smoke runner (`tools/smoke/`) drives the real OAT orchestration workflows end
+to end against a self-contained fixture project. It provisions a disposable Git
+worktree, hands that worktree to a live provider harness, collects durable
+evidence of what actually happened, verifies the evidence against per-scenario
+assertion profiles, and then removes everything it created.
+
+Run it manually as release validation and after any change that could alter
+orchestration behavior — dispatch, parallel phase topology, review gating, state
+transitions, or the fixture contract itself. It is deliberately **not** part of
+the default CI path: each run launches real provider processes and external
+review gates, so it is operator-initiated rather than automatic.
+
+This page describes the machinery and the process. It does not report the
+outcome of any particular run.
+
+## Data flow
+
+```mermaid
+flowchart TD
+  F["Fixture template\ntools/smoke/fixture/"] --> PRE["Preflight\ninstall + auth + fixture + local oat"]
+  PRE -->|blocked| STOP["Exit before provisioning"]
+  PRE -->|ready| PREP["Prepare / provision\ndisposable worktree + isolated config + manifest"]
+  PREP --> DRIVE["Drive\nper-harness protocol"]
+  DRIVE --> AUTO["Automated: runner launches provider"]
+  DRIVE --> OP["Operator: printed command + prompt"]
+  AUTO --> COLLECT["Collect\nevidence bundle + report"]
+  OP --> COLLECT
+  COLLECT --> CLEAN["Cleanup\nmanifest-scoped"]
+  COLLECT -.->|--keep| SKIP["Cleanup skipped"]
+```
+
+Collection runs even when the drive stage fails, so a broken run still produces
+an evidence bundle before cleanup reclaims its resources.
+
+## Prerequisites
+
+Preflight (`tools/smoke/runner/preflight.mjs`) derives the required runtime set
+from both the selected drive harness and its independent gate runtime. Every
+distinct required runtime must be installed and authenticated before
+provisioning. Preflight also runs `oat gate target list --json` and requires the
+configured target to report available without launching a review.
+
+| Harness      | Runtime probe            | Authentication probe  |
+| ------------ | ------------------------ | --------------------- |
+| `codex`      | `codex --version`        | `codex login status`  |
+| `claude`     | `claude --version`       | `claude auth status`  |
+| `cursor-ide` | `cursor --version`       | `cursor agent status` |
+| `cursor-cli` | `cursor-agent --version` | `cursor-agent status` |
+
+Additional readiness requirements before a run can start:
+
+- **`CURSOR_API_KEY` presence.** Required when the harness is `cursor-cli` or
+  `cursor-ide`, or when the selected gate runtime is Cursor (this is the case
+  for the Codex harness, whose review gate is cross-runtime). Preflight checks
+  only for a non-empty value; the key is never printed, logged, or written into
+  config, manifests, prompts, or evidence.
+- **Local build.** Preflight requires the CLI to resolve to the freshly built
+  local dist entrypoint (`packages/cli/dist/index.js`) through the committed
+  `tools/smoke/bin/oat` shim, with a version matching source. Build the CLI
+  first (for example, `pnpm build`) so the disposable worktree does not fall
+  through to a global `oat`.
+- **Fixture integrity.** Preflight runs the fixture validators and checks the
+  required project artifacts, presets, and seed logs before provisioning.
+
+If any required check fails, preflight raises `PreflightError` and no
+provisioning is started.
+
+## Scenario selection
+
+Select the scenario with `--scenario`. The manifest's applied scenario is the
+authoritative selector for which assertion profile the evidence is checked
+against.
+
+- **`plan-review`** — proves the plan-review lifecycle: the substantive plan
+  (task IDs and parallel groups) is stable across resume, the plan gate review
+  is corroborated against gate-owned invocation evidence, and state advances
+  atomically from pre-review through reviewed to implementation-ready.
+- **`implement`** — proves execution: one accepted, completed phase implementer
+  and one direct-root phase reviewer for each of `p01`, `p02`, and `p03`;
+  exactly five fixture markers and five bounded task commits; exact
+  at-or-below-ceiling target selection; isolated flat parallel branches with
+  fan-in after all declared dependencies; phase-review row and artifact
+  binding; explicit runtime identity status; and exactly one final code gate
+  after `p03`.
+- **`full`** — unions the plan-review and implement profiles. It runs exactly
+  two external gates: one plan-review gate before implementation and one final
+  code gate after `p03`.
+
+## Running
+
+The runner entrypoint is `tools/smoke/runner/run-smoke.mjs`. `--harness` and
+`--scenario` are always required. Drive mode defaults to `automated` and all
+stages (`prepare`, `drive`, `collect`) run by default.
+
+### Automated full run
+
+Automated drive supports `codex`, `claude`, and `cursor-cli`. The runner
+launches the provider itself and runs all three stages:
+
+```bash
+node tools/smoke/runner/run-smoke.mjs --harness codex --scenario full
+```
+
+### Operator prepare/collect split
+
+Operator mode splits the lifecycle so a noninteractive command cannot drive by
+accident. Passing `--drive-mode operator` without `--stage` defaults to
+`prepare` only, so you run prepare and collect as separate commands:
+
+```bash
+node tools/smoke/runner/run-smoke.mjs \
+  --harness claude --scenario full --drive-mode operator --stage prepare
+# Run the printed command and paste the printed prompt in an interactive TTY.
+node tools/smoke/runner/run-smoke.mjs \
+  --harness claude --scenario full --drive-mode operator --stage collect
+```
+
+Prepare prints the disposable worktree path, the interactive provider command,
+and the canned root prompt. Complete the driven session before running collect.
+
+### Manual Cursor IDE flow
+
+`cursor-ide` is operator-driven by definition, so it always uses the
+prepare/collect shape and never substitutes a headless CLI drive. Do not pass
+`--drive-mode operator`; its canonical report root omits the `operator/`
+segment.
+
+```bash
+node tools/smoke/runner/run-smoke.mjs --harness cursor-ide --scenario full --stage prepare
+```
+
+Then, following `tools/smoke/protocols/cursor-ide.md`:
+
+1. Open the printed disposable worktree in Cursor.
+2. Start a new Agent session in that worktree.
+3. Paste the canned root prompt printed by prepare and let the session finish.
+4. Run the matching collect stage:
+
+```bash
+node tools/smoke/runner/run-smoke.mjs --harness cursor-ide --scenario full --stage collect
+```
+
+For each required review gate, the canned prompt invokes `oat gate review`
+exactly once with the harness's fixed `--target`. Listing targets with
+`oat gate target list` is a valid probe; invoking a gate as a probe is not,
+because an accepted gate launch is terminal even when it fails.
+
+### Dry run and keep
+
+- `--dry-run` stubs the install and authentication probes and produces a drive
+  stub instead of launching a provider, letting you exercise the
+  provisioning and cleanup wiring. The fixture and local-CLI checks still run
+  for real.
+- `--keep` short-circuits cleanup so the worktree, branches, and manifest remain
+  on disk for inspection.
+
+```bash
+node tools/smoke/runner/run-smoke.mjs --harness cursor-cli --scenario plan-review --dry-run --keep
+```
+
+## Negative controls
+
+Negative controls prove the runner refuses to do the wrong thing.
+
+**Unavailable target.** Set `OAT_SMOKE_FORCE_UNAVAILABLE=<harness>` to force that
+harness's runtime probe to report unavailable. Preflight then blocks before any
+provisioning, and the control asserts that no manifests, branches, or worktrees
+were created. Capture the failed runner output, then normalize it:
+
+```bash
+OAT_SMOKE_FORCE_UNAVAILABLE=codex \
+  node tools/smoke/runner/run-smoke.mjs --harness codex --scenario plan-review \
+  > preflight-capture.txt 2>&1
+node tools/smoke/evidence/negative.mjs \
+  --harness codex \
+  --preflight preflight-capture.txt \
+  --repository "$(pwd)" \
+  --runs-dir "$(pwd)/tools/smoke/.runs" \
+  --out tools/smoke/reports/negative-controls/codex
+```
+
+**Post-acceptance failure.** Once a child launch is accepted and then fails, that
+outcome is terminal: any launch after an accepted failure is a Critical
+violation. Explicit pre-start rejections before the accepted launch remain
+valid. This control is verified through the `post-acceptance-failure` profile
+(see below).
+
+## Interpreting evidence reports
+
+Reports are written outside the disposable worktree, under
+`tools/smoke/reports/<harness>/<scenario>/` for automated runs and
+`tools/smoke/reports/<harness>/operator/<scenario>/` for operator runs
+(`cursor-ide` always uses the operator-free `tools/smoke/reports/cursor-ide/<scenario>/`
+path).
+
+The collect stage runs the collector and report generator automatically. To
+regenerate or re-verify a report by hand:
+
+```bash
+node tools/smoke/evidence/report.mjs --bundle <out>/bundle.json --out <out>
+node tools/smoke/evidence/report.mjs --check <out>/report.json \
+  --expect-profile <plan-review|implement|full|unavailable-target|post-acceptance-failure>
+```
+
+Reading the output:
+
+- **`report.json` is authoritative.** It records the SHA-256 digest and sibling
+  path of the `bundle.json` it was generated from. The `report.md` table
+  (columns Assertion, Severity, Status, Description) is a derived, human-readable
+  view.
+- **`--check` re-verification** rereads the bound bundle, validates its digest,
+  recomputes the scenario profile, and requires the caller's explicit expected
+  profile plus byte-equivalent results. It does not trust the report's stated
+  status, assertion IDs, severities, summary counts, or the bundle's own
+  scenario as the caller's intent.
+
+The evidence is organized as three layers — launcher-owned production records,
+independent durable corroboration from Git and the fixture, and the normalized
+bundle and assertion report. See
+[Evidence Layers](../workflows/projects/evidence-layers.md) for the model.
+
+## Cleanup and recovery
+
+Cleanup (`tools/smoke/runner/cleanup.mjs`) is manifest-scoped: it only removes
+resources the run journaled. It runs automatically when the run errored, when a
+full `prepare` → `drive` → `collect` lifecycle completed, or when a
+collection-only invocation ran. `--keep` short-circuits it entirely. An operator
+`prepare` stage therefore intentionally leaves its worktree in place for you to
+drive.
+
+After an interrupted run you may find:
+
+- `tools/smoke/.runs/smoke-<branch>/` containing the `provisioning-manifest.json`
+  and the disposable `worktree/`.
+- The outer `smoke-*` branch and any journaled child branches created for
+  parallel phases.
+
+Recovery validates the tracked smoke marker at each ownership baseline, refuses
+divergent branch tips, mismatched shared Git directories, missing baseline
+markers, and any run-descendant worktree or branch absent from the journal. A
+journaled worktree that is already gone from disk is still recoverable; a
+contradictory or unjournaled resource fails closed with a refusal rather than
+guessing.
+
+To finish a stalled run, re-run the matching `--stage collect` (collection-only
+triggers cleanup) or start a fresh run; the runner reconciles journaled
+resources on the next errored or collection-bearing invocation. If cleanup fails
+closed on unjournaled state, resolve that state manually before retrying.
+
+## Updating the fixture as workflows change
+
+When a workflow or skill contract changes shape, the fixture and its checks must
+change with it, and a passing smoke run on the updated fixture is the acceptance
+bar. Typical touch points:
+
+- **Fixture plan** (`tools/smoke/fixture/project/plan.md`) — task IDs, the
+  parallel-groups declaration, each task's write target, and the expected commit
+  subject. Preflight enforces the task count, groups, and per-task integrity.
+- **Lifecycle presets** (`tools/smoke/fixture/presets/`) — the `pre-review` and
+  `implementation-ready` frontmatter fingerprints that transition assertions
+  parse.
+- **Protocols** (`tools/smoke/protocols/*.md`) — the canned prompts, fixed gate
+  counts, and expected per-harness topology.
+- **Assertion profiles** (`tools/smoke/evidence/assertions.mjs`) — the expected
+  task IDs and the plan-review, implement, and full profiles.
+- **Format contract tests** (`tools/smoke/fixture/fixture-format-contract.test.mjs`,
+  `fixture-integrity.test.mjs`, and `presets/apply-preset.test.mjs`) — run by
+  preflight and updated alongside any contract change.
+
+Change these together, then run the affected scenario end to end. If the updated
+fixture does not pass, the workflow change is not accepted.
+
+## Related
+
+- [Contributing Code](code.md)
+- [Implementation Execution](../workflows/projects/implementation-execution.md)
+- [Dispatch Ceiling](../workflows/projects/dispatch-ceiling.md)

package/assets/docs/provider-sync/providers.md

@@ -12,7 +12,7 @@ description: 'Provider-specific path mappings for Claude, Cursor, Copilot, Gemin
     - Project: `.agents/skills` -> `.claude/skills`, `.agents/agents` -> `.claude/agents`, `.agents/rules` -> `.claude/rules`
     - User: `~/.agents/skills` -> `~/.claude/skills`, `~/.agents/agents` -> `~/.claude/agents`
     - Rule files stay `.md` and are rendered with Claude-compatible frontmatter when needed
-    - Managed task workers use the exact configured candidate returned as `providers.claude.dispatchArgs.model`; OAT passes that value as the actual Task `model`
+    - Managed phase implementers and optional nested workers use the exact configured candidate returned as `providers.claude.dispatchArgs.model`; OAT passes that value as the actual Agent `model`
 
 === "Cursor"
 
@@ -61,10 +61,10 @@ description: 'Provider-specific path mappings for Claude, Cursor, Copilot, Gemin
     - Codex `max` is a first-class dispatch effort. It is present only for the Sol family in the committed supported catalogue, for both implementer and reviewer roles.
     - Codex multi-agent dispatch uses config-defined roles (`[agents.<name>]`) and `agent_type`
     - Codex subagent workflows require `[features] multi_agent = true` in active Codex config layers
-    - Managed Codex roles require `agents.max_depth >= 2` for the native topology: root (depth 0) → phase coordinator (depth 1) → task worker (depth 2). Sync and direct materialization merge that floor without lowering a higher target value; project writes also preserve a higher inherited user value.
+    - Default managed Codex execution requires root (depth 0) → phase implementer (depth 1). `agents.max_depth >= 2` enables optional nested phase-agent work; sync and direct materialization still merge that capability floor without lowering a higher target value.
     - Project sync or materialization writes only the project's `.codex/config.toml`; explicit user-scope materialization writes only `~/.codex/config.toml`. Project scope may read the lower-precedence user depth, but never mutates user configuration.
-    - When managed roles exist and effective depth is missing, invalid, or below `2`, `oat doctor` and managed implementation preflight explain the topology and recommend `oat sync --scope project` or `oat sync --scope user` for the affected scope. Direct materialization with the same scope is the single-role repair path.
-    - `oat-phase-implementer` is dual-mode: Phase Scope makes it a phase coordinator, while Task Scope makes the exact materialized variant a one-task worker. The coordinator does not implement ordinary tasks itself.
+    - Missing depth and explicit depth `1` are sufficient for default phase execution. Invalid values or values below `1` block managed implementation preflight. `oat doctor` explains when depth `2` optional nesting is available.
+    - The phase implementer directly executes its planned tasks from one Phase Scope, preserves one bounded commit per task, and returns phase-wide verification. It does not dispatch the phase reviewer.
 
 ## Managed dispatch views
 
@@ -85,17 +85,17 @@ project `.codex` view. User-config candidates materialize under `~/.codex`.
 OAT does not auto-ignore project output or create its Git commit; the team owns
 that repository change.
 
-At implementation time, the phase coordinator passes the recorded named
-maximum through invocation-only `--ceiling-tier`, resolves one exact candidate
-per bounded task, and dispatches one task worker at a time. Codex first
-attempts the resolver-returned materialized role as the native `agent_type`.
-The launcher records the target, model axis, and effort axis from that resolved
-payload; worker self-report is not provenance and cannot replace those values.
+At implementation time, the root passes the recorded named maximum through
+invocation-only `--ceiling-tier`, resolves one exact candidate per phase, and
+dispatches one phase implementer. Codex first attempts the resolver-returned
+materialized role as the native `agent_type`. The launcher records the target,
+model axis, and effort axis from that resolved payload; child self-report is not
+provenance and cannot replace those values.
 Only an explicit pre-start native role-selection rejection permits a fresh
 pinned-child fallback. An accepted child, including one that later returns
 `BLOCKED` or lacks telemetry, is a task outcome rather than a fallback signal.
 Claude and Cursor bind the exact model arguments described above. A missing or
-unselectable managed target blocks rather than falling back to the coordinator
+unselectable managed target blocks rather than falling back to the root target
 or a base role.
 
 ## Scope rules

package/assets/docs/provider-sync/scope-and-surface.md

@@ -48,8 +48,8 @@ Rules are currently project-scoped canonical content. Unlike skills and agents,
 - `oat init --scope project` (interactive) prompts for supported providers and persists explicit true/false values.
 - `oat sync --scope project` uses config-aware provider activation and can prompt to remediate detected mismatches.
 - Codex project-scope subagent sync writes `.codex/config.toml` and `.codex/agents/*.toml` at command layer after path-mapping sync. Every generated project Codex variant and registration is repository-owned, version-controlled provider output. OAT provides no automatic ignore mechanism for this project output; collaborators review and commit it like other project configuration.
-- Managed Codex roles require an effective `agents.max_depth` of at least `2` for `root (0) → phase coordinator (1) → task worker (2)`. Sync and direct materialization apply that floor without lowering a higher target value. A project write may read a higher lower-precedence user value and preserves it in the project configuration; it writes only project `.codex/config.toml`. User scope writes only `~/.codex/config.toml` and does not read or change project configuration.
-- If a managed role has missing, invalid, or insufficient effective depth, `oat doctor` and managed implementation preflight report the topology and give a scope-specific repair: `oat sync --scope project` for project scope or `oat sync --scope user` for user scope. For a single role, use `oat providers codex materialize` with the same explicit scope.
+- Default Codex execution requires `root (0) → phase implementer (1)`. Sync and direct materialization continue to apply an `agents.max_depth` floor of `2` as optional nested-work capability without lowering a higher target value. A project write may read a higher lower-precedence user value and preserves it in project configuration; it writes only project `.codex/config.toml`. User scope writes only `~/.codex/config.toml` and does not read or change project configuration.
+- Missing depth or depth `1` does not block default phase execution. Invalid values or explicit values below `1` fail managed implementation preflight. `oat doctor` reports whether optional depth-two nesting is available and gives a scope-specific repair when the configured value is unusable.
 - Codex aggregate config drift is reported via sync/status extension metadata (`aggregateConfigHash`); it is not persisted as a separate manifest schema entry.
 - Codex user-config materialization writes user-owned implementer and reviewer roles under the user provider directory, `~/.codex`; it does not write those roles into the repository.
 

package/assets/docs/workflows/projects/dispatch-ceiling.md

@@ -1,6 +1,6 @@
 ---
 title: Dispatch Policy
-description: 'How OAT combines owned provider candidate ladders, project and phase named maximum ceilings, exact task dispatch, and provider-specific enforcement.'
+description: 'How OAT combines provider candidate ladders, project and phase named ceilings, exact phase-agent dispatch, and provider-specific enforcement.'
 ---
 
 # Dispatch Policy
@@ -12,15 +12,15 @@ constraints:
   or repo-local config. Each named tier contains one or more exact candidates.
 - A **named ceiling** is a project or phase maximum such as `balanced` or
   `high`. It is not an enduring model-family or effort preference.
-- A **task target** is one exact configured candidate selected at invocation
-  time at or below the named maximum.
+- A **phase target** is one exact configured candidate selected at invocation
+  time at or below the named maximum. Optional nested work resolves separately.
 
 The CLI command remains `oat project dispatch-ceiling resolve` for compatibility.
 Legacy `workflow.dispatchCeiling.*` and `oat_dispatch_ceiling` values remain
 readable, but new projects use ordered candidates plus `oat_dispatch_policy`.
 
 For raw config keys, see [Configuration](../../cli-utilities/configuration.md).
-For the coordinator and task-worker loop, see
+For the root-owned phase-agent loop, see
 [Implementation Execution](implementation-execution.md).
 
 ## Named Policy Choices
@@ -36,8 +36,8 @@ For the coordinator and task-worker loop, see
 
 A named `High` ceiling therefore keeps configured Economy, Balanced, and High
 candidates eligible and available. It does not pin Sol, `opus`, one Cursor
-string, or one effort value. The task coordinator chooses the lowest exact
-candidate it judges sufficient for each bounded task.
+string, or one effort value. The project root chooses one exact candidate it
+judges sufficient for the phase.
 
 `Uncapped` is explicit managed state. It is not represented by omitted policy
 state. `Unresolved` is a planning or preflight deferral and cannot begin
@@ -179,7 +179,7 @@ The final candidate in a named tier defines that tier's reviewer ceiling. Lower
 reviewer selection requires a separate reviewed contract; a normal reviewer
 does not use task candidate flags.
 
-## Exact Task Resolution
+## Exact Phase Resolution
 
 Planning and implementation preflight resolve the active policy first:
 
@@ -190,9 +190,9 @@ oat project dispatch-ceiling resolve \
   --json
 ```
 
-Before each managed capped implementation or fix task, the phase coordinator
-classifies the bounded task and requests one exact configured candidate. It
-passes the recorded project or narrower phase maximum through the
+Before each managed capped phase or bounded fix continuation, the root requests
+one exact configured candidate. It passes the recorded project or narrower
+phase maximum through the
 invocation-only `--ceiling-tier` option:
 
 ```bash
@@ -237,23 +237,23 @@ Successful JSON reports:
 
 The resolver rejects a missing candidate, an above-ceiling candidate, an
 ambiguous route, malformed ordering, a reviewer candidate request, or controls
-that cannot compile exactly. The coordinator blocks instead of reusing its own
-target, a base role, or a provider default.
+that cannot compile exactly. The root blocks instead of reusing its own target,
+a base role, or a provider default.
 
 `--preferred` remains available for legacy scalar ceilings and managed
-`Uncapped` compatibility. It is not the exact managed task-worker selection
+`Uncapped` compatibility. It is not the exact managed phase-agent selection
 path.
 
 ## Provider Enforcement
 
-| Provider | Exact task invocation                                                                                                              | Failure behavior                          |
+| Provider | Exact phase-agent or optional-child invocation                                                                                     | Failure behavior                          |
 | -------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
 | Codex    | Use `providers.codex.dispatchArgs.variant` as `agent_type`; otherwise launch a fresh child pinned to the returned model and effort | Block if neither exact route is usable    |
 | Claude   | Pass `providers.claude.dispatchArgs.model` as the actual Task `model`                                                              | Block if the model cannot be applied      |
 | Cursor   | Pass `providers.cursor.dispatchArgs.model` byte-for-byte as the actual invocation model; treat it as opaque                        | Block rather than normalize or substitute |
 | Other    | Use a registered provider adapter when it can compile exact controls                                                               | Unsupported providers remain advisory     |
 
-Materialized Codex roles exist before task dispatch after project/user sync.
+Materialized Codex roles exist before phase dispatch after project/user sync.
 The supported catalogue is committed project output; custom Codex candidates
 materialize according to config ownership. Workflow correctness still keeps a
 fresh pinned-child fallback and does not require provider restart or hot reload.
@@ -290,20 +290,23 @@ and prompts, stdout and stderr, exit and duration data, and capture-environment
 details such as user-specific binary paths; it is not limited to the structured
 second-pass projection.
 
-## Coordinator and Worker Layers
+## Phase and Optional-Worker Layers
 
-`oat-phase-implementer` has two explicit modes:
+The phase implementer directly implements the phase tasks from one Phase Scope
+and:
 
-1. **Phase coordinator:** reads phase artifacts once, preserves dependency
-   order, selects one exact candidate per task, waits for each worker, verifies
-   its result and commit, then performs phase-wide integration review. It does
-   not implement ordinary tasks itself.
-2. **Task worker:** receives exactly one Task Scope with one task ID, file
-   boundary, verification commands, commit convention, and exact dispatch
-   payload. It implements and commits that task, then stops.
+1. reads phase artifacts once and preserves dependency order;
+2. directly implements each planned task;
+3. creates and verifies one bounded commit per task; and
+4. runs phase-wide verification before returning to the root.
 
-Workers run serially in the same worktree. Parallelism remains limited to
-plan-declared phase worktrees. See
+Optional nested workers or recon agents resolve their own exact candidates only
+when they provide a concrete benefit. They are not required for ordinary plan
+tasks and do not own phase commits or review dispatch.
+
+Tasks run serially in the same worktree. Parallelism remains limited to
+plan-declared phase worktrees unless optional work has explicitly isolated
+write authority. See
 [Implementation Execution](implementation-execution.md) for the full loop.
 
 ## Dispatch Report V1 and Producer Provenance

package/assets/docs/workflows/projects/evidence-layers.md

@@ -0,0 +1,123 @@
+---
+title: Evidence Layers
+description: 'The three-layer dispatch evidence model — policy resolution, launcher-owned configured invocation, and optional runtime-observed identity — used across dispatch records and smoke verification.'
+---
+
+# Evidence Layers
+
+OAT dispatch evidence is layered so that trust flows from what OAT can prove
+toward what it can only observe. The launcher always knows which policy it
+resolved and which exact route it configured and launched, so that evidence is
+authoritative. A child's self-report of its own model is corroboration, not
+ground truth — it may be missing, delayed, or untrusted without ever
+invalidating the configured-invocation record.
+
+The model has **three layers**. The first two are what OAT decided and did; the
+third is what a runtime happened to say about itself. Assertions target the
+first two layers. The third is recorded as `reported` or `not-reported` and
+never gates a conclusion on its own.
+
+## Layer map
+
+```mermaid
+flowchart TD
+  L1["Layer 1 — Policy resolution\nnamed ceiling · candidates · capped/uncapped mode"]
+  L2["Layer 2 — Launcher-owned configured invocation\nroute · target/model/effort axes · selection reason ·\ncandidates considered · launch acceptance"]
+  L3["Layer 3 — Runtime-observed identity (optional)\nproducer + model, only under trusted provenance"]
+
+  L1 --> L2 --> L3
+
+  A["Assertions"] -->|assert on| L1
+  A -->|assert on| L2
+  A -.->|record only| L3
+
+  L3 --> R["reported\n(both present + trusted provenance)"]
+  L3 --> NR["not-reported\n(anything else normalizes here)"]
+```
+
+Assertions bind to Layers 1 and 2. Layer 3 is recorded as `reported` or
+`not-reported`; its absence never invalidates Layer 2.
+
+## Layer 1 — Policy resolution
+
+Layer 1 is the output of the dispatch-ceiling / policy resolver: the named
+ceiling in effect, the eligible candidates under that ceiling, and whether the
+policy is capped (a named maximum such as `balanced` or `high`), uncapped
+(explicit managed state), or inherit/default. It answers _what was allowed_
+before any single task chose a target.
+
+This layer is a maximum and a candidate set, not a selection. A named `high`
+ceiling keeps lower configured tiers eligible; it does not pin one family or
+effort. See [Dispatch Policy](dispatch-ceiling.md) for named policy choices,
+candidate ladders, and the resolver contract.
+
+## Layer 2 — Launcher-owned configured invocation
+
+Layer 2 is the dispatch record the launcher writes when it selects and launches
+a route. It is the **authoritative evidence of what was configured and
+launched**, and it records:
+
+- the selected route and the exact target, model axis, and effort axis;
+- the `selection.reason`, drawn from the stable shared values `native-catalog`,
+  `native-catalog-unsatisfying`, `pre-start-rejection`, `inherit`, and
+  `gate-target` (adapters may add a more specific diagnostic but never replace
+  or rename these);
+- the ordered `candidates_considered` before launch (never sorted);
+- launch acceptance status (`accepted` or `pre-start-rejected`) and mechanism.
+
+Because the launcher constructs the invocation payload itself, this layer does
+not depend on any child cooperation. A launch is judged consistent only when its
+candidate tier, selected model/effort axes, ceiling model/effort axes, policy,
+and exact target all agree. The `atOrBelowCeiling` boolean the launcher provides
+is retained as source evidence but is **not trusted** by assertions — they
+recompute eligibility from the configured candidates and named ceiling instead.
+This layer maps to Dispatch Report V1 and its provenance record; see the
+[Dispatch Report V1 / producer provenance](dispatch-ceiling.md#dispatch-report-v1-and-producer-provenance)
+section.
+
+## Layer 3 — Runtime-observed identity (optional corroboration)
+
+Layer 3 is the only layer that reflects what a runtime said about itself, and it
+is optional corroboration. It is normalized to `reported` **only** when both the
+`producer` and `model` are present _and_ provenance is one of
+`runtime-observed`, `provider-output`, or `gate-corroborated`. Anything else —
+missing producer, missing model, or a non-trusted provenance value — normalizes
+to `not-reported`.
+
+Requested controls, configured defaults, role-name parsing, and reviewer
+self-identification do not become observed runtime identity. Crucially, a
+missing or `not-reported` runtime identity **never invalidates** the
+launcher-owned configured-invocation evidence in Layer 2. Selected model and
+effort axes stay exact even when runtime producer identity is not reported.
+
+## How the smoke runner consumes these layers
+
+The smoke runner's evidence pipeline reads all three layers and asserts only on
+the trustworthy ones. Launcher-owned records (`dispatch/<scope>-<attempt>.json`),
+orchestration state-transition records, and gate JSON are written before
+collection. The collector then flows the evidence through three stages:
+
+1. **Bundle** — collect the immutable dispatch, orchestration, and gate records
+   into a normalized evidence bundle, preserving structured candidates and
+   recomputing eligible candidates through the named ceiling. Runtime identity
+   is normalized here to `reported` / `not-reported`.
+2. **Assertion profiles** — apply the profiles that assert on Layers 1 and 2
+   (policy resolution and configured invocation), while recording Layer 3 as
+   corroboration only.
+3. **Report** — emit the evidence report from launcher-owned records and gate
+   artifacts, carrying `reported` / `not-reported` runtime status without
+   letting a missing Layer 3 fail a Layer 2 assertion.
+
+For how to run this end to end and when to refresh the fixture, see
+[Smoke testing](../../contributing/smoke-testing.md).
+
+## Related
+
+- [Dispatch Policy](dispatch-ceiling.md) — Dispatch Report V1 and the
+  producer-provenance record that back Layers 1 and 2.
+- [Orchestration Model](orchestration-model.md) — the dispatch topology that
+  produces these records.
+- [Review Flavors](review-flavors.md) — how the four review flavors are recorded
+  through the same launcher-owned evidence.
+- [Smoke testing](../../contributing/smoke-testing.md) — operating the evidence
+  pipeline against real providers.