@open-agent-toolkit/cli 0.3.15 → 0.3.17

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

@@ -3,15 +3,19 @@ name: oat-project-review-receive
 description: Use when the user explicitly asks to receive review findings for an OAT project — e.g. "receive review", "process review", "process the project review", or confirms a previously offered review-receive step. Do NOT auto-invoke merely because a review file exists. Resolves the latest review and offers before acting.
 disable-model-invocation: false
 user-invocable: true
-allowed-tools: Read, Write, Bash(git:*), Bash(oat:*), Glob, Grep, AskUserQuestion
+allowed-tools: Read, Write, Bash(git:*), Bash(oat:*), Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: 1.6.7
+  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.
 
@@ -603,28 +619,46 @@ If the project itself is still untracked because earlier lifecycle steps never c
 
 **Bounded loop protection:**
 
-Count how many review cycles have occurred for this scope. Exclude gate-originated artifacts (`oat_review_invocation: gate`): the cap measures failed fix cycles of the standard review loop, not artifact volume, and phase gate re-runs are governed by the phase review gate flow in `oat-project-implement`, not by this cap.
+Count how many review cycles have occurred for this scope. Exclude gate-originated artifacts (`oat_review_invocation: gate`): the cap measures failed fix cycles of the standard review loop, not artifact volume, and phase gate re-runs are governed by the phase review gate flow in `oat-project-implement`, not by this cap. Saved complexity reports (`complexity-<scope>-*.md` under `reviews/archived/`) name the scope but are not review cycles, so the count skips them too.
 
 ```bash
 {
   find "$PROJECT_PATH/reviews" -maxdepth 1 -type f -name "*$SCOPE_TOKEN*.md" 2>/dev/null
   find "$PROJECT_PATH/reviews/archived" -maxdepth 1 -type f -name "*$SCOPE_TOKEN*.md" 2>/dev/null
 } | while IFS= read -r artifact; do
+  case "$(basename "$artifact")" in complexity-*) continue ;; esac
   grep -q "oat_review_invocation: gate" "$artifact" || echo "$artifact"
 done | wc -l
 ```
 
 **If 3 or more cycles:**
 
+Before showing the menu, dispatch the complexity review that
+`references/docs/complexity-review-fallback.md` defines for this scope's
+exhausted loop, then show its decision message with the menu below; under
+`OAT_AUTONOMOUS=1`, put the same content in the boundary report instead.
+Record the operator's choice with the report path in `implementation.md`.
+Agents never select the disposition. The loop history in the brief includes
+this scope's gate-originated artifacts even though the count excludes them. To
+launch the review, load the current `oat-project-dispatch-subagents/SKILL.md`
+and follow it, resolving the route as that doc's "Routing outside implement"
+section describes; inside an implement run, the implement route applies. A
+receive re-entered at the cap with no new review round since the scope's newest
+complexity report reuses that report instead of dispatching another.
+
 ```
 ⚠️  Review cycle limit reached (3 cycles).
 
 This scope has been reviewed {N} times. Further automated review cycles are blocked.
 
+Complexity review: {verdict}; recommended disposition: {recommended disposition}
+Report: {report path}
+
 Options:
 1. Review findings manually and decide which to address
 2. Proceed to PR with current state
 3. Request explicit user override to continue
+4. Simplify: apply the complexity review's accepted simplifications, then review again
 
 Choose an option:
 ```
@@ -747,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/references/docs/complexity-review-fallback.md

@@ -0,0 +1,262 @@
+# Complexity Review at Budget Exhaustion
+
+When a review or gate budget runs out, the loop has stopped converging, and
+another round of the same review is unlikely to change that. Before asking the
+operator how to proceed, the root dispatches one complexity review and shows its
+result together with the reasons the loop stopped. The review asks whether the
+reviewed work, or the machinery the findings keep demanding, earns its cost
+against the contract; it is not another correctness review.
+
+This document is read by two parties: the root (the orchestrating agent that
+owns the exhausted loop) and the reviewer subagent it dispatches.
+
+## When
+
+Each owning skill points here at its exhaustion point:
+
+| Exhaustion point                                                                    | Owning skill and step                                                                         |
+| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| Root-owned phase review still has Critical/High findings at the orchestration limit | `oat-project-implement`, `references/phase-execution.md`, Bounded Fix and Re-Review Loop      |
+| Optional phase review gate still blocks at the orchestration limit                  | `oat-project-implement`, `references/phase-execution.md`, Optional External Phase Review Gate |
+| Final review reaches the three-cycle review cap                                     | `oat-project-implement`, `references/completion-and-closeout.md`, Step 13                     |
+| Implementation exit gate ends in `block` at `maxAttempts`                           | `oat-project-implement`, `references/completion-and-closeout.md`, Step 14                     |
+| A review scope reaches the three-cycle review cap                                   | `oat-project-review-receive`, Step 8                                                          |
+| Quick-start plan gate (`QS-12`) ends in `block` at `maxAttempts`                    | `oat-project-quick-start`, Gate Execution step 6                                              |
+
+These are budget exhaustions only. A single `prompt` failure, a `warn`
+outcome, and launch, transport, or runtime failures that consume no attempt do
+not trigger the review.
+
+One exhausted loop gets one review. Before dispatching, look for an existing
+report for the scope and reuse the newest
+`reviews/archived/complexity-<scope>-*.md` when it is newer than every review
+artifact of that scope: its filename timestamp is at or after the newest of
+their `oat_generated_at` values, compared at seconds precision. Among reports
+from the same second, the highest collision suffix is the newest. A legacy
+minute-precision name (`YYYY-MM-DDTHHMMZ`) reads as second `00`, which errs
+toward a fresh review. For example, a report saved as
+`complexity-p03-2026-10-02T183045Z.md` is newer than a review generated at
+`2026-10-02T18:30:20Z` and older than one generated at `2026-10-02T18:30:50Z`,
+an order minute precision could not establish. Dispatch again only when a new
+review round has landed since that report. The rule covers a re-entered review-receive at the cap, the
+final review cap reached through review-receive Step 8, and a phase scope that
+reaches both the receive cap and the implement retry limit.
+
+The operator can ask for the same review at any other time. There is no
+automatic early trigger.
+
+## Probe
+
+The operator may have the full `complexity-review` skill installed. Probe these
+paths in order and bind the first that exists:
+
+```bash
+COMPLEXITY_REVIEW_SKILL=""
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || true)
+for candidate in \
+  "${HOME:-}/.agents/skills/complexity-review/SKILL.md" \
+  "${HOME:-}/.claude/skills/complexity-review/SKILL.md" \
+  "${REPO_ROOT:+$REPO_ROOT/.agents/skills/complexity-review/SKILL.md}"; do
+  [ -n "$candidate" ] && [ -f "$candidate" ] || continue
+  COMPLEXITY_REVIEW_SKILL="$candidate"
+  break
+done
+```
+
+- **Found:** the reviewer subagent reads that `SKILL.md` and the references it
+  links, and follows them as a document. The skill is not model-invocable, so
+  never launch it as a skill. Interactive questions are forbidden: where the
+  skill would ask, the reviewer states the gap, labels the contract inferred,
+  and marks the verdict provisional. It ignores any `--out` destination and
+  returns the report inline. It then adds the OAT sections below.
+- **Not found:** the reviewer follows the condensed method below, then adds the
+  OAT sections.
+
+Report which path ran in the report's first line, for example
+`Method: installed complexity-review (<path>)` or `Method: OAT condensed`.
+
+## Dispatch
+
+The root dispatches exactly one read-only reviewer-class subagent through
+`oat-project-dispatch-subagents`, at the reviewer ceiling already resolved for
+the exhausted loop. The reviewer:
+
+- writes nothing, commits nothing, and launches nothing;
+- reads committed content (`git show <rev>:<path>`, `git diff <range>`) rather
+  than the working tree whenever another writer may own the worktree; and
+- returns the full report inline to the root.
+
+The brief names the scope:
+
+- **Reviewed target:** the phase commit range, the final implementation range,
+  or the plan bundle (`plan.md` with the discovery, design, and spec it was
+  built from).
+- **Contract sources:** the backlog items the project closes, `discovery.md`,
+  `spec.md`, `design.md`, and the relevant records under
+  `.oat/repo/reference/decisions/`. A plan cannot justify its own machinery, so
+  the contract comes from these sources, not from the reviewed plan.
+- **Loop history:** every review artifact of the exhausted loop, active and
+  archived, gate artifacts included, plus the dispositions recorded for them
+  in `implementation.md` or `plan.md`.
+
+### Routing outside implement
+
+Inside an `oat-project-implement` run, the root already loaded its dispatch
+contract and resolved the reviewer route, and both apply here. When the
+exhausted loop belongs to `oat-project-quick-start` or to a standalone
+`oat-project-review-receive` run, resolve them before the launch:
+
+1. Independently probe each required `<name>/SKILL.md` in order:
+   `${SKILL_DIR}/..` from this loaded owning skill, `${HOME}/.agents/skills`,
+   then `<repo-root>/.agents/skills`. Bind each first match to its own root:
+   `${PROJECT_DISPATCH_SKILLS_ROOT}` for `oat-project-dispatch-subagents` and
+   `${DISPATCH_SKILLS_ROOT}` for `oat-dispatch-subagents`; never rely on ambient
+   discovery. On a miss, name the skill and give its recovery
+   command, then continue with
+   `Complexity review unavailable: <skill> not installed`:
+   - `oat-project-dispatch-subagents`:
+     `oat tools install workflows --scope <user|project>`;
+   - `oat-dispatch-subagents`:
+     `oat tools install utility --scope <user|project>`.
+2. Read `${PROJECT_DISPATCH_SKILLS_ROOT}/oat-project-dispatch-subagents/SKILL.md`,
+   then `${DISPATCH_SKILLS_ROOT}/oat-dispatch-subagents/SKILL.md`, and follow them.
+3. When no reviewer ceiling was resolved for this loop, resolve one with
+   `oat project dispatch-ceiling resolve --provider "$ACTIVE_PROVIDER" --role reviewer --json`
+   and launch at that ceiling.
+
+When no reviewer route is available, the root says so in the decision message
+(`Complexity review unavailable: <reason>`) and presents the decision with the
+loop-stop reasons alone. It never substitutes a weaker reviewer class and never
+blocks the decision on the missing review.
+
+## Condensed method
+
+Generated artifacts are cheap; owned complexity is not. Each piece of
+machinery must earn its cost for this contract. The simplest solution is the
+one with the lowest total lifecycle cost that still meets the contract and
+still proves that it works, not the one with the fewest lines.
+
+1. **Restate the contract** in four lines, from the contract sources:
+   - Outcome: what was asked for, in the requester's terms.
+   - Hard constraints: limits the requester or the repository imposes.
+   - Acceptance criteria: how the requester would know it is done.
+   - Minimum proof: the smallest evidence that the outcome is achieved.
+
+   Separate requirements from implementation choices treated as requirements.
+   Verify mechanically enforced constraints in source, validators, tests, or
+   tool behavior rather than in descriptive prose. When the originating request
+   is missing or ambiguous, label the contract inferred, cite each inference,
+   and mark the verdict provisional. When sources conflict, report the
+   conflict instead of picking the one that justifies the machinery.
+
+2. **Establish the simplest viable baseline:** the least complex version that
+   satisfies the contract and its minimum proof. It is the reference point every
+   additional piece of machinery must beat, not automatically the
+   recommendation.
+
+3. **Inventory the machinery.** Consider schemas and intermediate
+   representations; scripts and generated output; tests, fixtures, and
+   snapshots; validation and repair loops; multiple agents or passes; state
+   machines, phases, and resumable sessions; abstractions and plugin seams;
+   configuration, persistence, and caching; duplicated documentation; and
+   process ceremony (planning documents, review passes, phase gates). Report
+   only material items, and judge the system as a whole: ten individually
+   defensible additions can still be indefensible together.
+
+4. **Apply the deletion test** to each item: what outcome does it support, what
+   concrete failure occurs without it, is that failure observed or merely
+   imaginable, can a smaller mechanism address it, how would we know it helped,
+   what does it cost to own, and what would adding it later cost? Grade the
+   evidence as **hard requirement**, **observed**, **strongly inferred**,
+   **speculative**, or **unsupported**, and recommend **Keep**, **Simplify**,
+   **Defer** (with an observable reintroduction trigger), or **Delete**. If an
+   item can be deleted, deferred, or substantially simplified while the
+   contract and its proof stay intact, it should be. A hard requirement, a
+   credible threat model, an irreversible interface, or a low-frequency
+   high-impact risk can justify a mechanism before any failure.
+
+5. **Build the ledger before the verdict:**
+
+   | Item                | Claimed value | Evidence                        | Lifecycle cost | Recommendation                   |
+   | ------------------- | ------------- | ------------------------------- | -------------- | -------------------------------- |
+   | {file or component} | …             | {evidence grade, with citation} | …              | Keep / Simplify / Defer / Delete |
+
+   Cite a file and line, a section, a commit, a run, or a short quote from the
+   request. "Best practice" and "consistency with siblings" belong in Claimed
+   value, never in Evidence.
+
+6. **Assign the verdict:** `Deletion-rule compliant` when every item is Keep or
+   a trivial wording-only Simplify; `Partially compliant` when the central
+   approach is right and the overshoot is peripheral; `Not compliant` when the
+   central approach itself fails the deletion test. Append `, provisional`
+   whenever the contract was inferred.
+
+Report sections: Verdict, Contract, Simplest viable solution, and Complexity
+ledger always; Proposed changes, Risks of simplifying, Reintroduction triggers,
+and Out of lane only when they have content.
+
+**Stance: skeptical, not reflexively minimalist.** Do not remove complexity
+that satisfies a hard requirement, do not trade clear code for a clever
+abstraction, do not recommend a large rewrite to remove a minor burden, and do
+not increase net machinery. Sunk cost is irrelevant; removal and migration cost
+are not. Grade necessity, not correctness: correctness, security, or staleness
+findings noticed in passing go under Out of lane, one line each, and are not
+investigated.
+
+## OAT sections
+
+Both paths add these sections to the report:
+
+- **REQUIRES-OPERATOR:** mark each ledger row that only the operator can settle
+  (a contract question, a scope or product call, accepting a risk) with
+  `REQUIRES-OPERATOR` and state the question in plain terms.
+- **Open findings:** classify each finding still open in the exhausted loop as
+  `accepted-requirement` (the contract requires it), `regression` (the change
+  broke something that worked), or `new-hardening` (a new demand beyond the
+  contract). Call out recurring families: the same kind of finding returning
+  across rounds.
+- **Dissolvable findings:** list the open findings that a recommended Simplify,
+  Defer, or Delete would dissolve.
+- **Recommended disposition:** one of `extra cycles` (more fix and review
+  rounds), `proceed with override` (accept the residual findings and continue),
+  `corrective revision` (rework within the current approach), or `simplify`
+  (apply the ledger's simplifications, then review again), with a one-sentence
+  rationale. This is a recommendation only.
+
+## Decision message and record
+
+The root, never the reviewer:
+
+1. Saves the returned report verbatim at
+   `$PROJECT_PATH/reviews/archived/complexity-<scope>-<YYYY-MM-DDTHHMMSSZ>.md`,
+   beside the loop's archived review artifacts, with the UTC timestamp from
+   `date -u +%Y-%m-%dT%H%M%SZ`. When that path already exists, append `-2`,
+   then `-3`, and so on before `.md` until the path is free. It is not a review event: it
+   carries no `oat_review_*` or `oat_generated_at` frontmatter, has no `plan.md`
+   Reviews row, and stays out of the top-level `reviews/` directory, where
+   routers would read it as an unprocessed review. Write it only while no
+   dispatched child owns the worktree; when `reviews/archived/` is tracked,
+   commit it with the decision bookkeeping.
+2. Shows one decision message containing:
+   - why the loop stopped: the budget, the count reached, and the findings still
+     blocking;
+   - the verdict and the ledger highlights;
+   - the dissolvable findings;
+   - each REQUIRES-OPERATOR item, in plain terms;
+   - the recommended disposition;
+   - the dispositions on offer: the owning step's existing options plus
+     `simplify`; and
+   - the report path.
+3. Records the operator's choice in `implementation.md` with the date, the
+   scope, the exhaustion point, the verdict, the chosen disposition, and the
+   report path.
+
+Agents never select the disposition, including the recommended one. Under
+`OAT_AUTONOMOUS=1` the run stops at its boundary report, and that report
+includes the same decision-message content; no disposition is chosen or
+recorded on the operator's behalf. The operator's choice is recorded when the
+run resumes.
+
+A `simplify` choice routes the accepted ledger changes through the owning
+skill's normal revision path (fix tasks for a code scope, plan edits for a plan
+bundle), followed by a fresh review of the revised work.

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
 ```