@open-agent-toolkit/cli 0.3.16 → 0.3.17

package/assets/agents/oat-phase-implementer.md

@@ -1,6 +1,6 @@
 ---
 name: oat-phase-implementer
-version: 1.1.6
+version: 1.1.7
 description: Implements one plan phase end-to-end, commits each task separately, self-checks between tasks, and handles bounded review fixes when resumed by oat-project-implement.
 tools: Read, Write, Edit, Bash, Grep, Glob, Task
 color: cyan
@@ -142,11 +142,23 @@ replaces every task and phase verification command below.
 Artifact and recovery-ledger bookkeeping commits must first resolve scope with
 `oat project scope "$PROJECT_PATH" --format value`. A `synced` project uses
 `oat project push` with the original bookkeeping message; other scopes keep the
-existing scoped `git add` and `git commit` commands. Scope resolution fails
+shared `oat internal commit-paths --identity "$COMMIT_IDENTITY" --message "$BOOKKEEPING_MESSAGE" -- "${BOOKKEEPING_OWNED_FILES[@]}"` command with exact producer-owned files. Set a unique operation identity before the first attempt and retain it and the literal file list through retries. Scope resolution fails
 closed. A nonzero project-push exit stops bookkeeping until the reported
 recovery is resolved and the push is retried. Planned code task commits such as
 `feat(pNN-tNN)` are unchanged.
 
+## Recovery Capacity Disclosure
+
+Report the supplied effective phase limit, prior durable usage, remaining
+capacity and reconciled pending attempt in phase progress and boundary reports.
+The root owns policy resolution and its source/override disclosure; use the
+brief and authoritative `state.md` ledger, never a guessed local counter.
+Capacity is not permission: failed-attempt terminality, eligibility/proof,
+exact-target continuity and repository authority still apply when allowance
+remains. Recovery events, warnings and route retries are distinct from reserved
+attempt usage. Do not interpret remaining capacity as continue-after-failure
+authority.
+
 ## Prevention and Post-Commit Recovery
 
 Prevention is the first recovery control. Before every planned task commit:
@@ -431,11 +443,19 @@ For every task:
    prevention does not consume a recovery attempt.
 6. Self-review requirements, behavioral tests, scope, and accidental changes.
 7. Fix any issue before committing.
-8. Create exactly one task commit using `commit_convention`.
+8. Create exactly one task commit using `commit_convention` through the shared
+   `oat internal commit-paths --identity "${ORIGINAL_REQUEST_ID}:${TASK_ID}" --message "$TASK_COMMIT_MESSAGE" -- "${TASK_OWNED_FILES[@]}"` primitive.
+   Before task edits, initialize `TASK_OWNED_FILES=()` and append each exact
+   created, modified or removed file at its producer, including both rename
+   sides. Retain the list and request/task identity for retries; never discover
+   ownership from the staged index or pass directory pathspecs. Verify the
+   command's help first; if missing, stop and update the CLI with no alternate
+   Git commit route. A blocked/failed result stops with its receipt/diagnostic.
    In a smoke child, source preflight owns repository-wide hook validation and
-   the child intentionally has no dependency install. Use
-   `git -c core.hooksPath=/dev/null commit ...` for that task commit; do not
-   mutate Git config or use `--no-verify`.
+   the child intentionally has no dependency install. Keep that launcher-owned
+   hook policy on the same primitive using per-process
+   `env GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=core.hooksPath GIT_CONFIG_VALUE_0=/dev/null oat internal commit-paths ...`;
+   do not mutate Git config or use `--no-verify`. Ordinary tasks keep hooks enabled.
 9. Verify:
    - HEAD is exactly one commit after `PRE_TASK_HEAD`;
    - the commit changes only files in the effective task boundary, which is

package/assets/agents/oat-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: oat-reviewer
-version: 1.2.10
+version: 1.2.11
 description: Unified reviewer for OAT projects - mode-aware verification of requirements/design alignment and code quality. Writes a review artifact to disk by default, or returns structured findings in-memory when dispatched in structured-output mode.
 tools: Read, Bash, Grep, Glob, Write, Task
 color: yellow
@@ -201,6 +201,49 @@ Strategy`, check whether the evidence matches the declared strategy, covers
    - Code that doesn't map to any requirement
    - If significant: add to High findings (potential scope creep)
 
+### Step 3.5: Probe Changed Consequential Boundaries
+
+For code reviews, inventory the changed trust, input, size and limit boundaries
+within the resolved review scope. For each boundary, name a credible failure
+and a focused probe with an independent expected outcome. Include assurance
+contracts expressed in executable guidance when that guidance is the changed
+public boundary. Do not manufacture a probe for unchanged behavior or a
+merely cosmetic edit.
+
+Run applicable focused probes within existing containment and write authority;
+preserve review independence and never mutate product files to repair a
+finding. Record the exact command, input or fixture/artifact provenance,
+expected categorical result, observed categorical result and any concrete
+execution limitation. A passing suite alone cannot substantiate a changed
+consequential guarantee. Inspect a failing control that exercises the claimed
+bad state and an accepted control that shows the valid state still works.
+
+When execution is unavailable, independently read and inspect implementer
+probe artifacts, exact commands, the recorded failing and accepted controls,
+and their correspondence to the reviewed code and immutable revision. Exact
+commands, artifact provenance and the limitation must be recorded. This may
+satisfy the evidence obligation when the controls credibly substantiate the
+guarantee; an unsupported implementer assertion is insufficient. A limitation
+by itself is not evidence of correctness.
+
+Missing consequential evidence requires a blocking finding under the existing
+severity model. Use the
+existing Critical/High severity model for the guarantee's risk, name the
+unresolved claim and smallest missing proof, and do not report that guarantee
+as accepted. Do not add a new severity, gate status or acceptance exception.
+
+| Evidence case                                                  | Review disposition                                                         |
+| -------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| Consequential guarantee, absent evidence                       | Blocking finding; guarantee unresolved                                     |
+| Inspected failing + accepted controls, reviewer cannot execute | Eligible evidence when independently verified; record execution limitation |
+| Unsupported implementer assertion                              | Blocking finding; assertion cannot substantiate the guarantee              |
+| Docs-only, no credible changed boundary                        | No manufactured probe obligation; use conservation review                  |
+
+Keep scope proportional: no new harness, broad testing campaign or
+model-efficacy claim. Docs-only changes with no credible changed boundary have
+no manufactured probe obligation. Preserve containment, independence,
+dispatch controls and the existing output schemas.
+
 ### Step 4: Verify Artifact Quality
 
 This step applies to **artifact reviews** only.
@@ -487,6 +530,10 @@ worker claims, and root-inline coverage}
 
 ## Verification Commands
 
+{Changed-boundary probes: exact commands, input/artifact provenance,
+expected/observed categorical outcomes and limitations; distinguish executed
+commands, suggested reruns and independently inspected evidence.}
+
 Run these to verify the implementation:
 
 ```bash
@@ -559,6 +606,9 @@ interface StructuredFindings {
 - `severity` MUST be one of the four enum values, mapped from the same Critical/High/Medium/Low buckets as Step 7.
 - `file` and `line` MUST both be set or both be `null`. A finding with a concrete location sets both; a reviewer-level finding without a specific location sets both to `null` and is conveyed via the `summary` / its own `body`, not as an inline location.
 - `id` prefixes follow the existing convention (`C`/`H`/`M`/`L`) and are stable within a single dispatch — no renumbering.
+- Use existing `summary` and finding bodies for compact probe results and limitations,
+  including independently inspected control provenance. Keep exact repeatable
+  commands in `verification_commands`; add no fields to `StructuredFindings`.
 - `verification_commands` carries what Step 8's "Verification Commands" section would have carried, as an array of command strings.
 
 Default behavior is unaffected: when `oat_output_mode` is absent or set to anything other than `structured`, follow Steps 8-9 and write the artifact exactly as before. Analysis reviews MUST honor `oat_output_mode: structured` whenever supplied by an auto-review loop: return the `StructuredFindings` object and write no artifact.

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.3.16"
+  "oatVersion": "0.3.17"
 }

package/assets/docs/contributing/documentation.md

@@ -52,6 +52,10 @@ Documentation should ship with the code it explains. This page covers the core d
 ## Authoring Expectations
 
 - Keep docs aligned with the current repo behavior and current command surface.
+- Give each Markdown or MDX page exactly one document H1. `pnpm docs:validate`
+  reports the file and count when a page has zero or multiple H1s. ATX and
+  Setext headings count, including headings inside blockquotes or lists;
+  frontmatter and fenced code do not.
 - Prefer cross-links over duplicated conceptual content.
 - Use `oat-docs-authoring` for targeted OAT/Fumadocs docs edits; it delegates
   universal page-quality guidance to `authoring-docs` and keeps local

package/assets/docs/contributing/skills.md

@@ -238,7 +238,9 @@ the bundle strips — requires bumping that skill's `metadata.version` in the
 same PR, one bump per changed skill in the final PR diff, even if the skill was
 edited multiple times on the branch. A change to a skill's `scripts/` or
 `references/` therefore needs the bump just as an edit to `SKILL.md` does: both
-ship to every `oat tools install` consumer. Changing a canonical agent role
+ship to every `oat tools install` consumer. Changes under `.agents/docs/`
+also require a bump for every skill that vendors the changed document through
+a file or directory symlink, because bundling follows those links. Changing a canonical agent role
 under `.agents/agents/*.md` requires bumping that file's top-level `version:`;
 agent roles deliberately keep the top-level field, so the gate accepts either
 declaration shape and never demands `metadata.version` of them. The gate reads

package/assets/docs/getting-started/bootstrap.md

@@ -50,7 +50,7 @@ After core initialization completes, `oat init` can enter an interactive guided
    - after placement is chosen, repository `AGENTS.md` guidance is a separate opt-in. Accepting creates the root file with the managed `OAT tools` section when it is absent, and appends that section to an existing file or contained symlink target that lacks it, with one append-only write. An existing file is never replaced: when the section exists but differs, OAT prints a repository-relative, copy-pasteable managed-block patch instead. Declining leaves `AGENTS.md` unchanged
    - installing `project-management` installs the capability only. Adopting it for this repository is a third, separate choice made with `oat pjm init` — see [Install vs. initialize](tool-packs.md#install-vs-initialize)
 2. **Local paths** — multi-select from default gitignored artifact paths (analysis, PR, reviews, ideas). Pre-existing paths are pre-checked; only new paths are added.
-3. **Documentation** — detect or enter docs metadata for the repo when documentation exists.
+3. **Documentation** — detect or enter docs metadata for the repo when documentation exists. For existing plain documentation, choose **Plain Markdown** in the manual tooling menu and enter its docs root. Guided setup saves `documentation.tooling: "markdown"` and the normalized `documentation.root` while preserving the other documentation/config settings. Fumadocs remains the manual menu default; MkDocs, Docusaurus, VitePress and Nextra remain available. This choice does not add automatic Markdown detection or scaffold a framework.
 4. **Provider sync** — sync provider project views via `oat sync --scope project`.
 5. **Summary** — reports what was configured: active providers, tool packs status, local paths added/existing, and provider sync status. Includes suggested next steps.
 

package/assets/docs/getting-started/index.md

@@ -55,10 +55,6 @@ view is the file or link that tool reads.
   available it falls back to the best available reviewer, which can be from the
   same family, and only records a warning. See
   [How independent the reviewer must be](../workflows/advanced/workflow-gates.md#how-independent-the-reviewer-must-be).
-- **Re-running `oat pjm init` removes remote settings.** It replaces the `pjm`
-  section of `.oat/config.json` and deletes any `pjm.remote` settings, so back
-  the file up first. See
-  [Remote Project Management](../workflows/backlog-and-planning/remote-project-management.md#prerequisite).
 - **Ad-hoc reviews run in the agent you invoke them in.** `oat-review-provide`
   cannot send a review to a different model; to get another model's review,
   run the skill in that model's coding tool. See

package/assets/docs/getting-started/tool-packs.md

@@ -1294,10 +1294,3 @@ that: later pack updates and `oat tools remove` leave them alone.
   loads; OAT does not resolve that for you.
 
 Installing any pack never gives OAT permission to publish to an issue tracker.
-
-> [!WARNING]
-> Rerunning `oat pjm init` or `oat pjm migrate --apply` deletes the `pjm.remote`
-> settings from `.oat/config.json`, so every remote setting silently returns to
-> its default. Afterwards, check `git diff .oat/config.json` and restore the
-> settings you need with `oat config set` (shared remote storage is restored
-> with `oat pjm remote storage shared`) before doing more remote work.

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

@@ -37,6 +37,47 @@ Each full command reference should include:
 
 The first practical expansion path is to keep improving the existing owners: [Docs App Commands](../docs-tooling/commands.md), [Provider Interop Commands](../provider-sync/commands.md), [Config and Local State](config-and-local-state.md), [Tool Packs](../getting-started/tool-packs.md), [Workflow & Projects](../workflows/projects/index.md), and [Repository PR Comment Analysis](repository-pr-comments.md).
 
+## Exact-path maintenance commits
+
+`oat internal commit-paths --identity <operation> --message <message> -- <files...>`
+commits an explicit list of owned files with enabled Git hooks. Include tracked
+removals and both names of a rename. Directories, untracked missing paths,
+unmerged entries and paths outside the repository are rejected; the command
+does not discover ownership or expand directory/glob pathspecs. Unrelated staged
+entries and worktree bytes remain preserved, including partially staged files.
+On success, owned index/worktree bytes match the hook-final commit.
+
+Choose a unique identity before the first attempt and retain the identity,
+message and literal path list for retries. With global `--json`, outcomes are
+`committed`, `already-matching`, `nothing`, `blocked` or `failed`.
+Success exits 0, `blocked` exits 1 and `failed` exits 2. A blocked result can
+name a verified commit whose owned-index publication still needs repair; do not
+claim settlement until a matching retry succeeds. Ignored receipts under the
+Git directory verify the exact identity, commit, tree and paths before reuse.
+Lock inspection/retry is bounded and never deletes another writer's lock.
+
+If the command is unavailable, stop and update the CLI; there is no broad Git
+commit fallback. Synced project artifacts still use `oat project push` after
+successful scope resolution. During development, run the current source entry:
+
+```bash
+pnpm --silent run cli -- internal commit-paths --identity "$COMMIT_IDENTITY" --message "$COMMIT_MESSAGE" -- "${OWNED_FILES[@]}"
+```
+
+A `dist` invocation requires a fresh build after the latest CLI source changes.
+
+For `oat backlog archive --json`, use the complete returned `affectedPaths`
+array as the archive-owned list, converting absolute paths to literal
+repository-relative files against the same repository root. Union per-item
+results, append an owned
+handoff's filesystem deletion, and format only existing supported text with
+the repository command before the helper commit. Include both old/new item
+paths and every ledger/index/reference output; never stage only the old
+missing name. A settled noop may return no paths and needs no commit. Pending
+Git retries include prior outputs only with HEAD ownership evidence, while
+no-Git retries report current-pass mutations. See [Backlog
+Lifecycle](../workflows/backlog-and-planning/backlog-lifecycle.md).
+
 ## Command Groups
 
 | Command group                                   | What it covers                                                                                                                                                                                                             | Go deeper                                                                                   |
@@ -155,7 +196,7 @@ Notable commands introduced in the current CLI surface:
 - `oat project list --json` - summary state for tracked projects under the configured projects root
 - `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 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 verifies the complete selected package and every immutable file byte, then atomically exports one self-contained `.oat/repo/reference/project-recaps/<YYYYMMDD-project-slug>.html` page before deleting the active project. The full original package remains in the archived project. JSON `projectRecapExport` identifies `runId`, `page.sourceRelativePath`, `page.originalSha256`, `page.exportedSha256`, `verifiedArtifactCount`, and the flat `exportRoot`. No tracked sidecar is created. Matching dated pages are adopted on retry; conflicting destinations, incomplete inventory coverage, stale bytes, path escapes, and recipe mismatches fail without removing the active project. Summary and PR links point to the tracked page. 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>` - 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/advanced/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.

package/assets/docs/reference/config-and-local-state.md

@@ -50,7 +50,7 @@ The command validates all inputs before creating the scaffold or writing an item
 
 - Validates the item's current `status` against the enum (`open | in_progress | closed | wont_do`); an out-of-enum value such as `done` is a hard error with a fix hint. Archiving is legal from any valid status — a `closed` item still in `items/` just gets its move finished.
 - For the default `closed` path, validates and trims a nonblank `--summary` before any file or index mutation. The `wont_do` path may omit the summary and completion-ledger entry.
-- Rewrites only the `status:` and `updated:` frontmatter lines (preserving any inline enum comment), then moves the item from `items/` to `archived/` with `git mv` inside a work tree, falling back to a plain rename (with a warning) outside git or if `git mv` fails.
+- Rewrites only the `status:` and `updated:` frontmatter lines (preserving any inline enum comment), then moves the item from `items/` to `archived/` with a filesystem rename. Archive leaves the Git index unchanged on initial archive and retry; callers own formatting, staging and committing the complete operation.
 - `closed` archives append a canonical newest-first `completed.md` entry (`YYYY-MM-DD — <id> — Title — summary`). `wont_do` archives append an entry only when `--summary` is provided. A missing `completed.md` is scaffolded from the starter template; a missing `## Completed Items` heading is scaffolded with a warning.
 - Rewrites inbound references to the moved file across Markdown under `.oat/repo/**` — tracked and untracked files that Git does not ignore, or every `.md` file outside a Git work tree — (external plans, decision records, other backlog items): relative links, `.oat/repo`-relative and repository-root path strings (including `oat_external_plan_sources` frontmatter) that resolve to `items/<id>.md` now point at `archived/<id>.md`, and the moved item's own relative links (inline links with any title form, and reference-style definitions; never footnotes or prose) are rebased when their target exists, so they keep resolving. An inline code span whose whole content is a path to the item (optionally with an `#anchor`), such as an external plan's `Source artifact or scope` citation, is rewritten; any other code span or fenced code block that mentions `items/<id>.md` is left as written with a warning, so recorded commands keep their meaning. Only references that resolve to the item's former `items/<id>.md` path change, and a link that already resolves to a different existing file is never repointed; URLs are never touched, and symlinked Markdown files are skipped so nothing outside `.oat/repo` is read or written. Each rewritten file is reported; a reference that names `items/<id>.md` but cannot be resolved is left untouched with a warning.
 - Regenerates the managed backlog index after the move.
@@ -77,11 +77,18 @@ On success the payload is the archive result object:
   "rewrittenReferences": [
     ".oat/repo/reference/external-plans/2026-07-05-example-plan.md"
   ],
+  "affectedPaths": [
+    "/repo/.oat/repo/pjm/backlog/items/BL-260705-example.md",
+    "/repo/.oat/repo/pjm/backlog/archived/BL-260705-example.md",
+    "/repo/.oat/repo/pjm/backlog/completed.md",
+    "/repo/.oat/repo/pjm/backlog/index.md",
+    "/repo/.oat/repo/reference/external-plans/2026-07-05-example-plan.md"
+  ],
   "warnings": []
 }
 ```
 
-`result` is `archived` or `noop` (already archived); `completedEntry` is `written`, `scaffolded`, or `skipped` (e.g. a `wont_do` archive without `--summary`); `movedTo` is the destination path or `null`; `rewrittenReferences` lists the repository-relative Markdown files whose references to the moved item were rewritten (on a no-op this lists anything the retried rewrite changed, and the human output prints each file on both paths). On an actionable failure the payload is `{ "result": "error", "id": "<id>", "message": "<why + fix>" }`.
+`result` is `archived` or `noop` (already archived); `completedEntry` is `written`, `scaffolded`, or `skipped` (e.g. a `wont_do` archive without `--summary`); `movedTo` is the destination path or `null`; `rewrittenReferences` lists the repository-relative Markdown files whose references to the moved item were rewritten (on a no-op this lists anything the retried rewrite changed, and the human output prints each file on both paths). `affectedPaths` is the deduplicated, normalized absolute operation path list: old item path (a tracked deletion), archived destination, index, completed ledger when written, and rewritten references. Retries report actual current-pass changes. In Git, a retry also reports prior uncommitted outputs only when HEAD still contains the old item and lacks the destination: the item move, a newly inserted ledger entry, a removed index entry, and references whose HEAD bytes still resolve to the old item. Existing archived links and unrelated edits in already-settled files are not claimed. Without Git history, retries report current-pass mutations only. A `wont_do` archive without an entry does not claim unrelated ledger changes. Capture each successful JSON result, deduplicate the union of `affectedPaths`, add any owned handoff filesystem deletion, and format existing affected text using the repository command. Pass that complete literal list to `oat internal commit-paths` with enabled hooks and a unique retained operation identity; stop on unavailable or blocked/failed helper, preserve unrelated staged/unstaged work, and never stage only the missing old path. An empty settled-noop list requires no commit. On an actionable failure the payload is `{ "result": "error", "id": "<id>", "message": "<why + fix>" }`.
 
 For full project-management repo-reference setup, use [`oat pjm init`](../getting-started/tool-packs.md#install-vs-initialize). It scaffolds the two-layer PJM surface (`pjm/current-state.md`, `pjm/roadmap.md`, `reference/decisions/`, and AGENTS guides) and delegates the backlog sub-surface to `oat backlog init`.
 
@@ -209,6 +216,8 @@ with `oat pjm init` as the recovery instead of treating absent
 `.oat/repo/pjm/` files as drift. See
 [Install vs. initialize](../getting-started/tool-packs.md#install-vs-initialize).
 
+`oat pjm init` and `oat pjm migrate` update only their adoption markers; they preserve `pjm.remote` and other existing, unowned configuration fields.
+
 Workflow automation preferences are also visible through `oat config` and can be set at local, shared, or user scope. Notable review-loop keys:
 
 - `workflow.autoArtifactReview.plan` - default-on bounded artifact review for generated `plan.md` files before implementation handoff

package/assets/docs/reference/project-artifacts.md

@@ -75,6 +75,34 @@ implementation-then-regression, static/build, or manual/visual. Static or build
 checks alone fit only changes that cannot affect runtime behavior; every
 behavioral change needs evidence that fails without the change.
 
+## Blockers in state.md
+
+`oat_blockers` accepts legacy reason strings and structured workflow records:
+
+```yaml
+oat_blockers:
+  - task_id: p01-t03
+    reason: Waiting on API contract
+    since: '2026-10-03'
+  - waiting on review
+```
+
+The control plane exposes `ProjectBlocker` as
+`string | { task_id: string; reason: string; since: string }`.
+`oat project status --json` preserves the three literal fields. Human status
+shows the task, reason and date for records, and the reason for legacy strings.
+`--field project.blockers` emits JSON; `--shell BLOCKERS=project.blockers`
+emits a shell-quoted JSON assignment. Select a single field such as
+`--field project.blockers.0.reason` to read a structured reason alone.
+
+Empty lists remain empty. Mixed lists retain entries in order, with
+legacy string normalization unchanged. Records missing any nonempty string
+field, nested lists and non-string scalars become diagnostic legacy strings:
+`Malformed blocker entry: <JSON>`. They remain visible to blocker checks and
+human output without `[object Object]` coercion. The parser also accepts
+JSON-encoded blocker lists for compatibility. These representations do not change workflow recommendations
+or the state refresh command's existing raw-frontmatter handling.
+
 ## Supporting artifacts
 
 - `summary.md`: generated by `oat-project-summary` — re-runnable, tracks its own state via frontmatter for incremental updates after revisions
@@ -99,9 +127,12 @@ different retention contracts:
   the tracked branch with the active project tree. It remains only in the local
   archived project.
 - A selected final `project-recap` is a durable completion record. Before a
-  shared project is removed, archive copies the complete selected run to
-  `.oat/repo/reference/project-recaps/<YYYYMMDD-project-slug>/`, verifies its
-  package inventory and hashes, and reports that tracked export path. Summary
+  shared project is removed, archive verifies the complete selected run and
+  exports one self-contained HTML page to
+  `.oat/repo/reference/project-recaps/<YYYYMMDD-project-slug>.html`. The
+  report identifies the run, original page/hash, exported hash, and verified
+  artifact count. The full original run, manifest, source, and QA evidence
+  remain in the archived project. Summary
   and PR links use this export, never the gitignored local archive. Lifecycle
   callers identify the selected project-relative run with:
 
@@ -110,12 +141,16 @@ different retention contracts:
     --project-recap-run explainers/<recap-slug>
   ```
 
-The archive exports at most one selected recap package. It rejects an existing
-dated destination and requires the selected path to stay under the project's
+The archive exports at most one selected recap page, with local assets embedded
+and unavailable project-source links removed. It adopts a byte-identical dated
+page on retry and refuses a differing existing destination without overwriting
+it. It creates no tracked manifest, fact-base, QA, or hash sidecar and requires the selected path to stay under the project's
 `explainers/` directory with a `project-recap` manifest. Verification checks
-the manifest's exact inventory, every declared file byte, the fact base and
-ledger, resolved theme, authored page, and QA result before deleting the active
-project.
+the manifest version's exact inventory and raw immutable file-byte hashes before
+deleting the active project. Direct CLI archive also accepts legacy v1 recaps:
+the v1 contract verifies canonical fact-base and resolved-theme JSON identities
+and build-record run/outcome agreement. The v2 contract additionally requires
+ledger and QA evidence coverage. Project completion selects v2 recap runs.
 
 Both `built` and `built-needs-review` are complete, archivable outcomes.
 `built-needs-review` means the browser rung was unavailable or found an issue;

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

@@ -213,9 +213,11 @@ does not require a project name or an active-project pointer.
 the `oat-codebase-mapper` subagent. A preflight checks whether background
 agents can write files and switches to a read-only fallback if they cannot.
 Needs an active OAT project: no. If a knowledge directory already exists,
-choose whether to refresh it or skip the run. Refresh first deletes every
-`.md` file in `.oat/repo/knowledge/`, hand-written files included, and then
-regenerates the set. Move any notes you want to keep before you choose it.
+choose whether to refresh it or skip the run. Refresh removes only regular
+Markdown files marked `oat_generated: true` and regenerates the eight named
+outputs. Hand-written notes survive; an unmarked expected-output collision
+stops the run before deletion so you can decide how to preserve it. Symlinked
+knowledge directories and output collisions are refused.
 
 **Example scenario:** A new teammate needs to understand which packages own
 the CLI, how shared configuration reaches applications, and which test
@@ -234,8 +236,9 @@ answered.
 knowledge files already exist. Otherwise it creates `.oat/repo/knowledge/`,
 starts a test subagent and then four `oat-codebase-mapper` subagents in the
 background, and writes the knowledge files. It then runs
-`git add .oat/repo/knowledge/` and `git commit` on your current branch with
-no further prompt; that commit also includes anything you had already staged.
+`oat internal commit-paths` on your current branch with the exact generated
+output/deletion paths and enabled hooks. Unrelated staged and unstaged work
+remains intact.
 Afterwards it records the run in `.oat/tracking.json` and regenerates the
 `.oat/state.md` dashboard with `oat state refresh`; those two files are not
 part of the commit. It does not push.
@@ -244,8 +247,7 @@ part of the commit. It does not push.
 `project-index.md`, `stack.md`, `architecture.md`, `structure.md`,
 `conventions.md`, `testing.md`, `integrations.md`, and `concerns.md`. The
 workflow also updates its tracking/dashboard surface and commits the
-knowledge output on the current branch (unstage unrelated changes first; the
-commit includes anything already staged). Despite its name, `project-index.md` describes the
+knowledge output on the current branch with exact path ownership. Despite its name, `project-index.md` describes the
 repository; it does not require a pre-existing OAT lifecycle project.
 
 **Next step:** Read the index and the concern or testing documents relevant

package/assets/docs/workflows/advanced/autonomy.md

@@ -51,6 +51,46 @@ repository config, user config, or any other durable artifact. A later
 interactive session therefore needs no autonomy cleanup and behaves
 interactively around the state the autonomous run left behind.
 
+## Kickoff limits and hard stops
+
+Kickoff reads the owning recovery, gate and dispatch contracts and reports the
+effective project default and each known phase limit, source/override, prior
+durable usage, remaining capacity and pending-attempt status. For a new project,
+phase values remain unresolved until planning supplies them; the report is
+refreshed before implementation and on resume.
+
+Phase recovery uses `oat_phase_recovery_policy` in `state.md`: a
+`phase_attempt_limits.<pNN>` override wins over `default_attempt_limit`, whose
+owning default is `10`. Limits are integers from `0` through `20`. Usage comes
+from the monotonic `phase_attempt_usage.<pNN>.used_attempts` ledger; remaining
+capacity is `max(0, effective limit - used_attempts)`. A reconciled pending
+reservation finishes that same attempt without another increment, even at the
+limit.
+
+These dry kickoff controls illustrate the unchanged policy, without launching
+a provider:
+
+- Default control: limit 10, used 3, remaining 7; source is the owning default
+  when the project has no override.
+- Phase override control: limit 2, used 1, remaining 1; source is
+  `phase_attempt_limits.p01: 2`, even when the project default is 10.
+- Zero limit: no new automatic attempt; a direction-required stop consumes no
+  attempt.
+
+Capacity is not permission. A failed attempt is terminal even with remaining capacity.
+A continue-after-failure policy remains a separate future choice. Route retries,
+review-fix rounds, gate `maxAttempts`, recovery events and reserved recovery
+attempts are separate counters. An elevated warning at three recovery events
+changes no limit and grants no permission.
+
+Kickoff also names the applicable owning hard stops: recovery eligibility or
+proof failure, new-attempt budget exhaustion, malformed ledger or unresolved
+pending attempt, exact-target/accepted-launch failure, blocking review policy,
+missing credentials, repository authority, unresolved product judgment,
+unauthorized destructive risk and inventory gaps. Each stop retains its owning
+contract and configured gate semantics; the report names evidence and the
+operator action needed to resume.
+
 ## Gate outcomes
 
 Every interactive lifecycle gate has one of two autonomous outcomes:

package/assets/docs/workflows/backlog-and-planning/backlog-lifecycle.md

@@ -21,15 +21,6 @@ mutations write nothing and return an error naming the repository path and
 `oat pjm init` as the recovery. Check the current state with
 `oat pjm doctor --json` and read its `adoption.state` field.
 
-> [!WARNING]
-> Running `oat pjm init` again, or running `oat pjm migrate --apply`,
-> currently replaces the `pjm` section of `.oat/config.json` and deletes any
-> `pjm.remote` settings (your remote project management policy). Several
-> skills below tell you to rerun `oat pjm init` to repair a partial setup or
-> missing index markers. Before you do, back up `.oat/config.json`;
-> afterwards, check `git diff .oat/config.json` and restore `pjm.remote` if
-> it was removed.
-
 ## Where a backlog item lives
 
 - **`items/<id>.md`** - active, file-backed records. Each carries frontmatter with a `status` and an `updated` timestamp.
@@ -64,12 +55,24 @@ A single `oat backlog archive` run performs the whole close-out so its parts can
 
 1. Sets the terminal `status` (`closed` by default, `wont_do` with `--wont-do`) and stamps `updated`.
 2. Validates and trims a nonblank `--summary` before mutating a `closed` item, then appends its canonical (standard OAT format) newest-first `completed.md` entry. `wont_do` items may omit the summary and get an entry only when one is provided.
-3. Moves `items/<id>.md` into `archived/` — with `git mv` inside a work tree, or a plain rename outside git.
+3. Moves `items/<id>.md` into `archived/` with a filesystem rename, leaving Git staging to the caller.
 4. Rewrites inbound references to the moved file across Markdown under `.oat/repo/**` (tracked and untracked files that Git does not ignore; a code span whose whole content is the item's path, such as an external plan's source citation, is rewritten, while other code spans and fenced code are left as written with a warning) — external plans, decision records, and other backlog items — so no link dangles at `items/<id>.md`, and reports each rewritten file. A reference it cannot resolve is left alone with a warning.
 5. Regenerates the managed backlog index.
 
 The command is safe to re-run: an item already in `archived/` produces a no-op warning and only retries the reference rewrite and index regeneration, so an interrupted close-out finishes on the next run. A missing closed-item summary or an out-of-enum current status (for example a hand-set `done`) is a hard error before mutation and includes recovery guidance. See the [command reference](../../reference/config-and-local-state.md#oat-backlog-archive) for exit codes and the `--json` payload.
 
+The archive result includes normalized absolute `affectedPaths` for the whole
+operation. Capture `--json` for each item, union the lists, and include owned
+handoff deletions. Format existing affected text with the repository's
+formatter, then use `oat internal commit-paths` with a unique retained identity
+and the exact list. Include the old tracked item deletion and new destination
+as well as ledger/index/references; staging only the old missing path fails.
+Hooks remain enabled, and unrelated staged/unstaged work stays intact. Verify
+helper availability first, stop on failure, and follow its retry diagnostics.
+Settled noops claim only actual repairs; pending Git retries recover earlier
+operation outputs from HEAD evidence. See [exact-path maintenance
+commits](../../reference/cli-reference.md#exact-path-maintenance-commits).
+
 ## Catching lifecycle drift
 
 The manual close-out this command replaces is exactly where the two motivating repos drifted — an item was marked closed in frontmatter and summarized in `completed.md` but never moved to `archived/`, and one shipped with the invalid status `done`. `oat pjm doctor` (and therefore `oat doctor`, which aggregates the `pjm:*` checks) now surfaces that drift:
@@ -101,8 +104,7 @@ work. Like every PJM skill that writes files on this page, it refuses to
 write until the repository has adopted PJM with `oat pjm init`. The skill
 first runs `oat pjm doctor --json` and inspects `adoption.state`; only
 `declared` or `inferred-legacy` permits writes. For `none` or
-`partial-initialization` it stops and tells you to run `oat pjm init` (read
-the [warning about rerunning it](#adoption-comes-first) first). Installed
+`partial-initialization` it stops and tells you to run `oat pjm init`. Installed
 tools alone do not establish adoption. No active OAT project is required.
 
 **Example scenario:** A support incident exposed uncertainty about duplicate
@@ -145,7 +147,7 @@ the living review.
 `oat pjm doctor --json` before writes, and accessible backlog items. A
 roadmap is optional alignment evidence; an active OAT project is not
 required. The skill stops and tells you to run `oat pjm init` if adoption
-is absent or partial (see the [warning about rerunning it](#adoption-comes-first)).
+is absent or partial.
 
 **Example scenario:** Your team has time for one maintenance initiative, but
 the backlog mixes isolated fixes with work blocked on shared infrastructure.
@@ -211,8 +213,7 @@ Context, Decision, and Consequences sections and reruns
 `oat decision regenerate-index` if it changed the status or title. Its
 workflow has no commit or push step. If the decision index markers are
 missing, it stops and tells you to repair the repository with
-`oat pjm init`; that is a rerun, so read the
-[warning about rerunning it](#adoption-comes-first) first.
+`oat pjm init`.
 
 **Next step:** Review the record and link relevant work to it. If later
 evidence changes the choice, preserve history through the appropriate
@@ -249,9 +250,7 @@ sanitized description of which connector or provider CLI it can use for
 that tracker. The skill gathers that evidence for you.
 
 **Prerequisites:** PJM adoption verified by `oat pjm doctor --json` (the
-skill stops and points you to `oat pjm init` otherwise; rerunning init
-deletes `pjm.remote`, as the [warning above](#adoption-comes-first)
-explains), applicable local
+skill stops and points you to `oat pjm init` otherwise), applicable local
 policy, and an available host capability matching the provider, operation,
 and exact account, workspace, site, or repository. No active OAT project is
 required. Remote mutation authority defaults to `read-only`, so `publish`
@@ -336,12 +335,14 @@ sanity check distinguishes valid active paths from retired references.
 the curated overview, and backlog item files under `.oat/repo/pjm/` as it
 judges applicable, with no separate approval step. It runs
 `oat backlog archive` for completed items, which moves each item file into
-`archived/` (with `git mv` inside a Git work tree), and it creates decision
-records with `oat decision new`. Its workflow has no commit or push step,
-so review the working-tree diff afterwards. If the backlog index markers
-are missing, it stops and tells you to repair the repository with
-`oat pjm init`; that is a rerun, so read the
-[warning about rerunning it](#adoption-comes-first) first.
+`archived/` with a filesystem rename, and it creates decision
+records with `oat decision new`. It automatically commits the exact archive
+close-out paths and any owned kickoff handoff deletion with hooks enabled.
+Other reference edits remain uncommitted, and the workflow has no push step,
+so review the close-out commit and remaining working-tree diff afterwards.
+If the backlog index markers are missing, it stops and tells you to repair
+the repository with
+`oat pjm init`.
 
 **Next step:** Review the changes against the implementation evidence and
 rerun diagnostics for lifecycle consistency. Start deferred work separately;

package/assets/docs/workflows/backlog-and-planning/remote-project-management.md

@@ -26,13 +26,6 @@ oat pjm doctor --json
 Continue only when `adoption.state` is `declared` or `inferred-legacy`. Run
 `oat pjm init` first when adoption is absent or only partially initialized.
 
-> [!WARNING]
-> Running `oat pjm init` again, or running `oat pjm migrate --apply`,
-> currently replaces the `pjm` section of `.oat/config.json` and deletes any
-> `pjm.remote` settings, which hold the remote policy described below. Before
-> you rerun either command, back up `.oat/config.json`. Afterwards, run
-> `git diff .oat/config.json` and restore `pjm.remote` if it was removed.
-
 ## Lifecycle operations
 
 The command family is `oat pjm remote`:

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

@@ -90,13 +90,8 @@ Good to know:
   (shared scope), pushed to a project ref (synced scope, the default on a
   fresh install), or kept on your machine (local scope).
 
-> [!WARNING]
-> Backlog items need project management (PJM, OAT's file-backed backlog,
-> roadmap, and decision records) adopted with `oat pjm init`. Run it once.
-> Running `oat pjm init` again, or running `oat pjm migrate --apply`,
-> currently deletes any `pjm.remote` settings from `.oat/config.json`. If
-> you rerun either command, check `git diff .oat/config.json` afterwards and
-> restore `pjm.remote` if it was removed.
+Backlog items need project management (PJM, OAT's file-backed backlog,
+roadmap, and decision records) adopted with `oat pjm init`. Run it once.
 
 1. Quick capture: `oat-idea-scratchpad` to review or capture idea seeds
 2. Start brainstorming: `oat-idea-new` (scaffolds directory, then invokes `oat-idea-ideate`)