@open-agent-toolkit/cli 0.2.53 → 0.2.54

package/assets/agents/recon-worker.md

@@ -0,0 +1,105 @@
+---
+name: recon-worker
+version: 1.0.0
+description: Executes one bounded recon packet assignment as a non-interactive leaf worker and writes exactly one declared artifact.
+tools: Read, Bash, Grep, Glob, Write, WebSearch, WebFetch
+color: cyan
+---
+
+## Role
+
+You are a non-interactive recon leaf worker. Execute exactly one assignment in
+one declared mode: `map`, `gather`, `compile`, `verify`, `adversary`, `coverage`,
+or `reconcile`. No other mode is valid.
+
+## Assignment Gate
+
+Before work, require a complete envelope containing run, wave, and lane IDs;
+mode; bounded objective; included and excluded scope; allowed inputs; excluded
+inputs; source-read authority and read-only tools; sole write path; artifact
+kind and schema version; output schema; enforcement level; and deadline.
+
+Reject the assignment if inputs overlap exclusions, source authority is
+missing, the write path is not unique and packet-contained, the schema is
+unknown, or the mode is undeclared. Never infer missing authority.
+
+## Universal Invariants
+
+- Read only the declared allowed inputs under the stated source-read authority.
+- Write only the assigned artifact at the sole `writePath`.
+- Never modify investigated sources, shared manifests, canonical ledgers, or
+  another lane's artifact.
+- Never interact with the user.
+- Never dispatch children, helpers, reviewers, or replacement workers.
+- Never request credentials or broaden permissions.
+- Preserve exact typed locators and minimal display excerpts.
+- Report uncertainty, contradictions, missing evidence, and unavailable inputs
+  explicitly; never emit numeric confidence.
+- Redact detected secret spans before persistence and never persist a sensitive
+  value or its digest.
+
+## Mode Behavior
+
+### `map`
+
+Inventory only the assigned source partition. Emit candidate evidence areas,
+source identities, unavailable inputs, and coverage gaps. Do not form canonical
+claims.
+
+### `gather`
+
+Inspect assigned sources and emit findings with typed locators, minimal display
+excerpts, observations, uncertainty, contradictions, and gaps. Do not assign a
+canonical claim status.
+
+### `compile`
+
+Consume only the designated dossiers. Deduplicate their findings into a
+provisional claim-ledger candidate and cite direct input artifacts. Do not
+reopen excluded sources or invent evidence.
+
+### `verify`
+
+Consume only an immutable verification brief. Reopen the declared sources,
+test the provided locators and claim semantics, and emit claim-level
+dispositions plus newly observed evidence. Do not read dossiers, compiler
+reasoning, synthesis prose, or prior reviews.
+
+### `adversary`
+
+Consume only declared scope, questions, and provisional statements. Search for
+counterevidence, unsupported inference, incompatible interpretations, and
+missing alternatives. Do not read gathering or prior-review conclusions.
+
+### `coverage`
+
+Compare the declared scope and questions with the permitted ledger projection.
+Emit covered items, missing areas, and material gaps. Do not read gatherer
+reasoning.
+
+### `reconcile`
+
+Apply permitted review dispositions and contradiction outcomes to a new ledger
+candidate. Preserve the prior revision, legal state transitions, evidence
+links, qualifications, and unresolved issues. Never invent evidence or update
+the existing ledger in place.
+
+## Output
+
+Write one JSON artifact matching the supplied schema. Include kind, schema
+version, identities, mode, outcome, honored inputs and exclusions, findings or
+dispositions, uncertainty, contradictions, gaps, safe diagnostics, and direct
+input references where applicable.
+
+Return only the artifact path and compact outcome. Do not return source bodies,
+worker reasoning, or dossier contents to the controller.
+
+## Critical Rules
+
+**ONE MODE. ONE ARTIFACT.** Perform only the assigned mode and write only its
+assigned artifact.
+
+**LEAF ONLY.** Never interact with the user and never dispatch any child.
+
+**HONEST EVIDENCE.** Surface uncertainty and contradiction; do not manufacture
+coverage or assurance.

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.2.53"
+  "oatVersion": "0.2.54"
 }

package/assets/docs/cli-utilities/tool-packs.md

@@ -24,7 +24,7 @@ This page covers CLI commands that manage bundled OAT tool packs and installed O
 | `ideas`              | Lightweight ideation and promotion flows plus idea templates                                                                                                                                                    | project, user  | user                  |
 | `utility`            | Review and repo-maintenance helpers plus portable subagent-selection guidance and the provider-neutral dispatch engine                                                                                          | project, user  | user                  |
 | `project-management` | File-backed backlog/reference skills plus backlog, roadmap, current-state, file-per-record decision, and AGENTS-guide templates                                                                                 | project, user  | user                  |
-| `research`           | Research, analysis, comparison, and synthesis skills plus the skeptical-evaluator agent                                                                                                                         | project, user  | user                  |
+| `research`           | Recon evidence packets, research, analysis, comparison, and synthesis skills plus the recon-worker and skeptical-evaluator agents                                                                               | project, user  | user                  |
 | `brainstorm`         | Always-on brainstorming entry point with visual companion                                                                                                                                                       | project, user  | user                  |
 
 Every reusable pack is a complete user-scope capability. On a **fresh** install
@@ -116,6 +116,46 @@ present without the utility contracts, it fails closed and reports the missing
 dependency instead of inventing a fallback route. Non-project analytical
 skills can use the utility guidance and dispatch layers directly.
 
+### Research-pack dispatch dependencies
+
+The research pack owns `recon` and `recon-worker`, but the utility pack retains
+exclusive ownership of the two reusable dispatch skills that recon needs:
+
+- `oat-dispatch-subagents`; and
+- `subagent-orchestration`.
+
+Installing research acquires those two utility assets at the same scope. OAT
+records the research request as direct intent (`tools.research: true`) and a
+transitive lease under `tools.requiredBy.utility`, which includes `research`.
+The lease makes the selected utility assets available without pretending that
+research owns them or that the entire utility pack was directly installed.
+
+Direct utility intent and transitive leases are independent. If
+`tools.utility: true` already exists, removing research releases only the
+research lease and keeps the direct utility installation. When several packs
+require utility, each name remains in the sorted, deduplicated `requiredBy`
+list; dependency assets are removed only after no direct intent and no other
+lease retains them.
+
+Dependency lifecycle follows the root pack:
+
+- install and update reconcile the declared dependency assets idempotently at
+  the root pack's scope;
+- migration acquires and verifies destination leases before releasing source
+  leases, then removes the source only after the destination is complete; and
+- removal releases the root pack's lease, removes only dependency assets with
+  no remaining owner, and prunes provider views only for canonical assets that
+  were actually removed.
+
+Use explicit scopes when installing or updating recon's pack:
+
+```bash
+oat tools install research --scope user
+oat tools update --pack research --scope user
+oat tools install research --scope project
+oat tools update --pack research --scope project
+```
+
 ### Cross-pack explainer dependency
 
 The public explainer family also spans two packs:
@@ -151,10 +191,12 @@ the usage and lifecycle contract.
 
 Two independent facts describe a pack:
 
-- **Intent** is what you asked for. It is stored per scope as
-  `tools.<pack>: true` in that scope's config file (`.oat/config.json` for
-  project scope, `~/.oat/config.json` for user scope). Intent is _true-or-absent_:
-  removing a pack deletes the key rather than writing `false`.
+- **Intent** is why a pack is present. Direct intent is stored per scope as
+  `tools.<pack>: true`; transitive dependency intent is stored as a sorted,
+  deduplicated `tools.requiredBy.<pack>` list. Both live in that scope's config
+  file (`.oat/config.json` for project scope, `~/.oat/config.json` for user
+  scope). Direct intent remains _true-or-absent_: removing a direct pack deletes
+  its key rather than writing `false`.
 - **Inventory** is what is actually on disk right now: every managed asset the
   release manifest declares for that pack and scope, its presence, and its
   version or content digest.
@@ -575,6 +617,8 @@ Key behavior:
 - Compares installed versions and canonical content against bundled assets and
   copies updates; equal version metadata does not hide content drift
 - For `--pack <pack>` and `--all`, an already-installed pack is reconciled to the **current** release membership in the scopes where it is installed, adding newly bundled skills, agents, templates, and scripts
+- Pack dependencies are reconciled at the same scope without converting a
+  transitive-only dependency into direct pack intent
 - A pack whose managed assets are all missing but whose intent is still declared is repaired from intent rather than skipped
 - Managed template and script companions are refreshed at **user** scope. A project-scope repository template is an owner override and is left alone
 - Non-versioned assets are compared by content digest, so an identical refresh is a no-op instead of a rewrite
@@ -608,6 +652,9 @@ Key behavior:
   intent was eligible to be cleared; `removed: false` is a no-op and preserves
   intent.
 - Removal-triggered sync prunes exactly the canonical provider views for the removed paths in that scope, leaving other scopes and packs untouched
+- Removing a root pack releases its `requiredBy` leases. A dependency asset is
+  retained while its owning pack has direct intent or another pack still
+  requires that asset
 - Dry-run mode with `--dry-run`; auto-sync after mutations by default
 - Use `--no-sync` to skip auto-sync
 
@@ -629,6 +676,8 @@ Key behavior:
 - **Destination first, source second.** The destination is installed and
   re-inventoried, and destination intent is written only after the pack is
   verified complete there. Only then is source removal offered
+- Dependency leases follow the same order: acquire and verify destination
+  leases before releasing source leases, so a failed move remains retryable
 - Source removal requires an interactive confirmation. Declining leaves the
   pack installed at **both** scopes with the destination verified — a safe,
   recoverable state, not a failure. Non-interactive runs stop at the same point
@@ -650,7 +699,7 @@ To roll a migration back, run it in the opposite direction. Because the
 destination is always verified before the source is touched, a rollback is the
 same safe two-phase operation.
 
-## Pack intent: `tools.<pack>`
+## Pack intent: `tools.<pack>` and `tools.requiredBy`
 
 Pack intent is recorded per scope, in that scope's own config file:
 
@@ -661,10 +710,14 @@ Pack intent is recorded per scope, in that scope's own config file:
 
 - Intent is **true-or-absent**. Installing writes `true` for the scope you
   installed into; removing deletes the key. OAT never writes `false`.
+- `tools.requiredBy.<pack>` is a sorted list of packs that currently lease
+  selected assets from that pack at the same scope. It is transitive intent,
+  not a substitute for `tools.<pack>: true`.
 - A user-scope install never writes repository config, and a project-scope
   install never writes user config.
 - Intent for one pack is never derived from another pack's key, and no
-  command writes the full eight-pack map.
+  command writes the full eight-pack map. Dependency operations update only
+  the owning pack's `requiredBy` entry.
 - `.oat/config.local.json` is not an intent surface; per-developer state stays
   out of pack intent.
 - A manual `oat config set tools.<pack> true` is an override that the next
@@ -876,7 +929,8 @@ Installing the `project-management` pack does not adopt a repository. Run
 
 ### The `tools` config map is now sparse
 
-Pack intent is written as [true-or-absent](#pack-intent-toolspack). Earlier
+Pack intent is written as
+[true-or-absent](#pack-intent-toolspack-and-toolsrequiredby). Earlier
 releases wrote all eight pack keys as explicit `true`/`false` on reconcile;
 current releases write `true` for installed packs and delete the key otherwise.
 

package/assets/docs/contributing/skills.md

@@ -140,6 +140,32 @@ Codex, so a canonical fix must survive bundling and Codex sync as well. No test
 yet gates the generated `.claude` or `.cursor` agent views, so regenerate and
 spot-check those by hand.
 
+### Declare cross-pack dependencies in the pack manifest
+
+When a shipped skill depends on assets owned by another pack, declare exact
+asset IDs in `PACK_MANIFEST` instead of duplicating those assets or relying on
+ambient installation. Pack dependencies are same-scope: installation and
+update acquire a `tools.requiredBy.<owner-pack>` lease, while a direct install
+of the owner remains represented separately by `tools.<owner-pack>: true`.
+
+The owner pack keeps asset ownership. Removal releases only the caller's lease
+and may delete a dependency asset only when neither direct owner intent nor
+another pack lease retains it. Migration acquires and verifies destination
+leases before releasing the source leases. Keep dependency graphs acyclic,
+deduplicate edges, and make every dependency asset support the caller's scope.
+
+### Mark user-materializable pack agents explicitly
+
+Set `userMaterializable: true` only on a managed agent that supports user
+scope and has a bundled canonical source. User sync derives eligible agents
+from installed pack inventory, validates the installed and bundled definitions,
+and projects only those declared agents through active provider adapters.
+
+Do not use this marker to expose arbitrary user Markdown or to transfer role
+ownership to a provider view. Canonical/provider destination collisions fail
+closed, and removal keeps the projection while another installed pack or
+direct managed-role intent still retains the canonical agent.
+
 ## Contract components
 
 - Mode assertion (purpose, blocked/allowed activities)

package/assets/docs/workflows/skills/index.md

@@ -14,6 +14,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
 - [Explainer Kit](explainer-kit.md) - Core and OAT adapter usage, recipes and expansion profiles, the two authoring paths, warnings and QA severity, themes, lifecycle policy, durability, and publishing.
 - [Explainer Provider Integration](explainer-kit-providers.md) - Provider-neutral planner, author, trusted browser-session, and visual-critic contracts.
 - [Repo Improve](repo-improve.md) - Source modes, external-plan boundaries, optional tracking, and OAT import handoff.
+- [Recon Evidence Packets](recon.md) - Approved worker profiles, validated claim states, packet layout, partial outcomes, and directory-only handoff.
 
 ## Key Skills by Use Case
 
@@ -37,6 +38,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
 - Generate a shipping digest or scheduled recap: `oat-wrap-up`
 - Run a wave program over a corpus of external plans: `oat-wave-program` (durable program artifact: new/refresh/wave-close) and `oat-wave-execute` (one wave as a wrapper project) — see [Wave Workflows](../wave-workflows.md)
 - Research a topic in depth: `deep-research`
+- Acquire and validate bounded evidence for another workflow: `recon`
 - Analyze an artifact, codebase, or document: `analyze`
 - Compare options with domain-aware dimensions: `compare`
 - Verify a claim adversarially: `skeptic`
@@ -123,6 +125,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
 
 === "Research"
 
+    - `recon`
     - `deep-research`
     - `analyze`
     - `compare`

package/assets/docs/workflows/skills/recon.md

@@ -0,0 +1,194 @@
+---
+title: Recon Evidence Packets
+description: 'Use recon to gather and validate bounded evidence through approved worker waves, then hand off one durable packet directory.'
+---
+
+# Recon Evidence Packets
+
+`recon` turns a bounded investigation into a durable evidence-packet directory.
+It gathers source-grounded findings through approved worker waves, validates
+their locators and assurance state, and gives the next consumer one compact
+entry point instead of every worker transcript.
+
+The first release is standalone. It does not automatically run from project
+discovery, quick start, `analyze`, or `deep-research`. Those workflows can
+consume an explicitly supplied packet path without changing their own
+invocation behavior.
+
+## Choose the Right Research Skill
+
+| Need                                                               | Use             |
+| ------------------------------------------------------------------ | --------------- |
+| Acquire and validate bounded evidence for another workflow         | `recon`         |
+| Interpret a concrete artifact, codebase, document, system, or idea | `analyze`       |
+| Research a broader external topic and produce a narrative artifact | `deep-research` |
+
+Use `recon` when the evidence, exact source locators, contradictions, and gaps
+are the deliverable. It does not make the final product, architecture,
+security, or release decision, and it does not modify the investigated system.
+
+## Install or Update the Research Pack
+
+Install at user scope when you want `recon` available across repositories:
+
+```bash
+oat tools install research --scope user
+oat tools update --pack research --scope user
+```
+
+Install at project scope when the repository should own the capability:
+
+```bash
+oat tools install research --scope project
+oat tools update --pack research --scope project
+```
+
+The research pack acquires its two dispatch dependencies from the utility pack
+at the same scope. You do not need to select a named model during installation.
+At run time, OAT resolves a currently available target that meets the planned
+work's task-class floor and asks you to approve the exact provider, model,
+effort, role, topology, authority, and execution limits before any worker
+launches.
+
+## Run a Recon
+
+Provide a bounded question or target, then optionally choose a profile, scope,
+context source, output directory, or strict authority:
+
+```text
+/recon "How is provider sync materialized?" --profile standard --scope packages/cli/src/providers
+```
+
+The default profile is `standard`. Every run uses one approved model and effort
+for every pass. Profiles change pass topology, redundancy, lane caps, and
+maximum concurrency; they do not silently choose a different model tier.
+
+| Profile    | Use it for                                  | Required assurance work                                                                  | Claim ceiling |
+| ---------- | ------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------- |
+| `quick`    | Bounded orientation                         | Mapping, gathering, compilation, schema validation, and locator validation               | `supported`   |
+| `standard` | Load-bearing evidence                       | Quick work plus blind semantic verification, adversarial review, coverage, and reconcile | `verified`    |
+| `thorough` | Expensive failure or correlated blind spots | Standard work plus redundant gathering and verification and contradiction resolution     | `verified`    |
+
+The approval manifest shows the exact adaptive lane count, concurrency, pass
+topology, conditional lane caps, deadlines, retries, and source/write authority.
+Declining approval launches nothing. A material change to a provider, model,
+effort, route, role, service tier, or execution cap requires renewed approval;
+there is no silent substitution after approval.
+
+## Destination Precedence
+
+`recon` always creates a new topic-and-run directory. It never overwrites an
+existing run. The packet parent is selected in this order:
+
+1. an explicit `--output` override;
+2. the active project's `references/evidence/` directory when a caller supplies
+   that project context;
+3. the repository's `.oat/repo/reference/evidence/` directory;
+4. a fallback destination that the caller approves.
+
+An OAT project is optional. Standalone recon remains available when no project
+or repository evidence directory exists.
+
+## Packet Layout and Consumption
+
+Every structurally publishable run uses this top-level layout; a
+non-publishable candidate generation withdraws any existing `packet.md`:
+
+```text
+<topic>-<run-id>/
+├── packet.md
+├── manifest.json
+├── claims.json
+├── reviews/
+└── raw/
+```
+
+- `packet.md` is the compact consumer view and is published last.
+- `claims.json` is the canonical claim ledger.
+- `manifest.json` records request, source, dispatch, topology, stage, and gap
+  provenance.
+- `reviews/` contains compact locator, semantic, adversarial, coverage, and
+  reconciliation evidence.
+- `raw/` contains worker dossiers, dispatch receipts, candidate artifacts, and
+  safe failure diagnostics. It is not normal consumer input.
+
+The ledger compiler and packet validator enforce categorical referential
+integrity on `synthesis.keyClaimIds` and `synthesis.unresolvedQuestionIds`. Any
+reference to an unknown claim or question ID fails validation with
+`SYNTHESIS_REFERENCE_MISSING`.
+
+The normal handoff is the packet directory path plus a compact status summary.
+Open `packet.md` first and follow machine-readable or review links only when you
+need an audit trail. Do not copy `raw/` dossiers or worker reasoning into the
+next model's context by default.
+
+## Claim States
+
+Claims use categorical evidence states rather than generated confidence
+percentages:
+
+- `provisional`: compiled but not mechanically validated;
+- `supported`: cited evidence and locators validate, without completed
+  independent semantic verification;
+- `verified`: required independent review reopened and affirmed the sources,
+  with no unresolved material challenge;
+- `contested`: credible counterevidence or incompatible interpretations remain;
+- `unresolved`: available evidence cannot settle the claim; and
+- `unsupported`: valid supporting evidence is absent or verification failed.
+
+A quick packet never promotes a claim to `verified`. Stronger profiles can do
+so only when their required review artifacts and receipts validate.
+
+When an independent semantic review rejects a proposed claim, the reconciler
+transitions it to `unsupported` rather than deleting it. This preserves the
+claim statement, cited evidence, and transition history in `claims.json`, and
+renders the finding under Contradictions and Qualifications.
+
+An adversarial challenge transitions a claim to `contested`. A run with
+contested claims may publish as `complete` when all declared questions and
+claims are resolved or characterized; contested claims are rendered under
+Contradictions and Qualifications. If an unresolved challenge represents an
+unanswered question or missing source evidence that leaves investigation
+incomplete, it is recorded as a material gap in `manifest.gaps` and the run
+publishes as `partial`.
+
+## Selective Blindness and Authority
+
+Gatherers write separate dossiers. Verifiers receive only claim statements,
+display excerpts, typed locators, and the source descriptors required to reopen
+them. Adversarial reviewers receive the declared scope, questions, and
+provisional statements. Neither pass receives gatherer reasoning, synthesis
+prose, dossier paths, or earlier review conclusions.
+
+Each lane receives one explicit authority envelope and one unique output path.
+Its enforcement is recorded as:
+
+- `provider-enforced`: the host or tool technically restricts reads and writes;
+- `contract-enforced`: an audited leaf-worker contract restricts local reads
+  and the sole packet write path; or
+- `unavailable`: a safe read-only boundary cannot be established.
+
+By default, local repository and file work may use contract enforcement. Pass
+`--strict` to require provider enforcement for every lane. Mutation-capable
+source tools are unavailable unless their interface enforces a read-only
+operation.
+
+## Partial and Failed Runs
+
+A structurally valid run can publish an honest `partial` packet. The manifest
+and `packet.md` then identify the requested and achieved profiles, failed or
+omitted passes, material gaps, affected claims, and required assurance
+downgrades. A run may be partial even when it achieved the requested profile if
+a material evidence gap remains.
+
+Before assurance or publication, candidate runs are normalized into a deeply
+immutable `ValidatedRun`. To prevent premature or invalid promotion,
+`ValidatedRun` is only constructed and exposed when a candidate generation is
+structurally valid and publishable (`complete` or `partial`). Non-publishable
+runs (`failed`, `running`, `preparing`, `awaiting-approval`) withdraw any
+existing `packet.md` under the unchanged-root guard, leave no `ValidatedRun`,
+and cause the exported renderer to fail closed with `PACKET_NOT_PUBLISHABLE`.
+
+If the manifest, ledger, topology, receipts, source identities, or publication
+boundary cannot be validated, the run is `failed`. It may retain safe raw
+diagnostics, but it does not publish a misleading `packet.md`.

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.2.53",
-  "docs-config": "0.2.53",
-  "docs-theme": "0.2.53",
-  "docs-transforms": "0.2.53"
+  "cli": "0.2.54",
+  "docs-config": "0.2.54",
+  "docs-theme": "0.2.54",
+  "docs-transforms": "0.2.54"
 }

package/assets/skills/oat-dispatch-subagents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-dispatch-subagents
-version: 1.2.4
+version: 1.2.5
 description: Use when an OAT skill or workflow needs provider-neutral selection, launch, recovery, or evidence for bounded subagent work without project lifecycle policy.
 disable-model-invocation: true
 user-invocable: false
@@ -129,6 +129,11 @@ decomposition.
 The optional policy and ceiling are already-resolved inputs. Do not infer where
 they came from or resolve project state to obtain them.
 
+The optional `operation` is `prepare`, `execute`, or `dispatch`. `prepare` and
+`execute` form the approval-bound two-step path below. When `operation` is
+omitted, treat it as `operation: dispatch` and preserve the existing one-step
+selection-and-launch path for backwards compatibility.
+
 ## Native Dispatch Lineage
 
 For a project-aware dispatch, the calling workflow records native dispatch
@@ -370,9 +375,99 @@ Before explicit selection:
 Do not launch a diagnostic child solely to obtain a catalog the provider
 cannot expose before selection. Record the visibility timing instead.
 
+## Approval-Bound Preparation and Execution
+
+Use this path when a caller must show the exact selection and execution
+envelope for approval before any child starts. The caller still owns the user
+interaction; this skill produces and validates the approval evidence.
+
+### `operation: prepare`
+
+Preparation is selection-only. It must observe the live catalog in the exact
+dispatch context and return a complete prepared dispatch record without
+launching, reserving capacity, or obtaining a child handle.
+
+Before selecting a target:
+
+1. Classify all planned and conditional waves before selection. Record every
+   wave's `task_class` and `model_class_floor`.
+2. Compute the run-wide maximum model-class floor using the durable task-class
+   order. Conditional waves count even when the caller may later skip them.
+3. Select one exact target at or above that maximum floor and pin it across all
+   prepared waves. The pin includes provider, dispatch context, route, role,
+   model and selector granularity, effort, reasoning mode, and service tier.
+   Do not weaken a wave floor, split the target, or silently substitute a
+   cheaper target. If one target cannot satisfy every wave, return a blocked
+   preparation.
+4. Materialize each wave's exact authority, deadline, retry limit,
+   concurrency, lane cap, scopes, lane IDs, context controls, fallback, and
+   canonical redacted payload digest. Record the catalog observation identity
+   and the fingerprint of the relevant selectable facts.
+5. Construct the canonical approval projection defined in
+   `references/record-schema.md`, return `dispatch_state: prepared`, and stop.
+
+The calling workflow may combine prepared wave records into a run manifest,
+but it must preserve the run ID, maximum floor, pinned target, per-wave axes,
+canonical approval fingerprint, and prepared timestamp byte-for-byte.
+
+### Approval
+
+The caller presents the complete approval projection and records explicit
+approval by changing only `dispatch_state`, `approved_at`, and the approval
+evidence fields allowed by the schema. Approval is valid only for the exact
+canonical fingerprint. Editing any bound axis creates a new preparation; it
+does not update an already approved record in place.
+
+### `operation: execute`
+
+Execution accepts one approved prepared record. Before invoking the launcher:
+
+1. Validate the prepared-record version, legal state, approval timestamp, and
+   approval fingerprint against the unchanged canonical projection.
+2. Re-observe the live catalog in the same dispatch context and compare the
+   current relevant selectable facts with the prepared observation. A new
+   unrelated candidate alone is not relevant drift; removal, renaming,
+   semantic change, or loss of selectability for an approved control is.
+3. Re-resolve the actual launch controls without choosing alternatives and
+   compare every approval-bound axis exactly. Provider-native opaque values
+   stay byte-for-byte exact.
+4. Refuse launch and mark the record `stale` when any comparison differs. The
+   caller must run `prepare` again and obtain reapproval.
+5. Launch the approved payload once. Record `accepted` only from positive
+   launcher acceptance; otherwise record `not-accepted`.
+
+A model change is model drift. An effort change is effort drift. A provider
+change is provider drift. A route change is route drift. A role change is role
+drift. A service tier change is service tier drift. An authority change is
+authority drift. A deadline change is deadline drift. A concurrency change is
+concurrency drift. A lane cap change is lane cap drift. A relevant catalog
+change is catalog drift. The same fail-closed rule covers reasoning mode,
+selector granularity, retry limit, writable roots, context controls, fallback,
+wave topology, scope, lane identity, payload digest, floor, or pinned-target
+drift. Never adjust one of these controls to make execution fit the current
+surface.
+
+Launch acceptance remains terminal for replacement eligibility. After a
+prepared launch is accepted, no alternate route, replacement, or target
+substitution is allowed. Only continuation through the already accepted handle
+is permitted. A linked fresh same-target launch is forbidden, regardless of
+the generic caller lifecycle recovery exception. If that accepted handle is
+lost or cannot resume, record the terminal outcome and stop; the approval-bound
+record never authorizes a second child.
+
+### One-Step Backwards Compatibility
+
+Existing callers may omit `operation` or provide `operation: dispatch`. This
+retains exactly the current one-step selection-and-launch flow in
+Full-Information Selection: observe, select, record, and launch once in the
+same operation. Do not require those callers to invent a prepared record,
+approval timestamp, or approval fingerprint. New approval-bound callers must
+use `prepare` and `execute`; they may not collapse that path into `dispatch`.
+
 ## Full-Information Selection
 
-For every dispatch:
+For every legacy one-step dispatch and for the selection portion of
+`operation: prepare`:
 
 1. Validate the caller request and capability state.
 2. Resolve provider, context, role class, optional task class and model-class
@@ -387,8 +482,14 @@ For every dispatch:
 7. Record route, selection source, selection reason, candidates, catalog
    source, model, effort, reasoning mode, service tier, guidance version,
    authority, and deadline.
-8. Launch once.
-9. Record launch acceptance separately from child outcome and runtime identity.
+8. For `operation: prepare`, construct the prepared record and return without
+   launch. Do not continue into the legacy launch steps.
+9. For a legacy one-step dispatch only, launch once.
+10. Record launch acceptance separately from child outcome and runtime identity.
+
+The following diagram is the legacy one-step flow. Approval-bound preparation
+stops after selection and record construction; its later `execute` operation
+performs the separately approved launch.
 
 ```mermaid
 flowchart TD