@open-agent-toolkit/cli 0.2.24 → 0.2.25

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. package/assets/agents/oat-reviewer.md +12 -1
  2. package/assets/docs/cli-utilities/configuration.md +2 -4
  3. package/assets/docs/reference/cli-reference.md +1 -1
  4. package/assets/docs/workflows/projects/reviews.md +19 -10
  5. package/assets/public-package-versions.json +4 -4
  6. package/assets/skills/oat-project-autonomous/references/gate-inventory.md +3 -3
  7. package/assets/skills/oat-project-document/references/docs/autonomy-contract.md +3 -3
  8. package/assets/skills/oat-project-implement/SKILL.md +1 -1
  9. package/assets/skills/oat-project-implement/references/docs/autonomy-contract.md +3 -3
  10. package/assets/skills/oat-project-implement/references/phase-execution.md +29 -0
  11. package/assets/skills/oat-project-pr-final/references/docs/autonomy-contract.md +3 -3
  12. package/assets/skills/oat-project-quick-start/references/docs/autonomy-contract.md +3 -3
  13. package/assets/skills/oat-project-review-provide/SKILL.md +124 -26
  14. package/assets/skills/oat-project-review-provide-remote/SKILL.md +64 -15
  15. package/assets/skills/oat-project-review-receive/SKILL.md +21 -1
  16. package/assets/skills/oat-project-review-receive-remote/SKILL.md +39 -2
  17. package/assets/skills/oat-review-provide-remote/SKILL.md +55 -12
  18. package/assets/templates/plan.md +13 -7
  19. package/dist/commands/config/index.js +8 -8
  20. package/dist/commands/review/latest.d.ts.map +1 -1
  21. package/dist/commands/review/latest.js +22 -9
  22. package/dist/config/resolve.js +1 -1
  23. package/dist/review-remote/body-builder.d.ts +12 -3
  24. package/dist/review-remote/body-builder.d.ts.map +1 -1
  25. package/dist/review-remote/body-builder.js +11 -0
  26. package/dist/review-remote/marker-parser.d.ts +8 -3
  27. package/dist/review-remote/marker-parser.d.ts.map +1 -1
  28. package/dist/review-remote/marker-parser.js +13 -2
  29. package/dist/review-remote/narrowing.d.ts +44 -8
  30. package/dist/review-remote/narrowing.d.ts.map +1 -1
  31. package/dist/review-remote/narrowing.js +106 -10
  32. package/package.json +2 -2
package/assets/skills/oat-project-quick-start/references/docs/autonomy-contract.md CHANGED
@@ -187,7 +187,7 @@ remains.
187
187
  | REVIEWPROVIDE-02 | `oat-project-review-provide` | Missing type or scope | Infer then ask for confirmation | Use caller-provided scope or deterministic project-state inference; ambiguity stops | `auto-resolve` / `boundary:product-judgment` | Review Scope metadata |
188
188
  | REVIEWPROVIDE-03 | `oat-project-review-provide` | Detached branch | Ask which branch to review | Resolve only from authoritative worktree metadata; otherwise stop | `boundary:repository-policy-approval` | Branch-resolution diagnostic |
189
189
  | REVIEWPROVIDE-04 | `oat-project-review-provide` | Different branch without worktree | Switch, inline-only, or cancel | Do not switch branches or discard context autonomously; stop for a correct checkout/worktree | `boundary:repository-policy-approval` | Branch/worktree diagnostic |
190
- | REVIEWPROVIDE-05 | `oat-project-review-provide` | Re-review narrowing | Narrow to fixes or review full scope | Use configured preference; when unset, narrow to completed fix commits | `auto-resolve` | Review Scope metadata |
190
+ | REVIEWPROVIDE-05 | `oat-project-review-provide` | Re-review narrowing | Narrow automatically or use full scope | Use configured preference without prompting: unset or `true` narrows from a guarded prior same-lineage reviewed head, `false` uses full scope; fail open to full scope when provenance or Git guards fail | `auto-resolve` | Review Scope metadata |
191
191
  | REVIEWPROVIDE-06 | `oat-project-review-provide` | Commit-range fallback | Supply a range or accept merge-base | Use a verified merge-base-to-HEAD range when it covers the declared scope; otherwise stop | `auto-resolve` / `boundary:product-judgment` | Review Scope metadata |
192
192
  | REVIEWPROVIDE-07 | `oat-project-review-provide` | Reviewer delegation authorization | Authorize `oat-reviewer` | Approve once for the exact bounded review scope | `auto-resolve` | Dispatch authorization and record |
193
193
  | REVIEWPROVIDE-08 | `oat-project-review-provide` | Fresh-session or inline fallback | Choose execution route | Use the pre-launch-selected target-preserving route; a blocking review with no adequate route stops | `auto-resolve` / `boundary:missing-credentials` | Dispatch record |
@@ -245,7 +245,7 @@ remains immutable baseline evidence for the original p01-t01 verification.
245
245
  | `oat-project-pr-final/SKILL.md` | `601ac2b890f2 -> NG`; `5eb3949f32e1 -> NG`; `9efcbcee42ea -> NG`; `655d61df0a8f -> NG`; `cf317c17c586 -> PRFINAL-01`; `2de348a391c0 -> PRFINAL-03` |
246
246
  | `oat-project-pr-final/references/docs/autonomy-contract.md` | `* -> NG` |
247
247
  | `oat-project-complete/SKILL.md` | `6ed459f9e462 -> NG`; `a167d03559fa -> NG`; `79c2eeed668c -> COMPLETE-01`; `2c1514b9d9af -> COMPLETE-01`; `31c750b4fea7 -> COMPLETE-01`; `cfba413b1293 -> COMPLETE-01`; `ffcdc9d576c0 -> COMPLETE-01`; `7fcfce0423ac -> COMPLETE-01`; `9497d9f94eed -> COMPLETE-01`; `7b59c728d3fb -> COMPLETE-01`; `48e10a9636fe -> COMPLETE-01`; `c0dad37fc166 -> COMPLETE-01`; `aa9a36243ec1 -> COMPLETE-01`; `7bcbf58b54e9 -> NG`; `4c7f88a7f942 -> COMPLETE-02`; `6a1a95acc8cc -> COMPLETE-02`; `3b559956b3eb -> COMPLETE-03`; `14d161cdf99b -> COMPLETE-03`; `12f7c30a54c8 -> NG`; `fffe5eea5ebd -> NG` |
