@open-agent-toolkit/cli 0.2.62 → 0.2.64

package/assets/docs/provider-sync/manifest-and-drift.md

@@ -84,6 +84,111 @@ An exact alias is `in_sync`; an absent alias is `missing`; and a broken,
 replaced, foreign, or otherwise unverifiable alias is `drifted`. Provider list
 and inspect output summarize collection ownership separately from copy mode.
 
+### Resolution-time skill view classes
+
+Drift states answer "does the tracked view still match?", which presupposes a
+manifest entry. A canonical skill that was never synced has no entry at all, so
+`oat tools info <name>` adds a second, additive classification beside the
+unchanged drift state. Provider and path identity for an untracked projection
+come from the active provider set and the adapter's scope mappings, not from
+the manifest.
+
+- `missing-additive` — active, supported, no manifest entry, nothing at the expected path: the only true projection gap
+- `removed` — a manifest entry exists but the provider file is gone
+- `modified` — a manifest entry exists and the view no longer agrees with what the last sync recorded, or its version has fallen behind canonical. A `copy` view also reaches this class through the known limitation below, where the difference may be nothing but the generated banner
+- `in-sync` — a symlinked, collection-aliased, or natively read view _is_ the canonical file; a `copy` view matches the content recorded at its last sync
+- `untracked` — something exists at the expected path that no manifest entry tracks; stray detection skips provider entries whose name matches a canonical entry, so `oat status` does not report it as a stray and reports the untracked projection as `missing` instead
+- `unverified` — the view's state is unknown: either a manifest entry arrived with no drift observation, or reading that one view failed and the row carries the redacted reason
+- `inactive`, `unsupported`, `excluded` — no projection is expected in this scope, so none of them is reported as missing
+
+`unsupported` and `excluded` are defensive: no shipped adapter or config
+produces them today. Every shipped adapter maps skills in both scopes and the
+command passes no canonical-path filter. The branches exist so a future adapter
+or filter cannot be silently reported as a projection gap. `unverified` is
+reachable: an unreadable provider path makes drift detection throw, and that one
+view degrades to `unverified` with its reason.
+
+A row for `inactive`, `unsupported`, or `excluded` prints neither a projection
+qualifier nor a path, because no view is projected for it: naming an expected
+path and a sync strategy for a file that is never produced described work that
+is never going to happen.
+
+Only `missing-additive`, `removed`, and `modified` carry a repair, and it is
+always one concrete `oat sync --scope project` or `oat sync --scope user` for
+the scope where the gap was observed. Versions are compared only for `copy`
+views: a symlinked, collection-aliased, or natively read view is the canonical
+file, so it has no second version.
+
+If reading the sync config or the manifest fails — an invalid, unreadable, or
+otherwise non-loadable `.oat/sync/config.json` or `.oat/sync/manifest.json`, for
+instance — the section for that scope reports `unavailable` with the reason, and
+the rest of the command is unaffected. A failure while reading one provider's
+view, such as drift detection throwing on an unreadable provider path, is
+narrower: only that row degrades, to `unverified` with the same redacted reason,
+and the other providers keep their real rows. The
+diagnostic is additive evidence, so it never changes the exit code or removes
+the tool detail of a user whose sync state is already broken. A broken sync
+config is one of the likeliest reasons a provider view is missing, which is
+exactly what this command is run to explain, so it is reported rather than
+dropped: printing no section at all would read as "no providers configured".
+An absent `.oat/sync/config.json` is a different case and not a failure — it
+resolves to the defaults, and the scope is diagnosed normally. Reasons are
+redacted; the scope root becomes `<project>` or `~` (only at a path boundary, so
+a sibling directory that merely shares the prefix is left alone), and any
+absolute path outside it is replaced entirely with `<path>`, quoted or not and
+whatever punctuation precedes it. A manifest `providerPath` that escapes its own
+scope is redacted the same way rather than rendered in the row, and no version
+is read from it: its `SKILL.md` is a file outside the tree the command was asked
+about.
+
+A drift state and a view class can legitimately disagree. Drift compares a copy
+against the hash recorded at its last sync, so a copy that was never re-synced
+after a canonical edit still matches its own manifest entry and reads as
+`in_sync`. When the two versions differ, the view class is `modified` and the
+drift state is reported unchanged beside it.
+
+The manifest is keyed by `(canonicalPath, provider)` and never by path, so a
+manifest entry can track a view somewhere other than the adapter's expected
+projection path — reachable after a `providerDir` change or from a manifest
+written under an older layout. Drift resolves the entry's own `providerPath`, so
+in that case the row names the tracked path rather than the expected one, and
+its `--json` record carries the expected path separately as
+`expectedProviderPath`. The detail says which path the state describes and
+whether anything exists at the expected path. A drift verdict computed for one
+path is never attached to a row labelled with another: doing so reported `removed`
+with "the provider file is gone from disk" against a healthy file that was
+sitting at the expected path all along.
+
+Both sides resolve their version through the same shared reader, so
+`metadata.version` takes precedence over the deprecated top-level `version`
+alias for a projected view exactly as it does for the canonical source; the only
+extra step for a view is stripping the generated banner. When a projected
+`SKILL.md` contradicts itself — a top-level `version` and a differing
+`metadata.version` — or declares a version the reader cannot use at all, the
+comparison is withheld rather than decided: no version is reported for that
+view, and the class is left to the drift state alone. That is deliberately
+conservative and has a cost, since a copy in that state could be genuinely
+stale and would not be reported as such. The view's detail names the two
+declared values and says the comparison was skipped, so the ambiguity is
+visible rather than silently resolved. When the resolver's answer happens to
+agree with canonical, nothing is withheld and the detail says so instead.
+
+### Known limitation: copy-strategy skill views
+
+A `copy` skill view is reported `modified` immediately after a successful sync,
+and stays that way. The engine writes an OAT-managed banner into the copied
+`SKILL.md` and an `.oat-generated` sentinel beside it, and neither is accounted
+for in the manifest hash, so `oat status` reports `drifted:modified` and every
+later `oat sync --dry-run` plans another `update_copy`. Because no sync clears
+that state, `oat tools info` prints no repair line when a `modified` copy's
+version still matches canonical.
+
+That suppression is a conservative heuristic rather than a proof: equal versions
+do not establish equal bodies, so an edit to the canonical source or to the copy
+that kept the version reaches the same branch, and a sync _would_ repair that
+one. The class detail says so and names the concrete scope command to run if you
+know either side was edited. Tracked as `BL-260908-make-copy-strategy-skill`.
+
 ## Stray adoption
 
 `oat init` and `oat status` can offer adoption of unmanaged provider entries into canonical `.agents`.

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

@@ -149,7 +149,7 @@ Notable commands introduced in the current CLI surface:
 - `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).
 - `oat project set-mode` — deprecated no-op. Execution mode is no longer user-selectable; emits a deprecation warning and preserves the `--json` contract.
-- `oat gate review <prompt...>` - run a stateful, headless OAT review through the target registry, parse the produced review artifact, and exit nonzero for configured blocking findings. `--timeout-ms <milliseconds>` overrides target, `workflow.gateTimeouts`, environment, and scope defaults; accepted values are 1,000–14,400,000. Final/phase/range code reviews default to 30 minutes, while task code and artifact reviews default to 15 minutes. With `--json`, the result envelope on exit is the canonical completion signal: `status` is `ok` | `blocked` | `review_failed` | `artifact_missing` | `artifact_validation_failed` | `targeting_correlation_failed`, alongside `runId`, `generatedAt`, and `artifactPath` when available. `artifact_missing` means an accepted child exited cleanly without an artifact; fix synchronous review/artifact completion and start a new run, without review-receive or same-run remediation. For `targeting_correlation_failed`, correct the project declaration or artifact routing and start a new run; do not run review-receive even if an artifact path is present. For `artifact_validation_failed`, correct the artifact and rerun the gate until it revalidates as `ok` or `blocked`. Invoke `oat-project-review-receive` only when all three conditions hold: `status` is `ok` or `blocked`, `receiveEligible` is `true`, and `handoff` is non-null. `review_failed` may include structured `refusal`, `noOutputProduced`, and metadata-only `activityEvidence`; these diagnostic fields never make a run receive-eligible. After a timeout, a validated run-correlated artifact returns the ordinary `ok` or `blocked` envelope with additive `lateCompletion: true`. Duplicate run-ID matches or a changed artifact with a mismatched run ID retain `targeting_correlation_failed` and `receiveEligible: false`. Orchestrators should read the structured result rather than poll the filesystem. See [Workflow Gates](../cli-utilities/workflow-gates.md).
+- `oat gate review <prompt...>` - run a stateful, headless OAT review through the target registry, parse the produced review artifact, and exit nonzero for configured blocking findings. `--timeout-ms <milliseconds>` overrides target, `workflow.gateTimeouts`, environment, and scope defaults; accepted values are 1,000–14,400,000. Final/phase/range code reviews default to 30 minutes, while task code and artifact reviews default to 15 minutes. With `--json`, the result envelope on exit is the canonical completion signal: `status` is `ok` | `blocked` | `review_failed` | `artifact_missing` | `artifact_validation_failed` | `targeting_correlation_failed`, alongside `runId`, `generatedAt`, and `artifactPath` when available. `artifact_missing` means an accepted child exited cleanly without an artifact; fix synchronous review/artifact completion and start a new run, without review-receive or same-run remediation. For `targeting_correlation_failed`, correct the project declaration or artifact routing and start a new run; do not run review-receive even if an artifact path is present. For `artifact_validation_failed`, correct the artifact and rerun the gate until it revalidates as `ok` or `blocked`. Invoke `oat-project-review-receive` only when all three conditions hold: `status` is `ok` or `blocked`, `receiveEligible` is `true`, and `handoff` is non-null. `review_failed` may include structured `refusal`, `noOutputProduced`, and metadata-only `activityEvidence`; these diagnostic fields never make a run receive-eligible. After a timeout, a validated run-correlated artifact returns the ordinary `ok` or `blocked` envelope with additive `lateCompletion: true`. When post-selection work fails after the reviewer already committed a run-correlated artifact, the gate re-validates that selected snapshot through the same eligibility path rather than re-parsing whatever the path now holds, never re-dispatching, and returns the ordinary `ok` or `blocked` envelope with additive `postSelectionRecovery: true`; the artifact must still be present and unchanged for re-validation to succeed. When nothing recovers, `review_failed` names the failing sub-step in `postSelection.step` and its cause in `postSelection.code`. Duplicate run-ID matches or a changed artifact with a mismatched run ID retain `targeting_correlation_failed` and `receiveEligible: false`. Orchestrators should read the structured result rather than poll the filesystem. See [Workflow Gates](../cli-utilities/workflow-gates.md).
 - `oat gate route --expect-runtime <runtime> --expect-model <model> --can-await <true|false> --json` - return the headless child route (`inline`, `delegate-sync`, or `refuse`) from provider-marker and model evidence. Ambiguous or contradictory evidence never routes inline.
 - `oat gate exec <prompt...>` / `oat gate cross-provider-exec <prompt...>` - run a generic target prompt. `--timeout-ms` uses the same validated CLI override; untyped runs otherwise retain the legacy default path.
 - `oat gate target set <id> --invocation-model <model|provider-default> --invocation-reasoning-effort <effort|provider-default>` - persist optional configured invocation metadata alongside an exec target without inferring it from the target command.
@@ -159,15 +159,25 @@ Notable commands introduced in the current CLI surface:
 
 ## `oat config` surface flags
 
-`oat config set` supports mutually exclusive surface flags that control which config file receives the write:
+`oat config set` and `oat config unset` support the same mutually exclusive surface flags, which control the config file the write or removal lands in:
 
-- `--shared` — write to `.oat/config.json` (committed team repo settings)
-- `--local` — write to `.oat/config.local.json` (per-developer repo state, gitignored)
-- `--user` — write to `~/.oat/config.json` (user-level fallback, applies across all repos)
+- `--shared` — write to or remove from `.oat/config.json` (committed team repo settings)
+- `--local` — write to or remove from `.oat/config.local.json` (per-developer repo state, gitignored)
+- `--user` — write to or remove from `~/.oat/config.json` (user-level fallback, applies across all repos)
 
 When no flag is passed, the CLI picks a sensible default per key type: structural keys (`projects.root`, `documentation.*`, etc.) go to shared, state keys (`activeProject`, etc.) go to local, workflow preferences (`workflow.*`) go to local. Pass at most one flag — the command rejects multiple surface flags.
 
-Per-key restrictions apply: structural keys can only be written at shared scope, most state keys can only be written at local scope (`activeIdea` is the exception — it accepts both local and user), and workflow preference keys accept any non-auto surface. Legacy `autoReviewAtCheckpoints` remains shared-only; prefer `workflow.autoReviewAtHillCheckpoints`.
+Per-key restrictions apply identically to `set` and `unset`: structural keys can only be written at shared scope, most state keys can only be written at local scope (`activeIdea` is the exception — it accepts both local and user), and workflow preference keys accept any non-auto surface. Legacy `autoReviewAtCheckpoints` remains shared-only; prefer `workflow.autoReviewAtHillCheckpoints`.
+
+`oat config unset <key>` removes the key from the selected surface and prunes any parent object it empties, so the resolved value falls back through the remaining surfaces to the built-in default. Removing a key the surface does not hold is not an error: it reports an already-unset outcome and exits 0. With `--json` the envelope adds a `removed` boolean, which is the machine-readable way to tell a real removal from an already-unset no-op, since both exit 0. A stored value that fails validation is still removed, matching `oat config set`, which repairs the same file.
+
+`unset` refuses five classes of key, each with exit code 1:
+
+- **Unknown keys**, including keys OAT reads but does not expose in the `oat config` catalog (`documentation.index`). These are not removable by any `oat config` command.
+- **Lifecycle state** (`activeProject`, `lastPausedProject`) — cleared with `oat config set <key> ''` instead.
+- **Pack intent** (`tools.*`) — removed with `oat tools remove --pack <pack> --scope project`, which also removes the installed pack files. Clearing the intent alone would leave them behind.
+- **Aggregate read views** (`workflow.dispatchCeiling`, `workflow.dispatchCeiling.providers`) — these are assembled for `get` from the leaf keys and are not stored as such. Unset `workflow.dispatchCeiling.preset` or `workflow.dispatchCeiling.providers.<provider>` instead.
+- **Environment-shadowed keys with nothing stored on the target surface** — when `OAT_PROJECTS_ROOT`, `OAT_PROJECTS_DEFAULT_SCOPE`, or `OAT_WORKTREES_ROOT` supplies the effective value and the surface holds nothing to remove, clear the environment variable in your shell. When the surface _does_ hold a stored value, `unset` removes it (as `set` would rewrite it) and warns that the override still supplies the effective value.
 
 ## `workflow.*` preference keys
 

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

@@ -110,37 +110,38 @@ Legacy `.oat/active-project` / `.oat/projects-root` / `.oat/active-idea` files m
 
 Current schema keys:
 
-| Key                                                        | Type                       | Default                  | Description                                                                                                                                                                                                                                                                                             |
-| ---------------------------------------------------------- | -------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `version`                                                  | `number`                   | `1`                      | Schema version                                                                                                                                                                                                                                                                                          |
-| `worktrees.root`                                           | `string`                   | `".worktrees"`           | Root directory for git worktrees (repo-relative or absolute)                                                                                                                                                                                                                                            |
-| `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`                   | -                        | 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: 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. |
-| `workflow.dispatchPolicy.mode`                             | `string`                   | unset                    | Dispatch policy mode: `managed` lets OAT select model/effort controls; `inherit` leaves controls to the host/provider defaults.                                                                                                                                                                         |
-| `workflow.dispatchPolicy.policy`                           | `string`                   | unset                    | Managed dispatch policy: `economy`, `balanced`, `high`, `frontier`, or `uncapped`. Capped policies compile to provider targets; `uncapped` keeps OAT-managed preferred selection without provider caps. `inherit` mode is separate and leaves controls to the host/provider.                            |
-| `workflow.dispatchCeiling.preset`                          | `string`                   | unset                    | Legacy compatibility preset for capped managed policy setup (`balanced`, `maximum`, `cost-conscious`). `maximum` maps to `high`; `cost-conscious` maps to `economy`.                                                                                                                                    |
-| `workflow.dispatchCeiling.providers.<provider>`            | `object` or legacy scalar  | unset                    | Reusable provider candidate ladder. The canonical shape maps `economy`, `balanced`, `high`, and `frontier` to ordered candidate cells; project and phase state record only a named maximum over that ladder.                                                                                            |
-| `workflow.dispatchCeiling.providers.<provider>.<tier>`     | `{ candidates: [...] }`    | unset                    | One ordered candidate cell. Codex entries carry exact `model` plus `effort` and resolve to materialized roles; Claude entries carry a model; Cursor strings remain opaque and pass to Cursor byte-for-byte. The final candidate defines that tier's reviewer ceiling.                                   |
-| `workflow.dispatchCeiling.providers.{codex,claude,cursor}` | `string`, route, or target | unset                    | Legacy compatibility input normalized to a one-candidate ladder. New configuration should use tiered candidate cells. The flat keys `workflow.dispatchCeiling.codex` and `workflow.dispatchCeiling.claude` were removed without migration.                                                              |
-| `workflow.gates.skills`                                    | `object`                   | unset                    | Per-skill final gate config keyed by skill name. Managed with `oat gate set/unset`; gate-aware skills declare `oat_gateable: true`.                                                                                                                                                                     |
-| `workflow.gates.execTargets`                               | `object`                   | built-ins                | Cross-runtime exec target registry keyed by opaque target id. Managed with `oat gate target set/unset`; built-ins cover Codex, Claude, and Cursor defaults.                                                                                                                                             |
-| `archive.s3Uri`                                            | `string`                   | -                        | Base S3 URI for repo-scoped archived project sync, for example `s3://bucket/oat-archive`                                                                                                                                                                                                                |
-| `archive.s3SyncOnComplete`                                 | `boolean`                  | `false`                  | When `true`, `oat-project-complete` uploads the archived project to the configured S3 archive after local archive succeeds                                                                                                                                                                              |
-| `archive.summaryExportPath`                                | `string`                   | -                        | Repo-relative directory where completion exports `summary.md` as a dated snapshot like `20260401-<project-name>.md` for durable tracked reference                                                                                                                                                       |
-| `archive.wrapUpExportPath`                                 | `string`                   | -                        | Repo-relative directory where `oat-wrap-up` writes dated reports like `20260413-wrap-up-past-week.md`; when unset, the skill falls back to `.oat/repo/reference/wrap-ups/`                                                                                                                              |
-| `archive.awsProfile`                                       | `string`                   | -                        | Optional AWS named profile forwarded as `AWS_PROFILE` to every `aws` invocation in archive flows (`oat-project-complete` S3 sync, `oat repo archive sync`). Overrides ambient shell `AWS_PROFILE` / `AWS_DEFAULT_PROFILE` when set.                                                                     |
-| `archive.awsRegion`                                        | `string`                   | -                        | Optional AWS region forwarded as `AWS_REGION` to every `aws` invocation in archive flows. Overrides ambient shell `AWS_REGION` / `AWS_DEFAULT_REGION` when set.                                                                                                                                         |
-
-All `documentation.*` keys are managed via `oat config get/set` and are set automatically by `oat docs init`.
+| Key                                                        | Type                       | Default                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| ---------------------------------------------------------- | -------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `version`                                                  | `number`                   | `1`                      | Schema version                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `worktrees.root`                                           | `string`                   | `".worktrees"`           | Root directory for git worktrees (repo-relative or absolute)                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `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`                   | -                        | 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: 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.instructionPointerExcludes`                 | `string[]`                 | -                        | Repo-relative directories `oat instructions sync`/`validate` must not treat as pointer sites, additive to the documentation content root they skip by default. Normalized and de-duplicated; a malformed value (non-array, or an empty or non-string entry) is rejected with exit code `2`. Set as one comma-separated value with `oat config set`; absolute paths and paths escaping the repository are refused. See [Instruction Sync](../provider-sync/instruction-sync.md#documentation-trees). |
+| `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.                                                                                                                                                                                             |
+| `workflow.dispatchPolicy.mode`                             | `string`                   | unset                    | Dispatch policy mode: `managed` lets OAT select model/effort controls; `inherit` leaves controls to the host/provider defaults.                                                                                                                                                                                                                                                                                                                                                                     |
+| `workflow.dispatchPolicy.policy`                           | `string`                   | unset                    | Managed dispatch policy: `economy`, `balanced`, `high`, `frontier`, or `uncapped`. Capped policies compile to provider targets; `uncapped` keeps OAT-managed preferred selection without provider caps. `inherit` mode is separate and leaves controls to the host/provider.                                                                                                                                                                                                                        |
+| `workflow.dispatchCeiling.preset`                          | `string`                   | unset                    | Legacy compatibility preset for capped managed policy setup (`balanced`, `maximum`, `cost-conscious`). `maximum` maps to `high`; `cost-conscious` maps to `economy`.                                                                                                                                                                                                                                                                                                                                |
+| `workflow.dispatchCeiling.providers.<provider>`            | `object` or legacy scalar  | unset                    | Reusable provider candidate ladder. The canonical shape maps `economy`, `balanced`, `high`, and `frontier` to ordered candidate cells; project and phase state record only a named maximum over that ladder.                                                                                                                                                                                                                                                                                        |
+| `workflow.dispatchCeiling.providers.<provider>.<tier>`     | `{ candidates: [...] }`    | unset                    | One ordered candidate cell. Codex entries carry exact `model` plus `effort` and resolve to materialized roles; Claude entries carry a model; Cursor strings remain opaque and pass to Cursor byte-for-byte. The final candidate defines that tier's reviewer ceiling.                                                                                                                                                                                                                               |
+| `workflow.dispatchCeiling.providers.{codex,claude,cursor}` | `string`, route, or target | unset                    | Legacy compatibility input normalized to a one-candidate ladder. New configuration should use tiered candidate cells. The flat keys `workflow.dispatchCeiling.codex` and `workflow.dispatchCeiling.claude` were removed without migration.                                                                                                                                                                                                                                                          |
+| `workflow.gates.skills`                                    | `object`                   | unset                    | Per-skill final gate config keyed by skill name. Managed with `oat gate set/unset`; gate-aware skills declare `oat_gateable: true`.                                                                                                                                                                                                                                                                                                                                                                 |
+| `workflow.gates.execTargets`                               | `object`                   | built-ins                | Cross-runtime exec target registry keyed by opaque target id. Managed with `oat gate target set/unset`; built-ins cover Codex, Claude, and Cursor defaults.                                                                                                                                                                                                                                                                                                                                         |
+| `archive.s3Uri`                                            | `string`                   | -                        | Base S3 URI for repo-scoped archived project sync, for example `s3://bucket/oat-archive`                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `archive.s3SyncOnComplete`                                 | `boolean`                  | `false`                  | When `true`, `oat-project-complete` uploads the archived project to the configured S3 archive after local archive succeeds                                                                                                                                                                                                                                                                                                                                                                          |
+| `archive.summaryExportPath`                                | `string`                   | -                        | Repo-relative directory where completion exports `summary.md` as a dated snapshot like `20260401-<project-name>.md` for durable tracked reference                                                                                                                                                                                                                                                                                                                                                   |
+| `archive.wrapUpExportPath`                                 | `string`                   | -                        | Repo-relative directory where `oat-wrap-up` writes dated reports like `20260413-wrap-up-past-week.md`; when unset, the skill falls back to `.oat/repo/reference/wrap-ups/`                                                                                                                                                                                                                                                                                                                          |
+| `archive.awsProfile`                                       | `string`                   | -                        | Optional AWS named profile forwarded as `AWS_PROFILE` to every `aws` invocation in archive flows (`oat-project-complete` S3 sync, `oat repo archive sync`). Overrides ambient shell `AWS_PROFILE` / `AWS_DEFAULT_PROFILE` when set.                                                                                                                                                                                                                                                                 |
+| `archive.awsRegion`                                        | `string`                   | -                        | Optional AWS region forwarded as `AWS_REGION` to every `aws` invocation in archive flows. Overrides ambient shell `AWS_REGION` / `AWS_DEFAULT_REGION` when set.                                                                                                                                                                                                                                                                                                                                     |
+
+Most `documentation.*` keys are managed via `oat config get/set` and are set automatically by `oat docs init`. One has no `oat config set` entry and is edited directly in `.oat/config.json`: `documentation.index`, which `oat docs init` still seeds for you.
 The `git.defaultBranch` key is auto-detected during `oat init` and can be overridden via `oat config set git.defaultBranch <branch>`.
 Archive settings are managed via `oat config get/set`, and `oat config describe archive.s3Uri` (or the other archive keys) shows the lifecycle and ownership details from the CLI.
 Workflow gate objects are structured config and are managed with `oat gate`, not the scalar `oat config set` surface. See [Workflow Gates](../cli-utilities/workflow-gates.md).

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

@@ -141,6 +141,51 @@ On completion, OAT treats archive handling as an explicit closeout choice:
   ref. `oat project prune` is a separate destructive choice that removes
   terminal ref reachability but preserves local and S3 archive snapshots.
 
+### Absorbed-project retirement sweep
+
+Retiring a project that a later project absorbed is a semantic claim, not a
+filesystem operation. Deleting or archiving the old scaffold does not make the
+roadmap stop promising its work, so completion checks the claim against the
+prose that still makes it.
+
+When a quick project consolidates earlier scaffolds, quick-start records
+`absorbed_projects` and `absorbed_backlog_ids` in that project's `state.md`
+frontmatter. Those two fields are the only inputs the sweep takes.
+
+Recording them is a quick-mode step today. A lite project that consolidates
+earlier scaffolds records nothing, so the sweep finds no inputs and degrades to
+its recorded note rather than checking that project's surfaces.
+
+Inside the project-log completion gate — after the log status probe and before
+the roll-up and seal — completion searches the active planning surfaces for each
+absorbed slug and backlog ID, and for future-oriented ownership language tied to
+them:
+
+- `.oat/repo/pjm/roadmap.md` (the Now/Next/Later lanes and the sequencing map)
+- `.oat/repo/pjm/current-state.md`
+- the Curated Overview in `.oat/repo/pjm/backlog/index.md`
+- the scope-nested `state.md` of projects that are still active, under the
+  configured projects root, skipping the `archived` tree and any project already
+  recorded as complete
+
+The sweep is advisory. A raw match is never a hard block on closeout: each hit
+becomes a named finding carrying a recorded disposition: fixed in the same run,
+accepted as historical with a reason, or — in an autonomous run — recorded as
+`deferred advisory`. Prose that clearly describes
+past state is exempt, so a dated history entry, a retro, a decision record, or a
+changelog line reads as evidence rather than a stale claim.
+
+Placement is the point. Dispositions are appended to the project log before the
+roll-up, so the roll-up summarizes them and the completion seal remains the
+final entry — no project-log append ever follows the seal. Three variations
+change where and how the dispositions are recorded: an autonomous run records
+each finding as a `deferred advisory` warning and continues, a project with no log reports them in the
+final completion summary, and a resumed completion whose log already
+carries a seal runs report-only and appends nothing.
+
+Repositories that never adopted PJM skip the sweep with a one-line note. A
+missing planning surface degrades the sweep, never the closeout.
+
 ### Phase status: `pr_open`
 
 After `oat-project-pr-final` runs, `state.md` shows `oat_phase_status: pr_open`. This signals:

package/assets/docs/workflows/projects/picking-up-projects.md

@@ -36,6 +36,20 @@ its parent is reported and skipped rather than adopted.
 After adoption, set or open the project through the normal lifecycle command
 you are using. Arrival-aware project skills pull before reading its artifacts.
 
+An adopted quick-workflow project whose `plan.md` is not implementation-ready
+resumes through `oat-project-quick-start`, which continues it in place without
+re-scaffolding, rather than through `oat-project-implement`. `oat-project-plan`,
+`oat-project-progress`, and `oat-project-next` all route by the single **quick
+plan readiness** predicate that `oat-project-quick-start` defines; readiness is
+never inferred from the presence of tasks alone.
+
+`oat project status` and `oat project list` apply the same predicate. For a
+quick project at the `plan` phase they recommend `oat-project-quick-start`, with
+the unmet clause in the reason, until the plan carries ready frontmatter, a
+durable `## Reviews` disposition, and a substantive task; only then do they
+recommend `oat-project-implement`. Recommendations for lite, spec-driven, and
+import projects are unchanged, because the predicate is quick-workflow policy.
+
 ## What travels
 
 - The project ref carries the complete active artifact tree and its history.

package/assets/docs/workflows/skills/explainer-kit.md

@@ -420,10 +420,16 @@ Interactive project explainer and recap preferences resolve independently from
 the built-in default is `ask`. A resolved project decision in `state.md`
 outranks those preferences.
 
-Autonomous mode has stricter policy: it always attempts a project recap, while
-a project explainer runs only when the kickoff request explicitly asks for
-one. Lifecycle-triggered runs do not publish automatically, and recap failure
-does not block project completion.
+Autonomous mode has stricter policy: it always runs the project-recap gate,
+while a project explainer runs only when the kickoff request explicitly asks
+for one. The gate probes the five seams an unattended recap needs — author,
+fact critic, browser session, visual critic, and set planner — before
+generating. It attempts the recap only when all five resolve; when a seam has
+no provider configured at all, it records a `skip` with source
+`capability_probe` and a warning instead. A seam that is configured but invalid
+is a configuration error and still fails closed. Lifecycle-triggered runs do
+not publish automatically, and neither recap failure nor an unavailable seam
+blocks project completion.
 
 See [Project Artifacts](../projects/artifacts.md) for active and durable output
 locations, and [Configuration](../../cli-utilities/configuration.md) for the

package/assets/docs/workflows/skills/repo-improve.md

@@ -35,7 +35,7 @@ These are findings exclusions, not absolute read prohibitions. Improve may read
 
 ## Output boundary
 
-External plans are not canonical OAT project `plan.md` files. They contain self-contained context, scope, steps, verification, done criteria, and STOP conditions, but no OAT phase/task IDs or lifecycle bookkeeping.
+External plans are not canonical OAT project `plan.md` files. They contain self-contained context, scope, steps, verification, done criteria, and STOP conditions, but no canonical OAT phase/task IDs or lifecycle bookkeeping. External execution-readiness metadata is a separate thing and is carried deliberately: it describes whether the plan's own prerequisites have merged, not how an OAT project is moving through phases.
 
 After generation, choose either execution path:
 
@@ -44,6 +44,20 @@ After generation, choose either execution path:
 
 Project-sized candidates are split when possible. If inseparable work needs multiple design decisions or lacks one coherent verification boundary, improve recommends an OAT project workflow instead of emitting a mega-plan.
 
+## Plan readiness and execution readiness
+
+Improve scores candidates on two independent axes. A candidate is plan-ready when it is understood well enough to write a self-contained executable plan, and execution-ready when every hard dependency it names has already merged.
+
+A blocked candidate is still planned. Rather than dropping work whose prerequisite has not landed, improve writes the plan and records the block:
+
+- `oat_execution_status` is `READY` or `BLOCKED` in plan frontmatter.
+- A typed `## Dependencies` table marks each row `Hard`, `Soft`, or `Satisfied`, and every `Hard` row names the state that would unblock it.
+- `## Landing-event impact` records what to re-anchor when a named PR or project lands, and `## Revalidation Before Execution` records when the plan must be re-checked against live state.
+
+Plan provenance is recorded as two separate SHAs: `oat_external_plan_commit` is the full SHA of the `HEAD` whose content was actually inspected, and `oat_external_plan_main_commit` is the fetched `origin/main` or merge-base used only for comparison. They may differ, and normally do when planning happens on a branch.
+
+Plans written before this contract landed are read in legacy mode: a short SHA, a missing comparison SHA, missing sections, and a missing status (read as `READY`) are all accepted, and those plans are never rewritten.
+
 ## Optional tracking
 
 Plans are always the primary output. Tracking is optional and source-aware:

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.2.62",
-  "docs-config": "0.2.62",
-  "docs-theme": "0.2.62",
-  "docs-transforms": "0.2.62"
+  "cli": "0.2.64",
+  "docs-config": "0.2.64",
+  "docs-theme": "0.2.64",
+  "docs-transforms": "0.2.64"
 }

package/assets/skills/create-agnostic-skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-agnostic-skill
-version: 1.4.1
+version: 1.4.2
 description: Use when adding a reusable workflow skill for AI coding agents. Scaffolds a new .agents/skills skill using the Agent Skills open standard.
 argument-hint: '[skill-name]'
 disable-model-invocation: true
@@ -98,12 +98,13 @@ For detailed guidance, see `references/skill-template.md`.
 ```markdown
 ---
 name: skill-name
-version: 1.0.0
 description: Use when [trigger condition]. [What it does for disambiguation].
 argument-hint: '[arg1] [--flag]'
 disable-model-invocation: true
 allowed-tools: Read, Write, Glob, Grep
 user-invocable: true
+metadata:
+  version: 1.0.0
 ---
 
 # Skill Title
@@ -172,9 +173,10 @@ Natural language request that triggers this skill
 - `argument-hint`, `allowed-tools`, `user-invocable`, `context`, `hooks` are Claude Code specific
 - Other agents ignore unknown frontmatter fields, so it's safe to include Claude-specific fields everywhere
 - `name`: max 64 chars for cross-provider portability (Codex allows 100, but 64 is the spec limit)
-- `version`: include valid semver and start new skills at `1.0.0`
+- `metadata.version`: include valid semver and start new skills at `1.0.0`. The Agent Skills specification puts the version under `metadata`, and OAT resolves `metadata.version` first and the top-level `version` second — `resolveSkillVersion` in `packages/cli/src/commands/shared/frontmatter.ts` owns that order, backstopped by `packages/cli/src/commands/shared/frontmatter.test.ts`
+- `version` (top-level): the deprecated alias, still read when `metadata.version` is absent. Do not set both to different values: OAT reports the conflict, skill validation fails on it, and canonical role identity rejects it
 - `description`: **single line, ≤ 500 chars** (Codex enforces single-line ≤ 500 chars; spec allows 1024)
-- Bump `version` on future edits: patch for fixes/clarifications, minor for backward-compatible behavior additions, major for breaking workflow/interface changes
+- Bump `metadata.version` on future edits: patch for fixes/clarifications, minor for backward-compatible behavior additions, major for breaking workflow/interface changes
 
 **Writing the `description` field:**
 
@@ -200,7 +202,7 @@ Create the skill at `.agents/skills/{skill-name}/SKILL.md`
 **Key requirements:**
 
 - Skill name matches directory name
-- New skills include `version: 1.0.0` in frontmatter
+- New skills include `metadata.version: 1.0.0` in frontmatter
 - Workflow steps use "Step 1, 2, 3..." naming
 - Include both "Basic Usage" and "Conversational" example styles
 - Use imperative form for instructions
@@ -238,7 +240,7 @@ Verify:
 
 - File created at `.agents/skills/{skill-name}/SKILL.md`
 - Frontmatter syntax is valid
-- Frontmatter includes valid semver `version:` (new skills start at `1.0.0`)
+- Frontmatter includes valid semver `metadata.version:` (new skills start at `1.0.0`)
 - Skill appears in `AGENTS.md`
 - Examples include both invocation styles
 - If the skill name starts with `oat-`, run `pnpm oat:validate-skills` and fix any findings
@@ -264,7 +266,7 @@ Provide:
 
 - **Context window is a public good**—keep skills lean, challenge every paragraph
 - Description is the trigger—include "when to use" in frontmatter, not just body
-- Bump `version` for edits: patch = fixes/clarifications, minor = backward-compatible additions, major = breaking changes
+- Bump `metadata.version` for edits: patch = fixes/clarifications, minor = backward-compatible additions, major = breaking changes
 - Keep SKILL.md **under 500 lines / ~5,000 tokens** (spec constraint)
 - Use clear, task-based headings
 - Include working examples for both invocation styles

package/assets/skills/create-agnostic-skill/references/skill-template.md

@@ -28,9 +28,6 @@ Adjust based on complexity—not all sections are required:
 name: skill-name
 # Required: kebab-case, max 64 chars, must match directory name
 
-version: 1.0.0
-# Required: semver. Start new skills at 1.0.0.
-
 description: Use when [trigger condition]. [What it does as disambiguation keywords].
 # Required: Single line, ≤ 500 chars. Lead with "when to use" — this is the routing trigger.
 # Agents load ONLY name+description at startup to decide relevance.
@@ -38,9 +35,13 @@ description: Use when [trigger condition]. [What it does as disambiguation keywo
 # === Spec-optional fields (recognized by some providers) ===
 # license: Apache-2.0
 # compatibility: Requires Node.js 18+
-# metadata:
-#   author: my-org
-#   version: "1.0"
+
+metadata:
+  version: 1.0.0
+  # Required: semver. Start new skills at 1.0.0. The spec carries the version
+  # under `metadata`; a top-level `version:` is a deprecated alias that is read
+  # only when `metadata.version` is absent.
+  # author: my-org
 
 # === Claude Code / Cursor extension fields (ignored by Codex, safe to include) ===
 argument-hint: '[required-arg] [--optional-flag]'
@@ -187,9 +188,10 @@ Successful completion means:
 
 ## Versioning Guidance
 
-- Include `version:` in frontmatter for every skill and use semver (`MAJOR.MINOR.PATCH`).
+- Include `metadata.version` in frontmatter for every skill and use semver (`MAJOR.MINOR.PATCH`).
 - Start new skills at `1.0.0`.
 - Bump patch for fixes/clarifications, minor for backward-compatible behavior additions, major for breaking workflow/interface changes.
+- A top-level `version:` is the deprecated alias for the same value: it is read only when `metadata.version` is absent, and a skill that carries both with different values is reported as a conflict that validation rejects. `resolveSkillVersion` in `packages/cli/src/commands/shared/frontmatter.ts` owns that order.
 
 ## Cross-Provider Portability Notes
 

package/assets/skills/oat-explainer-kit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-explainer-kit
-version: 1.0.6
+version: 1.0.7
 description: Use when building project explainers or recaps from OAT configuration, state, and lifecycle artifacts.
 disable-model-invocation: false
 user-invocable: true
@@ -18,6 +18,7 @@ Adapt OAT project context into the versioned request consumed by the canonical
 - Resolve typed OAT configuration with source attribution.
 - Derive canonical project or repository output roots.
 - Bind OAT lifecycle artifacts to generic recipe source roles.
+- Probe recap seam availability before an unattended run is attempted.
 - Resolve project explainer and recap intent before invoking the core.
 - Resolve one provider-neutral set planner for unattended project recaps.
 - Require lifecycle callers to construct a brief-aware author seam.
@@ -79,6 +80,18 @@ source evidence, and medium rationale. The installed core continues reading
 `project-recap@1` for replay; the adapter never rewrites a retained request's
 recipe selector.
 
+Before an unattended `project-recap`, call
+`scripts/probe-recap-seams.mjs#probeRecapSeams` with the seam inputs you are
+about to pass. The probe is pure and checks all five required seams — author,
+fact critic, browser session, visual critic, and set planner — using the same
+rules `run.mjs` applies. `seams-unavailable` means no provider is configured
+for a required seam: pass the probe result to the intent resolver as
+`seamProbe`, which returns a recordable `skip` with source `capability_probe`
+and a warning. `seams-invalid` means a supplied seam violates a resolution
+rule: fail closed and report the configuration error; it is never a skip. When
+the probe returns `ok: true`, invoke the adapter with unchanged behavior, and
+treat any later failure as `failed` rather than as a skip.
+
 Before invocation, read `references/author-callback.md`. Unattended
 `project-recap` runs require exactly one provider-neutral set planner:
 in-process callers supply `planSet`, while JSON/CLI callers supply

package/assets/skills/oat-explainer-kit/references/config-contract.md

@@ -27,6 +27,18 @@ do not write config. Recipe, slug, fact-base path, output root, per-run art
 direction, and private wrapper lanes are invocation inputs rather than config
 keys and are rejected from the runtime config-override map.
 
+## Seams are invocation inputs, not configuration
+
+No supported key names an author, fact critic, browser session, visual critic,
+or set planner. Every seam is supplied per invocation as a callback or a module
+entry point, so seam availability is discovered by
+`scripts/probe-recap-seams.mjs#probeRecapSeams` against the inputs a caller is
+about to pass, not read from stored config. A host on which those inputs are
+absent has no configuration to correct: the probe reports `seams-unavailable`
+and the lifecycle caller records a `skip / capability_probe` recap intent. The
+`workflow.explainers.projectRecap` preference expresses whether a host _wants_
+a recap and cannot make an unavailable seam available.
+
 ## Source-sensitive paths
 
 A shared theme bundle path is repository-relative and must remain inside the