@open-agent-toolkit/cli 0.3.16 → 0.3.18

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

@@ -5,13 +5,17 @@ disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Bash(oat:*), Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: 1.6.8
+  version: 1.6.9
 ---
 
 # Receive Review
 
 Process review findings into actionable plan tasks and guide gap closure execution.
 
+## 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`.
+
 ## Purpose
 
 Turn review output into plan changes and a clear next action. This closes the feedback loop between reviewing and fixing.
@@ -412,6 +416,11 @@ Derive `TASK_PREFIX` from scope:
 
 ### Step 5: Convert Findings to Tasks
 
+Each generated fix task initializes `TASK_OWNED_FILES=()` before its first
+edit and appends the exact files at their producers, including removals and
+both rename sides. Carry that task-owned list and stable request/task identity
+into its Commit step; never infer ownership from the staged index.
+
 **For each Critical, High, and Medium finding (default):**
 
 Create a plan task entry:
@@ -440,8 +449,8 @@ Expected: {expected outcome}
 **Step 4: Commit**
 
 ```bash
-git add {files}
-git commit -m "fix({task_id}): {description}"
+OWNED_COMMIT_PATHS=("${TASK_OWNED_FILES[@]}")
+oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-review-receive:{task_id}" --message "fix({task_id}): {description}" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
 ```
 
 Fix tasks that edit synced artifacts use `oat project push` under the scope
@@ -560,8 +569,17 @@ After the fix tasks are complete:
 After plan/implementation/state updates reference the archived location, move the processed review artifact into the local-only history directory:
 
 ```bash
+REVIEW_ARCHIVE_PATHS=()
+# Record a tracked source deletion before the move; an untracked source has no
+# deletion to commit. The destination is included only when it is not ignored.
+if git --literal-pathspecs ls-files --error-unmatch -- "$REVIEW_PATH" >/dev/null 2>&1; then
+  REVIEW_ARCHIVE_PATHS+=("$REVIEW_PATH")
+fi
 mkdir -p "$ARCHIVED_REVIEW_DIR"
-mv "$REVIEW_PATH" "$ARCHIVED_REVIEW_PATH"
+mv "$REVIEW_PATH" "$ARCHIVED_REVIEW_PATH" || exit 1
+if ! git check-ignore -q -- "$ARCHIVED_REVIEW_PATH"; then
+  REVIEW_ARCHIVE_PATHS+=("$ARCHIVED_REVIEW_PATH")
+fi
 ```
 
 Rules:
@@ -582,12 +600,10 @@ 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 review findings and add fix tasks ({scope})" || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
 else
-  git add "$PROJECT_PATH/plan.md" "$PROJECT_PATH/implementation.md" "$PROJECT_PATH/state.md"
-  # Capture the Step 7.5 archive move: stages both the deletion of the original
-  # review path and the new archived location. Scope to the project's reviews/
-  # directory — never use repo-wide `git add -A`.
-  git add "$PROJECT_PATH/reviews/"
-  git diff --cached --quiet || git commit -m "chore(oat): record review findings and add fix tasks ({scope})"
+  OWNED_COMMIT_PATHS=("$PROJECT_PATH/plan.md" "$PROJECT_PATH/implementation.md" "$PROJECT_PATH/state.md")
+  # Consume the exact producer list retained from the Step 7.5 archive move.
+  OWNED_COMMIT_PATHS+=("${REVIEW_ARCHIVE_PATHS[@]}")
+  oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-review-receive:2" --message "chore(oat): record review findings and add fix tasks ({scope})" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
 fi
 ```
 
@@ -595,7 +611,7 @@ Do not use `git add -A` or glob patterns that reach outside `"$PROJECT_PATH/revi
 
 If the project itself is still untracked because earlier lifecycle steps never committed the initial artifact set, widen this bookkeeping commit to include the untracked core project artifacts (`discovery.md`, `spec.md`, `design.md`, `plan.md`, `implementation.md`, `state.md`). Do not stage `.oat/state.md`; it is generated dashboard state and normally gitignored. Do not leave the project tree partially tracked after receive-review finishes.
 
-**Note on archived review paths:** When `reviews/archived/` matches a `localPaths` pattern (the default setup), the archived file is gitignored and `git add "$PROJECT_PATH/reviews/"` will only stage the deletion of the original (now-moved) top-level review file. When `reviews/archived/` is tracked, both the deletion and the new archived location are staged. Both cases are safe — the command handles them uniformly.
+**Note on archived review paths:** Retain `REVIEW_ARCHIVE_PATHS` across a retry. When `reviews/archived/` matches a `localPaths` pattern, include the old tracked review path only; when the destination is tracked, include both rename sides. Do not pass the reviews directory or ignored destination to the helper. A resumed operation uses the retained producer list and identity so the helper can verify a previously committed removal.
 
 **Worktree handling:** If the project was resolved via a worktree in Step 0, run the git commands scoped to the worktree (`git -C "$WORKTREE_PATH" ...`) so the commit lands on the worktree branch.
 
@@ -765,8 +781,17 @@ For `artifact` reviews, do not route to implementation tasks. After user-approve
 **Archive the consumed review artifact (same as Step 7.5):**
 
 ```bash
+REVIEW_ARCHIVE_PATHS=()
+# Record a tracked source deletion before the move; an untracked source has no
+# deletion to commit. The destination is included only when it is not ignored.
+if git --literal-pathspecs ls-files --error-unmatch -- "$REVIEW_PATH" >/dev/null 2>&1; then
+  REVIEW_ARCHIVE_PATHS+=("$REVIEW_PATH")
+fi
 mkdir -p "$ARCHIVED_REVIEW_DIR"
-mv "$REVIEW_PATH" "$ARCHIVED_REVIEW_PATH"
+mv "$REVIEW_PATH" "$ARCHIVED_REVIEW_PATH" || exit 1
+if ! git check-ignore -q -- "$ARCHIVED_REVIEW_PATH"; then
+  REVIEW_ARCHIVE_PATHS+=("$ARCHIVED_REVIEW_PATH")
+fi
 ```
 
 - Before the move, use the Step 1 `REVIEW_FILENAME` for every artifact-review reference or event identity written by the approved edits.

package/assets/skills/oat-project-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.5.3
+  version: 1.5.4
 ---
 
 # Project Remote Review Receive
 
 Fetch unresolved GitHub PR feedback and convert it into review-fix tasks inside the 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
 
 - Active OAT project with `plan.md` and `implementation.md`.
@@ -273,8 +277,8 @@ 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 remote review findings and add fix tasks (pr-#$PR_NUMBER)" || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
 else
-  git add "$PROJECT_PATH/plan.md" "$PROJECT_PATH/implementation.md" "$PROJECT_PATH/state.md" "$REMOTE_REVIEW_PATH"
-  git diff --cached --quiet || git commit -m "chore(oat): record remote review findings and add fix tasks (pr-#$PR_NUMBER)"
+  OWNED_COMMIT_PATHS=("$PROJECT_PATH/plan.md" "$PROJECT_PATH/implementation.md" "$PROJECT_PATH/state.md" "$REMOTE_REVIEW_PATH")
+  oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-review-receive-remote:1" --message "chore(oat): record remote review findings and add fix tasks (pr-#$PR_NUMBER)" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
 fi
 ```
 

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

@@ -5,13 +5,17 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.0.4
+  version: 1.0.5
 ---
 
 # Project Revise
 
 Accept post-PR human feedback and create revision tasks without starting a new 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`.
+
 ## Purpose
 
 Provide a clean re-entry point for post-PR feedback. Routes inline feedback, GitHub PR comments, or review artifacts into revision tasks, manages state transitions (`pr_open` ↔ `in_progress`), and ensures agents understand the project is in revision mode — not done.
@@ -174,6 +178,10 @@ Source: inline feedback ({today})
 
 - Modify: `{file}`
 
+Before the first edit, initialize `TASK_OWNED_FILES=()` and append each exact
+created, modified or removed file at its producer, including both rename sides.
+Retain the task list and its unique task identity for commit/retry.
+
 **Step 1:** {What to change}
 
 **Step 2: Verify**
@@ -183,8 +191,8 @@ Expected: {expected outcome}
 **Step 3: Commit**
 
 ```bash
-git add {files}
-git commit -m "fix(prev{N}-t01): {description}"
+OWNED_COMMIT_PATHS=("${TASK_OWNED_FILES[@]}")
+oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-revise:prev{N}-t01" --message "fix(prev{N}-t01): {description}" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
 ```
 
 Fix tasks that edit synced artifacts use `oat project push` under the scope
@@ -277,8 +285,8 @@ PROJECT_SCOPE=$(oat project scope "$PROJECT_PATH" --format value) || { echo "oat
 if [ "$PROJECT_SCOPE" = "synced" ]; then
   oat project push "$PROJECT_PATH" --message "chore(oat): create revision tasks for {project-name}" || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
 else
-  git add "$PROJECT_PATH/plan.md" "$PROJECT_PATH/implementation.md" "$PROJECT_PATH/state.md"
-  git diff --cached --quiet || git commit -m "chore(oat): create revision tasks for {project-name}"
+  OWNED_COMMIT_PATHS=("$PROJECT_PATH/plan.md" "$PROJECT_PATH/implementation.md" "$PROJECT_PATH/state.md")
+  oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-revise:2" --message "chore(oat): create revision tasks for {project-name}" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
 fi
 ```
 

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

@@ -5,13 +5,17 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Bash(oat template:*), Glob, Grep, AskUserQuestion
 metadata:
-  version: 2.0.4
+  version: 2.0.5
 ---
 
 # Specification Phase
 
 Transform discovery insights into a formal specification with detailed requirements and acceptance criteria.
 
+## 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
 
 **Required:** Complete discovery document. If missing, run the `oat-project-discover` skill first.
@@ -450,14 +454,14 @@ Requirements:
 Ready for design phase" || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
 else
   PROJECT_OUTPUT_PATHS=("$PROJECT_PATH/spec.md" "$PROJECT_PATH/state.md")
-  git add -- "${PROJECT_OUTPUT_PATHS[@]}"
-  git commit -m "docs: complete specification for {project-name}
+  OWNED_COMMIT_PATHS=("${PROJECT_OUTPUT_PATHS[@]}")
+  oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-spec:1" --message "docs: complete specification for {project-name}
 
 Requirements:
 - {N} functional requirements (P0: {n}, P1: {n}, P2: {n})
 - {N} non-functional requirements (P0: {n}, P1: {n}, P2: {n})
 
-Ready for design phase"
+Ready for design phase" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
 fi
 ```
 

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

@@ -5,13 +5,17 @@ disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Bash(jq:*), Bash(oat config:*), Bash(oat decision:*), Bash(oat pjm:*), Bash(oat project log:*), Bash(oat project push:*), Bash(oat project scope:*), Bash(oat template:*), Bash(oat tools:*), Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.5.7
+  version: 1.5.8
 ---
 
 # Project Summary
 
 Generate a durable project summary artifact from project lifecycle artifacts.
 
+## 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`.
+
 ## Purpose
 
 Produce a `summary.md` that serves as institutional memory — capturing what was built, why decisions were made, what tradeoffs occurred, and what follow-up work was identified. This artifact is distinct from the PR description: summary.md is reflective and thorough; PR descriptions are reviewer-oriented and actionable.
@@ -566,7 +570,7 @@ fi
 
 PARENT_DURABILITY_COMMIT=""
 if [ "$PROJECT_SCOPE" = "synced" ] && [ "${#PARENT_OUTPUT_PATHS[@]}" -gt 0 ]; then
-  git add -- "${PARENT_OUTPUT_PATHS[@]}"
+  OWNED_COMMIT_PATHS=("${PARENT_OUTPUT_PATHS[@]}")
   if [ "$PROJECT_LOG_LEDGER_APPENDED" = "true" ] && [ "$DECISION_INDEX_CHANGED" = "true" ]; then
     PARENT_COMMIT_MESSAGE="docs: update project log ledger and decisions for {project-name}"
   elif [ "$PROJECT_LOG_LEDGER_APPENDED" = "true" ]; then
@@ -574,7 +578,7 @@ if [ "$PROJECT_SCOPE" = "synced" ] && [ "${#PARENT_OUTPUT_PATHS[@]}" -gt 0 ]; th
   else
     PARENT_COMMIT_MESSAGE="docs: promote summary decisions for {project-name}"
   fi
-  git commit --only -m "$PARENT_COMMIT_MESSAGE" -- "${PARENT_OUTPUT_PATHS[@]}"
+  oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-summary:1" --message "$PARENT_COMMIT_MESSAGE" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
   PARENT_DURABILITY_COMMIT=$(git rev-parse HEAD)
   PARENT_COMMIT_PATHS=$(git diff-tree --no-commit-id --name-only -r "$PARENT_DURABILITY_COMMIT")
   # Inspect the complete output and require exact set equality with the
@@ -609,8 +613,8 @@ else
   if [ "${#PARENT_OUTPUT_PATHS[@]}" -gt 0 ]; then
     PROJECT_OUTPUT_PATHS+=("${PARENT_OUTPUT_PATHS[@]}")
   fi
-  git add -- "${PROJECT_OUTPUT_PATHS[@]}"
-  git commit --only -m "docs: generate summary for {project-name}" -- "${PROJECT_OUTPUT_PATHS[@]}"
+  OWNED_COMMIT_PATHS=("${PROJECT_OUTPUT_PATHS[@]}")
+  oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-summary:2" --message "docs: generate summary for {project-name}" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
   SUMMARY_COMMIT_SHA=$(git rev-parse HEAD)
 fi
 
@@ -639,8 +643,8 @@ if [ "$PROJECT_SCOPE" = "synced" ]; then
   SUMMARY_PUSH=$(oat project push "$PROJECT_PATH" --message "docs: update summary for {project-name}" --json) || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
   SUMMARY_COMMIT_SHA=$(parse_synced_push_receipt "$SUMMARY_PUSH") || { printf '%s\n' "$SUMMARY_PUSH" >&2; echo "Recovery: run oat project pull \"$PROJECT_PATH\", resolve conflicts, then retry this push." >&2; exit 1; }
 else
-  git add -- "${PROJECT_OUTPUT_PATHS[@]}"
-  git commit --only -m "docs: update summary for {project-name}" -- "${PROJECT_OUTPUT_PATHS[@]}"
+  OWNED_COMMIT_PATHS=("${PROJECT_OUTPUT_PATHS[@]}")
+  oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-summary:3" --message "docs: update summary for {project-name}" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
   SUMMARY_COMMIT_SHA=$(git rev-parse HEAD)
 fi
 ```

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: