@open-agent-toolkit/cli 0.3.15 → 0.3.17

package/assets/skills/oat-project-quick-start/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-quick-start/references/docs/gate-approval-record.md

@@ -0,0 +1,80 @@
+# Lifecycle Gate Approval Record
+
+A configured lifecycle gate ends in an outcome the operator or a later session
+needs to see again: it passed, it warned, the operator explicitly continued
+past a failure, the project disabled it, or it blocked. Chat output does not
+survive the session, so the skill that runs the gate persists the outcome in
+project `state.md`. This document defines the record's shared core once; each
+carrier names where it lives and what it adds.
+
+## Core record
+
+```yaml
+<carrier>:
+  status: allowed # allowed | blocked
+  disposition: passed # passed | warned | prompt_approved | project_disabled; null when blocked
+  config_fingerprint: '<stable hash of the resolved gate declaration>'
+  reviewed_head: '<full SHA of the commit the gate reviewed>'
+  decided_at: '2026-10-02T15:20:00Z'
+```
+
+- `status`: `allowed` | `blocked`.
+- `disposition`: `passed`, `warned`, `prompt_approved`, or `project_disabled`
+  when `status` is `allowed`; `null` when `status` is `blocked`.
+- `config_fingerprint`: the writer's stable hash of the resolved gate
+  declaration it ran (command, description, `onFailure`, `maxAttempts`, and the
+  project override state), recorded as provenance. Implement recomputes its own
+  carrier's fingerprint under its Step 14 rules; quick-start readers do not.
+- `reviewed_head`: the full 40-character SHA of the commit the gate reviewed,
+  recorded as provenance. `null` when no gate ran.
+- `decided_at`: the ISO 8601 UTC time the outcome was decided. A record written
+  before `decided_at` existed is not malformed for that reason alone.
+
+## Write rules
+
+| Gate outcome                                                    | Record                                                      |
+| --------------------------------------------------------------- | ----------------------------------------------------------- |
+| Passed its threshold                                            | `allowed` / `passed`                                        |
+| Failed under `onFailure: warn`                                  | `allowed` / `warned`                                        |
+| Failed under `onFailure: prompt`, operator explicitly continued | `allowed` / `prompt_approved`                               |
+| Failed under `onFailure: prompt`, operator declined or deferred | `blocked` / `null`                                          |
+| `block` still failing after `maxAttempts`                       | `blocked` / `null`                                          |
+| Configured but disabled by project override (no launch)         | `allowed` / `project_disabled`                              |
+| Launch, transport, validation, or receive failure               | `blocked` / `null`                                          |
+| Not configured                                                  | no record (quick-start); implement writes `allowed/no_gate` |
+
+Only an explicit operator continuation writes `prompt_approved`. Declining,
+deferring, giving no response, or running under `OAT_AUTONOMOUS=1` writes
+`blocked`, never anything that reads as approval. A rerun of the same gate
+replaces the record.
+
+## Carriers
+
+- **`oat_implement_exit_gate`** (`oat-project-implement`,
+  `references/completion-and-closeout.md` Step 14) uses this core and keeps its
+  additional values and fields there: the `pending` and `stale` statuses, the
+  `no_gate` disposition, and the resolution, attempt, launch, receive, waiver,
+  and freshness fields. Its own effective-delta freshness rule decides whether a
+  record is current.
+- **`oat_quick_start_gate`** (`oat-project-quick-start`, Gate Execution) carries
+  exactly the core.
+
+## Reading a quick-start record
+
+Readers report a quick-start record as recorded and do not recompute
+`config_fingerprint`: no CLI emits a canonical fingerprint for the quick-start
+gate, so a recomputation could not be reproduced across sessions. They do not
+route on the record either.
+
+- Report `status`, `disposition`, `decided_at`, and `config_fingerprint` (as
+  provenance) exactly as stored.
+- Report the record as malformed when `status` and `disposition` do not form
+  one of the combinations in the write rules, or when a present `decided_at` is
+  not a valid ISO 8601 UTC time.
+- `reviewed_head` is provenance only and is not compared with `HEAD`, because
+  the quick-start completion step commits after the gate.
+- An absent record means none was written: no gate was configured, the gate
+  has not reached an outcome, or the plan predates the record. Readers do not
+  infer which.
+
+Readers never write, repair, or infer a record.

package/assets/skills/oat-project-reconcile/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.3
+  version: 1.0.4
 ---
 
 # Reconcile Manual Implementation
 
 Bridge the gap between human implementation and OAT's artifact-driven workflow. Analyzes commits made outside the structured OAT flow, maps them to planned tasks, and updates tracking artifacts after human confirmation.
 
+## 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:**
@@ -684,10 +688,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): reconcile manual implementation ({first_task_id}..{last_task_id})" || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
 else
-  git add "$PROJECT_PATH/implementation.md" "$PROJECT_PATH/state.md"
+  OWNED_COMMIT_PATHS=("$PROJECT_PATH/implementation.md" "$PROJECT_PATH/state.md")
   # Only add plan.md if it was modified
-  git diff --name-only "$PROJECT_PATH/plan.md" 2>/dev/null | grep -q . && git add "$PROJECT_PATH/plan.md"
-  git diff --cached --quiet || git commit -m "chore(oat): reconcile manual implementation ({first_task_id}..{last_task_id})"
+  git diff --name-only "$PROJECT_PATH/plan.md" 2>/dev/null | grep -q . && OWNED_COMMIT_PATHS+=("$PROJECT_PATH/plan.md")
+  oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-reconcile:1" --message "chore(oat): reconcile manual implementation ({first_task_id}..{last_task_id})" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
 fi
 ```
 

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

@@ -5,7 +5,7 @@ disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Bash(jq:*), Bash(mkdir:*), Bash(pnpm:*), Bash(oat config:*), Bash(oat decision:*), Bash(oat project log:*), Bash(oat project push:*), Bash(oat project scope:*), Bash(oat template:*), Bash(oat tools:*), Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.0.8
+  version: 1.0.9
 ---
 
 # Project Retrospective

package/assets/skills/oat-project-retro/references/apply-procedure.md

@@ -118,8 +118,8 @@ continues immediately, this can be written back together with the final
        CORRECTION_PUSH=$(oat project push "$PROJECT_PATH" --message "chore(oat): apply retro correction $RP_ID" --json) || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
        CORRECTION_COMMIT=$(parse_synced_push_receipt "$CORRECTION_PUSH") || { printf '%s\n' "$CORRECTION_PUSH" >&2; echo "Recovery: run oat project pull \"$PROJECT_PATH\", resolve conflicts, then retry this push." >&2; exit 1; }
      else
-       git add "$PROJECT_PATH/project-log.md"
-       git commit -m "chore(oat): apply retro correction $RP_ID"
+       OWNED_COMMIT_PATHS=("$PROJECT_PATH/project-log.md")
+       oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-retro:apply-procedure:1" --message "chore(oat): apply retro correction $RP_ID" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
        CORRECTION_COMMIT=$(git rev-parse HEAD)
      fi
      ```
@@ -260,8 +260,8 @@ Compute `oat_retro_promotions` exactly:
   if [ "$PROJECT_SCOPE" = "synced" ]; then
     # RETRO_TARGET_PATHS contains exact ordinary-doc, agent-instruction, rule,
     # or decision-record paths; include the managed decision index only when changed.
-    git add -- "${RETRO_TARGET_PATHS[@]}"
-    git commit --only -m "chore(oat): apply retro target $RP_ID" -- "${RETRO_TARGET_PATHS[@]}"
+    OWNED_COMMIT_PATHS=("${RETRO_TARGET_PATHS[@]}")
+    oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-retro:apply-procedure:2" --message "chore(oat): apply retro target $RP_ID" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
     RETRO_TARGET_COMMIT=$(git rev-parse HEAD) || exit 1
     RETRO_TARGET_COMMIT_PATHS=$(git diff-tree --no-commit-id --name-only -r "$RETRO_TARGET_COMMIT") || exit 1
     # Require RETRO_TARGET_COMMIT_PATHS to equal the complete normalized
@@ -277,8 +277,8 @@ Compute `oat_retro_promotions` exactly:
     # shared/local route with only the exact target and retro paths.
     APPLIED_REF="${RETRO_TARGET_PATHS[*]}"
     RETRO_COMMIT_PATHS=("${RETRO_TARGET_PATHS[@]}" "$PROJECT_PATH/references/project-retro.md")
-    git add -- "${RETRO_COMMIT_PATHS[@]}"
-    git commit --only -m "chore(oat): apply retro item $RP_ID" -- "${RETRO_COMMIT_PATHS[@]}"
+    OWNED_COMMIT_PATHS=("${RETRO_COMMIT_PATHS[@]}")
+    oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-retro:apply-procedure:3" --message "chore(oat): apply retro item $RP_ID" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
     RETRO_TARGET_COMMIT=$(git rev-parse HEAD) || exit 1
   fi
 

package/assets/skills/oat-project-retro-file/SKILL.md

@@ -5,7 +5,7 @@ disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Bash(jq:*), Bash(pnpm:*), Bash(gh:*), Bash(oat backlog:*), Bash(oat config:*), Bash(oat project push:*), Bash(oat project scope:*), Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.0.3
+  version: 1.0.4
 ---
 
 # File Project Retro Feedback
@@ -17,6 +17,10 @@ idempotent status writeback.
 This skill never applies `Disposition: apply` repo edits and never mutates
 `oat_retro_promotions`.
 
+## 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 one banner and concise step indicators:
@@ -395,8 +399,8 @@ if [ "$PROJECT_SCOPE" = "synced" ]; then
   RETRO_PUSH=$(oat project push "$PROJECT_PATH" --message "chore(oat): record project retro filing writeback" --json) || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
   WRITEBACK_COMMIT=$(parse_synced_push_receipt "$RETRO_PUSH") || { printf '%s\n' "$RETRO_PUSH" >&2; echo "Recovery: run oat project pull \"$PROJECT_PATH\", resolve conflicts, then retry this push." >&2; exit 1; }
 else
-  git add "$RETRO_PATH"
-  git diff --cached --quiet || git commit -m "chore(oat): record project retro filing writeback"
+  OWNED_COMMIT_PATHS=("$RETRO_PATH")
+  oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-retro-file:1" --message "chore(oat): record project retro filing writeback" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
   WRITEBACK_COMMIT=$(git rev-parse HEAD)
 fi
 

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

@@ -5,13 +5,17 @@ disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Write, Edit, Bash(git:*), Bash(oat:*), Bash(pnpm:*), Bash(mkdir:*), Bash(date:*), Bash(realpath:*), Bash(awk:*), AskUserQuestion
 metadata:
-  version: 1.5.12
+  version: 1.5.13
 ---
 
 # Request Review
 
 Request and execute a code or artifact review for the current project scope.
 
+## 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 an independent review artifact that verifies requirements/design alignment (mode-aware) and code quality.
@@ -622,6 +626,21 @@ Build the "Review Scope" metadata for the reviewer:
 - Deferred Low count: {DEFERRED_LOW_COUNT}
   {DEFERRED_LEDGER}
 
+**Changed-Boundary Probe Guidance (code review only):**
+
+- Apply the reviewer's proportional changed-boundary probe contract to changed
+  trust/input/size/limit boundaries with credible failure modes.
+- Record exact commands, input/artifact provenance, categorical results and
+  any concrete execution limitation. Independently inspected implementer
+  failing and accepted controls may count when the reviewer cannot execute;
+  unsupported assertions cannot count.
+- Missing consequential evidence requires a blocking finding under the existing
+  severity model, with
+  the unresolved guarantee and smallest missing proof. Docs-only changes with
+  no credible changed boundary require no manufactured probes.
+- Preserve containment, independence, dispatch policy, severity and output
+  schemas; do not start a broad campaign or create a harness.
+
 **Design Drift Review Guidance:**
 
 - If implementation differs from `spec.md`, `design.md`, or `plan.md`, decide whether the code should change or whether the artifact is stale.
@@ -1193,9 +1212,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 {scope} review artifact" || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
 else
-  git add "$ACTIVE_REVIEW_PATH"
-  [ -f "$PROJECT_PATH/plan.md" ] && git add "$PROJECT_PATH/plan.md"
-  git diff --cached --quiet || git commit -m "chore(oat): record {scope} review artifact"
+  OWNED_COMMIT_PATHS=("$ACTIVE_REVIEW_PATH")
+  [ -f "$PROJECT_PATH/plan.md" ] && OWNED_COMMIT_PATHS+=("$PROJECT_PATH/plan.md")
+  oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-review-provide:1" --message "chore(oat): record {scope} review artifact" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
 fi
 ```
 

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

@@ -5,7 +5,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash, Glob, Grep, Task, AskUserQuestion
 metadata:
-  version: 1.1.9
+  version: 1.1.10
 ---
 
 # Remote Review Provide (Project-Scoped GitHub PR)
@@ -209,6 +209,24 @@ Resolve the workflow mode and the scope token:
 
 NEVER mutate, commit, or push any project artifact. This is a read-only project context on machine B.
 
+For code reviews, carry the reviewer's proportional changed-boundary probe
+contract in every Tier 1/2/3 brief: inventory changed trust/input/size/limit
+boundaries and credible failures, record exact commands, input/artifact
+provenance, categorical results and any concrete execution limitation.
+Independently inspected implementer failing and accepted controls may count
+when the reviewer cannot execute; unsupported assertions cannot count. Missing
+consequential evidence requires a blocking finding under the existing severity
+model naming the
+unresolved guarantee and smallest missing proof. Docs-only changes with no
+credible changed boundary require no manufactured probes. Preserve containment,
+independence, dispatch policy and the existing severity/output schemas; no new
+harness, broad campaign or model-efficacy claim.
+
+Put compact results, inspected-control provenance and execution limitations in
+existing `StructuredFindings.summary`/finding bodies, with exact repeatable
+commands in `verification_commands`. Add no schema fields or project artifacts.
+Diff-only context is an execution limitation, not evidence of correctness.
+
 ### Step 4: Detect Prior Reviews + Narrow Scope
 
 Resolve the current invocation lineage before selecting a candidate: