@open-agent-toolkit/cli 0.3.9 → 0.3.11

package/assets/docs/reference/cli-reference.md

@@ -53,6 +53,7 @@ The first practical expansion path is to keep improving the existing owners: [Do
 | `oat docs ...`                                  | Docs app bootstrap, migration, index generation, nav sync, and docs workflow entrypoints.                                                                                                                                  | [Docs Tooling Commands](../docs-tooling/commands.md)                               |
 | `oat status` / `oat sync` / `oat providers ...` | Provider sync, drift inspection, provider configuration, and adoption behavior.                                                                                                                                            | [Provider Sync](../provider-sync/index.md)                                         |
 | `oat project ...` / `oat cleanup ...`           | Project scaffolding, active-project status inspection, tracked-project listing, plan validation, archive creation, and project/artifact cleanup commands.                                                                  | [Workflow & Projects](../workflows/projects/index.md)                              |
+| `oat template resolve`                          | Resolve a lifecycle template in repository, user, then bundle order and optionally copy it into place.                                                                                                                     | [File Locations](file-locations.md)                                                |
 | `oat review ...`                                | Review artifact discovery helpers, including latest-review resolution for project and ad-hoc review flows.                                                                                                                 | [Reviews](../workflows/projects/reviews.md)                                        |
 | `oat repo ...`                                  | Repository-level workflows such as archive sync and PR-comment analysis.                                                                                                                                                   | [Repository Analysis](../workflows/projects/repo-analysis.md)                      |
 
@@ -149,12 +150,14 @@ Notable commands introduced in the current CLI surface:
 - `oat project status --project-path <path>` - read from a repo-relative or absolute project path instead of `.oat/config.local.json`'s active project pointer. Combine it with `--field` or `--shell` when a skill has already resolved the target project path.
 - `oat project status --shell NAME=path ...` - print shell-safe assignments for one or more fields from one status read, e.g. `WORKFLOW_MODE='quick'`. This is the preferred multi-field read API for skills. See [Writing Skills → Reading project state](../contributing/skills.md#reading-project-state) for examples and the `npx`-backed `oat` shim contract.
 - `oat project promote <project-path> --to quick [--json]` - promote an authored lite project to quick mode. The command derives `discovery.md` from the lite plan's Summary, Decisions, Assumptions, Out of Scope, and Validation Criteria; carries Product Behavior into Success Criteria and Technical Design into a carried-forward discovery section when those adaptive sections are present; preserves the original as `references/lite-plan.md`; and scaffolds a fresh quick `plan.md`. It refuses unsupported targets, non-lite or unreadable projects, an existing lite-plan reference, invalid authored sections, unresolved scope, unavailable templates, failed writes, or failed persistence. JSON output is `{ status: "promoted" | "refused", reason, files }`; `reason` is the stable categorical contract and refused results exit non-zero.
+- `oat template resolve <name> [--output <path>] [--json]` - resolve a template in repository (`<repo>/.oat/templates/`), user (`~/.oat/templates/`), then bundled order and report `name`, `found`, `tier` (`repository` | `user` | `bundle`), and `path`. `path` is set only for the repository and user tiers; it is `null` for the bundled tier, so callers never depend on a package-manager path. `<name>` accepts `plan` or `plan.md` and rejects path separators and `..`. `--output <path>` copies the resolved content to that file, replacing an existing file, and does not create missing parent directories; JSON output adds the absolute `output` path. A template missing from every tier exits 1 with `found: false`. Lifecycle skills use `--output` to copy their artifact templates, so a user-scope-only install works without a repository `.oat/templates/` directory.
 - `oat review latest --json` - find the newest review artifact by `oat_generated_at`, scanning the active or specified project's `reviews/` and `reviews/archived/` directories plus ad-hoc review locations. Same-time candidates use target priority, then lifecycle recency (`final` > higher phase/task > lower phase/task). The JSON contract returns `path`, `scope`, `generatedAt`, `kind` (`project` or `adhoc`), `archived`, and `actionable`, with `null` values when no review exists. Archived project reviews remain discoverable as history but return `actionable: false`.
 - `oat project list --json` - summary state for tracked projects under the configured projects root
-- `oat project complete-state <project-path>` - apply the canonical completed-state mutation to a project's `state.md`; used by `oat-project-complete` during lifecycle closeout
+- `oat project closeout-check <project-path> [--autonomous] [--json]` - read-only check of the closeout invariant: a closeout that must snapshot its post-implementation sequence cannot reach terminal completion until its `oat_post_implement_sequence` snapshot exists, every stored step is recorded complete, approval is recorded, and the snapshot reached `status: complete`. A snapshot is required when the effective layered `workflow.postImplementSequence` is configured, when the closeout is autonomous (`--autonomous`, or `OAT_AUTONOMOUS=1` in the environment even without the flag), or when `oat_workflow_mode` is `lite`. Once a snapshot exists its recorded state is authoritative and current configuration is not consulted. JSON output reports `status` (`complete`, `not_required`, or `incomplete`), the missing `invariant` (`snapshot_missing`, `snapshot_malformed`, `sequence_failed`, `pre_approval_step_pending`, `approval_pending`, `post_approval_step_pending`, or `sequence_not_complete`), `route` (`oat-project-implement` when incomplete), `nextOwner` (the next stored step and its skill, or the approval), and the evaluated `inputs`. An incomplete or malformed result exits 1.
+- `oat project complete-state <project-path> [--archived] [--autonomous]` - apply the canonical completed-state mutation to a project's `state.md`; used by `oat-project-complete` during lifecycle closeout. It first evaluates the same closeout invariant as `oat project closeout-check` and refuses, with the same message and without writing, a configured, autonomous, or lite closeout whose snapshot is absent, malformed, or incomplete. A project whose implementation finished before closeout snapshots existed recovers by running `oat-project-implement`, which persists the snapshot (`completion-and-closeout.md` Step 15) and completes its stored steps; there is no override flag. An unconfigured, interactive, non-lite closeout without a snapshot completes as before.
 - `oat project archive [project-path] [--project-recap-run <project-relative-path>] [--no-commit]` - archive a tracked project through the same local move, summary export, and configured S3 upload path used by completion. When omitted, the project path falls back to the active project. The optional recap path must identify a `project-recap` run inside the project's `explainers/` directory. Archive stages the selected complete package into `.oat/repo/reference/project-recaps/<YYYYMMDD-project-slug>/`, verifies every manifest-declared file byte, then atomically installs the export before deleting the active project. Existing destinations, incomplete inventory coverage, stale bytes, path escapes, and recipe mismatches fail without removing the active project. For synced projects, a configured S3 upload must succeed before terminal cleanup. Successful closeout makes `refs/oat/completed/<project>` authoritative, deletes the tracked JSON record and nested checkout, and leaves archive metadata sufficient for an idempotent recordless retry. With `--json`, the terminal receipt reports `completedRef`, `verifiedSourceSha`, whether `activeAliasDisposition` was `retained` or `removed`, whether `recordRetired` completed, and the parent `lifecycleCommit`. `--no-commit` is a manual/library-only option: for a synced project it still removes the checkout but deliberately leaves `lifecycleCommit` null. Never pass it through `oat-project-complete`, which requires that receipt.
 - `oat repo archive sync [project-name]` - hydrate archived project snapshots from the configured repo-scoped S3 archive into `.oat/projects/archived/`. The old `oat project archive sync` path remains as a deprecated shim.
-- `oat project dispatch record --event-file <json-file-or-dash> [--project <project-path>]` - validate one generic dispatch record plus its namespaced OAT evidence event, and persist it into the project's append-only `dispatch/` journal (optional; no lifecycle skill requires persistence). Omit `--project` to validate without persisting. Managed, effort-pinned Claude launches use the validation-only form before launch: the input carries `claudeLaunch` with the real resolver result, generated definition, and proposed payload, plus `recordBase` and `event`. The command validates their agreement and derives the configured invocation fields; callers cannot copy those fields into `recordBase`. One validation run reports every violation across `claudeLaunch`, `recordBase`, and `event` in a single error message, one `stage path: message` line each; the `recordBase` cross-field rules run even when a required field is missing, checks that need a value that failed to parse are skipped and named on a final line, secret-shaped values and absolute paths are scrubbed from the message, and the exit code stays 1. A validated input per role is published at `.agents/skills/oat-dispatch-subagents/references/managed-claude-example.json`. Revision 1 is `dispatch/<request-id>.json` and every later revision is `dispatch/<request-id>@<NNNN>.json`; superseded revisions are never replaced or removed. The command validates and records evidence only — it never launches a provider. A `runtime-observation` event may carry either a finished `observation` or the provider `metadata` envelope (`provider`, `observedAt`, `entries`) to normalize, but not both. `entries` may be raw provider output: they are projected through the owning parser's allowlist, are never persisted, and both forms have their `match` derived from the record's configured invocation rather than trusted from the caller, with the observation's `provider` bound to the record's. With `--json`, the result adds `runtimeIdentity` with separate `configured` and `observed` objects plus a `match` of `matching`, `mismatching`, `not-comparable`, or `null`; observation is corroboration only and never overrides configured invocation. Error output is redacted on a best-effort basis; absolute paths in identity fields are rejected outright, while some prose forms (colon-prefixed, URL routes) can survive. See [Evidence Layers](../workflows/projects/evidence-layers.md).
+- `oat project dispatch record --event-file <json-file-or-dash>` - validate one generic dispatch record plus its namespaced OAT evidence event and print the result with `status: validated-only`. The command writes nothing; launches are recorded in the calling workflow's run record. Managed, effort-pinned Claude launches run it before launch: the input carries `claudeLaunch` with the real resolver result, generated definition, and proposed payload, plus `recordBase` and `event`. The command validates their agreement and derives the configured invocation fields; callers cannot copy those fields into `recordBase`. One validation run reports every violation across `claudeLaunch`, `recordBase`, and `event` in a single error message, one `stage path: message` line each; the `recordBase` cross-field rules run even when a required field is missing, checks that need a value that failed to parse are skipped and named on a final line, secret-shaped values and absolute paths are scrubbed from the message, and the exit code stays 1. A validated input per role is published at `.agents/skills/oat-dispatch-subagents/references/managed-claude-example.json`. The command validates evidence only — it never launches a provider. A `runtime-observation` event may carry either a finished `observation` or the provider `metadata` envelope (`provider`, `observedAt`, `entries`) to normalize, but not both. `entries` may be raw provider output: they are projected through the owning parser's allowlist, are never echoed in the output, and both forms have their `match` derived from the record's configured invocation rather than trusted from the caller, with the observation's `provider` bound to the record's. With `--json`, the result adds `runtimeIdentity` with separate `configured` and `observed` objects plus a `match` of `matching`, `mismatching`, `not-comparable`, or `null`; observation is corroboration only and never overrides configured invocation. Error output is redacted on a best-effort basis; absolute paths in identity fields are rejected outright, while some prose forms (colon-prefixed, URL routes) can survive. See [Evidence Layers](../workflows/projects/evidence-layers.md).
 - `oat project dispatch canonical-role --role <name> --request-id <id> --skill-dir <dir> [--json]` - resolve a canonical role through the loaded, user (`$HOME/.agents`), and project (`<repo>/.agents`) tiers and print the `canonical-role-resolution` event that `oat project dispatch record` accepts unchanged: redacted `canonicalPath` and `selectedPath` in the form `<loaded|user|project>/agents/<name>.md`, the role's `contentDigest`, and `candidateMisses`. `--skill-dir` is required because the loaded tier is derived from the loaded skill's directory; a missing or invalid directory exits 1 with a redacted error. An unknown role prints `missing` evidence with its recovery commands. Read-only; the dependency is the `workflows` pack.
 - `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. Lite plans must contain exactly one phase, declare no parallel groups, and give every Validation Criteria bullet either a backticked command or a `manual:` instruction. See [Implementation Execution](../workflows/projects/implementation-execution.md#parallel-phase-groups).
 - `oat project log append|check|synthesize|rollup` - manage the optional append-only project observation log: append validated judgment or structural entries, inspect grammar and synthesis status, complete end-of-run synthesis, and roll observations into `summary.md` plus the configured repository ledger. See [Project Log](../cli-utilities/project-log.md).

package/assets/docs/reference/docs-index-contract.md

@@ -1,6 +1,6 @@
 ---
 title: Docs Index Contract
-description: 'Docs source contract: authored index.md maps, generated Fumadocs manifests, and MkDocs nav sync.'
+description: 'Docs source contract: authored index.md maps, generated Fumadocs manifests and meta.json navigation, and MkDocs nav sync.'
 ---
 
 # Docs Index Contract
@@ -15,7 +15,7 @@ OAT docs navigation starts from authored `docs/**/index.md` files. Each `## Cont
 - Every `## Contents` link should use a `.md`-suffixed relative target, including child directory links such as `subdir/index.md`.
 - Do not hand-edit generated navigation or generated root-index artifacts.
 - For Fumadocs, refresh or freshness-check the generated app-root manifest after adding, removing, or renaming Markdown files. Compare that manifest against authored `## Contents` maps for drift; reordering `## Contents` does not reorder the generated manifest's file-tree sort.
-- For MkDocs, run `oat docs nav sync` after adding, removing, renaming, or reordering pages. It regenerates `mkdocs.yml` from authored `## Contents` maps and preserves the order declared in each local map.
+- Run `oat docs nav sync` after adding, removing, renaming, or reordering pages. It regenerates the framework's navigation from authored `## Contents` maps and preserves the order declared in each local map: the `nav:` block in `mkdocs.yml` for MkDocs, and one `meta.json` per docs directory for Fumadocs.
 
 ## `## Contents` format
 
@@ -37,7 +37,7 @@ Notes:
 
 ## Fumadocs Generation
 
-For this Fumadocs app, rendered page routing and sidebar data come from the Fumadocs file/source pipeline over `apps/oat-docs/docs`. The generated root manifest, `apps/oat-docs/index.md`, is an inventory for agents and tooling; it is not the rendered sidebar/page-tree source.
+For this Fumadocs app, rendered page routing comes from the Fumadocs file/source pipeline over `apps/oat-docs/docs`, and the sidebar order comes from the committed `meta.json` files that `oat docs nav sync` writes (see [Fumadocs Nav Sync](#fumadocs-nav-sync)). The generated root manifest, `apps/oat-docs/index.md`, is an inventory for agents and tooling; it is not the rendered sidebar/page-tree source.
 
 `oat docs generate-index` walks the Markdown file tree under `docs/` and writes the app-root generated manifest. The app scripts run:
 
@@ -46,7 +46,7 @@ fumadocs-mdx
 pnpm -w run cli:source -- docs generate-index --docs-dir apps/oat-docs/docs --output apps/oat-docs/index.md
 ```
 
-`oat docs generate-index` rewrites the generated root manifest from the docs source tree. It is the command to use after adding, removing, or retiring pages in this Fumadocs app. Do not use `oat docs nav sync` as the Fumadocs regeneration step.
+`oat docs generate-index` rewrites the generated root manifest from the docs source tree. Run it after adding, removing, or retiring pages in this Fumadocs app, and run `oat docs nav sync` as well so the sidebar's `meta.json` files follow the same change. The two commands produce different artifacts: `generate-index` writes the agent-facing inventory and `nav sync` writes the sidebar navigation.
 
 Fumadocs generated behavior:
 
@@ -54,6 +54,22 @@ Fumadocs generated behavior:
 - Reordering a `## Contents` block does not reorder the generated manifest's file-tree sort.
 - Generated manifests should carry an autogen warning and are rewritten by `predev` / `prebuild`.
 
+## Fumadocs Nav Sync
+
+In a Fumadocs app (detected by its `source.config.ts`), `oat docs nav sync --target-dir <docs-app-dir>` writes one `meta.json` beside every docs directory `index.md`. The files are generated and committed; edit the `## Contents` map, not the `meta.json`.
+
+Fumadocs generated behavior:
+
+- `pages` follows the order of the directory's `## Contents` links. The root list starts with `index`; a child directory appears by its folder name, and its own `index.md` becomes that folder's landing page. A folder whose `meta.json` keeps `root: true` also lists `index` first, because Fumadocs gives a root folder no implicit landing page.
+- Navigation is strict: there is no `"..."` rest entry. A page or folder that no `## Contents` map lists stays out of the sidebar, and the command reports it by path in its human output and in `--json` (`unlisted`). Add the page to its directory's `## Contents` map to show it.
+- A `## Contents` link to a page in another directory is written as a Fumadocs link entry such as `[Writing Skills](/contributing/skills)`, so each page belongs to exactly one folder.
+- The folder `title` comes from the `index.md` frontmatter `title`, falling back to its first `#` heading.
+- Keys nav sync does not own, such as `icon` or `defaultOpen`, are kept.
+- Existing files are compared by meaning, not bytes, so a second run with no docs changes writes nothing, even after a formatter rewrites the files.
+- `.md` and `.mdx` pages can both be listed; each appears in `pages` by its file name without the extension.
+
+`oat docs nav sync --check` computes the same result and writes nothing. It exits 1 when a `meta.json` file would change or a page or folder is unlisted, and names each one. In this app, `prebuild` runs it, so `pnpm build:docs` fails until the `## Contents` maps and the committed `meta.json` files agree.
+
 ## MkDocs Nav Sync
 
 MkDocs apps use `oat docs nav sync --target-dir <docs-app-dir>` to walk the docs tree from `docs/index.md` downward and regenerate the `nav:` block in `mkdocs.yml` from discovered directory `index.md` files.
@@ -69,7 +85,7 @@ MkDocs generated behavior:
 
 - Edit authored files under `docs/`, especially the nearest `index.md` and `## Contents`.
 - Do not hand-edit a Fumadocs app-root generated `index.md`; regenerate it from the docs source tree.
-- Do not hand-maintain MkDocs `nav:` entries when the local workflow uses `oat docs nav sync`.
+- Do not hand-maintain MkDocs `nav:` entries or Fumadocs `meta.json` `pages` lists when the local workflow uses `oat docs nav sync`.
 - If a Fumadocs generated manifest lists pages that are missing from authored `## Contents`, treat that as authored-source drift or intentional generator-inventory behavior to verify before relying on the generated file as navigation evidence.
 
 ## Authoring guidance
@@ -77,7 +93,7 @@ MkDocs generated behavior:
 - Use `index.md` as the local discovery surface for humans and agents.
 - Add a short topic description next to each link so agents can choose the right file without opening every page.
 - Update `## Contents` whenever you add, remove, rename, or reorder docs files in a directory.
-- Regenerate the framework-specific artifact after structural changes: `generate-index` for Fumadocs root manifests, `nav sync` for MkDocs `mkdocs.yml`.
+- Regenerate the framework-specific artifacts after structural changes: `nav sync` for MkDocs `mkdocs.yml` and Fumadocs `meta.json` navigation, plus `generate-index` for Fumadocs root manifests.
 - Refresh or freshness-check the generated artifact before committing structural docs changes.
 
 ## If You Are Trying To...

package/assets/docs/reference/file-locations.md

@@ -38,7 +38,12 @@ columns are ordinary states.
 
 Project-scope templates under `.oat/templates/` are owner overrides that OAT
 seeds once and never rewrites; the managed default lives at user scope and in
-the bundle. PJM templates resolve repository → user → bundle.
+the bundle. Project lifecycle and PJM templates resolve repository → user →
+bundle. Run `oat template resolve <name>` to see which tier supplies one, or
+add `--output <path>` to copy it. Idea templates under `ideas/` are different:
+the ideas skills select `.oat/templates/ideas/` or `~/.oat/templates/ideas/` by
+the ideas scope, and `oat template resolve` does not search nested
+directories.
 
 Pack intent is stored per scope:
 
@@ -172,7 +177,7 @@ Archive sync surfaces:
 - `packages/cli/src/commands/docs/init/` — scaffold a docs app (Fumadocs or MkDocs)
 - `packages/cli/src/commands/docs/migrate/` — convert MkDocs admonitions to GFM callouts
 - `packages/cli/src/commands/docs/index-generate/` — generate a docs index from markdown files
-- `packages/cli/src/commands/docs/nav/` — regenerate mkdocs.yml nav from index.md sections
+- `packages/cli/src/commands/docs/nav/` — regenerate mkdocs.yml nav or Fumadocs meta.json from index.md sections
 - `packages/cli/src/commands/instructions/`
 - `packages/cli/src/commands/project/`
 - `packages/cli/src/commands/internal/`

package/assets/docs/reference/index.md

@@ -13,7 +13,7 @@ Contributor how-to material now lives under `contributing/`, and user-facing rou
 
 - [CLI Reference](cli-reference.md) - Shallow map of the OAT command surface with links to owning sections.
 - [File Locations](file-locations.md) - Where core OAT files, assets, and artifacts live.
-- [Docs Index Contract](docs-index-contract.md) - Authored `index.md` maps, `.md` links, generated Fumadocs manifests, and MkDocs nav sync boundaries.
+- [Docs Index Contract](docs-index-contract.md) - Authored `index.md` maps, `.md` links, generated Fumadocs manifests, and MkDocs and Fumadocs nav sync boundaries.
 - [OAT Directory Structure](oat-directory-structure.md) - Canonical `.oat/` tree map and the role of each major directory.
 - [Troubleshooting](troubleshooting.md) - Common issues, diagnostics, and remediation guidance.
 

package/assets/docs/reference/meta.json

@@ -0,0 +1,10 @@
+{
+  "title": "Reference",
+  "pages": [
+    "cli-reference",
+    "file-locations",
+    "docs-index-contract",
+    "oat-directory-structure",
+    "troubleshooting"
+  ]
+}

package/assets/docs/reference/troubleshooting.md

@@ -97,6 +97,27 @@ Use [Instruction Sync](../provider-sync/instruction-sync.md) for the full strate
 - Per-pack install commands no longer accept the previously inert `--force`
   option.
 
+## A skill fails with `unknown command 'template'` or `'closeout-check'`
+
+Lifecycle skills from OAT 0.3.11 copy their templates with
+`oat template resolve` and check closeout with `oat project closeout-check`.
+An older `oat` on `PATH` rejects both:
+
+```text
+error: unknown command 'template'
+error: unknown command 'closeout-check'
+```
+
+`oat-project-complete` treats a failed closeout check as an incomplete
+closeout, so with an older CLI it stops and routes back to
+`oat-project-implement` even when every closeout step is done. This happens
+when the skills a host loads are newer than the CLI, for example repository
+skills from a newer checkout run against an older global CLI.
+
+Check `oat --version`. Install `@open-agent-toolkit/cli` 0.3.11 or later, then
+refresh the installed skills to that CLI's bundle with
+`oat tools update --all`.
+
 ## `sync` reports an unsafe provider parent
 
 Errors containing `Unsafe provider parent`, `symbolic links are not allowed in
@@ -200,7 +221,13 @@ OAT could not read the canonical managed-pack inventory. `oat status` keeps the
 rest of the report available and returns `packs.availability.status` as
 `unavailable` in JSON, with an empty `packs.states` array and a structured
 diagnostic. `oat doctor` emits the same condition as a warning instead of
-stopping its other checks. Reported project and home paths remain redacted.
+stopping its other checks.
+
+The diagnostic message redacts only the roots that are part of the run: the
+project root becomes a relative path (or `.`) when project scope is checked,
+and the home root becomes `~` when user scope is checked. Redaction is a literal
+replacement of those exact root paths, so a path outside them, such as a global
+bundle path in an assets error, stays absolute in the message.
 
 Rebuild the CLI workspace, then rerun the command named in the diagnostic:
 
@@ -269,16 +296,24 @@ oat pjm init
 scaffold — rerun `oat pjm init`), or `none`. `oat pjm init` records
 `pjm.initialized` in `.oat/config.json` after verifying the canonical scaffold.
 
-## A PJM template change is not taking effect
+## A template change is not taking effect
+
+Project lifecycle and PJM templates resolve repository → user → bundle, first
+match wins (idea templates follow the ideas scope instead). A repository
+template under `.oat/templates/` is an owner override that pack updates never
+rewrite, so it shadows the managed user default. Check which tier supplies a
+template:
 
-PJM templates resolve repository → user → bundle, first match wins. A
-repository template under `.oat/templates/` is an owner override that pack
-updates never rewrite, so it shadows the managed user default.
+```bash
+oat template resolve plan
+```
 
 Delete the repository copy to fall back to the managed default, or update the
-managed default itself:
+managed default itself (`workflows` owns the project lifecycle templates,
+`project-management` the PJM templates):
 
 ```bash
+oat tools update --pack workflows --scope user
 oat tools update --pack project-management --scope user
 ```
 

package/assets/docs/workflows/ideas/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Ideas Workflow",
+  "pages": ["lifecycle"]
+}

package/assets/docs/workflows/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Agentic Workflows",
+  "pages": ["ideas", "projects", "wave-workflows", "skills"]
+}

package/assets/docs/workflows/projects/cursor-cloud.md

@@ -95,9 +95,14 @@ dispatch records, prompts, logs, or the VM image.
 ## User-scope asset precedence
 
 In provisioned cloud environments, the user-scope installation is the execution
-source for every OAT asset class: skills, templates, and scripts. The user tier
-is refreshed from the published package during environment setup; repository
-copies are compatibility context, not an override.
+source for skills and scripts. The user tier is refreshed from the published
+package during environment setup; repository copies of skills and scripts are
+compatibility context, not an override.
+
+Templates are the exception. They resolve repository, then user, then bundled,
+the same order as everywhere else, because a repository template is an owner
+override. Agents resolve and copy them with `oat template resolve <name>
+--output <destination>` rather than reading `~/.oat/templates/` directly.
 
 For skills, compare frontmatter versions as a freshness check:
 

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

@@ -85,13 +85,15 @@ Run the same command without `--dry-run` to replace bundled cells. Use
 `--shared` or `--local` instead when that scope owns the ladder. Add
 `--keep-existing` to fill only missing cells and preserve existing choices.
 
-Version `2026-09-25.1` is the current bundled recommendation. It prefers
-GPT-6 Luna and Sol in Codex, then Sol xhigh, Astra high, and Astra xhigh in
+Version `2026-10-01.1` is the current bundled recommendation. It prefers
+GPT-6 Luna and GPT-6.1 Sol in Codex, then Sol 6.1 xhigh, Astra high, and Astra xhigh in
 Codex Frontier. Astra's task advantage has not been measured locally; this is
 an explicit user-directed preference, not acceptance by the separately
-maintained model-selection policy. Opus 5.5 low/medium/high remains in Claude High.
+maintained model-selection policy. Sonnet 5.5 medium replaces Sonnet 5 medium
+in Claude Economy; the older generation stays supported for explicit cells.
+Opus 5.5 low/medium/high remains in Claude High.
 The Claude low option suits bounded intelligent recon in Balanced or High;
-medium remains the implementation starting point under High. GPT-5.6 targets remain
+medium remains the implementation starting point under High. GPT-6 Sol and GPT-5.6 targets remain
 supported for explicit Codex and Cursor configurations. Cursor's preferred
 ladder interleaves verified GPT-5.6 and Opus 5.5 mappings: Balanced adds
 Opus 5.5 low above Terra high, High orders Sol medium, Opus low, Sol high,
@@ -249,19 +251,23 @@ oat_dispatch_policy:
 The bundled ladder is a curated subset of the supported targets:
 
 - **Codex:** GPT-6 Luna at `low` through `max` across Economy and Balanced;
-  GPT-6 Sol at `low` through `high` in High and `xhigh` in Frontier; then
+  GPT-6.1 Sol at `low` through `high` in High and `xhigh` in Frontier; then
   GPT-6 Astra at `high` and `xhigh` in Frontier. Astra and Sol remain supported
-  at `low`, `medium`, `high`, `xhigh`, and `max`, while GPT-5.6 variants remain
+  at `low`, `medium`, `high`, `xhigh`, and `max`, while GPT-6 Sol and GPT-5.6 variants remain
   available outside this preferred ladder.
-- **Claude:** `haiku` and Sonnet 5 at Economy/Balanced, Opus 5.5 at High and
-  Frontier, and Fable 5.1 at Frontier.
+- **Claude:** `haiku` and Sonnet 5.5 medium at Economy; Opus 5.5 low at
+  Balanced, low/medium/high at High, and xhigh/max at Frontier; Fable 5.1
+  high ends Frontier. Sonnet 5 remains supported for explicit configurations.
 - **Cursor:** the preferred ladder uses approved Composer 2.5, GPT-5.6, Grok
   4.6, Opus 5.5, and Fable 5.1 targets. The catalogue maps each flat ladder ID
-  to its separately verified bracket-form frontmatter model. Grok 4.6 (`low`
+  to its separately verified frontmatter model. Sonnet 5.5 exact-ID pins
+  remain supported outside the ladder; existing families keep their bracket
+  selectors. Grok 4.6 (`low`
   through `xhigh`) and Fable 5.1 (`low` through `max`, thinking variants) were
   approved from a 2026-09-25 [native desktop probe](../../contributing/verifying-cursor-pins.md);
   targets outside the ladder remain available for explicit selection. Grok
-  4.7 has no approved mapping because it ignores bracket selectors.
+  4.7 stays outside the shipped catalogue pending its own approved mapping
+  and per-pin evidence; exact-ID support does not admit arbitrary CLI IDs.
 
 The final candidate in a named tier defines that tier's reviewer ceiling. Lower
 reviewer selection requires a separate reviewed contract; a normal reviewer
@@ -363,9 +369,9 @@ branch replaces, rather than supplements, preferred selection.
 
 An effort-pinned Claude candidate must establish the exact generation and that
 generation's supported effort. Current directly recognized generations include
-`claude-fable-5-1`, `claude-fable-5`, `claude-opus-5-5`, `claude-sonnet-5`,
+`claude-fable-5-1`, `claude-fable-5`, `claude-opus-5-5`, `claude-sonnet-5-5`, `claude-sonnet-5`,
 `claude-opus-4-7`, `claude-opus-4-6`, and `claude-sonnet-4-6`.
-Opus 5.5 supports `low`, `medium`, `high`, `xhigh`, and `max`; consult the
+Opus 5.5 and Sonnet 5.5 support `low`, `medium`, `high`, `xhigh`, and `max`; consult the
 [updating guide](../../contributing/updating-model-guidance.md) before adding
 further generations or rungs. Retired Opus 5.0 and 4.8 are no longer directly
 recognized for effort-pinned dispatch.
@@ -413,8 +419,9 @@ Cursor selection, pin mapping, catalogue availability, and runtime identity are
 separate evidence layers:
 
 - The candidate ladder and resolver use an opaque flat ID.
-- The materialized definition uses the mapping's explicit bracket-form
-  frontmatter model.
+- The materialized definition uses the mapping's explicit frontmatter model,
+  either a verified bracket selector or a separately verified exact ID.
+  Sonnet 5.5 uses exact IDs; existing families keep their bracket mappings.
 - Mapping-specific native-launch evidence authorizes the shipped mapping data.
   An approved mapping may carry a probe record whose `submittedSelector` must
   equal the mapping's `frontmatterModel` and whose `resolvedModel` must equal

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

@@ -77,14 +77,12 @@ section.
 
 For project-aware work, the calling workflow records each launch in its run
 record in `implementation.md` (request ID, `Dispatch:` stamp, launch status,
-terminal outcome). Persisting one generic record per request under the
-project's `dispatch/` directory with `oat project dispatch record` is optional
-and off by default; no lifecycle skill or command consumes those files. Managed
-effort-pinned Claude launches still pass the real resolver result, generated
-definition, and proposed payload through the command without `--project`
-before launch. That validation-only call derives the configured invocation and
-does not persist a journal file. When a host opts in, the generic snake-case
-fields remain authoritative. A namespaced `oat` block adds
+terminal outcome); that run record is the only launch record.
+`oat project dispatch record` validates a generic record and writes nothing.
+Managed effort-pinned Claude launches pass the real resolver result, generated
+definition, and proposed payload through it before launch, and that
+validation-only call derives the configured invocation. In a validated record
+the generic snake-case fields remain authoritative. A namespaced `oat` block adds
 only canonical-role identity, proven pre-start rejection, fallback linkage,
 and optional runtime observation. `oat project dispatch canonical-role`
 prints the canonical-role-resolution event read-only, so callers do not

package/assets/docs/workflows/projects/implementation-execution.md

@@ -76,10 +76,10 @@ that scope.
 Before a native launch, the root constructs and redacts the complete generic
 dispatch record and OAT role event. When the host returns, it writes the
 request ID, the `Dispatch:` stamp, and the accepted or `blocked-before-start`
-result into the run record in `implementation.md`; persisting a per-dispatch
-file with `oat project dispatch record` is optional and off by default. Before
-an effort-pinned managed Claude launch, the root must still run that command
-without `--project` as a validation-only boundary. It supplies the real
+result into the run record in `implementation.md`, the only launch record.
+Before an effort-pinned managed Claude launch, the root must run
+`oat project dispatch record`, which writes nothing, as a validation-only
+boundary. It supplies the real
 resolver result, generated definition, and proposed launch payload, and launches
 only the payload returned by the accepted envelope. An accepted launch closes
 replacement. Only an explicit rejection proving no child started permits one
@@ -319,6 +319,32 @@ and start a new gate generation. Beyond the version's own exclusion set, no
 implementation or closeout output path is excluded from the comparison. Legacy unqualified fingerprints retain the older
 fail-closed descendant-path behavior and are not migrated in place.
 
+There is no automatic test-only freshness exception. An operator can instead
+waive named stale-making descendants of an `effective-delta-v1` or
+`effective-delta-v2` generation (`DR-260927-operator-waiver-for-test-only`).
+Each waiver is appended to `oat_implement_exit_gate.waivers` with who waived,
+the reason, the covered `from_commit..to_commit` range, the effective-delta
+fingerprint at the range end (in the generation's own version), and a UTC
+timestamp. A waiver never rewrites `reviewed_head`, the implementation
+fingerprint, `freshness_head`, or the freshness fingerprint, and an earlier
+waiver is never edited. Agents write a waiver only on an explicit operator
+instruction. Under `OAT_AUTONOMOUS=1` an attempted waiver write is refused,
+and a run that finds a stale generation persists `stale` and starts a new gate
+run instead of pausing. A waived generation stays fresh only while nothing
+substantive lands after the covered range, under both versions; a malformed or
+unverifiable waiver fails closed as stale. The project summary and the final PR
+description's Verification section list every waiver.
+
+The waiver is offered where staleness is found. Before an interactive
+`oat-project-implement` run persists an allowed generation as `stale` because
+of descendant commits no waiver covers, it lists those commits and asks the
+operator to waive that range or start a new gate run; it persists `stale` only
+when the operator declines. An autonomous run never offers a waiver and starts
+a new gate run. An operator may also record a waiver before resuming
+implementation, for example after `oat-project-next` reports stale state, by
+giving the range, name, and reason in the instruction that resumes
+`oat-project-implement`.
+
 This narrow merge-only exemption relies on fresh repository CI, automated
 review such as Bugbot, and lifecycle self-review to cover integration risk.
 Those checks do not substitute for the semantic gate on the full
@@ -389,8 +415,11 @@ Provider controls remain exact: Codex uses
 `providers.claude.dispatchArgs.variant` for an effort-pinned target and
 `providers.claude.dispatchArgs.model` only for a legacy model-only target; and
 Cursor uses `providers.cursor.dispatchArgs.variant`. Cursor launches that exact
-resolver-selected native agent type first; the flat ID and bracket-form pin
+resolver-selected native agent type first; the flat ID and frontmatter pin
 remain inside the explicit mapping and are never normalized by workflow prose.
+A mapping may retain a verified bracket-form selector or use a separately
+verified exact ID, as Sonnet 5.5 does. Exact IDs require an approved mapping
+and native probe evidence; catalog presence alone never enables pass-through.
 The launcher records this selection as `configured`, while runtime identity
 remains `not-reported` without independent observation. Only a pre-start native
 role-selection rejection permits another target-preserving route.

package/assets/docs/workflows/projects/lifecycle.md

@@ -65,6 +65,12 @@ allowed and fresh disposition before pre-approval work starts. A
 not inferred from missing state, and a null, missing, or unrecognized resolver
 result fails closed as unresolved instead.
 
+A later substantive change makes an allowed result stale, test-only changes
+included. Only an operator can keep it fresh, by recording an append-only
+exit-gate waiver for the exact commits; agents never issue one. An autonomous
+run that finds a stale result persists `stale` and starts a new gate run; it
+refuses only an attempted waiver write. The summary and PR description list every waiver.
+
 After implementation closeout finishes:
 
 1. **Summary** (`oat-project-summary`) — generates `summary.md` as institutional memory from project artifacts; PR-final and completion will auto-refresh it if you have not already run it or if it is stale
@@ -75,7 +81,7 @@ After implementation closeout finishes:
    - GitHub PR feedback delegates to `oat-project-review-receive-remote`
    - Review artifacts delegate to `oat-project-review-receive`
    - After revision tasks complete, state returns to `pr_open`
-5. **Complete** (`oat-project-complete`) — accepts any phase status (`pr_open`, `complete`, `in_progress`), auto-refreshes `summary.md` before closeout when needed, and archives when selected by the workflow preference or completion prompt
+5. **Complete** (`oat-project-complete`) — accepts any phase status (`pr_open`, `complete`, `in_progress`), auto-refreshes `summary.md` before closeout when needed, and archives when selected by the workflow preference or completion prompt. Before any completion write it runs the read-only `oat project closeout-check`: a configured, autonomous, or lite closeout whose `oat_post_implement_sequence` snapshot is missing, malformed, or incomplete stops and routes back to `oat-project-implement`, and `oat project complete-state` refuses the same state. There is no override; see the [CLI reference](../../reference/cli-reference.md).
 
 ### Project-recap gate (non-lite)
 

package/assets/docs/workflows/projects/meta.json

@@ -0,0 +1,25 @@
+{
+  "title": "Workflow & Projects",
+  "pages": [
+    "lifecycle",
+    "retro",
+    "autonomy",
+    "cursor-cloud",
+    "design-modes",
+    "hill-checkpoints",
+    "dispatch-ceiling",
+    "orchestration-model",
+    "review-flavors",
+    "evidence-layers",
+    "programmatic-execution",
+    "artifacts",
+    "implementation-execution",
+    "reviewing-oat-prs",
+    "picking-up-projects",
+    "splitting",
+    "state-machine",
+    "reviews",
+    "pr-flow",
+    "repo-analysis"
+  ]
+}

package/assets/docs/workflows/projects/orchestration-model.md

@@ -76,14 +76,14 @@ sequenceDiagram
   participant Root as Project root
   participant Adapter as Project adapter
   participant Engine as Dispatch engine
-  participant Journal as Project dispatch journal
+  participant Record as Run record in implementation.md
   participant Phase as Phase implementer
 
   Root->>Adapter: Phase + lifecycle authority
   Adapter->>Engine: Provider-neutral dispatch request
   Engine-->>Root: Exact route + request ID
   Root->>Phase: Phase Scope
-  Root->>Journal: Accepted or blocked-before-start record
+  Root->>Record: Accepted or blocked-before-start result
   Phase-->>Root: Phase report + commits
 ```
 
@@ -125,10 +125,9 @@ launch.
 The launcher constructs and redacts the complete generic record plus the
 namespaced OAT role event before it calls the native host. When the host
 returns, the calling workflow writes the accepted or `blocked-before-start`
-state into its run record in `implementation.md`. Persisting a per-dispatch
-file with `oat project dispatch record` is optional and off by default; the
-command is a recorder only and never launches a provider or changes selection
-authority.
+state into its run record in `implementation.md`, the only launch record.
+`oat project dispatch record` validates a record and writes nothing; it never
+launches a provider or changes selection authority.
 
 An accepted handle owns the scope and closes replacement. One fresh fallback
 record is legal only when the native wrapper proves no child started, links the

package/assets/docs/workflows/skills/meta.json

@@ -0,0 +1,10 @@
+{
+  "title": "Skills",
+  "pages": [
+    "[Writing Skills](/contributing/skills)",
+    "[Docs Workflows](/docs-tooling/workflows)",
+    "explainer-kit",
+    "repo-improve",
+    "recon"
+  ]
+}

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

@@ -275,6 +275,12 @@ them. Adversarial reviewers receive the declared scope, questions, and
 provisional statements. Neither pass receives gatherer reasoning, synthesis
 prose, dossier paths, or earlier review conclusions.
 
+Review briefs come only from the production brief generator. The packet
+validator rebuilds every brief from the prior claim ledger and manifest with
+that same generator and rejects any difference with `REVIEW_BRIEF_MISMATCH`, so
+a brief carrying an injected claim, note, or source fails publication. A
+review's dispositions must also be unique members of its brief's claims.
+
 Each lane receives one explicit authority envelope and one unique output path.
 Its enforcement is recorded as:
 
@@ -293,8 +299,17 @@ operation.
 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. The achieved profile is derived from the
+downgrades. Every claim a review kept below `verified` (an unresolved issue
+scoped to it or global to its review, a coverage finding that names it, or a
+non-affirming disposition) is listed under Review Downgrades with the review's
+own text, even when it is not a key claim, so a `complete` packet cannot hide a
+downgraded claim. A claim that a required review left without a disposition stays
+`unresolved` and is listed there as not reviewed. A review's
+`unresolvedIssues` entry may name the claim IDs it affects or apply to the
+whole review; a legacy plain-string entry is read as review-wide. A material
+coverage gap does not fail publication by itself: the claims it affects stay
+below `verified` and the run publishes as an honest `partial`. A run may be partial even when it achieved the requested
+profile if 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. Each approved lane
 must likewise have a complete artifact or a material outcome gap carrying its
@@ -310,7 +325,17 @@ honest `partial` packet at that achieved profile.
 
 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
+say whether every accepted lane reached a terminal result.
+
+A launch the provider rejects before any child is accepted, such as a Codex
+agent-limit rejection, is a `provider/dispatch` failure, never a worker
+failure, and every accepted artifact is kept. The approved `retryLimit` counts
+these pre-acceptance admission retries per lane, and the controller makes at
+most one per lane, so the approval preview's worst case is two attempts per
+lane. The default of 0 allows none. If admission still fails, recon uses an
+alternate route only when it was already approved; otherwise it stops with a
+partial run and asks for a continuation amendment. An accepted lane is never
+rerun to free capacity. Workers that
 completed are never reported as failed because the controller could not
 publish.
 

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.3.9",
-  "docs-config": "0.3.9",
-  "docs-theme": "0.3.9",
-  "docs-transforms": "0.3.9"
+  "cli": "0.3.11",
+  "docs-config": "0.3.11",
+  "docs-theme": "0.3.11",
+  "docs-transforms": "0.3.11"
 }