@open-agent-toolkit/cli 0.2.54 → 0.2.56

package/assets/bundle-metadata.json

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

package/assets/docs/cli-utilities/configuration.md

@@ -90,6 +90,7 @@ Common keys in `.oat/config.json`:
 - `worktrees.root` — where OAT-managed worktrees live
 - `git.defaultBranch` — base branch fallback for PR workflows
 - `documentation.root`, `documentation.tooling`, `documentation.config` — docs-surface ownership
+- `documentation.excludes` — a JSON array of globs, relative to the docs directory, that `oat docs generate-index` leaves out of the generated index. `oat config set` takes the list as one comma-separated value (`"a/**,b.md"`) and stores it as an array; repeated `--exclude` flags extend it, and an empty value clears the key
 - `documentation.requireForProjectCompletion` — whether docs sync is a completion gate
 - `archive.s3Uri` — base S3 archive prefix
 - `archive.s3SyncOnComplete` — upload archived projects to S3 during completion
@@ -242,8 +243,17 @@ packaged `assets/` directory next to the installed CLI. Setting a non-empty
   directory.
 - The override is validated exactly like the packaged root and fails closed:
   the path must be a directory containing bundle metadata whose version matches
-  the running CLI (`OAT_VERSION`). A missing, malformed, or version-mismatched
-  override is an error — the CLI never silently falls back to packaged assets.
+  the running CLI (`OAT_VERSION`) **and** the seven top-level directories the
+  bundle producer creates (`skills`, `agents`, `templates`, `scripts`, `docs`,
+  `migration`, `config`), each of which must be a directory. A missing,
+  malformed, version-mismatched, or structurally incomplete override is an
+  error with exit code 2 that names the first offending path — the CLI never
+  silently falls back to packaged assets, and a metadata-only directory is no
+  longer accepted as an empty installation.
+- Remedies are source-aware: an `OAT_ASSETS_DIR` failure tells you to fix or
+  unset the override, never to rebuild or reinstall the CLI; a packaged-bundle
+  failure keeps the rebuild/reinstall guidance. A directory that exists but
+  cannot be read reports the underlying error code.
 - Produce a matching bundle with `bash packages/cli/scripts/bundle-assets.sh`
   while `OAT_ASSETS_DIR` points at the target directory (the script already
   honors the variable as its destination).

package/assets/docs/docs-tooling/commands.md

@@ -128,23 +128,54 @@ Key behavior:
 - recursively walks the docs directory
 - extracts page titles from frontmatter (falls back to first `# heading`, then filename title-case)
 - includes descriptions from frontmatter when present
-- outputs to app root (`index.md`) by default, not inside the docs directory
-- updates `documentation.index` in `.oat/config.json`
+- resolves omitted paths from `.oat/config.json` rather than the current directory: `--docs-dir` defaults to `<documentation.root>/docs` when that directory exists and to `<documentation.root>` otherwise, and `--output` defaults to the app-root manifest `<documentation.root>/index.md`
+- treats explicitly supplied `--docs-dir` / `--output` paths as overrides resolved from the current directory
+- fails with exit code `2` before generating or writing anything when an omitted path has no non-empty `documentation.root` to resolve against, or when the configured root is not a directory
+- refuses unsafe output targets with exit code `1` before generation, for derived and explicit paths alike, comparing symlink-resolved paths: inside the docs directory it indexes, equal to `documentation.config`, or ending in `.yml` / `.yaml` in any case. A derived output whose existing file lacks the `AUTOGENERATED` header is refused too; naming that path with `--output` overwrites it explicitly. A refused target is an actionable flag error (`1`); unusable path configuration is a separate condition and exits `2`, so scripts can branch on the two
+- writes configuration only for the Fumadocs manifest transition — recording the manifest it just wrote inside `documentation.root` in `documentation.index`, when `documentation.tooling` is `fumadocs` or the config declares neither `tooling` nor `config`. MkDocs configurations are never written, and `documentation.root` and `documentation.config` are never modified
 - prepends an `AUTOGENERATED` warning comment to the output and rewrites the file on every run; do not hand-edit the generated `index.md`
 - should be freshness-checked against authored `docs/**/index.md` `## Contents` maps before treating it as navigation evidence
 - sorting: `index.md` first, then directories before files, then lexical
+- reports the derived docs directory in human output and as `docsDir` / `docsDirSource` under `--json`
+- omits pages matching the exclusion list. Nothing is excluded by default; once listed, non-page Markdown such as `CLAUDE.md` or `AGENTS.md` stops reaching the manifest. Patterns come from `documentation.excludes` in `.oat/config.json` and from repeated `--exclude` flags, and the flags **extend** the configured list rather than replacing it. A directory left empty by exclusion emits no heading, and an empty list produces byte-identical output to no exclusions at all
 
 Supported flags:
 
-- `--docs-dir <path>` (default: `docs`)
-- `--output <path>` (default: `index.md` at app root)
+- `--docs-dir <path>` (default: `<documentation.root>/docs`, falling back to `<documentation.root>`)
+- `--output <path>` (default: `<documentation.root>/index.md`)
+- `--exclude <glob>` (repeatable; additive to `documentation.excludes`)
+
+### Exclusion patterns
+
+Patterns match the path of each candidate **relative to the docs directory being indexed** — `api/auth.md`, `api/nested` — never an absolute or current-directory-relative path, and never the repository-relative path.
+
+| Pattern        | Matches                                                  |
+| -------------- | -------------------------------------------------------- |
+| `CLAUDE.md`    | only the root-level `CLAUDE.md`; patterns are anchored   |
+| `**/CLAUDE.md` | `CLAUDE.md` at any depth, including the docs root        |
+| `*.md`         | root-level Markdown only; `*` never crosses `/`          |
+| `drafts/`      | the `drafts` directory and everything beneath it         |
+| `drafts`       | the same directory; the trailing `/` only forbids a file |
+| `api/**/*.md`  | Markdown at any depth under `api/`, including `api/x.md` |
+
+A trailing `/` restricts a pattern to directories and never matches a file; without it, a pattern that matches a directory path still prunes that directory. `**` spans `/` only as a whole path segment — inside a segment (`a**b`) it is an ordinary single-segment wildcard. Matching is case-sensitive, `/` is the separator on every platform, and only `*` and `**` are metacharacters — every other character, `.` included, is literal. A leading `./` or `/` is stripped, so both spellings anchor at the docs root.
 
 Example:
 
 ```bash
-oat docs generate-index --docs-dir docs
+# Resolve both paths from .oat/config.json
+oat docs generate-index
+
+# Portable explicit form, resolved from the current directory
+oat docs generate-index --docs-dir apps/oat-docs/docs --output apps/oat-docs/index.md
+
+# Persist the repository's own exclusions, then add a one-off
+oat config set documentation.excludes "**/CLAUDE.md,**/AGENTS.md"
+oat docs generate-index --exclude 'drafts/'
 ```
 
+See [Documentation path resolution](../reference/oat-directory-structure.md#documentation-path-resolution) for the app-root meaning of `documentation.root` and the legacy source-root compatibility rule.
+
 The Fumadocs scaffold runs this automatically via `predev`/`prebuild` npm
 script hooks.
 

package/assets/docs/reference/oat-directory-structure.md

@@ -117,10 +117,11 @@ Current schema keys:
 | `projects.root`                                            | `string`                   | `".oat/projects/shared"` | Default root directory for OAT projects                                                                                                                                                                                                                                                                 |
 | `projects.defaultScope`                                    | `string`                   | `"synced"`               | Scope used by project creation when `--scope` is omitted: `shared`, `local`, or `synced`. Environment override: `OAT_PROJECTS_DEFAULT_SCOPE`.                                                                                                                                                           |
 | `localPaths`                                               | `string[]`                 | -                        | Gitignored directories to sync between main repo and worktrees. Supports glob patterns. Managed via `oat local add/remove`.                                                                                                                                                                             |
-| `documentation.root`                                       | `string`                   | -                        | Root directory containing documentation source files (e.g., `apps/docs/docs`)                                                                                                                                                                                                                           |
+| `documentation.root`                                       | `string`                   | -                        | Docs **app root** — the directory `oat docs init` scaffolds (e.g., `apps/docs`). Authored pages live under `<root>/docs`. See [Documentation path resolution](#documentation-path-resolution).                                                                                                          |
 | `documentation.tooling`                                    | `string`                   | -                        | Documentation framework identifier (`mkdocs` or `fumadocs`)                                                                                                                                                                                                                                             |
 | `documentation.config`                                     | `string`                   | -                        | Path to the documentation framework config file (e.g., `mkdocs.yml`, `next.config.js`)                                                                                                                                                                                                                  |
-| `documentation.index`                                      | `string`                   | -                        | Path to the docs surface entry point (e.g., `index.md` for Fumadocs, `mkdocs.yml` for MkDocs). Set by `oat docs init` and updated by `oat docs generate-index`.                                                                                                                                         |
+| `documentation.index`                                      | `string`                   | -                        | Path to the docs surface entry point: the generated app-root manifest `<root>/index.md` for Fumadocs, `mkdocs.yml` for MkDocs. Set by `oat docs init`. `oat docs generate-index` writes it only for the Fumadocs manifest transition and never for MkDocs.                                              |
+| `documentation.excludes`                                   | `string[]`                 | -                        | Globs, relative to the docs directory, that `oat docs generate-index` leaves out of the generated index. See [Excluding pages from the generated index](#excluding-pages-from-the-generated-index).                                                                                                     |
 | `documentation.requireForProjectCompletion`                | `boolean`                  | `false`                  | When `true`, OAT project completion gates require documentation to be updated                                                                                                                                                                                                                           |
 | `git.defaultBranch`                                        | `string`                   | `"main"`                 | Default branch for PR creation. Auto-detected during `oat init` via `gh repo view` or `origin/HEAD`. Used by `oat-project-pr-final` and `oat-project-pr-progress`.                                                                                                                                      |
 | `workflow.autoReviewAtHillCheckpoints`                     | `boolean`                  | unset                    | When `true`, completing a HiLL checkpoint automatically runs the extra lifecycle review. Does not control Tier 1 per-phase `oat-reviewer` gates. Can be overridden per-project via `oat_auto_review_at_hill_checkpoints` in `plan.md` frontmatter. Legacy `autoReviewAtCheckpoints` remains a fallback. |
@@ -157,14 +158,65 @@ Example:
     "root": ".worktrees"
   },
   "documentation": {
-    "root": "apps/docs/docs",
+    "root": "apps/docs",
     "tooling": "mkdocs",
-    "config": "mkdocs.yml",
+    "config": "apps/docs/mkdocs.yml",
+    "index": "apps/docs/mkdocs.yml",
     "requireForProjectCompletion": false
   }
 }
 ```
 
+### Documentation path resolution
+
+`documentation.root` canonically names the docs **app root** — exactly the directory `oat docs init` scaffolds. Authored Markdown lives under `<root>/docs`, and the generated Fumadocs manifest is written to `<root>/index.md`, outside the tree it indexes.
+
+`oat docs generate-index` resolves omitted options from this configuration:
+
+| Option       | Omitted                                                                                  | Supplied                            |
+| ------------ | ---------------------------------------------------------------------------------------- | ----------------------------------- |
+| `--docs-dir` | `<documentation.root>/docs` when that directory exists, otherwise `<documentation.root>` | Resolved from the current directory |
+| `--output`   | `<documentation.root>/index.md`                                                          | Resolved from the current directory |
+
+If an omitted option has no non-empty `documentation.root` to resolve against, or the configured root is not a directory, the command fails with exit code `2` before generating or writing anything.
+
+**Compatibility behavior.** Preferring `<root>/docs` exists for legacy configs whose `root` names a docs _source_ directory rather than an app root; it is not a second meaning of the key. Because the rule is a plain directory-existence test, a source root that happens to contain its own `docs` subdirectory is narrowed to it. The command prints the directory it derived in both human and JSON output (`docsDir`, `docsDirSource`), and `--docs-dir` is the escape hatch when the derivation is wrong.
+
+A legacy source root with no `docs` child resolves `--docs-dir` and `--output` to the same tree, so a bare run is refused rather than allowed to overwrite an authored page. Pass an explicit `--output` outside the source tree, or repoint `documentation.root` at the app root.
+
+**Refused output targets.** Checked before generation for derived and explicit paths alike, the command refuses to write an output that is inside the docs directory it indexes, equals `documentation.config`, or ends in `.yml` / `.yaml`. A derived output whose existing file lacks the `AUTOGENERATED by oat docs generate-index` header is also refused; naming that same path with `--output` overwrites it explicitly.
+
+**Configuration writes.** The only configuration write generation performs is the Fumadocs manifest transition: when the written manifest lies inside `documentation.root` and `documentation.tooling` is `fumadocs`, the repo-relative output path is recorded in `documentation.index`. A config that declares neither `documentation.tooling` nor `documentation.config` is treated as the same Fumadocs-shaped case. Any other declared tooling — `mkdocs` included — is never written, and neither are `documentation.root` and `documentation.config`. The value is always repo-relative: when `documentation.root` points outside the repository, the manifest is still generated but the key is left untouched rather than recording a machine-specific path.
+
+### Excluding pages from the generated index
+
+`documentation.excludes` and the repeatable `--exclude <glob>` flag feed one matcher. Flags **extend** the configured list rather than replacing it, so a one-off exclusion cannot silently republish pages the repository deliberately excluded. A directory left empty by exclusion emits no heading, and an empty list produces byte-identical output to no exclusions at all.
+
+Patterns are matched against each candidate's path **relative to the docs directory being indexed** — the directory `--docs-dir` resolved to, not `documentation.root` and not the repository root.
+
+| Pattern        | Matches                                                  |
+| -------------- | -------------------------------------------------------- |
+| `CLAUDE.md`    | only the root-level `CLAUDE.md`; patterns are anchored   |
+| `**/CLAUDE.md` | `CLAUDE.md` at any depth, including the docs root        |
+| `*.md`         | root-level Markdown only; `*` never crosses `/`          |
+| `drafts/`      | the `drafts` directory and everything beneath it         |
+| `api/**/*.md`  | Markdown at any depth under `api/`, including `api/x.md` |
+
+A trailing `/` restricts a pattern to directories and never matches a file; without it, a pattern that matches a directory path still prunes that directory. `**` spans `/` only as a whole path segment — inside a segment (`a**b`) it is an ordinary single-segment wildcard. Matching is case-sensitive, `/` is the separator on every platform, and only `*` and `**` are metacharacters — every other character, `.` included, is literal. A leading `./` or `/` is stripped, so both spellings anchor at the docs root. Entries are trimmed and de-duplicated; a malformed `documentation.excludes` (a non-array, or an empty or non-string entry) is rejected rather than silently ignored. `oat docs generate-index` reports it with exit code `2`; `oat config` surfaces the same error as an ordinary exit-`1` user error. `oat config set documentation.excludes` can still replace or clear a malformed value, so the repair the error names always works.
+
+Set the list with the comma-separated grammar, and clear it with an empty value:
+
+```bash
+oat config set documentation.excludes "**/CLAUDE.md,**/AGENTS.md"
+oat config set documentation.excludes ""
+```
+
+This repository pins the invocation explicitly, which is the portable fallback anywhere the configured defaults are not what you want:
+
+```bash
+oat docs generate-index --docs-dir apps/oat-docs/docs --output apps/oat-docs/index.md
+```
+
 ### Worktree root precedence
 
 When resolving the worktree root directory, `oat-worktree-bootstrap` uses this strict precedence (stops at the first match):

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

@@ -70,10 +70,17 @@ maximum concurrency; they do not silently choose a different model tier.
 | `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.
+topology, deadlines, retries, and source/write authority. Declining approval
+launches nothing. A change to a provider, model, effort, route, role, service
+tier, or execution cap requires renewed approval; there is no silent
+substitution after approval.
+
+Before any worker launches, recon confirms that the live launch surface can run
+the approved role, model, effort, and authority level. If it cannot, the run
+stays at `awaiting-approval` with a provider/dispatch diagnostic and nothing is
+launched. Deadlines are approved execution limits chosen for the task class,
+not short watchdogs; an accepted lane is never interrupted by hand because a
+displayed deadline elapsed.
 
 ## Destination Precedence
 
@@ -105,12 +112,12 @@ non-publishable candidate generation withdraws any existing `packet.md`:
 
 - `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
+- `manifest.json` records request, source, approved execution envelope, and
+  gap provenance.
+- `reviews/` contains compact semantic, adversarial, coverage, and
   reconciliation evidence.
-- `raw/` contains worker dossiers, dispatch receipts, candidate artifacts, and
-  safe failure diagnostics. It is not normal consumer input.
+- `raw/` contains worker dossiers, 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
@@ -137,7 +144,8 @@ percentages:
 - `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.
+so only when their required review artifacts validate and were written by
+approved lanes.
 
 When an independent semantic review rejects a proposed claim, the reconciler
 transitions it to `unsupported` rather than deleting it. This preserves the
@@ -179,7 +187,15 @@ 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.
+a material evidence gap remains. The achieved profile is derived from the
+complete typed artifacts in the packet; each required pass without a complete
+result needs a material `PASS_FAILED` or `PASS_OMITTED` gap naming it.
+
+Status updates and the final handoff label each failure as `worker`,
+`provider/dispatch`, `contract validation`, or `source availability`, and
+say whether every accepted lane reached a terminal result. Workers that
+completed are never reported as failed because the controller could not
+publish.
 
 Before assurance or publication, candidate runs are normalized into a deeply
 immutable `ValidatedRun`. To prevent premature or invalid promotion,
@@ -189,6 +205,6 @@ 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
+If the manifest, ledger, approval envelope, 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.54",
-  "docs-config": "0.2.54",
-  "docs-theme": "0.2.54",
-  "docs-transforms": "0.2.54"
+  "cli": "0.2.56",
+  "docs-config": "0.2.56",
+  "docs-theme": "0.2.56",
+  "docs-transforms": "0.2.56"
 }

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

@@ -1,6 +1,6 @@
 ---
 name: oat-dispatch-subagents
-version: 1.2.5
+version: 1.2.6
 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,11 +129,6 @@ 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
@@ -375,99 +370,9 @@ 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 legacy one-step dispatch and for the selection portion of
-`operation: prepare`:
+For every dispatch:
 
 1. Validate the caller request and capability state.
 2. Resolve provider, context, role class, optional task class and model-class
@@ -482,14 +387,8 @@ For every legacy one-step dispatch and for the selection portion of
 7. Record route, selection source, selection reason, candidates, catalog
    source, model, effort, reasoning mode, service tier, guidance version,
    authority, and deadline.
-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.
+8. Launch once.
+9. Record launch acceptance separately from child outcome and runtime identity.
 
 ```mermaid
 flowchart TD

package/assets/skills/oat-dispatch-subagents/references/record-schema.md

@@ -69,232 +69,6 @@ retain the original role-based selection and fallback behavior. The legacy
 `explicit-downgrade` example above is valid only for an unconstrained request
 without task-class metadata or a declared class floor.
 
-## Approval-Bound Prepared Record
-
-Approval-bound records use `prepared_record_version: 1`. They extend the
-complete Record below: every baseline request, selection, route, payload,
-fallback, diagnostic, and invocation-evidence field remains required when it
-applies. Preparation fills all launch controls but performs no launch.
-
-```yaml
-prepared_record_version: 1
-operation: prepare
-dispatch_state: prepared
-approval_projection: <exact Canonical Approval Projection v1 object below>
-approval_canonical_json: <RFC-8785-JSON-text>
-approval_fingerprint: sha256:<64-lowercase-hex>
-approved_at: null
-approval_evidence: null
-launch_acceptance: null
-terminal_outcome: null
-```
-
-### Canonical Approval Projection v1
-
-`approval_projection` is exactly the object shape below. Its object keys and
-nested structure are immutable for `prepared_record_version: 1`; missing or
-extra keys are invalid. The complete ordered `execution.waves` array and every
-ordered wave-local `lanes` array are values in the projection, not paths to be
-looked up elsewhere. Any future field or aggregation change requires a new
-prepared-record version. Scalar values and example array lengths below are
-illustrative; field names, nesting, value types, and each wave and lane element
-shape are normative. Wave and lane arrays may vary in length only within their
-approved caps.
-
-```json
-{
-  "schema": "oat-dispatch-approval/v1",
-  "prepared_record_version": 1,
-  "run_id": "recon-run-2026-07-12-001",
-  "prepared_at": "2026-07-12T00:00:00Z",
-  "request": {
-    "request_id": "dispatch-recon-001",
-    "caller": "recon",
-    "objective": "Gather bounded evidence",
-    "action": "analysis",
-    "expected_output": "versioned-dossiers",
-    "verification_evidence": "artifact-digests",
-    "escalate_when": ["approved scope is insufficient"]
-  },
-  "selection": {
-    "provider": "codex",
-    "dispatch_context": "nested-native",
-    "dispatch_policy": "economy",
-    "dispatch_ceiling": "high",
-    "selected_route": "native",
-    "selection_source": "native-default",
-    "candidates_considered": ["exact-provider-model"],
-    "selection_reason": "native-catalog",
-    "role_name": "recon-worker",
-    "role_class": "recon",
-    "role_selector": "recon-worker",
-    "model_selector": "exact-provider-model",
-    "model_selector_granularity": "exact-native-model-choice",
-    "effort_selector": "high",
-    "reasoning_mode_selector": null,
-    "service_tier_selector": "standard",
-    "guidance_reference": "subagent-orchestration/references/provider-codex.md",
-    "guidance_version": "2026-07-21",
-    "guidance_verified_at": "2026-07-21",
-    "guidance_status": "fresh"
-  },
-  "execution": {
-    "waves": [
-      {
-        "wave_id": "gathering",
-        "conditional": false,
-        "task_class": "intelligent-recon",
-        "model_class_floor": "intelligent-recon",
-        "scope": "repo:packages/cli",
-        "lanes": [
-          {
-            "lane_id": "commands",
-            "scope": "packages/cli/src/commands"
-          },
-          {
-            "lane_id": "engine",
-            "scope": "packages/cli/src/engine"
-          }
-        ],
-        "authority": "read-only",
-        "authorization_scope": "this-recon-run",
-        "writable_roots": ["packet/raw/dossiers/gathering"],
-        "deadline_seconds": 300,
-        "retry_limit": 1,
-        "fallback": { "mode": "block" },
-        "dispatch_mode": "background",
-        "context_fork_controls": { "fork_turns": "all" },
-        "concurrency": 2,
-        "lane_cap": 4,
-        "payload_digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000"
-      },
-      {
-        "wave_id": "contradiction-resolution",
-        "conditional": true,
-        "task_class": "hard-reasoning",
-        "model_class_floor": "hard-reasoning",
-        "scope": "packet:claims",
-        "lanes": [
-          {
-            "lane_id": "reconcile",
-            "scope": "packet/reviews"
-          }
-        ],
-        "authority": "read-only",
-        "authorization_scope": "this-recon-run",
-        "writable_roots": ["packet/reviews/reconciliation"],
-        "deadline_seconds": 300,
-        "retry_limit": 0,
-        "fallback": { "mode": "block" },
-        "dispatch_mode": "background",
-        "context_fork_controls": { "fork_turns": "all" },
-        "concurrency": 1,
-        "lane_cap": 1,
-        "payload_digest": "sha256:1111111111111111111111111111111111111111111111111111111111111111"
-      }
-    ],
-    "run_maximum_floor": "hard-reasoning",
-    "pinned_target": {
-      "provider": "codex",
-      "dispatch_context": "nested-native",
-      "selected_route": "native",
-      "role_selector": "recon-worker",
-      "model_selector": "exact-provider-model",
-      "model_selector_granularity": "exact-native-model-choice",
-      "effort_selector": "high",
-      "reasoning_mode_selector": null,
-      "service_tier_selector": "standard"
-    }
-  },
-  "catalog_observation": {
-    "id": "nested-native-2026-07-12-001",
-    "source": "tool-schema",
-    "dispatch_context": "nested-native",
-    "observed_at": "2026-07-12T00:00:00Z",
-    "relevant_catalog_fingerprint": "sha256:2222222222222222222222222222222222222222222222222222222222222222"
-  }
-}
-```
-
-The values in the complete Record and launch payload must exactly match their
-counterparts in `approval_projection`; a mismatch is invalid rather than an
-implicit override. `execution.waves` lists every planned and conditional wave
-before selection. Each wave records its caller-classified task class, equal
-model-class floor, conditionality, ordered lane identities and scopes, and all
-wave-local execution controls. Compute `run_maximum_floor` using this increasing
-order: `mechanical-recon`, `intelligent-recon`, `default-implementation`,
-`hard-reasoning`, `consequential`. `pinned_target` is one exact target shared by
-every prepared wave and must satisfy the maximum; per-wave selection or floor
-weakening is invalid.
-
-Absent optional values in the projection are JSON `null`. Preserve caller order
-for waves and lanes; for sets such as writable roots, require the caller to
-provide a stable sorted array. Do not normalize opaque provider values.
-Canonicalize the whole `approval_projection` as canonical JSON using RFC 8785,
-encode that text as UTF-8, hash it with SHA-256, format lowercase hexadecimal,
-and prefix the value with `sha256:`. `payload_digest` is the same construction
-over that wave's complete redacted launch payload. The approval timestamp is
-`approved_at`; `prepared_at` records when selection evidence was fixed.
-
-`catalog_observation` identifies the original source, dispatch context, and
-observation time. Its `relevant_catalog_fingerprint` covers the approved
-target's selectability plus the role, model, effort, reasoning-mode, service-
-tier, route, and launcher controls used to qualify it. Execution preserves the
-original observation and separately records its fresh recheck. A new unrelated
-candidate is not drift, but removal, renaming, changed semantics, or loss of
-selectability for an approved control is relevant catalog drift and makes the
-record stale.
-
-### Legal State Transitions
-
-- `prepared -> approved`: the caller explicitly approves the exact
-  `approval_fingerprint`; set `approved_at` and immutable approval evidence.
-- `prepared -> not-accepted`: the caller declines or cancels before approval.
-- `prepared -> stale`: a bound axis or relevant catalog fact changes before
-  approval is recorded.
-- `approved -> accepted`: `operation: execute` verifies the unchanged
-  fingerprint and current relevant catalog, invokes the exact payload once,
-  and receives positive launcher acceptance.
-- `approved -> not-accepted`: the exact launch is rejected before child start.
-- `approved -> stale`: fingerprint validation, an approval-bound axis, or the
-  relevant catalog comparison differs before launch.
-- `accepted -> completed`: record exactly one terminal child outcome, including
-  success, failure, timeout, interruption, `BLOCKED`, or contract refusal.
-
-`completed`, `not-accepted`, and `stale` are terminal record states. There is
-no transition from them back to `approved` or `accepted`; prepare a new record
-and obtain a new approval. `accepted` is terminal for replacement eligibility
-even before the child outcome changes the record to `completed`. An accepted
-record must not become `not-accepted` or `stale`, and must never authorize a
-replacement, alternate route, model substitution, provider substitution, or
-second child. Only continuation through the already accepted handle is
-permitted. A linked fresh same-target launch is forbidden, regardless of the
-generic lifecycle recovery exception. Handle loss or inability to resume is a
-terminal stop for this approval-bound record; generic recovery remains
-unchanged for non-approval-bound dispatches.
-
-### Execute Validation and Drift
-
-`operation: execute` accepts only `dispatch_state: approved`. First recompute
-the approval fingerprint from the stored projection to detect mutation. Then
-re-observe the same live catalog and resolve the actual launch controls without
-selecting alternatives. A changed model, effort, provider, route, role,
-service tier, authority, deadline, retry limit, concurrency, lane cap,
-reasoning mode, selector granularity, writable root, context control, fallback,
-wave topology, scope, lane identity, payload digest, floor, pinned target, or
-relevant catalog fact changes the record to `stale`. Refuse the launch and
-return for reapproval through a newly prepared record.
-
-### Legacy One-Step Compatibility
-
-Legacy callers that omit `operation`, or set `operation: dispatch`, retain the
-existing one-step selection-and-launch flow: selection and launch occur in the
-same operation and produce the existing Legacy Record or Record shapes. A
-legacy caller must not fabricate an `approval_fingerprint`, approval evidence,
-or a prepared record merely to remain compatible. `prepared_record_version`
-is required only for the approval-bound path; version `1` is the only supported
-prepared-record version, and unknown versions fail closed before launch.
-
 ## Legacy Record
 
 This baseline Record remains valid without optional model-guidance evidence: