@open-agent-toolkit/cli 0.3.15 → 0.3.17

package/assets/docs/workflows/projects/reviews/index.md

@@ -166,7 +166,7 @@ is evaluated.
 - **Passing gate** (no findings at or above the threshold): receive runs a non-pausing **judgment sweep**. It makes a per-finding decision for each Medium/Low — defer to final review (the default, recorded so [final review](#phase-and-final-review) resurfaces it), address now (only for small, contained, low-risk fixes, which do **not** re-trigger the standard reviewer or re-gate the phase), or reject with rationale — then archives the artifact. Address-now is an exception, not the norm; if such a fix reveals a Critical/High concern it escalates to the blocking path.
 - **Blocking gate** (one or more findings at or above the threshold): receive converts findings to fix tasks and implementation re-runs the standard reviewer and the gate for the phase. These block → fix → re-gate rounds are bounded by `oat_orchestration_retry_limit` (default `2`); exhausting the bound stops a sequential run or excludes the phase in a parallel group, matching the standard fix loop's terminal handling.
 
-Gate-originated artifacts (`oat_review_invocation: gate`) are excluded from the same-scope review-cycle cap in `oat-project-review-receive`. The cap measures failed fix cycles of the standard review loop, so counting gate artifacts would trip it on artifact volume rather than real fix rounds.
+Gate-originated artifacts (`oat_review_invocation: gate`) and saved complexity reports are excluded from the same-scope review-cycle cap in `oat-project-review-receive`. The cap measures failed fix cycles of the standard review loop, so counting gate artifacts would trip it on artifact volume rather than real fix rounds.
 
 When a phase is re-gated multiple times, each round produces a distinct review artifact — filenames and `oat_generated_at` are seconds-precision, so rounds never collide and `oat review latest` resolves the newest. An orchestrator should know a gate finished from the `oat --json gate review` result envelope on process exit (`status`, `runId`, `generatedAt`), not by watching the `reviews/` directory or the provider's log; see [Gate completion signal](../../advanced/workflow-gates.md#gate-completion-signal).
 
@@ -226,6 +226,68 @@ Final review `passed` gate requires:
 - Deferred Medium findings resurfaced and explicitly dispositioned.
 - Low findings explicitly dispositioned (after plain-language explanation).
 
+## Complexity review at budget exhaustion
+
+When a review or gate budget runs out, another round of the same review is
+unlikely to converge. Before asking the operator how to proceed, the root
+dispatches one complexity review and shows it together with the reasons the
+loop stopped. The review asks whether the reviewed work, and the machinery the
+findings keep demanding, earns its cost against the contract. It is not
+another correctness review.
+
+It runs at every budget-exhaustion point:
+
+| Exhaustion point                                              | Owning skill                 |
+| ------------------------------------------------------------- | ---------------------------- |
+| Phase review fix rounds reach `oat_orchestration_retry_limit` | `oat-project-implement`      |
+| A phase review gate still blocks at that limit                | `oat-project-implement`      |
+| The final review reaches its three-cycle cap                  | `oat-project-implement`      |
+| The implementation exit gate ends in `block` at `maxAttempts` | `oat-project-implement`      |
+| A review scope reaches the three-cycle cap                    | `oat-project-review-receive` |
+| The quick-start plan gate ends in `block` at `maxAttempts`    | `oat-project-quick-start`    |
+
+A single `prompt` failure, a `warn` outcome, and launch or transport failures
+that consume no attempt are not budget exhaustions. The operator can ask for
+the same review at any other time; there is no automatic early trigger.
+
+How it runs:
+
+- **Probe.** OAT looks for an installed `complexity-review` skill in
+  `~/.agents/skills`, then `~/.claude/skills`, then the repository's
+  `.agents/skills`. When one is found, the reviewer follows it as a document,
+  without asking questions. Otherwise the reviewer follows a condensed method
+  bundled with the lifecycle skills: restate the contract from independent
+  sources, establish the simplest viable baseline, inventory the machinery,
+  apply the deletion test, build a ledger (Item, Claimed value, Evidence,
+  Lifecycle cost, Recommendation), and give a verdict of
+  `Deletion-rule compliant`, `Partially compliant`, or `Not compliant`.
+- **Read-only reviewer.** One reviewer-class subagent at the resolved reviewer
+  ceiling reads the reviewed target, the contract sources (backlog items,
+  discovery, spec, design, and decision records), and every review artifact of
+  the exhausted loop. It writes nothing and returns its report to the root.
+  Outside an implement run (quick-start, or a standalone review-receive), the
+  root loads the project dispatch skills and resolves the reviewer ceiling with
+  `oat project dispatch-ceiling resolve --role reviewer`.
+- **One review per exhausted loop.** A saved report for the scope that is newer
+  than every review artifact of that scope is reused, so re-entering a capped
+  receive does not dispatch a second review.
+- **OAT additions.** The report marks rows only the operator can settle as
+  `REQUIRES-OPERATOR`, classifies each open finding as an accepted
+  requirement, a regression, or new hardening, lists the findings a
+  simplification would dissolve, and recommends a disposition: extra cycles,
+  proceed with override, corrective revision, or **simplify**.
+- **Decision message.** The root saves the report as
+  `reviews/archived/complexity-<scope>-<timestamp>.md` (outside the top-level
+  `reviews/` directory, so routers never mistake it for an unprocessed review,
+  and outside the review-cycle count), shows one decision message with the
+  stop reasons, verdict, dissolvable findings, and operator questions, and
+  records the operator's choice with the report path in `implementation.md`.
+
+Agents never select the disposition, including the recommended one. Under
+`OAT_AUTONOMOUS=1` the run stops at its boundary report, which carries the same
+content. The condensed method adapts the operator's `complexity-review` skill
+from `tkstang/skills`; see `NOTICES.md`.
+
 ## Subagent Compatibility
 
 `oat-project-review-provide` uses provider-aware subagent dispatch when available. This outer dispatch starts the primary `oat-reviewer`; it is separate from any optional reconnaissance workers that the reviewer may launch after resolving its authoritative review scope:

package/assets/docs/workflows/projects/reviews/review-flavors.md

@@ -36,6 +36,14 @@ for the deep review request/receive mechanics.
   `oat-project-dispatch-subagents` lifecycle-role table, and the OAT design
   decision that defined these four flavors.
 
+Reviews of changed trust or input-limit boundaries require focused probes for
+credible failure modes. Record the failure and accepted controls, their source,
+and any concrete execution limitations. Independently verified implementer
+evidence can satisfy the obligation when the reviewer cannot run the probe;
+unsupported consequential guarantees remain blocking findings. Keep probes
+proportional to the changed boundary and preserve review independence and
+containment.
+
 ## Flow map
 
 === "Diagram"

package/assets/docs/workflows/waves/wave-workflows.md

@@ -113,7 +113,9 @@ for your approval before the first wave starts. When the final wave merges,
 the skill stops at one human-gated checkpoint that asks whether to run the
 deferred completion tail (archive, S3 upload, and active-project clear) for
 every wave's wrapper project; autonomous runs never answer that question
-themselves.
+themselves. On yes, it runs `oat-project-complete-auto` once in batch mode;
+a wrapper the companion refuses keeps its deferral, and the report names its
+next step (usually completing it with `oat-project-complete`).
 
 **Example scenario:** Twelve reviewed external plans include a shared API
 foundation, client changes, and independent documentation work. Use `new` to
@@ -173,7 +175,10 @@ closeout it archives the wave's backlog items with `oat backlog archive` and
 runs the configured closeout sequence (which can open the PR). It then stops
 once at a HiLL (human-in-the-loop) approval checkpoint before running the
 `oat-project-complete` process, including project archive and any configured
-S3 upload. After you merge the wave, it resets the working branch, deletes
+S3 upload. Under autonomous execution it runs that process through the
+`oat-project-complete-auto` companion, which needs
+`workflow.autonomousComplete: true` and records a completion-before-merge
+exception for the open wave PR. After you merge the wave, it resets the working branch, deletes
 stale phase branches, and runs `oat-wave-program wave-close`. Merging the wave
 into `main` stays your decision.
 
@@ -192,7 +197,10 @@ presented as proof the integrated tree passes.
 
 Closeout writes end-of-run synthesis before archive work. Autonomous execution
 can defer a wrapper's archive tail to program close only with an explicit
-ledger disposition. That deferral does not satisfy the full completion tail.
+ledger disposition, and only when the companion refuses for a deferrable
+reason (the opt-in is off, the PR precondition is unmet, or a completion
+question has no recorded answer); any other refusal stops closeout at a
+boundary. That deferral does not satisfy the full completion tail.
 Source-plan requirements remain intact even when live drift changes a mechanism.
 
 **Next step:** Follow the wave's reported review and merge boundary. After the

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.3.15",
-  "docs-config": "0.3.15",
-  "docs-theme": "0.3.15",
-  "docs-transforms": "0.3.15"
+  "cli": "0.3.17",
+  "docs-config": "0.3.17",
+  "docs-theme": "0.3.17",
+  "docs-transforms": "0.3.17"
 }

package/assets/skills/oat-agent-instructions-apply/SKILL.md

@@ -5,13 +5,17 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash(git:*), Bash(gh:*), Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.7.3
+  version: 1.7.4
 ---
 
 # Agent Instructions Apply
 
 Generate or update agent instruction files based on an analysis artifact, with user review and PR-based workflow.
 
+## Hook-safe exact-path commits
+
+Before a parent-branch commit, verify `oat internal commit-paths --help` succeeds. If unavailable, stop and update the OAT CLI; never fall back to a staged-index or pathspec-only commit. Set `COMMIT_IDENTITY` to a unique operation/artifact identity before the first attempt and retain it for every retry; use a new identity for a new operation. Pass only the exact produced file list, including tracked removals and both names of a rename. A blocked/failed result stops the workflow; retain its receipt and follow its diagnostics. Hooks remain enabled. Synced project artifacts continue through `oat project push`.
+
 ## Prerequisites
 
 - Git repository with a recent analysis artifact in `.oat/repo/analysis/`.
@@ -317,6 +321,12 @@ If branch creation fails (e.g., uncommitted changes), ask the user to resolve an
 
 ### Step 5: Generate/Update Instruction Files
 
+Before the first approved write, initialize `OWNED_OUTPUT_FILES=()`. Append
+each exact successfully created, modified or removed path at that write,
+including both names of a rename and any generated navigation/index file this
+step actually changes. Retain the complete list through verification and commit
+retries; do not substitute a directory or staged-index diff.
+
 For each approved recommendation, in the order from Step 2:
 
 - When the companion bundle exists, load the approved recommendation's manifest entry and matching pack before
@@ -382,11 +392,11 @@ not from repo-root `.agents/docs/`.
 **Stage and commit:**
 
 ```bash
-git add {list of generated/updated files}
-git commit -m "chore: update agent instruction files
+OWNED_COMMIT_PATHS=("${OWNED_OUTPUT_FILES[@]}")
+oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-agent-instructions-apply:1" --message "chore: update agent instruction files
 
 Generated by oat-agent-instructions-apply from analysis artifact.
-Files: {count} created, {count} updated."
+Files: {count} created, {count} updated." -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
 ```
 
 **Offer to open a PR:**

package/assets/skills/oat-brainstorm/SKILL.md

@@ -5,13 +5,17 @@ disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.3.7
+  version: 1.3.8
 ---
 
 # Brainstorm
 
 Project-independent brainstorming dispatcher. Owns the explicit activation gate (see `## Activation Contract`), the Superpowers-style conversational cadence, the visual-need assessment and conditional visual-companion offer, the destination identification, and the per-destination handoff to existing OAT skills.
 
+## Hook-safe exact-path commits
+
+Before a parent-branch commit, verify `oat internal commit-paths --help` succeeds. If unavailable, stop and update the OAT CLI; never fall back to a staged-index or pathspec-only commit. Set `COMMIT_IDENTITY` to a unique operation/artifact identity before the first attempt and retain it for every retry; use a new identity for a new operation. Pass only the exact produced file list, including tracked removals and both names of a rename. A blocked/failed result stops the workflow; retain its receipt and follow its diagnostics. Hooks remain enabled. Synced project artifacts continue through `oat project push`.
+
 ## Activation Contract
 
 Brainstorm-quality response (options, tradeoffs, open questions, no premature implementation, no destination guess) is the **default** for any exploratory phrasing without a named destination. Mode assertion + banner is **reserved** for explicit hard-activation triggers or user confirmation. The banner is a workflow commitment marker, not a quality marker.
@@ -662,8 +666,8 @@ beside another dirty project file must take Step 4.
      FOLD_BACK_PUSH=$(oat project push "$ACTIVE_PROJECT" --message "chore(oat): integrate brainstorm into <artifact-basename> for <project-name>" --json) || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
      FOLD_BACK_COMMIT_SHA=$(parse_synced_push_receipt "$FOLD_BACK_PUSH") || { printf '%s\n' "$FOLD_BACK_PUSH" >&2; echo "Recovery: run oat project pull \"$ACTIVE_PROJECT\", resolve conflicts, then retry this push." >&2; exit 1; }
    else
-     git add -- "$ARTIFACT_PATH"
-     git commit -m "chore(oat): integrate brainstorm into <artifact-basename> for <project-name>"
+     OWNED_COMMIT_PATHS=("$ARTIFACT_PATH")
+     oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-brainstorm:1" --message "chore(oat): integrate brainstorm into <artifact-basename> for <project-name>" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
      FOLD_BACK_COMMIT_SHA=$(git rev-parse HEAD)
    fi
    ```
@@ -690,8 +694,8 @@ failures remain fail-closed.
     CURRENT_ARTIFACT_PUSH=$(oat project push "$ACTIVE_PROJECT" --message "$CURRENT_ARTIFACT_SUBJECT" --json) || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
     CURRENT_ARTIFACT_COMMIT_SHA=$(parse_synced_push_receipt "$CURRENT_ARTIFACT_PUSH") || { printf '%s\n' "$CURRENT_ARTIFACT_PUSH" >&2; echo "Recovery: run oat project pull \"$ACTIVE_PROJECT\", resolve conflicts, then retry this push." >&2; exit 1; }
   else
-    git add -- "$ARTIFACT_PATH"
-    git commit --only -m "$CURRENT_ARTIFACT_SUBJECT" -- "$ARTIFACT_PATH"
+    OWNED_COMMIT_PATHS=("$ARTIFACT_PATH")
+    oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-brainstorm:2" --message "$CURRENT_ARTIFACT_SUBJECT" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
     CURRENT_ARTIFACT_COMMIT_SHA=$(git rev-parse HEAD)
   fi
   ```
@@ -705,8 +709,8 @@ failures remain fail-closed.
     FOLD_BACK_PUSH=$(oat project push "$ACTIVE_PROJECT" --message "chore(oat): integrate brainstorm into <artifact-basename> for <project-name>" --json) || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
     FOLD_BACK_COMMIT_SHA=$(parse_synced_push_receipt "$FOLD_BACK_PUSH") || { printf '%s\n' "$FOLD_BACK_PUSH" >&2; echo "Recovery: run oat project pull \"$ACTIVE_PROJECT\", resolve conflicts, then retry this push." >&2; exit 1; }
   else
-    git add -- "$ARTIFACT_PATH"
-    git commit --only -m "chore(oat): integrate brainstorm into <artifact-basename> for <project-name>" -- "$ARTIFACT_PATH"
+    OWNED_COMMIT_PATHS=("$ARTIFACT_PATH")
+    oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-brainstorm:3" --message "chore(oat): integrate brainstorm into <artifact-basename> for <project-name>" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
     FOLD_BACK_COMMIT_SHA=$(git rev-parse HEAD)
   fi
   ```
@@ -722,8 +726,8 @@ failures remain fail-closed.
     MIXED_FOLD_BACK_PUSH=$(oat project push "$ACTIVE_PROJECT" --message "chore(oat): integrate brainstorm + prior edits into <artifact-basename> for <project-name>" --json) || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
     FOLD_BACK_COMMIT_SHA=$(parse_synced_push_receipt "$MIXED_FOLD_BACK_PUSH") || { printf '%s\n' "$MIXED_FOLD_BACK_PUSH" >&2; echo "Recovery: run oat project pull \"$ACTIVE_PROJECT\", resolve conflicts, then retry this push." >&2; exit 1; }
   else
-    git add -- "$ARTIFACT_PATH"
-    git commit --only -m "chore(oat): integrate brainstorm + prior edits into <artifact-basename> for <project-name>" -- "$ARTIFACT_PATH"
+    OWNED_COMMIT_PATHS=("$ARTIFACT_PATH")
+    oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-brainstorm:4" --message "chore(oat): integrate brainstorm + prior edits into <artifact-basename> for <project-name>" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
     FOLD_BACK_COMMIT_SHA=$(git rev-parse HEAD)
   fi
   ```
@@ -773,7 +777,7 @@ The filename was confirmed at step 8 (default `YYYY-MM-DD-<topic>.md`). Resolve
 
 If `<ACTIVE_PROJECT>/brainstorming/` does not exist, create it (`mkdir -p`). The `brainstorming/` subdirectory is parallel to existing `pr/` and `reviews/` subdirectories — explicit purpose, naturally discoverable.
 
-Render `${SKILL_DIR}/templates/brainstorm-doc.md` (resolve `${SKILL_DIR}` per the rule in step 3) with the synthesized payload (same shape as the doc-to-path destination) and write to the resolved path.
+Set `REFERENCE_PATH` to the exact resolved file path before writing. Render `${SKILL_DIR}/templates/brainstorm-doc.md` (resolve `${SKILL_DIR}` per the rule in step 3) with the synthesized payload (same shape as the doc-to-path destination) and write to `REFERENCE_PATH`. Retain that produced filename for commit/retry.
 
 After writing, persist the file with the same fail-closed scope guard:
 
@@ -784,13 +788,13 @@ if [ "$PROJECT_SCOPE" = "synced" ]; then
   REFERENCE_PUSH=$(oat project push "$ACTIVE_PROJECT" --message "chore(oat): capture brainstorming reference for <project-name>" --json) || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
   REFERENCE_COMMIT_SHA=$(parse_synced_push_receipt "$REFERENCE_PUSH") || { printf '%s\n' "$REFERENCE_PUSH" >&2; echo "Recovery: run oat project pull \"$ACTIVE_PROJECT\", resolve conflicts, then retry this push." >&2; exit 1; }
 else
-  git add -- "<active-project-relative-path>"
-  git commit -m "chore(oat): capture brainstorming reference for <project-name>"
+  OWNED_COMMIT_PATHS=("$REFERENCE_PATH")
+  oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-brainstorm:5" --message "chore(oat): capture brainstorming reference for <project-name>" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
   REFERENCE_COMMIT_SHA=$(git rev-parse HEAD)
 fi
 ```
 
-For shared/local scope, use only `git add -- <path>` so unrelated working-tree changes are not swept into the commit, then capture `git rev-parse --short HEAD`. For synced scope, use the validated push receipt SHA and never stage the artifact on the parent branch. Report the resulting SHA alongside the absolute path written, then end mode assertion.
+For shared/local scope, commit only the exact produced path through `oat internal commit-paths` with the retained operation identity, stop on a nonzero result, then capture `git rev-parse --short HEAD`. For synced scope, use the validated push receipt SHA and never stage the artifact on the parent branch. Report the resulting SHA alongside the absolute path written, then end mode assertion.
 
 For synced projects, the preceding short-hash sentence is superseded by the
 full `REFERENCE_COMMIT_SHA` returned from `oat project push --json`; no parent

package/assets/skills/oat-docs-apply/SKILL.md

@@ -5,13 +5,17 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash(git:*), Bash(gh:*), Glob, Grep, AskUserQuestion
 metadata:
-  version: '1.4.2'
+  version: '1.4.3'
 ---
 
 # Docs Apply
 
 Generate or update documentation files from a docs analysis artifact, with explicit approval and branch-based workflow.
 
+## Hook-safe exact-path commits
+
+Before a parent-branch commit, verify `oat internal commit-paths --help` succeeds. If unavailable, stop and update the OAT CLI; never fall back to a staged-index or pathspec-only commit. Set `COMMIT_IDENTITY` to a unique operation/artifact identity before the first attempt and retain it for every retry; use a new identity for a new operation. Pass only the exact produced file list, including tracked removals and both names of a rename. A blocked/failed result stops the workflow; retain its receipt and follow its diagnostics. Hooks remain enabled. Synced project artifacts continue through `oat project push`.
+
 ## Prerequisites
 
 - A recent docs analysis artifact in `.oat/repo/analysis/`.
@@ -196,6 +200,12 @@ If branch creation fails because of unrelated local changes, ask the user to res
 
 ### Step 4: Apply Approved Changes
 
+Before the first approved write, initialize `OWNED_OUTPUT_FILES=()`. Append
+each exact successfully created, modified or removed path at that write,
+including both names of a rename and any generated navigation/index file this
+step actually changes. Retain the complete list through verification and commit
+retries; do not substitute a directory or staged-index diff.
+
 For each approved recommendation:
 
 1. Read only the affected docs files and the evidence sources cited by the artifact.
@@ -245,8 +255,8 @@ If no docs app exists yet, use file-level verification and confirm the structura
 Commit the approved changes:
 
 ```bash
-git add {approved-files}
-git commit -m "docs: apply approved docs recommendations"
+OWNED_COMMIT_PATHS=("${OWNED_OUTPUT_FILES[@]}")
+oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-docs-apply:1" --message "docs: apply approved docs recommendations" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
 ```
 
 **Offer to open a PR:**

package/assets/skills/oat-doctor/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Bash, Glob, Grep, AskUserQuestion
 metadata:
-  version: 2.0.3
+  version: 2.0.4
 ---
 
 # OAT Doctor
@@ -223,6 +223,16 @@ State the adoption state (`declared`, `inferred-legacy`, `partial-initialization
 | `pjm:remote_schema`, `pjm:remote_binding_ids`, `pjm:remote_metadata_state`, `pjm:remote_storage_content`, `pjm:remote_policy`, `pjm:remote_concurrent_intents`, `pjm:remote_operations`, `pjm:remote_retention`, `pjm:remote_host_capability` | emitted only when a remote binding is adopted: `oat-pjm-remote` (reconcile or refresh) and `workflows/backlog-and-planning/remote-project-management.md`                                          |
 | any other `pjm:*` name                                                                                                                                                                                                                        | `info` with the check's message; no fix path is invented                                                                                                                                          |
 
+When applying a backlog close-out fix, use `oat backlog archive <id> --summary
+"outcome" --json` (or the agreed `--wont-do` outcome). Capture its complete
+`affectedPaths`, append only an owned handoff's filesystem deletion, format
+existing affected text with the repository command, and commit the exact paths
+via `oat internal commit-paths` with a unique retained identity and enabled
+hooks. Include tracked old/new item names, ledger/index and rewritten
+references. Verify helper availability and stop on an unavailable or
+blocked/failed helper; preserve unrelated staged/unstaged work. Follow the
+repository's PJM Backlog Lifecycle; do not stage only the missing old path.
+
 #### Agent instructions dive
 
 Explain the sync strategy in use (`oat instructions validate --json` `.strategy`: `none`, the default, keeps no CLAUDE.md because Claude Code reads AGENTS.md itself; `pointer`, `symlink`, and `copy` keep a shim beside each AGENTS.md) and each non-`ok` entry and leftover-CLAUDE.md warning with its path. Explain each missing heading: what the CLI writes there and why an agent needs it (`getting-started/bootstrap.md` for `## Tool Packs`; `workflows/backlog-and-planning/backlog-lifecycle.md` § Adoption comes first for the PJM sections). Offer `oat instructions sync`, `oat tools guidance` (read-only: prints the `OAT tools` block to add), or `oat pjm init` (appends absent PJM blocks) as the finding names; for wording and coverage beyond presence, hand off to `oat-agent-instructions-analyze` then `oat-agent-instructions-apply`.

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

@@ -5,7 +5,7 @@ disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion
 metadata:
-  version: 1.0.10
+  version: 1.0.11
 ---
 
 # OAT Explainer Kit

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

@@ -126,9 +126,12 @@ roll back an approved plan.
 
 At project completion, pass only a selected satisfied `project-recap` run to
 `oat project archive --project-recap-run`. Consume
-`projectRecapExport.sourceRunRoot`, `projectRecapExport.exportRoot`, and
-`projectRecapExport.manifest.relativePath` from the archive JSON response. Do
-not infer the dated export path. The archive export is the durable copy.
+`projectRecapExport.sourceRunRoot`, `exportRoot`, `runId`,
+`page.sourceRelativePath`, `page.originalSha256`, `page.exportedSha256`, and
+`verifiedArtifactCount` from the archive JSON response. Do not infer the dated
+export path: `exportRoot` is one tracked HTML page. The complete original run,
+manifest, source, and QA evidence remain in the archived project. Persisted
+legacy package receipts remain readable; new exports have no tracked sidecars.
 
 Project-explainer runs remain active-project working artifacts and are never
 exported as completion reference products. Local-scope projects do not export a

package/assets/skills/oat-pjm-review-backlog/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 allowed-tools: Read, Write, Glob, Grep, Bash(git:*), AskUserQuestion, Task
 user-invocable: true
 metadata:
-  version: 1.6.2
+  version: 1.6.3
 ---
 
 # Review Backlog
@@ -259,7 +259,7 @@ This step mirrors the **Project Kickoff Handoffs** section of the pjm instructio
 - the recommended project mode (`oat-project-lite` for single-sitting work, `oat-project-quick-start` for quick work, or `oat-project-new` for spec-driven work), including which artifacts (spec/design/plan) to pre-populate from existing research when it exists;
 - authoritative input pointers (research directories, decision records, code paths);
 - repo conventions and verification gates the item file does not restate;
-- a close-out section requiring (a) the **Backlog Lifecycle** — `oat backlog archive <id>` — executed in the same PR that ships the item, and (b) deletion of the handoff file (`git rm`) in that same PR.
+- a close-out section requiring (a) the **Backlog Lifecycle** — `oat backlog archive <id> --summary "outcome" --json` — in the same PR that ships the item, and (b) filesystem deletion of its owned handoff. Consume the complete returned `affectedPaths`, append the tracked handoff deletion, format existing text with the repository command, and commit the exact list via `oat internal commit-paths` with a unique retained identity and enabled hooks; stop if unavailable or blocked/failed. Include both old/new item names, ledger, index and rewritten references; preserve unrelated staged/unstaged work.
 
 **Staleness:** if this alignment pass drops an item from the kickoff stack, delete its handoff (`git rm .oat/repo/pjm/handoffs/<BL-id>.md`) in the same pass rather than letting it drift.
 

package/assets/skills/oat-pjm-update-repo-reference/SKILL.md

@@ -5,7 +5,7 @@ disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.4.1
+  version: 1.4.2
 ---
 
 # Update Repo Reference
@@ -120,8 +120,8 @@ To close out a completed backlog item, run the atomic close-out command rather
 than moving files by hand:
 
 ```bash
-oat backlog archive <id> --summary "one-line outcome"
-# abandoned work: oat backlog archive <id> --wont-do --summary "why"
+oat backlog archive <id> --summary "one-line outcome" --json
+# abandoned work: oat backlog archive <id> --wont-do --summary "why" --json
 ```
 
 This flips the item's `status` to a terminal value (`closed`/`wont_do` — never
@@ -135,6 +135,31 @@ backlog files by hand outside this command (curated overview text, an enriched
 oat backlog regenerate-index
 ```
 
+Archive never stages files. Capture each successful `--json` result and retain
+its complete `affectedPaths` array, including the old tracked item deletion,
+the archived destination, completed ledger, index and rewritten references.
+On retry use the returned operation paths; do not reconstruct ownership from
+all files that mention the item. If this close-out owns a kickoff handoff,
+remove it with a filesystem operation and append its tracked deletion path.
+Convert returned absolute paths to literal repository-relative files using
+the same repository root (avoiding checkout/scratch-path aliases).
+Deduplicate the exact file list, format only existing supported text files
+with the repository's documented formatter, and commit that list through
+`oat internal commit-paths` with enabled hooks. Verify helper availability
+first; if unavailable, stop and update the CLI. Set a unique `COMMIT_IDENTITY`
+before the first attempt and retain the identity, message and literal paths
+through retries; a blocked/failed helper result stops close-out. Unrelated
+staged and unstaged work must remain intact. An empty settled-noop path list
+needs no commit; omit a missing source path only if Git proves it was never
+tracked, never omit a tracked old path or the new destination.
+
+```bash
+oat internal commit-paths --help || exit 1
+# ARCHIVE_OWNED_FILES is the literal affectedPaths union plus owned handoff deletion.
+# Format the existing text members with the repository's documented write command.
+oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:backlog-closeout" --message "chore(pjm): archive completed backlog work" -- "${ARCHIVE_OWNED_FILES[@]}" || exit 1
+```
+
 ### Step 5: Sanity Checks
 
 Use the `Grep` tool for focused searches:

package/assets/skills/oat-project-autonomous/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: 1.0.17
+  version: 1.0.19
 ---
 
 # Autonomous OAT Project
@@ -15,6 +15,10 @@ Run an OAT project from its persisted entry state to final PR by chaining the
 existing lifecycle skills. This skill supplies policy and sequencing; each
 lifecycle skill continues to own its artifacts, gates, reviews, and state.
 
+## Hook-safe exact-path commits
+
+Before a parent-branch commit, verify `oat internal commit-paths --help` succeeds. If unavailable, stop and update the OAT CLI; never fall back to a staged-index or pathspec-only commit. Set `COMMIT_IDENTITY` to a unique operation/artifact identity before the first attempt and retain it for every retry; use a new identity for a new operation. Pass only the exact produced file list, including tracked removals and both names of a rename. A blocked/failed result stops the workflow; retain its receipt and follow its diagnostics. Hooks remain enabled. Synced project artifacts continue through `oat project push`.
+
 ## When to Use
 
 Use this skill only when the user explicitly requests autonomous end-to-end OAT
@@ -233,6 +237,57 @@ Select the earliest incomplete lifecycle owner:
 An approved plan enters at implementation. Never replay completed phases solely
 because this is a new session.
 
+### Step 1.5: Disclose Effective Limits and Hard Stops
+
+Before lifecycle execution, read the owning contracts: the vendored autonomy
+contract/gate inventory, `oat-project-implement/references/phase-execution.md`
+and `oat-phase-implementer` recovery contract, the current project dispatch
+adapter and generic dispatch contract, and each applicable lifecycle gate's
+configuration and failure policy. Do not infer permission from an allowance.
+
+For an existing project, resolve `oat_phase_recovery_policy` from `state.md`:
+use `phase_attempt_limits.<pNN>` when present, otherwise
+`default_attempt_limit` (default `10`); require integer limits from `0` through
+`20`. Read prior durable `used_attempts` and `pending_attempt` from
+`phase_attempt_usage.<pNN>` and reconcile pending identities before work. Report
+remaining capacity as `max(0, effective limit - used_attempts)`, the source and
+any phase override. A fully reconciled pending attempt completes the same
+reserved attempt, even at the limit; it receives no new reservation.
+
+Print the effective project default and every known phase's values at kickoff:
+
+```text
+Recovery: project default={limit}; source={state.md | owning default 10}
+Phase {pNN}: effective={limit}; source={phase override | project default | owning default}
+  prior durable usage={used}; remaining capacity={remaining}; pending={none | reconciled attempt/status}
+Dispatch/review: {resolved route retry limit, review-cycle cap, gate maxAttempts and their sources}
+Stops: {applicable owning stop conditions and evidence/next action}
+```
+
+For a new project, disclose the owning defaults and mark phase-specific values
+unresolved until scaffolding/planning supplies them; refresh the report before
+implementation and on resume or a configured limit change. Never invent phase
+usage. An unavailable or malformed policy/ledger stops before dispatch.
+
+Capacity is not permission. A `failed-attempt` disposition is terminal even
+with remaining capacity. Applicable hard stops include recovery eligibility or
+proof failure; budget exhaustion for a new attempt; malformed ledger or
+unresolved pending attempt; immediate direction-required stop for a lost or
+unbindable exact target, with no fallback; accepted-launch failure when neither
+same-handle continuation nor a lifecycle-authorized fresh recover launch at the
+same exact target can continue; blocking review policy;
+missing credentials; repository authority or ownership limits; unresolved
+product judgment; unauthorized destructive risk; and inventory gaps. Apply the
+owning gate's validated `block`/`prompt`/`warn` semantics without weakening its
+operational or provenance stops. Name the exact inventory boundary and its
+owner when reporting a stop.
+
+Route retries, implementation recovery events, reserved recovery attempts,
+review-fix rounds and gate attempts are separate counters. The elevated warning
+at three recovery events does not grant recovery permission or change a limit.
+Remaining allowance covers separate eligible events. Continue-after-failure is
+a separate future policy choice, not authority supplied by this kickoff.
+
 ### Step 2: Select Workflow Mode by Review Density
 
 For a new goal, choose mode as a rigor selector:
@@ -299,8 +354,8 @@ PROJECT_SCOPE=$(oat project scope "$PROJECT_PATH" --format value) || {
 if [ "$PROJECT_SCOPE" = "synced" ]; then
   oat project push "$PROJECT_PATH" --message "chore(oat): persist autonomous explainer intent" || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
 else
-  git add "$PROJECT_PATH/state.md"
-  git diff --cached --quiet || git commit -m "chore(oat): persist autonomous explainer intent"
+  OWNED_COMMIT_PATHS=("$PROJECT_PATH/state.md")
+  oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-autonomous:1" --message "chore(oat): persist autonomous explainer intent" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
 fi
 ```
 
@@ -351,8 +406,8 @@ PROJECT_SCOPE=$(oat project scope "$PROJECT_PATH" --format value) || {
 if [ "$PROJECT_SCOPE" = "synced" ]; then
   oat project push "$PROJECT_PATH" --message "chore(oat): update autonomous execution learnings" || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
 else
-  git add "$PROJECT_PATH/oat-execution-learnings.md"
-  git diff --cached --quiet || git commit -m "chore(oat): update autonomous execution learnings"
+  OWNED_COMMIT_PATHS=("$PROJECT_PATH/oat-execution-learnings.md")
+  oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-autonomous:2" --message "chore(oat): update autonomous execution learnings" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
 fi
 ```