248
- | `oat-project-review-provide/SKILL.md` | `1f4b981cac8b -> NG`; `adaeca152bb2 -> NG`; `2f7c201c3c06 -> NG`; `88f79700afdc -> NG`; `655d61df0a8f -> NG`; `efafde9ef5a0 -> NG`; `d2a3861d6323 -> REVIEWPROVIDE-02`; `65f5b9cf49cd -> REVIEWPROVIDE-04`; `962cb38d246a -> REVIEWPROVIDE-04`; `1a568483ba0b -> REVIEWPROVIDE-04`; `610e27edfe85 -> REVIEWPROVIDE-04`; `fab62c510bd0 -> REVIEWPROVIDE-05`; `a9f30853c867 -> REVIEWPROVIDE-05`; `0929c916fc20 -> REVIEWPROVIDE-05`; `f9a37c63afab -> REVIEWPROVIDE-05`; `687bb9368f92 -> REVIEWPROVIDE-05`; `bb0096e95c47 -> REVIEWPROVIDE-06`; `55f6357a987d -> REVIEWPROVIDE-06`; `1bee61f8531c -> REVIEWPROVIDE-07`; `3d35091607a1 -> REVIEWPROVIDE-08`; `fb40c4341c4c -> NG`; `b22d16885150 -> NG`; `d2b25906242e -> REVIEWPROVIDE-08`; `fd8ebf72b3c4 -> NG`; `fcb9de611ff3 -> NG`; `d2a838dfb18d -> NG`; `c3d50ea7cf69 -> NG`; `09b1b8dd445c -> NG`; `7acc8f3718d2 -> REVIEWPROVIDE-09`; `b2fa883fc4a2 -> NG`; `fe4421531b4c -> NG` |
248
+ | `oat-project-review-provide/SKILL.md` | `1f4b981cac8b -> NG`; `adaeca152bb2 -> NG`; `2f7c201c3c06 -> NG`; `88f79700afdc -> NG`; `655d61df0a8f -> NG`; `efafde9ef5a0 -> NG`; `d2a3861d6323 -> REVIEWPROVIDE-02`; `65f5b9cf49cd -> REVIEWPROVIDE-04`; `962cb38d246a -> REVIEWPROVIDE-04`; `1a568483ba0b -> REVIEWPROVIDE-04`; `610e27edfe85 -> REVIEWPROVIDE-04`; `bb0096e95c47 -> REVIEWPROVIDE-06`; `55f6357a987d -> REVIEWPROVIDE-06`; `1bee61f8531c -> REVIEWPROVIDE-07`; `3d35091607a1 -> REVIEWPROVIDE-08`; `fb40c4341c4c -> NG`; `b22d16885150 -> NG`; `d2b25906242e -> REVIEWPROVIDE-08`; `fd8ebf72b3c4 -> NG`; `fcb9de611ff3 -> NG`; `d2a838dfb18d -> NG`; `c3d50ea7cf69 -> NG`; `09b1b8dd445c -> NG`; `7acc8f3718d2 -> REVIEWPROVIDE-09`; `b2fa883fc4a2 -> NG`; `fe4421531b4c -> NG` |
249
249
  | `oat-project-review-receive/SKILL.md` | `9b8a3743d626 -> NG`; `df49c8c6f192 -> NG`; `4ee8730382d3 -> NG`; `655d61df0a8f -> NG`; `765f897d67ac -> NG`; `53b58d16dd32 -> NG`; `fb8755a3bdf4 -> NG`; `c8ab5dd90075 -> NG`; `1f7dd98dff2f -> NG`; `56f78c6740e6 -> NG`; `76f5fb5a88cd -> NG`; `085abfa3599f -> REVIEWRECEIVE-01`; `3ad3aadb8c60 -> NG`; `a7d114059bb6 -> NG`; `ac88cfaa83d9 -> NG`; `3f758313fedb -> REVIEWRECEIVE-08`; `f31f07284718 -> REVIEWRECEIVE-02`; `aba178a21441 -> REVIEWRECEIVE-04`; `a37e601cd731 -> REVIEWRECEIVE-05`; `20e05e1a4381 -> REVIEWRECEIVE-06`; `90001dadf75f -> REVIEWRECEIVE-07`; `f8fd58180ecf -> NG`; `c3abcdc02d9f -> NG`; `f2ebdd6abb9b -> NG` |
250
250
  | `oat-project-review-provide/SKILL.md` | `2e794bf4fc4a -> REVIEWPROVIDE-08`; `5441ab977b46 -> REVIEWPROVIDE-08` |
251
251
  | `oat-project-review-provide/SKILL.md` | `f4238ebb1887 -> NG`; `0360fa2db9a5 -> NG` |
