@open-agent-toolkit/cli 0.3.15 → 0.3.17

package/assets/skills/oat-repo-knowledge-index/SKILL.md

@@ -5,7 +5,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: 1.3.2
+  version: 1.3.3
 ---
 
 # Knowledge Base Generation
@@ -42,20 +42,39 @@ EXISTING_MD=$(find .oat/repo/knowledge -name "*.md" -type f 2>/dev/null | head -
 **If `$EXISTING_MD` is non-empty (actual content exists):**
 
 - List current files: `ls -la .oat/repo/knowledge/*.md 2>/dev/null`
-- Ask: "Refresh (delete + regenerate) or Skip?"
-- If Refresh: `rm -rf .oat/repo/knowledge/*.md && mkdir -p .oat/repo/knowledge`
+- Ask: "Refresh generated knowledge or Skip? Hand-written files will be kept; unmarked output-name collisions stop refresh."
+- If Refresh: Continue to the owned-output preflight in Step 2; do not delete files by a wildcard.
 - If Skip: Exit
 
 **If `$EXISTING_MD` is empty (no content or only .gitkeep):**
 
 - Continue to Step 2
 
-### Step 2: Create Knowledge Directory
+### Step 2: Prepare Only Owned Generated Outputs
+
+Set `SKILL_DIR` to the absolute directory containing this loaded `SKILL.md`.
+Resolve the repository root, then run the deterministic ownership preflight
+before thin-index generation or mapper writes. It checks every expected
+output name before deleting anything: an unmarked file, symlink or directory
+collision stops the run and remains intact. Only regular Markdown files with
+frontmatter `oat_generated: true` are removed; other files and manual notes
+survive. Symlinked directories in `.oat/repo/knowledge` are refused.
 
 ```bash
-mkdir -p .oat/repo/knowledge
+REPO_ROOT=$(git rev-parse --show-toplevel) || exit 1
+node "$SKILL_DIR/scripts/refresh-owned.mjs" --prepare "$REPO_ROOT" || exit 1
 ```
 
+Retain the printed JSON report's exact `affectedPaths` (removed generated paths
+plus the eight expected outputs) through generation and commit, including
+across separate shell calls. The report is operation evidence, not a persistent
+ownership manifest; no temporary report file is created. Do not broaden
+ownership to the whole directory. Expected outputs are `project-index.md`,
+`stack.md`, `architecture.md`, `structure.md`, `integrations.md`, `testing.md`,
+`conventions.md` and `concerns.md`; mappers must write only their declared
+outputs, retaining the generated frontmatter. Relocate an authored collision
+only with the operator's direction, then rerun the preflight.
+
 ### Step 3: Get Git SHAs for Frontmatter
 
 ```bash
@@ -655,23 +674,38 @@ cat .oat/repo/knowledge/project-index.md | head -50
 
 Expected: Complete overview with frontmatter and links
 
-### Step 10: Commit Knowledge Base
+### Step 10: Commit Only Generated Knowledge Paths
+
+Verify all eight generated outputs, then format their existing supported text
+using the repository's documented write command. Retain removed tracked
+generated paths from the preparation report, including filenames outside the
+current eight-output set. Resolve the repository root again with
+`git rev-parse --show-toplevel`, then convert the report's absolute paths to
+literal repository-relative files using that root, deduplicate them, and populate
+the next shell call's positional arguments; the snippet below initializes
+`KNOWLEDGE_OWNED_FILES` from that retained exact array. Resolve `SKILL_DIR` again
+in each shell call rather than relying on prior shell variables. Omit a removed
+path only if Git proves it was never tracked; never omit a tracked generated
+deletion. Do not add manual files,
+collisions or the tracking/dashboard files below to this commit.
 
 ```bash
-git add .oat/repo/knowledge/
-git commit -m "docs: generate knowledge base
-
-- project-index.md - High-level codebase overview
-- stack.md - Technologies and dependencies
-- architecture.md - System design and patterns
-- structure.md - Directory layout
-- conventions.md - Code style and patterns
-- testing.md - Test structure and practices
-- integrations.md - External services and APIs
-- concerns.md - Technical debt and issues
-
-Generated from commit: {MERGE_BASE_SHA}"
-```
+REPO_ROOT=$(git rev-parse --show-toplevel) || exit 1
+KNOWLEDGE_OWNED_FILES=("$@")
+[ "${#KNOWLEDGE_OWNED_FILES[@]}" -gt 0 ] || { echo "Missing retained knowledge affectedPaths; refusing to commit" >&2; exit 1; }
+node "$SKILL_DIR/scripts/refresh-owned.mjs" --verify "$REPO_ROOT" || exit 1
+oat internal commit-paths --help || exit 1
+# KNOWLEDGE_OWNED_FILES is the exact retained affectedPaths list after verification.
+# Format existing generated text members using the repository write command.
+oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:knowledge-index" --message "docs: generate knowledge base from $MERGE_BASE_SHA" -- "${KNOWLEDGE_OWNED_FILES[@]}" || exit 1
+```
+
+Set a unique `COMMIT_IDENTITY` before the first commit attempt and retain the
+identity, message and literal file list for retries. If the shared command is
+unavailable, stop and update the CLI; a blocked/failed result stops this run
+and retains its receipt for the reported recovery. Hooks stay enabled;
+unrelated staged entries and unstaged bytes remain preserved. Verify the
+owned paths match the committed hook-final content before proceeding.
 
 ### Step 10b: Update Tracking Manifest
 

package/assets/skills/oat-repo-knowledge-index/scripts/refresh-owned.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+import {
+  lstat,
+  mkdir,
+  readdir,
+  readFile,
+  realpath,
+  unlink,
+} from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const GENERATED_OUTPUTS = Object.freeze([
+  'project-index.md',
+  'stack.md',
+  'architecture.md',
+  'structure.md',
+  'integrations.md',
+  'testing.md',
+  'conventions.md',
+  'concerns.md',
+]);
+
+function generated(content) {
+  const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/u.exec(content);
+  const markers = frontmatter?.[1].match(/^oat_generated:.*$/gmu) ?? [];
+  return (
+    markers.length === 1 &&
+    /^oat_generated:[ \t]*true[ \t]*(?:#[^\r\n]*)?\r?$/u.test(markers[0])
+  );
+}
+
+async function knowledgeDirectory(repoRoot, create) {
+  const root = await realpath(repoRoot);
+  let path = root;
+  // Only this repo's known knowledge directory is owned. Never follow a
+  // symlink in the .oat/repo/knowledge directory chain.
+  for (const component of ['.oat', 'repo', 'knowledge']) {
+    path = join(path, component);
+    if (create) {
+      await mkdir(path).catch((error) => {
+        if (error.code !== 'EEXIST') throw error;
+      });
+    }
+    const identity = await lstat(path);
+    if (!identity.isDirectory() || identity.isSymbolicLink()) {
+      throw new Error(`Knowledge path is not an owned directory: ${path}`);
+    }
+  }
+  return path;
+}
+
+/** Validate every collision before deleting only explicitly generated files. */
+export async function prepareOwnedRefresh(repoRoot) {
+  const directory = await knowledgeDirectory(repoRoot, true);
+  const entries = await readdir(directory, { withFileTypes: true });
+  const owned = [];
+  for (const entry of entries) {
+    const expected = GENERATED_OUTPUTS.includes(entry.name);
+    if (!expected && (!entry.isFile() || !entry.name.endsWith('.md'))) continue;
+    const path = join(directory, entry.name);
+    const marked = entry.isFile() && generated(await readFile(path, 'utf8'));
+    if (expected && !marked) {
+      throw new Error(
+        `Unmarked knowledge output collision: ${path}; preserve or relocate the authored file before refreshing.`,
+      );
+    }
+    if (marked) owned.push(path);
+  }
+  // Preflight above is all-or-nothing: collisions leave every old file intact.
+  for (const path of owned.sort()) await unlink(path);
+  const outputPaths = GENERATED_OUTPUTS.map((name) => join(directory, name));
+  return {
+    removedPaths: owned,
+    outputPaths,
+    affectedPaths: [...new Set([...owned, ...outputPaths])].sort(),
+  };
+}
+
+/** Run after generation and before formatting/committing the retained list. */
+export async function verifyOwnedOutputs(repoRoot) {
+  const directory = await knowledgeDirectory(repoRoot, false);
+  const outputPaths = GENERATED_OUTPUTS.map((name) => join(directory, name));
+  for (const path of outputPaths) {
+    const identity = await lstat(path);
+    if (
+      !identity.isFile() ||
+      identity.isSymbolicLink() ||
+      !generated(await readFile(path, 'utf8'))
+    ) {
+      throw new Error(`Expected marked generated knowledge output: ${path}`);
+    }
+  }
+  return { outputPaths };
+}
+
+if (
+  process.argv[1] &&
+  (await realpath(process.argv[1]).catch(() => resolve(process.argv[1]))) ===
+    fileURLToPath(import.meta.url)
+) {
+  try {
+    const [mode, root, ...extra] = process.argv.slice(2);
+    if (!root || extra.length || !['--prepare', '--verify'].includes(mode)) {
+      throw new Error(
+        'Usage: refresh-owned.mjs <--prepare|--verify> <repo-root>',
+      );
+    }
+    const result =
+      mode === '--prepare'
+        ? await prepareOwnedRefresh(root)
+        : await verifyOwnedOutputs(root);
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+  }
+}

package/assets/skills/oat-review-provide/SKILL.md

@@ -6,13 +6,17 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.2.5
+  version: 1.2.6
 ---
 
 # Ad-Hoc Review
 
 Request and execute a code/file review that is not tied to an OAT project lifecycle.
 
+## 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 changes/files to review.
@@ -207,8 +211,8 @@ If artifact is in tracked storage (e.g., `.oat/repo/reviews`), ask whether to co
 Suggested commit (when approved):
 
 ```bash
-git add "{artifact-path}"
-git commit -m "chore(oat): record ad-hoc review artifact"
+OWNED_COMMIT_PATHS=("{artifact-path}")
+oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-review-provide:1" --message "chore(oat): record ad-hoc review artifact" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
 ```
 
 For local-active or inline modes, do not commit unless user explicitly requests.

package/assets/skills/oat-review-receive-remote/SKILL.md

@@ -5,13 +5,17 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.3.2
+  version: 1.3.3
 ---
 
 # Remote Review Receive (Ad-hoc GitHub PR)
 
 Process unresolved GitHub PR review feedback into normalized findings and standalone tasks without requiring an active OAT project.
 
+## 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
 
 - `npx agent-reviews` is available.
@@ -172,6 +176,12 @@ Also output deferred and dismissed lists with reasons.
 
 ### Step 6: Optional Fix Implementation
 
+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.
+
 After the task list is confirmed, ask:
 
 `Would you like me to address these fixes, commit, and push the changes? [yes/no]`
@@ -183,10 +193,10 @@ If yes:
 3. Stage and commit with a descriptive message referencing the PR:
 
    ```bash
-   git add {changed-files}
-   git commit -m "fix: address PR #<N> review feedback
+   OWNED_COMMIT_PATHS=("${OWNED_OUTPUT_FILES[@]}")
+   oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-review-receive-remote:1" --message "fix: address PR #<N> review feedback
 
-   Resolved findings: {list of finding IDs and titles}"
+   Resolved findings: {list of finding IDs and titles}" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
    ```
 
 4. Push to the current branch:

package/assets/skills/oat-wave-execute/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Task
 metadata:
-  version: 1.9.5
+  version: 1.9.7
 ---
 
 # Execute a Wave of External Plans
@@ -25,6 +25,10 @@ Historical `DR-*` and `BL-*` slugs in this skill (including the provenance
 record above) are evidence citations in the source program's repository; they
 are not required artifacts in the consuming repo.
 
+## 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`.
+
 ## Progress Indicators (User-Facing)
 
 Print this banner once when execution starts:
@@ -256,6 +260,12 @@ terminal state for gate rows (Orc operator-audit S8).
 Persist the gate artifact and its dispositions through the wrapper project's
 scope-aware bookkeeping route:
 
+Before running the gate, initialize `WAVE_GATE_OUTPUT_PATHS=()` and append the
+exact plan, state, implementation, review and receive-receipt files each gate
+producer actually writes. Include tracked removals and both rename sides, omit
+ignored outputs, and retain the list through retries. Do not discover ownership
+from a project-directory or staged-index diff.
+
 ```bash
 PROJECT_PATH=$(oat config get activeProject 2>/dev/null || true)
 if [ -z "$PROJECT_PATH" ]; then
@@ -267,14 +277,9 @@ PROJECT_SCOPE=$(oat project scope "$PROJECT_PATH" --format value) || { echo "oat
 if [ "$PROJECT_SCOPE" = "synced" ]; then
   oat project push "$PROJECT_PATH" --message "chore(oat): record wave plan gate" || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
 else
-  PROJECT_OUTPUT_PATHS=()
-  while IFS= read -r output_path; do
-    PROJECT_OUTPUT_PATHS+=("$output_path")
-  done < <(git diff --name-only -- "$PROJECT_PATH")
-  [ "${#PROJECT_OUTPUT_PATHS[@]}" -gt 0 ] || exit 1
-  git add -- "${PROJECT_OUTPUT_PATHS[@]}"
-  git diff --cached --quiet -- "${PROJECT_OUTPUT_PATHS[@]}" ||
-    git commit --only -m "chore(oat): record wave plan gate" -- "${PROJECT_OUTPUT_PATHS[@]}"
+  : "${WAVE_GATE_OUTPUT_PATHS:?retain the exact gate producer file list}"
+  OWNED_COMMIT_PATHS=("${WAVE_GATE_OUTPUT_PATHS[@]}")
+  oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-wave-execute:1" --message "chore(oat): record wave plan gate" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
 fi
 ```
 
@@ -392,8 +397,16 @@ archive anything first.
    `summary.md`** (this is the "before any archive step" gate): convention
    verdicts with evidence, adjustments-as-rules for later waves, graduated-entries
    ledger, rolled into `summary.md` `## Workflow Observations`.
-3. **Serialized backlog archival** — `oat backlog archive` with real summaries,
-   one commit.
+3. **Serialized backlog archival** — run `oat backlog archive --json` for
+   each item with its real outcome summary. Union and deduplicate all returned
+   `affectedPaths`, including tracked old item deletions, new destinations,
+   ledger/index and rewritten references; append owned handoff filesystem
+   deletions. Format existing supported text with the repository command,
+   then use `oat internal commit-paths` for one exact-operation commit with
+   enabled hooks and the unique retained `COMMIT_IDENTITY`. Stop if the helper
+   is unavailable or blocked/failed; unrelated staged/unstaged work survives.
+   A settled noop returns only actual repairs; do not infer paths from every
+   archived link or commit only the old missing path.
 4. **Closeout gate run** — after the archival commit, and after ANY later commit
    that touches a gated surface (`.oat/repo/**`, `.agents/**`, `packages/**`,
    `apps/**`), re-run the integration DoD gates with cache bypass. The last
@@ -417,35 +430,56 @@ archive anything first.
    HiLL. File follow-up-ledger backlog items at closeout (on main post-merge, or
    pre-gate if the operator prefers them in the PR).
 8. **The full `oat-project-complete` PROCESS, with an explicit autonomous
-   deferral branch.** Interactive runs retain the standing per-wave order
-   review → complete → merge (an open PR is expected, not a blocker — the
-   archive-aware PR body sync handles it). The requirement remains the whole
-   completion process, named explicitly: `oat project complete-state` →
-   `oat project archive` (the CLI owns the local archive move, the summary
-   export, and the S3 sync when `s3SyncOnComplete` is configured) →
-   active-project pointer clear → the completion bookkeeping commit. Running
-   `oat project complete-state` ALONE does NOT satisfy this step: in the Orc
-   first run all four wrapper projects were left lifecycle-complete but
-   unarchived until an operator audit asked (S10).
-
-   Under autonomous execution, each wave MUST still run
-   `oat project complete-state` and its then-current project bookkeeping. The
-   archive tail — `oat project archive` (including configured S3 sync) →
-   active-project pointer clear → completion bookkeeping commit — MAY be
-   deferred to the program boundary so the wave can merge and execution can
-   continue. Record every such choice in the wave ledger exactly as
-   `completion tail: deferred to program close`; deferral is an outstanding
-   disposition, never satisfaction of the full-tail requirement. Interactive
-   per-wave full-tail completion remains valid.
+   companion and deferral branch.** Interactive runs retain the standing
+   per-wave order review → complete → merge (an open PR is expected, not a
+   blocker — the archive-aware PR body sync handles it). The requirement
+   remains the whole completion process, named explicitly:
+   `oat project complete-state` → `oat project archive` (the CLI owns the local
+   archive move, the summary export, and the S3 sync when `s3SyncOnComplete` is
+   configured) → active-project pointer clear → the completion bookkeeping
+   commit. Running `oat project complete-state` ALONE does NOT satisfy this
+   step: in the Orc first run all four wrapper projects were left
+   lifecycle-complete but unarchived until an operator audit asked (S10).
 
    The interactive completion skill is model-invisible
-   (`disable-model-invocation: true`), so an autonomous orchestrator executes
-   its `SKILL.md` as a document, resolving its gates from config
-   (`workflow.archiveOnComplete`, `workflow.createPrOnComplete`), until an
-   `oat-project-complete-auto` companion ships
-   (BL-260720-add-oat-project-complete-auto). If the archive tail is deferred,
-   that execution occurs after the one human-gated program-end checkpoint in
-   `oat-wave-program`, across every deferred wave wrapper.
+   (`disable-model-invocation: true`). Under autonomous execution, invoke
+   `oat-project-complete-auto` for the wave wrapper project with this step's
+   completion-before-merge provenance:
+   `--requested-by oat-wave-execute:closeout-step-8 --completion-before-merge --reason "wave <wave-id> completes before its merge handoff" <wrapper-project-path>`.
+   The companion runs only with `workflow.autonomousComplete: true`, preflights
+   the wrapper, records the completion-before-merge exception for the open,
+   tracked wave PR in the wrapper's `implementation.md`, and then runs the full
+   completion process. Record its run-report outcome in the wave ledger.
+
+   Fall back to the deferral below only when the run report's `refused_check`
+   is `opt-in` (`interactive completion required`), `preflight:4` (the PR
+   precondition), or `preflight:7` (a completion question with no recorded
+   answer). Any other refusal — an objective preflight failure, namely
+   `preflight:1` (post-implement sequence incomplete), `preflight:2`
+   (incomplete tasks), `preflight:3` (final review not passed), `preflight:5`
+   (unresolved blockers), or `preflight:6` (project-log gate unsatisfied), or
+   an `activation` refusal — stops wave closeout at a boundary: report the
+   failing check and run neither `oat project complete-state` nor the merge
+   handoff. `oat project complete-state` checks only the closeout snapshot, so
+   running it after an objective refusal would mark an unhealthy wrapper
+   complete. A `preflight:1` refusal whose reason is
+   `project directory absent (archived?); resume with oat-project-complete`
+   means an earlier run archived the wrapper and a later completion step
+   failed: the boundary report names `oat-project-complete` as the next owner,
+   whose archive-resume branches finish the tail, and never another companion
+   run.
+
+   On a deferrable stop, the wave MUST still run `oat project complete-state`
+   and its then-current project bookkeeping, and the archive tail —
+   `oat project archive` (including configured S3 sync) → active-project
+   pointer clear → completion bookkeeping commit — MAY be deferred to the
+   program boundary so the wave can merge and execution can continue. Record
+   every such choice in the wave ledger exactly as
+   `completion tail: deferred to program close`, with the companion's stated
+   reason; deferral is an outstanding disposition, never satisfaction of the
+   full-tail requirement. Interactive per-wave full-tail completion remains
+   valid. A deferred tail runs after the one human-gated program-end
+   checkpoint in `oat-wave-program`, across every deferred wave wrapper.
 
 9. **After the operator merges:** reconcile (squash-merge means content-diff the
    branch vs main; cherry-pick stragglers), reset the working branch, clean stale

package/assets/skills/oat-wave-execute/assets/wrapper-plan-template.md

@@ -119,8 +119,16 @@ disposition every finding in the phase report. }
 
 **Step { N }: Commit**
 
+Before task edits, initialize `TASK_OWNED_FILES=()` and append the exact files
+at each source-plan producer, including created files, tracked removals and both
+rename sides. Retain the complete list and a stable unique `COMMIT_IDENTITY`
+for this wrapper task through retries; each task uses its own identity/suffix.
+Never infer ownership from the staged index or pass directories. Verify
+`oat internal commit-paths --help` first; if unavailable, stop and update the CLI.
+A nonzero result stops with its receipt and diagnostic; hooks remain enabled.
+
 ```bash
-git commit -m "{type}(p{NN}-t01): { description }"
+oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-wave-execute:wrapper-plan-template:p{NN}-t01" --message "{type}(p{NN}-t01): { description }" -- "${TASK_OWNED_FILES[@]}" || exit 1
 ```
 
 ---
@@ -144,7 +152,13 @@ git commit -m "{type}(p{NN}-t01): { description }"
 - [ ] { N }/{ N } phases, { M }/{ M } tasks complete
 - [ ] Every source plan's `## Done criteria` confirmed (recorded in `implementation.md`)
 - [ ] **Serialized backlog bookkeeping** (integration branch, after all merges):
-      `oat backlog archive` with real outcome summaries for { backlog IDs }, one commit
+      `oat backlog archive --json` with real outcome summaries for { backlog IDs }.
+      Union complete returned `affectedPaths` (tracked old deletions, new
+      destinations, ledger/index/references), append owned handoff filesystem
+      deletions, format existing text with the repo command, and create one
+      `oat internal commit-paths` commit with enabled hooks and a retained unique
+      identity. Stop on unavailable/blocked/failed helper; preserve unrelated
+      staged/unstaged work.
 - [ ] Orchestration-log end-of-run synthesis written; roll-up into `summary.md`
       before any archive step
 - [ ] Full DoD gates green on the integration branch

package/assets/skills/oat-wave-program/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Task
 metadata:
-  version: 1.5.3
+  version: 1.5.4
 ---
 
 # Program a Corpus of External Plans into Waves
@@ -124,11 +124,20 @@ target (same disclaimer as the plan indexes).
    including in autonomous runs:
    "All waves are merged and the program is complete. Run the completion tail
    (oat-project-complete: archive + S3 + pointer clear) across all N wave wrapper
-   projects now?" On yes, run the full deferred tail for each wrapper via
-   `oat-project-complete-auto` when it ships, or execute the interactive skill's
-   `SKILL.md` as a document until then, and flip every
-   `completion tail: deferred to program close` ledger disposition to `done`. On
-   no or defer, record the standing deferral and its owner in the program ledger.
+   projects now?" On yes, record the answer in the program ledger and invoke
+   `oat-project-complete-auto` once in batch mode with
+   `--requested-by oat-wave-program:program-completion-checkpoint --batch --program-checkpoint <ledger-ref>`
+   and every deferred wrapper project path. Flip each wrapper the run report
+   lists as `completed` from `completion tail: deferred to program close` to
+   `done`; a refused or failed wrapper keeps its deferral with the reported
+   reason. When the companion stops with `interactive completion required`, the
+   operator completes the wrappers with `oat-project-complete`. List every
+   wrapper refused for a deferrable reason (`preflight:4` or `preflight:7`)
+   with its next step: the operator completes it with `oat-project-complete`,
+   or sets the missing config and answers the checkpoint again. A wrapper
+   refused for an objective reason keeps its deferral and reports the failing
+   check. On no or defer,
+   record the standing deferral and its owner in the program ledger.
    This is the program completion gate; never answer it autonomously or repeat
    it once per wave.
 

package/assets/skills/oat-worktree-bootstrap-auto/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: false
 user-invocable: false
 allowed-tools: Read, Write, Bash, Glob, Grep
 metadata:
-  version: 1.6.2
+  version: 1.6.3
 ---
 
 # Autonomous Worktree Bootstrap
@@ -17,6 +17,10 @@ This skill is **model-invocable** (`disable-model-invocation: false`): orchestra
 
 > ⚠️ **When not to substitute.** This skill is the **only** supported mechanism for orchestrator-driven worktree creation in OAT skills. Host-native isolation primitives — Claude Code's `Agent({ isolation: "worktree" })`, Cursor's worktree-isolated agent invocations, and equivalents in other hosts — are **not** substitutes. They may use the primary repo's checkout (often `main`) as the base regardless of the caller's current branch, silently producing a worktree at the wrong base. OAT orchestrators dispatching mid-run from a feature branch MUST go through this skill with an explicit `--base` so the resulting worktree contains the orchestrator's prior commits.
 
+## 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`.
+
 ## Relationship to oat-worktree-bootstrap
 
 This skill is the **autonomous companion** to `oat-worktree-bootstrap`. Key differences:
@@ -358,28 +362,52 @@ Create them if missing, run the `git_clean` baseline check, and then run sync:
 mkdir -p "{target-path}/.claude/skills"
 mkdir -p "{target-path}/.cursor/rules"
 git status --porcelain
-oat sync --scope all
+SYNC_PLAN_JSON=$(oat sync --scope all --dry-run --json) || exit 1
+SYNC_OUTPUT_FILES=()
+# Populate the exact list from the producer evidence described below before apply.
+SYNC_RESULT_JSON=$(oat sync --scope all --json) || exit 1
 ```
 
-After sync completes, commit sync-managed output if any scoped path is dirty:
+Before the apply invocation, populate `SYNC_OUTPUT_FILES` from the supported
+`SYNC_PLAN_JSON.plans[]` entries/removals for `scope: project`:
+
+- `providerPath` is the planned target, and `canonical.isFile` identifies file
+  assets. Include that exact file for a mutating operation; include old tracked
+  paths for removals. Skip `operation: skip` unless the manifest was restamped.
+- A symlink projection owns the single provider symlink path. A copy projection
+  of a directory owns concrete copied members: enumerate the canonical producer
+  files before applying and map each relative member to its provider destination.
+  Capture the exact existing tracked members with literal `git ls-files -z`
+  before a planned removal. Do not discover this list from the staged index.
+- Include `.oat/sync/manifest.json` when the project manifest is written. Omit
+  ignored output files and user-scope paths, which are outside the worktree.
+- `operationResults[]` reports scope/provider/contentKind/asset/action/status,
+  **not file paths**. Match those identities to the planned entries/removals and
+  require successful/current results before committing. Materialization
+  extensions expose their own `operations[].path`; include only verified
+  concrete project files. Collection/directory outcomes require complete
+  producer member evidence. Stop on unknown, failed, incomplete or changed
+  inventories; never pass a directory to the helper.
+
+Append each exact planned output to `SYNC_OUTPUT_FILES` before mutation and
+verify it against the actual result after sync. Include both rename sides and
+retain the list and identity through a retry. The helper never expands a
+provider directory or invents a producer inventory.
+
+After sync completes, commit the retained exact list:
 
 ```bash
-SYNC_PATHS=(.oat/sync/manifest.json .claude .cursor .codex)
-SYNC_STAGE_PATHS=(existing-or-tracked sync paths)
-git status --porcelain -- "${SYNC_STAGE_PATHS[@]}"
-git add -A -- "${SYNC_STAGE_PATHS[@]}"
-STAGED_SYNC_FILES=(staged sync-managed files from git diff --cached)
-git commit -m "chore: run sync" -- "${STAGED_SYNC_FILES[@]}"
+if [ "${#SYNC_OUTPUT_FILES[@]}" -gt 0 ]; then
+  oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-worktree-bootstrap-auto:1" --message "chore: run sync" -- "${SYNC_OUTPUT_FILES[@]}" || exit 1
+else
+  echo "sync_commit: skip"
+fi
 ```
 
-Use a staged-diff guard so no empty commit is created. After scoped staging,
-derive the concrete staged sync-managed files from
-`git diff --cached --name-only --no-renames -- "${SYNC_STAGE_PATHS[@]}"` and
-commit only those file paths. Do not pass provider directory pathspecs to
-`git commit`, because empty provider directories can make the commit fail. This
-file-list isolation is what keeps `chore: run sync` limited to sync-managed
-paths even if unrelated files were already staged. If no scoped path is dirty,
-or staging produces no diff, report `sync_commit: skip`.
+A `nothing` result reports `sync_commit: skip`; blocked/failed results
+stop bootstrap and retain the helper's resumable diagnostic. Never use directory
+pathspecs, staged-diff discovery, or an empty broad commit. Smoke mode continues
+to skip sync and this commit entirely.
 
 ### Step 5: Return Structured Status