@@ -297,7 +297,7 @@ inventory`). The file-and-line mappings below were captured against that commit.
297
297
  | `oat-project-summary/SKILL.md` | `4,7,30 -> NG`; `86 -> SUMMARY-01`; `201,203,209-210,249,257,297 -> NG` |
298
298
  | `oat-project-pr-final/SKILL.md` | `4,7,26,43 -> NG`; `104 -> PRFINAL-01` |
299
299
  | `oat-project-complete/SKILL.md` | `7,16 -> NG`; `57,61,63,80,89,92,95,103,105,114,124 -> COMPLETE-01`; `140 -> NG`; `205,214 -> COMPLETE-02`; `219,223 -> COMPLETE-03`; `283,468 -> NG` |
300
- | `oat-project-review-provide/SKILL.md` | `4,7,28,34,44,93 -> NG`; `166 -> REVIEWPROVIDE-02`; `236,239-240,261 -> REVIEWPROVIDE-04`; `308,314-316,318 -> REVIEWPROVIDE-05`; `370,373 -> REVIEWPROVIDE-06`; `621 -> REVIEWPROVIDE-07`; `632,664 -> REVIEWPROVIDE-08`; `645,647,751,770-772,778 -> NG`; `869 -> REVIEWPROVIDE-09`; `911,927 -> NG` |
300
+ | `oat-project-review-provide/SKILL.md` | `4,7,28,34,44,93 -> NG`; `166 -> REVIEWPROVIDE-02`; `236,239-240,261 -> REVIEWPROVIDE-04`; `308,314-316,318 -> REVIEWPROVIDE-05`; `370,373 -> REVIEWPROVIDE-06`; `621 -> REVIEWPROVIDE-07`; `632,664 -> REVIEWPROVIDE-08`; `645,647,751,770-772,778 -> NG`; `869 -> REVIEWPROVIDE-09`; `915,931 -> NG` |
301
301
  | `oat-project-review-receive/SKILL.md` | `4,7,26,40,71,128,178,211,215,252,259 -> NG`; `267 -> REVIEWRECEIVE-01`; `273-274,278 -> NG`; `482 -> REVIEWRECEIVE-08`; `517 -> REVIEWRECEIVE-02`; `548 -> REVIEWRECEIVE-04`; `590 -> REVIEWRECEIVE-05`; `614 -> REVIEWRECEIVE-06`; `647 -> REVIEWRECEIVE-07`; `721,724 -> NG` |
302
302
  | `oat-dispatch-subagents/SKILL.md` | `94,98 -> DISPATCH-01`; `110 -> PDISPATCH-01`; `117,123 -> DISPATCH-02`; `126 -> PDISPATCH-01` |
303
303
  | `oat-dispatch-subagents/references/provider-cursor.md` | `40,49 -> NG` |
package/assets/skills/oat-project-review-provide/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: oat-project-review-provide
3
- version: 1.3.22
3
+ version: 1.4.0
4
4
  description: Use when the user explicitly asks to review an OAT project — e.g. "review project", "review the project", "run project review", or confirms a previously offered review. Do NOT auto-invoke on completed work alone. Resolves a project review scope and offers before running.
5
5
  disable-model-invocation: false
6
6
  user-invocable: true
@@ -309,35 +309,74 @@ If review type is `code`, use the scope resolution below.
309
309
 
310
310
  **Step 3a: Detect Re-Review Context**
311
311
 
312
- Before resolving scope, check if this is a re-review of fixes from a prior review cycle:
312
+ After parsing the requested scope, distinguish an explicit range override from a
313
+ nominal project scope. An explicitly supplied `base_sha=<sha>` or
314
+ `<sha1>..<sha2>` range takes priority and skips automatic narrowing. Nominal
315
+ scope identifiers (`pNN`, `pNN-pMM`, `final`, and task IDs) identify the review
316
+ scope but do not override re-review narrowing.
317
+
318
+ For every code review, detect re-review context independently from deciding
319
+ whether to narrow:
320
+
321
+ 1. Set `REVIEW_HEAD` to the full commit from
322
+ `git rev-parse HEAD^{commit}`. Resolve the current lineage:
323
+ - `manual` and `auto` invocations use lifecycle lineage.
324
+ - A `gate` invocation uses gate lineage qualified by its exact
325
+ `oat_gate_target`.
326
+ 2. Resolve `workflow.autoNarrowReReviewScope` before any prior-review lookup or
327
+ Git guard. Unset and `true` enable automatic narrowing; `false` disables it.
328
+ Do not perform candidate work yet.
329
+ 3. Find the newest prior completed code review for the same project, exact
330
+ nominal scope, and lineage. Do this even when an explicit range override was
331
+ supplied. If one exists, set `IS_RE_REVIEW=true`. Lifecycle lineage treats
332
+ `manual` and `auto` as interchangeable. Gate lineage matches only a prior
333
+ `gate` review with the same exact gate target; it never matches a lifecycle
334
+ review or another gate target.
335
+ 4. If an explicit range override was supplied, resolve that exact range through
336
+ the explicit-input rules below, set the resolution reason to
337
+ `explicit base/range override`, and skip automatic narrowing.
338
+ 5. Otherwise, when the resolved preference is `false`, set the resolution
339
+ reason to `narrowing disabled`, skip all prior-head candidate lookup and
340
+ guards, and continue to normal full-scope resolution. Do not replace that
341
+ reason with a provenance or guard reason.
342
+ 6. Only when automatic narrowing is enabled, resolve `PRIOR_REVIEWED_HEAD` from
343
+ these provenance sources:
344
+ - First inspect the matching prior review artifact at its active path or
345
+ locally archived counterpart and read its full `oat_review_head_sha`.
346
+ - Then inspect the matching append-ordered event row in the tracked
347
+ `plan.md` Reviews table and read its `Reviewed Head`. Match row provenance
348
+ by `Scope`, `Type=code`, and invocation lineage: `manual` and `auto` are
349
+ interchangeable lifecycle values; `gate` matches only `gate` with the same
350
+ exact `Gate Target`. Legacy rows without a usable lineage qualifier are
351
+ ineligible.
352
+ - When both matching sources exist, they must name the same reviewed head.
353
+ If they disagree, do not prefer either source.
354
+ - When the artifact is absent (for example, after receive/archive), use the
355
+ matching tracked row. When neither source yields a candidate, this is an
356
+ initial review or provenance is unavailable.
357
+ 7. Accept a candidate only when it is exactly 40 hexadecimal characters and
358
+ both guards pass:
313
359
 
314
- 1. Scan `plan.md` for tasks tagged with `(review)` in the scope being reviewed (e.g., `(p02-review)` fix tasks for a `p02` phase review or `(p02-p03-review)` for a contiguous phase-range review).
315
- 2. If `(review)` fix tasks exist **and** their status is `completed`:
316
- - This is a re-review. Before prompting, check the workflow preference:
317
-
318
- ```bash
319
- AUTO_NARROW=$(oat config get workflow.autoNarrowReReviewScope 2>/dev/null || true)
320
- ```
321
-
322
- - **If `AUTO_NARROW` is `true`:** Auto-narrow. Print `Re-review scope: narrowed to fix commits (from workflow.autoNarrowReReviewScope).` Gather only the commits for completed `(review)` fix tasks (see below). Skip the prompt.
323
- - **If `AUTO_NARROW` is `false`:** Use full scope. Print `Re-review scope: full (from workflow.autoNarrowReReviewScope).` Skip the prompt and proceed with full scope resolution below.
324
- - **If unset:** Fall through to the standard prompt.
325
-
326
- - Standard prompt (when preference is unset):
327
-
328
- ```
329
- Detected completed review fix tasks for this scope:
330
- - {task IDs and descriptions}
360
+ ```bash
361
+ git cat-file -e "${PRIOR_REVIEWED_HEAD}^{commit}" &&
362
+ git merge-base --is-ancestor "$PRIOR_REVIEWED_HEAD" "$REVIEW_HEAD"
363
+ ```
331
364
 
332
- Scope to fix task commits only? (Y/n)
333
- ```
365
+ If accepted, the narrowed range is exactly
366
+ `SCOPE_RANGE="$PRIOR_REVIEWED_HEAD..$REVIEW_HEAD"`. Mark the range resolved
367
+ and skip the normal scope-resolution rules below.
334
368
 
335
- - **If yes (default):** gather only the commits associated with those fix tasks using commit convention grep (e.g., `git log --oneline --grep="\(pNN-tNN\)" HEAD~50..HEAD` for each fix task ID). Set `SCOPE_RANGE` to cover only those commits.
336
- - **If no:** proceed with full scope resolution below (re-review everything).
369
+ 8. Fail open to normal full-scope resolution when this is an initial review,
370
+ neither provenance source yields a valid candidate, the sources disagree,
371
+ the commit does not exist, or the ancestry guard fails. State the specific
372
+ fallback reason; never infer narrowing from ambiguous or legacy lineage.
337
373
 
338
- 3. If no `(review)` fix tasks exist, or they are not yet completed, proceed with normal scope resolution.
374
+ If no valid guarded range was resolved, continue with normal full-scope
375
+ resolution automatically. The re-review path has no interactive narrowing
376
+ decision.
339
377
 
340
- **Priority order for scope resolution:**
378
+ **Priority order for scope resolution (only when Step 3a did not resolve a
379
+ narrowed range):**
341
380
 
342
381
  1. **Explicit user input (preferred):**
343
382
  - `base_sha=<sha>` → review range is `<sha>..HEAD`
@@ -387,6 +426,32 @@ Before resolving scope, check if this is a re-review of fixes from a prior revie
387
426
  SCOPE_RANGE="$MERGE_BASE..HEAD"
388
427
  ```
389
428
 
429
+ **Step 3b: Classify and Report Re-Review Resolution**
430
+
431
+ After `SCOPE_RANGE` is final, classify it for reporting whenever
432
+ `IS_RE_REVIEW=true`, including when an explicit base or SHA-range override
433
+ supplied the exact final range:
434
+
435
+ - `empty`: `git diff --name-only "$SCOPE_RANGE"` returns no files.
436
+ - `bookkeeping-only`: every changed path is inside the exact active project
437
+ prefix `"$PROJECT_RELATIVE/"`, where `PROJECT_RELATIVE` is the path from
438
+ `git rev-parse --show-toplevel` to `PROJECT_PATH`.
439
+ - `substantive`: any changed path is outside that project prefix. If changed
440
+ files cannot be enumerated, conservatively use `substantive` and include
441
+ `changed-files-unavailable` in the reason.
442
+
443
+ Classification is reporting-only; all three classifications still dispatch the
444
+ review over the resolved range.
445
+
446
+ Print exactly one re-review resolution line:
447
+
448
+ ```
449
+ Re-review scope: range={SCOPE_RANGE}; classification={empty|bookkeeping-only|substantive}; reason={explicit base/range override | narrowing disabled | no usable prior reviewed head | provenance disagreement | prior commit missing | prior commit not an ancestor | narrowed from guarded prior reviewed head | changed-files-unavailable plus the applicable resolution reason}.
450
+ ```
451
+
452
+ The reason must state why narrowing applied or why full scope was selected. Do
453
+ not print a second narrowing-decision line elsewhere.
454
+
390
455
  ### Step 4: Get Files Changed
391
456
 
392
457
  If review type is `code`, once scope range is determined:
@@ -510,6 +575,17 @@ Build the "Review Scope" metadata for the reviewer:
510
575
  **Commits (code review only):**
511
576
  {git log --oneline for SCOPE_RANGE}
512
577
 
578
+ **Narrowed Review Provenance (code re-reviews only):**
579
+
580
+ - Narrowing applied: {yes|no}
581
+ - Prior review artifact: {artifact path from the matching event}
582
+ - Prior reviewed head: {full PRIOR_REVIEWED_HEAD, or unavailable}
583
+ - Resolved range: {SCOPE_RANGE}
584
+ - When narrowing applied, the resulting review artifact must name the prior
585
+ review artifact and reviewed head it builds on. Treat requirements coverage
586
+ outside the narrowed range as inherited from that artifact, not re-verified
587
+ by this pass.
588
+
513
589
  **Deferred Findings Ledger (final scope only):**
514
590
 
515
591
  - Deferred Medium count: {DEFERRED_MEDIUM_COUNT}
@@ -766,7 +842,8 @@ When inline is allowed:
766
842
 
767
843
  - Run "reset protocol":
768
844
  1. Re-read required artifacts for current workflow mode from scratch
769
- 2. Read all files in FILES_CHANGED
845
+ 2. Read all files in `FILES_CHANGED`. For a narrowed re-review, do not expand
846
+ this back to every file in the nominal full scope.
770
847
  3. Apply oat-reviewer checklist inline
771
848
  4. Write review artifact
772
849
 
@@ -826,6 +903,12 @@ oat_review_scope: { scope }
826
903
  oat_review_type: { code|artifact }
827
904
  oat_review_invocation: { manual|auto|gate }
828
905
  oat_project: { PROJECT_PATH }
906
+ # Code-review only: full 40-character SHA from `git rev-parse <range-head>^{commit}`.
907
+ oat_review_head_sha: { authoritative range head commit SHA }
908
+ # Narrowed code-review only: copy the complete resolved provenance chain.
909
+ oat_review_range: { prior reviewed head }..{ authoritative range head }
910
+ oat_prior_review_artifact: { prior artifact path }
911
+ oat_prior_review_head_sha: { prior artifact's full reviewed head commit SHA }
829
912
  # Gate-only: copy the exact prompt-provided fields below.
830
913
  oat_gate_run_id: { gate run id }
831
914
  oat_gate_target: { configured target id }
@@ -955,12 +1038,27 @@ Record this artifact as one append-ordered review event:
955
1038
  - `Status`: `received` (receive-review will decide `fixes_added` vs `passed`; `passed` now requires no unresolved Critical/Important/Medium and final deferred-medium disposition when applicable)
956
1039
  - `Date`: `{today}`
957
1040
  - `Artifact`: `reviews/{filename}.md`
1041
+ - `Reviewed Head`: for code reviews, the full 40-character SHA from
1042
+ `git rev-parse <authoritative-range-head>^{commit}`; `-` for non-code reviews.
1043
+ Never record an abbreviation, symbolic ref, or range string.
1044
+ - `Invocation`: for code reviews, the artifact's `oat_review_invocation`
1045
+ (`manual`, `auto`, or `gate`); `-` for non-code reviews.
1046
+ - `Gate Target`: for gate code reviews, the exact gate-context
1047
+ `oat_gate_target`; `-` otherwise.
958
1048
 
959
1049
  For the first event with this Scope + Type, claim an unbound `pending`
960
1050
  placeholder only when its Artifact is `-`. Otherwise append a new row for the
961
1051
  new artifact. Never replace or regress a bound event merely because Scope +
962
1052
  Type matches; distinct artifact filenames are distinct review events.
963
1053
 
1054
+ Before writing, inspect the table header. A legacy five-column ledger is valid:
1055
+ widen its header and separator with `Reviewed Head`, `Invocation`, and
1056
+ `Gate Target`, and pad existing rows with `-` in those three cells. For an
1057
+ already widened ledger, mutate cells by header name rather than rebuilding the
1058
+ row. Preserve every existing row and every trailing cell, including columns
1059
+ this skill does not recognize; never rewrite a widened row back to five or
1060
+ eight columns.
1061
+
964
1062
  If plan.md is missing (e.g., spec/design review before planning), skip this update and rely on the review artifact + next-step routing.
965
1063
 
966
1064
  ### Step 9.5: Commit Review Bookkeeping Atomically (Required)
package/assets/skills/oat-project-review-provide-remote/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: oat-project-review-provide-remote
3
- version: 1.0.4
3
+ version: 1.1.0
4
4
  description: Use when reviewing a GitHub PR opened on another machine for an active OAT project and posting findings back as a single PR review. Resolves the project from the PR diff, reads project artifacts for mode-aware review, and posts via gh api.
5
5
  disable-model-invocation: true
6
6
  user-invocable: true
@@ -56,7 +56,7 @@ If you catch yourself:
56
56
  - Pushing or committing anything from this machine -> STOP; machine A's receive-remote owns all project-state mutations.
57
57
  - Posting the review to GitHub without explicit user confirmation -> STOP and present the body + verdict for approval first.
58
58
  - Narrowing against a prior review SHA without running the existence + ancestry guard -> STOP and run the guard first.
59
- - Narrowing against a prior review for a different project or a different scope -> STOP; only the same `(project, scope)` prior review narrows this one.
59
+ - Narrowing against a prior review for a different project, scope, or lineage -> STOP; only the same `(project, scope, lineage)` prior review narrows this one.
60
60
  - Forgetting to remove the ephemeral worktree after posting (or on failure) -> STOP and release it in a `finally`.
61
61
 
62
62
  ## Progress Indicators (User-Facing)
@@ -90,7 +90,7 @@ oat-project-review-provide-remote [code <scope>|artifact <scope>]
90
90
  - `--pr <N>`: target PR number. When omitted, auto-detect from the current branch.
91
91
  - `--project <path>`: explicit OAT project directory. Takes precedence over the diff scan. Required when the diff touches zero or multiple projects' `state.md`.
92
92
  - `--no-checkout`: skip the ephemeral worktree and review from `gh pr diff` only (degraded context; project artifacts read from `gh` blob fetches instead of the checkout).
93
- - `--narrow` / `--no-narrow`: force or forbid re-review narrowing against a prior provide-remote review for this `(project, scope)`. When neither is passed, honor `workflow.autoNarrowReReviewScope` (no prompt when `true`; confirm prompt otherwise).
93
+ - `--narrow` / `--no-narrow`: force or forbid re-review narrowing against a prior provide-remote review for this `(project, scope, lineage)`. `--narrow` takes precedence over the configured preference; `--no-narrow` forces full scope. When neither is passed, honor `workflow.autoNarrowReReviewScope`: unset and `true` narrow automatically, while only `false` forces full scope. This path never prompts for a narrowing decision.
94
94
 
95
95
  Inputs are CLI-style args parsed from `$ARGUMENTS`. No file inputs. No file outputs on this machine.
96
96
 
@@ -186,26 +186,69 @@ NEVER mutate, commit, or push any project artifact. This is a read-only project
186
186
 
187
187
  ### Step 4: Detect Prior Reviews + Narrow Scope
188
188
 
189
- List prior PR reviews and parse each body's marker block. Filter to reviews where `oat_provide_remote: true` AND `oat_project == "$PROJECT_PATH"` AND `oat_review_scope == "<current-scope-token>"`. Different-project or different-scope prior reviews do NOT narrow this one (mirrors the tested helper at `packages/cli/src/review-remote/narrowing.ts`, `pickNarrowingTarget` with `rail: "project"`).
189
+ Resolve the current invocation lineage before selecting a candidate:
190
+
191
+ - `manual` and `auto` are the lifecycle lineage and are interchangeable.
192
+ - `gate` is a separate lineage qualified by the exact `oat_gate_target`.
193
+
194
+ Resolve preference and per-invocation flags before candidate enumeration:
195
+
196
+ 1. `--no-narrow` forces full PR scope with reason `narrowing-disabled` and skips `gh api` review enumeration entirely.
197
+ 2. `--narrow` forces a narrowing attempt even when the configured preference is `false`.
198
+ 3. With neither flag, unset and `true` attempt narrowing; only `false` forces full PR scope with reason `narrowing-disabled` and skips `gh api` review enumeration entirely.
199
+
200
+ Only when narrowing will be attempted, list prior PR reviews and parse each body's target-qualified GitHub review marker block. Capture command status and stderr separately:
190
201
 
191
202
  ```bash
192
- gh api "/repos/{owner}/{repo}/pulls/$PR/reviews"
203
+ REVIEWS_ERROR_FILE=""
204
+ REVIEWS_DIAGNOSTIC=""
205
+ REVIEWS_DISCOVERY_OK=false
206
+
207
+ if ! REVIEWS_ERROR_FILE=$(mktemp "${TMPDIR:-/tmp}/oat-review-errors.XXXXXX"); then
208
+ REVIEWS_DIAGNOSTIC="diagnostic-file-unavailable: unable to create a temporary stderr file"
209
+ elif REVIEWS_JSON=$(gh api "/repos/{owner}/{repo}/pulls/$PR/reviews" 2>"$REVIEWS_ERROR_FILE"); then
210
+ REVIEWS_DISCOVERY_OK=true
211
+ rm -f -- "$REVIEWS_ERROR_FILE"
212
+ REVIEWS_ERROR_FILE=""
213
+ else
214
+ REVIEWS_DIAGNOSTIC=$(dd if="$REVIEWS_ERROR_FILE" bs=500 count=1 2>/dev/null)
215
+ rm -f -- "$REVIEWS_ERROR_FILE"
216
+ REVIEWS_ERROR_FILE=""
217
+ fi
193
218
  ```
194
219
 
195
- Take the most recent matching review (by submitted timestamp). Before narrowing to `<prior_sha>..<HEAD>`, run the stale-SHA guard (design.md → Error Handling → Stale prior-review SHA):
220
+ Do not run `gh api` when diagnostic-file creation fails. Treat that failure, a nonzero `gh api` result, or a response-level enumeration/parsing failure as discovery failure. Before removing the diagnostic file, preserve at most 500 bytes from stderr. If response parsing later fails, set `REVIEWS_DISCOVERY_OK=false` and put at most 500 characters of the parse error in `REVIEWS_DIAGNOSTIC`. Apply the forced/automatic policy below whenever `REVIEWS_DISCOVERY_OK=false`. Do not treat individual irrelevant or lineage-ineligible marker blocks as response-level failure.
221
+
222
+ - With forced `--narrow`, discovery failure is a hard error with reason `prior-reviews-unavailable`; report the diagnostic and stop instead of pretending to narrow.
223
+ - On the automatic path, discovery failure fails open to full PR scope with stable reason `prior-reviews-unavailable` plus the diagnostic detail, then continues to review the full PR diff.
224
+
225
+ After successful enumeration, candidate discovery belongs to this rail: use only marker blocks where `oat_provide_remote: true`, `oat_project == "$PROJECT_PATH"`, and `oat_review_scope == "<current-scope-token>"`, then require the same lineage. A lifecycle invocation accepts only a prior `manual` or `auto` marker. A gate invocation accepts only a prior `gate` marker carrying the same exact non-empty `oat_gate_target`; a target-less gate marker is ineligible, and a gate never inherits a lifecycle review or another gate target. Invocation-less or unknown legacy markers, and markers for another project or scope, remain unknown and ineligible. Do not read the local lifecycle Reviews table or use a project-plan fallback on this rail.
226
+
227
+ Take the most recent eligible marker by submitted timestamp. Candidate discovery and marker provenance remain rail-specific; only after this rail supplies that candidate apply the shared guard, fallback, and classification semantics mirrored by `packages/cli/src/review-remote/narrowing.ts`. When no eligible marker supplies a full 40-character hexadecimal `oat_review_head_sha`, use full PR scope with reason `no-prior-review`. Do not run Git guards for an invalid candidate.
228
+
229
+ Before accepting `<prior_sha>..<PR_HEAD_SHA>`, run the stale-SHA guard (design.md → Error Handling → Stale prior-review SHA):
196
230
 
197
231
  Run the guard in the available git context `$GIT_CTX` — `$EPHEMERAL_PATH` in rich-context (checkout) mode, or `$REPO_ROOT` in diff-only mode (where no worktree exists):
198
232
 
199
233
  1. **Existence:** `git -C "$GIT_CTX" cat-file -e <prior_sha>` (diff-only mode: `git -C "$REPO_ROOT" fetch origin <prior_sha>:refs/oat-prior-review` first, then re-check; if that fetch fails, fall back to full PR scope).
200
234
  2. **Ancestry:** `git -C "$GIT_CTX" merge-base --is-ancestor <prior_sha> "$PR_HEAD_SHA"`.
201
235
 
202
- Guard outcomes:
236
+ Guard outcomes and reasons:
203
237
 
204
- - Both pass -> narrow to `<prior_sha>..<HEAD>`.
205
- - Either fails -> fall back to full PR scope and warn that the prior SHA is unreachable (likely rebase/force-push).
238
+ - Both pass -> narrow to exactly `<prior_sha>..<PR_HEAD_SHA>` with reason `narrowed from guarded prior reviewed head`.
239
+ - Object missing or fetch failure -> fall back to full PR scope with reason `stale-sha` and detail `prior-commit-missing`.
240
+ - Ancestry failure -> fall back to full PR scope with reason `stale-sha` and detail `prior-commit-not-ancestor`.
206
241
  - `--narrow` set AND guard fails -> hard error; surface unreachability and stop.
207
- - `workflow.autoNarrowReReviewScope == true` -> never prompt; guard failure auto-falls back to full scope with the warning as the auto-fallback notice.
208
- - No matching prior review (for this `(project, scope)`) -> use full PR diff.
242
+ - The automatic path fails open for every candidate or guard failure and preserves the applicable reason.
243
+
244
+ When a guarded narrow range is accepted, enumerate its changed files with `git diff --name-only "<prior_sha>..<PR_HEAD_SHA>"` and classify it for reporting. Resolve `PROJECT_RELATIVE` as the active project's repository-relative path first:
245
+
246
+ - `empty`: no changed files.
247
+ - `bookkeeping-only`: every changed path is inside the exact active project prefix `"$PROJECT_RELATIVE/"`.
248
+ - `substantive`: any changed path is outside that exact prefix.
249
+ - If changed-file enumeration fails, conservatively classify as `substantive` and add `changed-files-unavailable` to the reason.
250
+
251
+ Classification is reporting-only: `empty`, `bookkeeping-only`, and `substantive` all dispatch the review over the same resolved range. It never skips, gates, or shortens the review. Print one narrowing resolution line containing the resolved full-scope or narrow range, classification when narrowed, and the explicit reason. Do not print another narrowing prompt or decision line elsewhere.
209
252
 
210
253
  ### Step 5: Run the Review (Tier 1/2/3 Dispatch)
211
254
 
@@ -311,11 +354,12 @@ oat_provide_remote: true
311
354
  oat_review_head_sha: <PR_HEAD_SHA>
312
355
  oat_review_scope: <scope token, e.g. p02 | final>
313
356
  oat_project: <PROJECT_PATH>
314
- oat_review_invocation: manual
357
+ oat_review_invocation: <manual | auto | gate>
358
+ oat_gate_target: <exact configured gate target; omit for lifecycle>
315
359
  -->
316
360
  ```
317
361
 
318
- `oat_project` carries the resolved project path so machine A's `oat-project-review-receive-remote` routes findings into the right project's plan tasks. Verdict: `REQUEST_CHANGES` when any critical or important finding exists; `COMMENT` otherwise (including a clean, zero-findings review — never auto-`APPROVE`).
362
+ `oat_project` carries the resolved project path so machine A's `oat-project-review-receive-remote` routes findings into the right project's plan tasks. Preserve the current invocation lineage in the GitHub marker: omit `oat_gate_target` for lifecycle reviews and include the exact target for gate reviews. Verdict: `REQUEST_CHANGES` when any critical or important finding exists; `COMMENT` otherwise (including a clean, zero-findings review — never auto-`APPROVE`).
319
363
 
320
364
  ### Step 8: Post the Review + Clean Up
321
365
 
@@ -353,6 +397,9 @@ Posting failure handling (design.md → Error Handling → Posting failures): on
353
397
  Always release the ephemeral worktree in a `finally`, even when review or posting fails:
354
398
 
355
399
  ```bash
400
+ if [[ -n "${REVIEWS_ERROR_FILE:-}" ]]; then
401
+ rm -f -- "$REVIEWS_ERROR_FILE"
402
+ fi
356
403
  git -C "$REPO_ROOT" worktree remove --force "$EPHEMERAL_PATH" || git -C "$REPO_ROOT" worktree prune
357
404
  rm -rf "$EPHEMERAL_PATH"
358
405
  ```
@@ -378,7 +425,7 @@ At completion, report:
378
425
  - Review type and scope token.
379
426
  - Read mode (worktree checkout vs diff-only).
380
427
  - Dispatch tier used (Tier 1 structured-output / Tier 2 fresh session / Tier 3 inline).
381
- - Narrowing decision (full scope vs `<prior_sha>..<HEAD>`, and why).
428
+ - Narrowing decision (full scope vs `<prior_sha>..<PR_HEAD_SHA>`), reporting-only classification when narrowed, and the explicit reason.
382
429
  - Severity counts and total findings.
383
430
  - Inline-comment count posted vs findings downgraded to the body (out-of-diff).
384
431
  - Verdict (`REQUEST_CHANGES` or `COMMENT`).
@@ -391,7 +438,9 @@ At completion, report:
391
438
  - PR scope resolved and confirmed.
392
439
  - OAT project resolved from the diff (or `--project` override) and validated; project artifacts read read-only for mode-aware context.
393
440
  - PR content acquired via ephemeral worktree (or diff-only fallback) without mutating the caller's working tree.
394
- - Prior provide-remote reviews detected and filtered to this `(project, scope)`; re-review narrowing applied only after the stale-SHA guard passes.
441
+ - Prior provide-remote GitHub markers detected and filtered to this `(project, scope, lineage)`; re-review narrowing applied only after the full-SHA, existence, and ancestry guards pass, with explicit fail-open reasons and no local Reviews-table or project-plan fallback.
442
+ - Unset and `true` narrow automatically, only `false` forces full scope, per-invocation flags retain precedence, and no narrowing prompt remains.
443
+ - Narrowed ranges are classified as `empty`, `bookkeeping-only`, or `substantive` for reporting only; changed-file enumeration failure conservatively reports `substantive`.
395
444
  - Review executed via Tier 1 (`oat-reviewer` structured-output, NO artifact) /
396
445
  Tier 2 (fresh session) / Tier 3 (inline), with fallthrough limited to
397
446
  dispatch unavailability or explicit pre-start native role rejection.
package/assets/skills/oat-project-review-receive/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: oat-project-review-receive
3
- version: 1.5.9
3
+ version: 1.6.0
4
4
  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.
5
5
  disable-model-invocation: false
6
6
  user-invocable: true
@@ -139,6 +139,14 @@ Use this fallback only for active project reviews. It cannot discover ad-hoc rev
139
139
 
140
140
  **Read the selected review file completely.**
141
141
 
142
+ For a code review, read `oat_review_head_sha`, `oat_review_invocation`, and
143
+ `oat_gate_target` from frontmatter. Accept the reviewed head only when it is a
144
+ full 40-character hexadecimal SHA; never expand or infer an abbreviated,
145
+ symbolic, or range value during receive. A missing invocation remains unknown;
146
+ do not assume a legacy artifact was manual. Write `-` for absent provenance
147
+ rather than borrowing values from another review event. `oat_gate_target` is
148
+ meaningful only when the invocation is `gate`.
149
+
142
150
  Derive archive bookkeeping before making lifecycle edits:
143
151
 
144
152
  ```bash
@@ -406,8 +414,17 @@ Add new tasks to plan.md in the target phase. When adding or editing tasks, pres
406
414
  **Review-fix bookkeeping (required):**
407
415
  - When you add review-generated fix tasks:
408
416
  - Locate the Reviews event matching the selected review's Scope, Type, and `SOURCE_REVIEW_FILENAME`, then update it to `fixes_added` (work queued), set the Date, and replace its Artifact with `reviews/archived/$REVIEW_FILENAME`.
417
+ - For code events, populate or preserve `Reviewed Head`, `Invocation`, and
418
+ `Gate Target` from the selected artifact's validated frontmatter. Never
419
+ replace known provenance with `-`; if the artifact is legacy or a value is
420
+ invalid, preserve existing cells and otherwise leave the value unknown.
409
421
  - The written `REVIEW_FILENAME` becomes the event's artifact filename and identity for every later mutation; use the already-resolved final basename in every plan and implementation reference.
410
422
  - Never select a row by scope alone or move an event status backward. If the exact bound event is missing, stop and reconcile the ledger instead of mutating another event.
423
+ - Mutate cells by header name. If the table is still the legacy five-column
424
+ shape, add `Reviewed Head`, `Invocation`, and `Gate Target` to the header
425
+ and separator and pad every existing row with `-`. If it is already
426
+ widened, preserve all existing and unknown trailing cells; never rebuild a
427
+ row as only five or eight cells.
411
428
  - Update `## Implementation Complete` totals (phase counts + total task count) so downstream PR/review summaries don’t go stale.
412
429
  - If the plan includes any phase rollups that reference task counts, update those too.
413
430
 
@@ -429,6 +446,9 @@ Add new tasks to plan.md in the target phase. When adding or editing tasks, pres
429
446
  - Status: `fixes_added` (if tasks were added) or `passed` (if no Critical/Important/Medium and no unresolved final-scope gates)
430
447
  - Date: `{today}`
431
448
  - Artifact: `reviews/archived/$REVIEW_FILENAME`
449
+ - Reviewed Head: validated full `oat_review_head_sha` for code reviews
450
+ - Invocation: `oat_review_invocation` for code reviews
451
+ - Gate Target: exact `oat_gate_target` for gate code reviews; `-` otherwise
432
452
  ````
433
453
 
434
454
  **Status semantics (v1):**
package/assets/skills/oat-project-review-receive-remote/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: oat-project-review-receive-remote
3
- version: 1.4.2
3
+ version: 1.5.0
4
4
  description: Use when processing GitHub PR review comments within project context. Fetches PR comments, creates plan tasks, and updates project artifacts.
5
5
  disable-model-invocation: true
6
6
  user-invocable: true
@@ -115,6 +115,33 @@ Confirm resolved PR number with user.
115
115
  npx agent-reviews --json --unresolved --pr <N>
116
116
  ```
117
117
 
118
+ Resolve provenance from the GitHub review event that produced the fetched
119
+ feedback, not from the PR's current head. Parse its OAT marker block when
120
+ present:
121
+
122
+ - accept `oat_review_head_sha` only as a full 40-character hexadecimal SHA;
123
+ - preserve `oat_review_invocation` as the invocation kind;
124
+ - preserve `oat_gate_target` only for a gate invocation.
125
+
126
+ If the source review is legacy, multiple source reviews disagree, or the
127
+ lineage cannot be associated with this receive event, leave the corresponding
128
+ ledger cells unknown (`-`). Never infer lineage from the reviewer identity or
129
+ substitute the current PR head for the commit that was actually reviewed.
130
+
131
+ **Reviews ledger write contract (all receive paths):**
132
+
133
+ - Resolve `Scope`, `Type`, `Status`, `Date`, `Artifact`, `Reviewed Head`,
134
+ `Invocation`, and `Gate Target` by header name before mutating a row; never
135
+ use fixed cell positions.
136
+ - If the Reviews table has only the legacy five columns, add `Reviewed Head`,
137
+ `Invocation`, and `Gate Target` to its header and separator and pad every
138
+ existing row with `-`. In an already widened table, pad a shorter row with
139
+ `-` through the current header width before mutation.
140
+ - Mutate only the event selected by the event-identity rules below. Preserve
141
+ every unknown column in its original position and every existing known value
142
+ unless the operation explicitly advances that cell. Never truncate a row to
143
+ five, eight, or any other assumed width.
144
+
118
145
  If no unresolved comments:
119
146
 
120
147
  1. Create a UTC timestamp and event-distinct filename:
@@ -125,10 +152,14 @@ If no unresolved comments:
125
152
  remain in top-level `reviews/`.
126
153
  3. Record the clean result as a `passed` Reviews event whose event identity
127
154
  combines `Scope`, `Type`, and artifact filename:
155
+ - Apply the Reviews ledger write contract above before claiming, appending,
156
+ or mutating the event.
128
157
  - Claim only an unbound `pending` placeholder with matching Scope + Type and
129
158
  Artifact `-`; otherwise append a distinct row.
130
159
  - Set Date and Artifact to this clean event. Advance only this event and
131
160
  never mutate another row by scope alone.
161
+ - Populate `Reviewed Head`, `Invocation`, and `Gate Target` only from the
162
+ validated source-review provenance above; use `-` when it is unknown.
132
163
  4. Commit `plan.md` and the clean review artifact atomically with
133
164
  `chore(oat): record clean remote review (pr-#<N>)`. Do not stop with
134
165
  uncommitted bookkeeping.
@@ -176,7 +207,8 @@ For each converted finding:
176
207
  ### Step 6: Update Project Artifacts
177
208
 
178
209
  Before changing the ledger, write an event-distinct review artifact containing
179
- the PR number, fetch timestamp, normalized findings, and dispositions:
210
+ the PR number, fetch timestamp, normalized findings, dispositions, and any
211
+ validated source-review head/invocation/gate-target provenance:
180
212
  `reviews/archived/remote-pr-<N>-review-YYYY-MM-DDTHHMMSSZ.md`. Remote receive
181
213
  fully dispositions the event as `passed` or `fixes_added`, so the artifact is
182
214
  consumed immediately and belongs in `reviews/archived/`, not top-level
@@ -198,11 +230,16 @@ Update `plan.md`:
198
230
  - status `passed` when no actionable findings remain
199
231
  - date set to today
200
232
  - artifact `reviews/archived/remote-pr-<N>-review-YYYY-MM-DDTHHMMSSZ.md`
233
+ - reviewed head set to the validated full source-review SHA, or `-`
234
+ - invocation set to the source-review invocation kind, or `-`
235
+ - gate target set only for a gate source review, or `-`
201
236
  - Claim an unbound `pending` placeholder only when its Scope + Type matches and
202
237
  its Artifact is `-`; otherwise append the event. Later mutations select it by
203
238
  Scope + Type + artifact filename, never by scope or `github-pr #<N>` alone.
204
239
  - Never move an event status backward or overwrite an earlier event from the
205
240
  same PR.
241
+ - Apply the Reviews ledger write contract above before claiming, appending, or
242
+ mutating the event.
206
243
  - Update `## Implementation Complete` totals.
207
244
 
208
245
  Update `implementation.md`: