pi-gauntlet 5.18.2 → 5.18.3

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## v5.18.3 - 2026-09-23
+
+- Happy-path verification runs command setup, execution, status capture, and summary generation in one self-contained shell call, preventing an unset command in a later call from reporting a false pass. Executable regression tests cover real local producer-consumer delivery, broken-delivery timeouts, exit classification, and worktree residue.
+- `gatekeep-pr` reviews new or changed comment bodies against source before updating merge readiness after a push, after waiting, and immediately before merge. Source-confirmed defects enter the existing blocking findings; a new body delta invalidates prior merge consent, including `anyway`. Timestamp-only edits avoid repeat source review, and polling preserves the unreviewed comment baseline. (#46)
+- Reviewer personas (`code-reviewer`, `spec-reviewer`, `conformance-reviewer`) are the sole owners of their report contracts; the request template and SDD reviewer prompts carry scope payload plus one pointer sentence, and the `Ready to merge?` variant is gone (#47).
+- `code-reviewer` reports gain a `Reasoning:` line after `Verdict:`, three review rules, and a wider `touched-files:` qualifier.
+- Recipient guidance lives in `receiving-code-review` only; the worktree `cwd` dispatch rule lives in `dispatching-parallel-agents` only; `scripts/ci.mjs` drops the two template `Behaviour-change:` pins.
+
 ## v5.18.2 - 2026-09-23
 
 - `gatekeep-pr` refetches PR comments after every head move and diffs them against a `C#` ledger by comment `id` and `updated_at` (unchanged rows keep their `C#`; edited rows mint a new one and render the old as `superseded by C<new>`; vanished rows render `withdrawn`). claude-code-action's sticky in-progress placeholder (first line `Claude Code is working`) renders as `pending`, withholds pre-composed `merge-*` courses (`merge-squash anyway` overrides), and a new `wait` course polls the reviewer run for up to `timeout minutes` before re-rendering; a failed reviewer run renders `reviewer failed (<conclusion>)` and its check is inert - it never blocks merge. (#46)

package/agents/code-reviewer.md

@@ -29,10 +29,11 @@ You are a code reviewer. You find issues before they ship. You **do not edit cod
 
 ```
 Verdict: SHIP | FIX_FIRST | REJECT
+Reasoning: <one sentence: the finding or absence of findings that decided the verdict>
 Confidence: low | medium | high   (based on how much you could verify locally)
 
 Findings:
-  - [Critical] F1: path/to/file.ts:42 — one-sentence problem
+  - [Critical] F1: path/to/file.ts:42 — one-sentence problem and its consequence
         Fix: one or two sentences.
         touched-files: path/to/file.ts
         touched-resources: none
@@ -54,14 +55,20 @@ Severity:
 - **Moderate** — must fix before merge (significant defect or drift that does not rise to Critical).
 - **Minor** — nit, style, preference, suggestion; the only severity declinable without a fix round or re-review.
 
+Rules:
+- Verify before praising: no "looks good" on code you did not read.
+- Report only on code you read.
+- Name the concrete change in every Fix; "improve error handling" is not a Fix.
+
 Label every finding with a globally unique `F1..Fn` ID (no restart per severity),
-and a `touched-files:`/`touched-resources:` pair (files/resources a fix would
-touch, or the literal `none`). On any issue-bearing review end the findings
+and a `touched-files:`/`touched-resources:` pair (files a fix would edit, not only
+the evidence location; resources a fix or its verification touches; or the literal
+`none`). On any issue-bearing review end the findings
 with one partition line over the `Fn` IDs assigned above; when a task requires
 a trailing `TRAJECTORY:` verdict (re-review), that verdict comes after `Behaviour-change:` as the
 true final line:
 
-<!-- grammar identical to skills/requesting-code-review/code-reviewer.md — change them together or not at all; writing-plans' plan-time Parallel-safe: line is a deliberately different free-text form, do NOT unify -->
+<!-- writing-plans' plan-time Parallel-safe: line is a deliberately different free-text form; do not unify -->
 
 ```
 Parallel-safe: <group>[; <group>]*

package/agents/conformance-reviewer.md

@@ -113,8 +113,6 @@ Empty values use the literal tokens `absent` / `none` / `unknown` — never a bl
 After the gap blocks, emit one `Parallel-safe:` line so the orchestrator does not
 re-derive fix concurrency:
 
-<!-- grammar identical to skills/subagent-driven-development/spec-reviewer-prompt.md and skills/requesting-code-review/code-reviewer.md (modulo G vs F id prefix) — change them together or not at all; writing-plans' plan-time Parallel-safe: line is a deliberately different free-text form, do NOT unify -->
-
 ```
 Parallel-safe: <group>[; <group>]*
   <group> = <comma-separated gap-id list> " disjoint"
@@ -131,6 +129,8 @@ Any **file OR runtime-resource** overlap forces the conflicting gaps into separa
 serial waves — identical to planned-execution wave grouping. Runtime-resource disjointness is not machine-checkable; estimate it over: DB/schema, port, fixture, external service, shared temp path. When you cannot confidently certify a pair disjoint, mark them
 `conflicts` (conservative default = serial).
 
+Footer order: `Parallel-safe:` is the final line of the report.
+
 ### `recommended` selection policy
 
 `recommended` is a proposal; you never decide, edit, dispatch, or re-audit.

package/agents/spec-reviewer.md

@@ -77,8 +77,6 @@ end the findings with one partition line over the `Fn` IDs assigned above; when
 a task requires a trailing `TRAJECTORY:` verdict (re-review), that verdict
 follows it as the true final line:
 
-<!-- grammar identical to skills/subagent-driven-development/spec-reviewer-prompt.md — change them together or not at all; writing-plans' plan-time Parallel-safe: line is a deliberately different free-text form, do NOT unify -->
-
 ```
 Parallel-safe: <group>[; <group>]*
   <group> = <comma-separated finding-id list> " disjoint"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "5.18.2",
+  "version": "5.18.3",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "author": "Jacek Juraszek",
   "type": "module",

package/skills/dispatching-parallel-agents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dispatching-parallel-agents
-description: Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
+description: "Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies, when fanning out review-finding fixes in parallel, or when checking a reviewer's Parallel-safe: line before doing so"
 ---
 
 > **Related skills:** Verify all fixes with `/skill:verification-before-completion`.

package/skills/gatekeep-pr/reference/decision-menu.md

@@ -94,7 +94,7 @@ the reason: `reviewer still running` or `comments not refreshed`. This is a
 menu-level gate modelled on the `flaky` disposition's custom-row path, never
 a `## Verdict` precondition: `### Merge course` does not refuse the override.
 Only the custom row's `merge-squash anyway` / `merge-commit anyway` executes
-merge in that state, under the normal Merge course rules.
+merge in that state, under the normal Merge course rules. Apply the comment-delta consent and incomplete-review rules in `post-selection-loop.md` `### Compare-and-swap` and `### Re-render`; `anyway` does not bypass an unreviewed delta or a blocking finding.
 
 `wait` is `[recommended]` in cells whose recommended course would otherwise
 be `merge-*` or `approve` (clean / follow-ups only, and the post-fix
@@ -187,7 +187,26 @@ Pick one:
 ```
 
 (b) The run concluded `success`; the reviewer check moved from pending to
-`success` in the refreshed rollup and the comment carries the verdict:
+`success` in the refreshed rollup and the comment carries the verdict. Reconcile C5 against source at the assessed head. For a confirmed retry bug missed by the previous source review, mint source-backed P11 and withhold merge; C5's triage label remains verdict-neutral:
+
+```markdown
+## Findings (blocking)
+Blocking findings (P#):
+  P11. **<source_ref>** - Retry attempts never increment. Fix: increment attempts on failure and throw after the retry limit. | Action: fix P11. [code]
+## Comment-thread replies
+  C1. <thread ref> -> superseded by C3
+  C2. <thread ref> -> superseded by C4
+  C3. <thread ref> -> superseded by C5
+  C4. <thread ref> -> <drafted reply>  (reasonable)
+  C5. <thread ref> -> <drafted reply>  (reasonable)
+Pick one:
+  1. fix P11   [recommended]
+  2. stop
+  3. review-comment
+  4. Custom
+```
+
+When source review instead disproves C5's concern, mint no `P#` and retain the clean menu:
 
 ```markdown
 ## Comment-thread replies
@@ -204,3 +223,5 @@ Pick one:
   4. review-comment
   5. Custom
 ```
+
+Golden fixture 4 - last premerge refetch finds a new human comment after merge consent. Reconcile it against source at the assessed head, abort that merge even when the concern is false, and show the refreshed menu for a new selection. A same-head identical-body timestamp edit mints the next `C#` but causes no repeat source review or test run. A bot placeholder or error header keeps its existing state and does not enter source review.

package/skills/gatekeep-pr/reference/post-selection-loop.md

@@ -6,7 +6,7 @@ Read from SKILL.md `## Act`. Treat the menu as a state machine: execute only the
 
 ### Compare-and-swap
 
-Before every external write, re-fetch `headRefOid`, `state`, and `mergeable`. Any change since assessment invalidates the current state - re-sync the worktree, re-run Phase 3 per `assessment.md` `## Phase 3 - Verify, then review`, and re-render the menu. Exception: a course's own push updates the assessed head to the pushed SHA as part of that course's execution - this self-inflicted head move does not invalidate the course; the next compare-and-swap check runs against the new head on the next external write. Before a merge executes (plain or `anyway`), also run one comment refetch with placeholder detection and the reviewer-run check (`### Re-render` steps 1-2). A newly `pending` row, a queued/in-progress reviewer run, or a failed refetch (`comments not refreshed (<reason>)`) refuses a plain merge and re-renders; `anyway` proceeds and prints what it overrode.
+Before every external write, re-fetch `headRefOid`, `state`, and `mergeable`. Any change since assessment invalidates the current state - re-sync the worktree, re-run Phase 3 per `assessment.md` `## Phase 3 - Verify, then review`, and re-render the menu. Exception: a course's own push updates the assessed head to the pushed SHA as part of that course's execution - this self-inflicted head move does not invalidate the course; the next compare-and-swap check runs against the new head on the next external write. Before a merge executes (plain or `anyway`), run the full comment refetch and reconciliation (`### Re-render` steps 1-5), not just placeholder detection. If the head changed, follow the re-assessment rule above instead. A new or changed-body delta since the consent render aborts the selected merge, plain or `anyway`: show the reconciled report and request a fresh selection even when no blocker resulted. A newly `pending` row, a queued/in-progress reviewer run, or a failed refetch (`comments not refreshed (<reason>)`) refuses a plain merge and re-renders; `anyway` overrides only those existing pending/refetch-failure overlays and prints what it overrode, never a new blocker or unreviewed delta.
 
 ### Fix wave
 
@@ -28,7 +28,7 @@ Merge always executes as `gh pr merge --match-head-commit <assessed-sha>`. Push
 
 ### Re-render
 
-After any mutation that can change readiness (fix wave pushed, docs pushed, PR head moved), re-run the claim-check and Review on the synced worktree: claims are re-checked against the new head and findings are re-rendered, but do not re-execute the verification command here - the fix wave's evidence re-resolution already was the wave's one gate pass. Annotate each selected `P#`/`L#` confirmed resolved as `(fixed in <sha>)` under its original ID; unresolved ones stay open unchanged; new findings continue the sequence. Then refetch comments - the last read before the menu renders:
+After every push or any mutation that can change readiness (fix wave pushed, docs pushed, PR head moved), re-run the claim-check and Review on the synced worktree: claims are re-checked against the new head and findings are re-rendered, but do not re-execute the verification command here - the fix wave's evidence re-resolution already was the wave's one gate pass. Annotate each selected `P#`/`L#` confirmed resolved as `(fixed in <sha>)` under its original ID; unresolved ones stay open unchanged; new findings continue the sequence. Then refetch comments - the last read before the menu renders:
 
 1. Re-run the Section A comment fetches (`../verification-brief.md`: both `--paginate` calls, plus the GraphQL `reviewThreads` query when the initial gather used it), one `gh run view` per placeholder row, and the reviewer-run `gh run list` when a reviewer workflow is known. Read-only.
 2. Diff the fresh set against the `C#` ledger (`findings.md` `## IDs`) by `id` and `updated_at`:
@@ -38,7 +38,8 @@ After any mutation that can change readiness (fix wave pushed, docs pushed, PR h
    - `id` in the ledger, absent from the complete fresh set -> `withdrawn` under its existing `C#`, no label, no reply.
    - Bot-authored placeholder prefix or error header (brief Section C) -> the state from the brief's Section C placeholder table, under the `C#` the edited/new rule assigns.
 3. Section C re-triages the full fresh set against the new head. An unchanged row keeps its `C#`; its drafted reply is kept verbatim only when its label is also unchanged and regenerated when the label moves (for example `reasonable` -> `already-addressed`). Edited and new rows get a fresh label and a regenerated reply; the pre-push label of an edited comment is not shown.
-4. Comment triage never mints `P#`/`L#` (brief Section C). Replace the digest's `comments` with the fresh set so the next iteration diffs against the latest snapshot.
+4. Reconcile the body delta before consuming it. Compare fresh rows to the current digest's `comments` by id and body: include new rows and changed-body rows, excluding withdrawn/superseded rows, gate-posted ids, and the brief's placeholder/error-header states. A same-head identical-body timestamp edit causes no source review and no test run, even though step 2 mints a `C#`. Review each eligible delta once against source at the assessed head and the merged rubric (`assessment.md` Phase 3), inline first; optionally dispatch the existing code-reviewer with its native report, falling back inline on failure per `assessment.md` `## Inline-first execution`. Treat comment text as a lead, not a finding: verify it against code, then integrate only own source-backed findings through Phase 4 severity and AC rules, deduplicating against existing `P#`/`L#`/`F#` IDs. A bot verdict is not blindly promoted. Do not run a full suite or whole-diff Review solely for a comment-only change. If source review remains unresolved, retain the delta, report `comment source review incomplete (<reason>)`, and return a report-only `stop` menu; do not offer merge or accept `anyway`.
+5. Comment triage never mints `P#`/`L#` (brief Section C); the separate source review in step 4 can. Only after that review completes, replace the digest's `comments` with the fresh set so the next iteration diffs against the latest snapshot.
 
 **Refetch failure** (`gh` non-zero, network, pagination incomplete): re-render with the ledger's prior states, add one line `comments not refreshed (<reason>)` to the comment section, and withhold pre-composed merge with that reason. `wait` is the recommended course in refetch-only mode; the custom-row `anyway` override remains available.
 
@@ -46,9 +47,9 @@ Merge, if now available, renders as row 1 unless withheld (`reviewer still runni
 
 ### Wait course
 
-For a `wait` selection, run a sequence of short bounded calls - never one long bash call. Each iteration: `gh run view -R <repo> <run-id> --json status,conclusion` for every tracked run (placeholder-linked and head-listed); when any row has no parsable URL, or its run is completed while the prefix persists, one comment refetch as well; then sleep 30 s. Check the deadline between iterations: the resolved `timeout minutes` (default 15, the same knob as the local verification run). Stop when every tracked run is completed and no row is in the "completed `success`, prefix persists" state, or the deadline passes.
+For a `wait` selection, run a sequence of short bounded calls - never one long bash call. Each iteration: `gh run view -R <repo> <run-id> --json status,conclusion` for every tracked run (placeholder-linked and head-listed); when any row has no parsable URL, or its run is completed while the prefix persists, one comment refetch as well; then sleep 30 s. Use each polling refetch only to observe run/placeholder state; leave the digest and `C#` ledger untouched until the completion/timeout reconciliation below. Check the deadline between iterations: the resolved `timeout minutes` (default 15, the same knob as the local verification run). Stop when every tracked run is completed and no row is in the "completed `success`, prefix persists" state, or the deadline passes.
 
-Then re-fetch `statusCheckRollup`, `headRefOid`, `state`, `mergeable` for the assessed head and re-resolve the brief's Evidence table on the fresh rollup; run the verification command only when the re-resolved table selects the Fallback row and no evidence exists yet for this head (the Pending row never ran it) - otherwise the existing evidence stands: the head is unchanged, so the wave's evidence stays valid and the Stale head row does not fire. Run the refetch (steps 1-4 above) and re-render the comment section, evidence, and menu; no claim-check or Review re-run, because the head did not move. On timeout: rows in the completed-`success`/prefix-persists state become `reviewer failed (stale placeholder)` (brief Section C placeholder table); every other `pending` row stays `pending`, merge stays withheld, `wait` renders as row 1 again, then the cell's courses, then Custom.
+Then re-fetch `statusCheckRollup`, `headRefOid`, `state`, `mergeable`. If the head advanced or state/mergeability changed, route through compare-and-swap re-assessment before reusing evidence or reviewing comments; otherwise re-resolve the brief's Evidence table on the fresh rollup; run the verification command only when the re-resolved table selects the Fallback row and no evidence exists yet for this head (the Pending row never ran it) - otherwise the existing evidence stands: the head is unchanged, so the wave's evidence stays valid and the Stale head row does not fire. On completion or timeout, run the refetch (steps 1-5 above) and re-render the comment section, evidence, findings, and menu; do not re-run claim-check or whole-diff Review solely because the head did not move. On timeout: rows in the completed-`success`/prefix-persists state become `reviewer failed (stale placeholder)` (brief Section C placeholder table); every other `pending` row stays `pending`, merge stays withheld, `wait` renders as row 1 again, then the cell's courses, then Custom.
 
 ### Teardown
 

package/skills/gatekeep-pr/verification-brief.md

@@ -75,15 +75,16 @@ result as not merge-ready. Bot author noted
         isCrossRepository, mergeable, headRefOid, files, additions, deletions, reviewDecision }
 - viewer: { login, is_author, permission }
 - status_checks: [ { name, status, conclusion, required, url, workflowName } ]   # evidence semantics: Section B Evidence resolution; workflowName from the CheckRun rollup entry (absent on StatusContext)
-- comments: { inline[ { id, updated_at, user_type, ... } ], top_level[ { id, updated_at, user_type, ... } ], review_threads[]? }   # id/updated_at/user_type from the REST payload; the C# ledger (reference/findings.md ## IDs) diffs on id/updated_at, Section C gates placeholder detection on user_type
+- comments: { inline[ { id, updated_at, user_type, body, ... } ], top_level[ { id, updated_at, user_type, body, ... } ], review_threads[]? }   # retain REST body for source-review deltas; C# identity diffs on id/updated_at, Section C gates placeholder detection on user_type
 - issue: { ref, title, body, acceptance_criteria[], comments[] } | null
 - worktree_discovery: { expected_path, exists, branch, dirty, ahead, behind }
 - truncation_notes: []
 ```
 
-Every entry under `comments.inline[]` and `comments.top_level[]` records `id`,
-`updated_at`, and `user_type` (REST `user.type`) from the payload the
-`--paginate` calls already return.
+Retain `id`, `updated_at`, `body`, and `user_type` (REST `user.type`) in every
+entry under `comments.inline[]` and `comments.top_level[]` from the payload
+the `--paginate` calls already return. Keep body text for the reconciliation
+baseline; do not substitute the drafted reply or triage label.
 `review_threads[]` stays resolution flags only: `C#` identity comes from inline
 and top-level comment ids, so a thread's inline comments are diffed once, as
 inline comments.
@@ -239,7 +240,7 @@ alone when none is (never inventing ACs either way).
 each labeled one of: already-addressed, reasonable, judgment-call - except
 placeholder rows, which carry a state instead of a label. Comment triage never
 mints `P#`/`L#`: a landed reviewer verdict is a labelled `C#`; a concern it
-raises becomes a `P#` only through the Reviewer's own finding on the code.
+raises becomes a `P#` only through source-backed review on the code (`reference/post-selection-loop.md` `### Re-render` step 4 for refetched body deltas).
 
 **Placeholder detection.** A comment - inline or top-level - whose author is
 a GitHub App (digest `user_type == "Bot"`, from REST `user.type`) and whose body's first line starts

package/skills/receiving-code-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: receiving-code-review
-description: Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation
+description: Use when receiving code review feedback from a human or external reviewer (GitHub review, human partner), before implementing suggestions, especially when feedback is unclear or technically questionable - verify, push back with evidence, never perform agreement; the subagent-driven-development review-fix loop is out of scope
 ---
 
 > **Related skills:** Verify each fix with `/skill:verification-before-completion`. Use `/skill:test-driven-development` for regression tests.
@@ -51,7 +51,7 @@ WHY: Items may be related. Partial understanding = wrong implementation.
 
 **Example:**
 ```
-your human partner: "Fix 1-6"
+your human partner: "Fix items 1-6"
 You understand 1,2,3,6. Unclear on 4,5.
 
 ❌ WRONG: Implement 1,2,3,6 now, ask about 4,5 later
@@ -130,6 +130,13 @@ Push back when:
 
 **Signal if uncomfortable pushing back out loud:** "Strange things are afoot at the Circle K"
 
+**Example:**
+
+```
+Reviewer: "Remove legacy code"
+✅ "Checking... build target is 10.15+, this API needs 13+. Need legacy for backward compat. Current impl has wrong bundle ID - fix it or drop pre-13 support?"
+```
+
 ## Gracefully Correcting Your Pushback
 
 If you pushed back and were wrong:
@@ -156,33 +163,6 @@ State the correction factually and move on.
 | Partial implementation | Clarify all items first |
 | Can't verify, proceed anyway | State limitation, ask for direction |
 
-## Real Examples
-
-**Performative Agreement (Bad):**
-```
-Reviewer: "Remove legacy code"
-❌ "You're absolutely right! Let me remove that..."
-```
-
-**Technical Verification (Good):**
-```
-Reviewer: "Remove legacy code"
-✅ "Checking... build target is 10.15+, this API needs 13+. Need legacy for backward compat. Current impl has wrong bundle ID - fix it or drop pre-13 support?"
-```
-
-**YAGNI (Good):**
-```
-Reviewer: "Implement proper metrics tracking with database, date filters, CSV export"
-✅ "Grepped codebase - nothing calls this endpoint. Remove it (YAGNI)? Or is there usage I'm missing?"
-```
-
-**Unclear Item (Good):**
-```
-your human partner: "Fix items 1-6"
-You understand 1,2,3,6. Unclear on 4,5.
-✅ "Understand 1,2,3,6. Need clarification on 4 and 5 before implementing."
-```
-
 ## GitHub Thread Replies
 
 When replying to inline review comments on GitHub, reply in the comment thread (`gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`), not as a top-level PR comment.

package/skills/requesting-code-review/SKILL.md

@@ -51,42 +51,9 @@ subagent({ agent: "code-reviewer", async: false, task: "... filled template ..."
 - `{DESCRIPTION}` - Brief summary
 - `{SCOPED_TEST_COMMANDS}` - the scoped verification commands the reviewer may run, or `none`
 
-**3. Act on feedback:**
-- Fix Critical issues immediately
-- Fix Moderate issues before proceeding
-- Note Minor issues for later
-- Push back if reviewer is wrong (with reasoning)
-
 **Fix rounds.** Critical and Moderate findings trigger a fix round; when dispatched from an orchestrating skill, fixes go to `implementer` subagents (per the orchestrator's no-self-coding rule), fanned out per `dispatching-parallel-agents` "Fix fan-out" when the review's `Parallel-safe:` line certifies a `disjoint` group of ≥ 2 findings. Before fanning out, validate the review's `Parallel-safe:` line with the structural probe in `dispatching-parallel-agents` § Fix fan-out (exactly-one-line grammar check, one re-ask, then explicit sequential fallback). After integration and the project's test command, re-dispatch the reviewer once on the integrated delta in the foreground with top-level `async: false`; await its terminal result. If Critical or Moderate findings remain, run one more fix round and one more foreground re-review; still failing → escalate to the user. Minor findings never trigger the fan-out.
 
-## Example
-
-```
-[Just completed Task 2: Add verification function]
-
-You: Let me request code review before proceeding.
-
-BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
-HEAD_SHA=$(git rev-parse HEAD)
-
-[Dispatch code-reviewer subagent]
-  WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index
-  PLAN_OR_REQUIREMENTS: Task 2 from doc/plans/deployment-plan.md
-  BASE_SHA: a7981ec
-  HEAD_SHA: 3df7661
-  SCOPED_TEST_COMMANDS: none (whole-branch review; orchestrator gate owns execution)
-  DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
-
-[Subagent returns]:
-  Strengths: Clean architecture, real tests
-  Issues:
-    Moderate: Missing progress indicators
-    Minor: Magic number (100) for reporting interval
-  Assessment: Ready to proceed
-
-You: [Fix progress indicators]
-[Continue to Task 3]
-```
+Take the recipient stance from `receiving-code-review`: verify each finding, answer a wrong finding with evidence, defer Minor items explicitly.
 
 ## Integration with Workflows
 
@@ -107,11 +74,6 @@ You: [Fix progress indicators]
 - Proceed with unfixed Moderate issues
 - Argue with valid technical feedback
 
-**If reviewer wrong:**
-- Push back with technical reasoning
-- Show code/tests that prove it works
-- Request clarification
-
 See template at: `code-reviewer.md` in this skill directory
 
 ## Project overrides

package/skills/requesting-code-review/code-reviewer.md

@@ -15,7 +15,7 @@ You are reviewing code changes for production readiness.
 2. Compare against {PLAN_OR_REQUIREMENTS}
 3. Check code quality, architecture, testing
 4. Categorize issues by severity
-5. Flag plan deviations explicitly
+5. Report each plan deviation as a finding: what the plan says, what the code does, whether the deviation is acceptable.
 6. Assess production readiness
 
 SCOPED_TEST_COMMANDS: {SCOPED_TEST_COMMANDS}
@@ -25,9 +25,7 @@ SCOPED_TEST_COMMANDS: {SCOPED_TEST_COMMANDS}
 Before writing the report:
 
 - **Not everything is Critical.** Reserve Critical for bugs, data loss, security, broken functionality. A missing helper method is Moderate. A naming preference is Minor.
-- **Lead with strengths.** Accurate praise earns the implementer's trust on the critique that follows. Generic praise ("good code") undermines it.
 - **If you wouldn't block a PR over it, it's not Critical.** Be honest with yourself about severity before assigning it.
-- **Plan deviations get their own treatment.** If the implementation diverged from the spec/plan — added scope, removed scope, changed an interface — call it out under a dedicated "Plan Deviations" heading, not buried in Critical or Minor.
 
 ## What Was Implemented
 
@@ -80,124 +78,4 @@ git diff {BASE_SHA}..{HEAD_SHA}
 - Documentation complete?
 - No obvious bugs?
 
-## Output Format
-
-### Strengths
-[What's well done? Be specific.]
-
-### Plan Deviations
-[Did the implementation diverge from {PLAN_OR_REQUIREMENTS}? List each deviation with: what the spec said, what the code does, whether the deviation is acceptable. If none, write "None."]
-
-### Issues
-
-#### Critical (Must Fix)
-[Bugs, security issues, data loss risks, broken functionality]
-
-#### Moderate (Should Fix)
-[Architecture problems, missing features, poor error handling, test gaps]
-
-#### Minor (Nice to Have)
-[Code style, optimization opportunities, documentation improvements]
-
-**For each issue:**
-- `Fn` label - globally unique, numbered across the whole report (no restart per severity section)
-- File:line reference
-- What's wrong
-- Why it matters
-- How to fix (if not obvious)
-- `touched-files:` - files a fix would edit (not just the evidence location), comma-separated, or the literal `none`
-- `touched-resources:` - shared runtime resources a fix or its verification touches (DB/schema, port, fixture, external service, shared temp path), or the literal `none`
-
-### Recommendations
-[Improvements for code quality, architecture, or process]
-
-### Assessment
-
-**Ready to merge?** [Yes/No/With fixes]
-
-**Reasoning:** [Technical assessment in 1-2 sentences]
-
-### Fix-concurrency certification
-
-On any issue-bearing review, emit one partition line over the
-`Fn` IDs assigned above:
-
-<!-- grammar identical to agents/conformance-reviewer.md (modulo G vs F id prefix) — change them together or not at all; writing-plans' plan-time Parallel-safe: line is a deliberately different free-text form, do NOT unify -->
-
-```
-Parallel-safe: <group>[; <group>]*
-  <group> = <comma-separated finding-id list> " disjoint"
-          | <finding-id> " conflicts " <finding-id> " (" <reason> ")"
-```
-
-Example: `Parallel-safe: F1,F3 disjoint; F2 conflicts F1 (both touch auth.ts)`
-
-IDs inside a `disjoint` list are mutually parallel-safe (their fixes can run
-concurrently). Any file OR runtime-resource overlap between two findings' fixes
-forces `conflicts`. Runtime-resource disjointness is estimated over: DB/schema,
-port, fixture, external service, shared temp path. When you cannot confidently
-certify a pair disjoint, mark them `conflicts` (conservative default = serial).
-
-Footer order: `Parallel-safe:` when present (issue-bearing reviews only), then `Behaviour-change:` on **every** report including clean ones, then `TRAJECTORY:` when a re-review trigger fired - `TRAJECTORY:` stays the true final line. `Behaviour-change: yes` when applying any Critical or Moderate fix would alter observable behaviour - values, control flow, routing, emitted output, persisted state; `no` when every fix is structural or stylistic, and on clean reports.
-
-## Critical Rules
-
-**DO:**
-- Categorize by actual severity (not everything is Critical)
-- Be specific (file:line, not vague)
-- Explain WHY issues matter
-- Acknowledge strengths
-- Give clear verdict
-
-**DON'T:**
-- Say "looks good" without checking
-- Mark nitpicks as Critical
-- Give feedback on code you didn't review
-- Be vague ("improve error handling")
-- Avoid giving a clear verdict
-
-## Example Output
-
-```
-### Strengths
-- Clean database schema with proper migrations (db.ts:15-42)
-- Comprehensive test coverage (18 tests, all edge cases)
-- Good error handling with fallbacks (summarizer.ts:85-92)
-
-### Issues
-
-#### Moderate
-F1. **Missing help text in CLI wrapper**
-   - File: index-conversations:1-31
-   - Issue: No --help flag, users won't discover --concurrency
-   - Fix: Add --help case with usage examples
-   - touched-files: index-conversations.ts
-   - touched-resources: none
-
-F2. **Date validation missing**
-   - File: search.ts:25-27
-   - Issue: Invalid dates silently return no results
-   - Fix: Validate ISO format, throw error with example
-   - touched-files: search.ts
-   - touched-resources: none
-
-#### Minor
-F3. **Progress indicators**
-   - File: indexer.ts:130
-   - Issue: No "X of Y" counter for long operations
-   - Impact: Users don't know how long to wait
-   - touched-files: indexer.ts
-   - touched-resources: none
-
-### Recommendations
-- Add progress reporting for user experience
-- Consider config file for excluded projects (portability)
-
-### Assessment
-
-**Ready to merge: With fixes**
-
-**Reasoning:** Core implementation is solid with good architecture and tests. Moderate issues (help text, date validation) are easily fixed and don't affect core functionality.
-
-Parallel-safe: F1,F2,F3 disjoint
-```
+Report in the output format `agents/code-reviewer.md` defines in your system prompt.

package/skills/subagent-driven-development/SKILL.md

@@ -179,7 +179,7 @@ Auto-selected at handoff by `writing-plans` (any wave with ≥2 tasks) when the
 
 **Caveat:** each task must be independently runnable and verifiable in a fresh worktree — no reliance on uncommitted local state. `pi-cohort` symlinks `node_modules`; repos needing other per-worktree setup must account for it.
 
-**Set `cwd` to your worktree — resilience-critical.** The work lives in a worktree while the process stays in the primary checkout, and the `subagent` tool resolves the worktree base from the **top-level `cwd``, which defaults to the orchestrator's process cwd — the *primary* checkout (usually `main`), not the worktree. Omit `cwd` and `worktree: true` branches every child from the primary checkout's HEAD: the children never see your spec, plan, or prior-wave commits, and integration runs against the wrong baseline. Pass the worktree's absolute path as the top-level `cwd`. Do **not** set per-task `cwd` under `worktree: true` — pi-cohort requires it to equal the shared cwd and errors otherwise. (Clean-tree is enforced here too — `resolveRepoState` rejects a dirty tree — which is why each wave commits before the next.)
+Pass the worktree's absolute path as the top-level `cwd` on every dispatch; rule and rationale: `dispatching-parallel-agents` "pi-cohort Integration".
 
 ```bash
 REPORT_DIR=$(mktemp -d)
@@ -226,20 +226,52 @@ For the fan-out + worktree + patch-integration + conflict mechanics, see `dispat
 
    **Happy-path run - first action of this step, only when the plan header carries a `**Happy path:**` line or the diff selects a row.** The overrides file's `## Happy path` table (schema in the README overrides contract) names path-prefixed rows; the plan header's line is the plan-time default.
 
-   1. Bind `HP_DIR=$(mktemp -d)` first. Re-derive the row from `git -C "<worktree>" diff --name-only <base>..HEAD` (`<base>` = the branch point): two or more non-`cross-cutting` rows, or a path inside the `cross-cutting` row's own `Paths` and inside no other row's -> `cross-cutting`, taking precedence (no `cross-cutting` row -> no run and no outcome line); else paths inside exactly one non-`cross-cutting` row's `Paths` -> that row; none -> no run and no outcome line. Run the diff-derived row; when it differs from the header label, record `row: <diff-derived> (header: <label>)` in `summary.txt`.
-   2. Pre-checks: bind `TO=$(command -v timeout || command -v gtimeout)` -> else `not run - no timeout binary`; the command's first token after any leading `NAME=value` assignments resolves via `(cd "<abs worktree path>" && bash -c 'command -v <token>')` -> else `not run - command not found` (a header present but the script missing from the branch lands here; never a gap). A pre-check failure still writes `$HP_DIR/summary.txt` with only the outcome, `head:`, and `row:` lines (no blank line, no tail - there is no `transcript.log`) and counts as a run for the reviewer input and the closure sentinel.
-   3. Snapshot `git -C "<worktree>" status --porcelain --untracked-files=all`, then run, with `<duration>` = the row's `Timeout` (default `10m`) and `HP_CMD` holding the row's command verbatim:
+   1. Re-derive the row from `git -C "<worktree>" diff --name-only <base>..HEAD` (`<base>` = the branch point): two or more non-`cross-cutting` rows, or a path inside the `cross-cutting` row's own `Paths` and inside no other row's -> `cross-cutting`, taking precedence (no `cross-cutting` row -> no run and no outcome line); else paths inside exactly one non-`cross-cutting` row's `Paths` -> that row; none -> no run and no outcome line. Run the diff-derived row; when it differs from the header label, record `row: <diff-derived> (header: <label>)` in `summary.txt`.
+   2. Substitute shell-quoted literal values for every placeholder in this one bash block: the absolute worktree path, command verbatim, first command token after leading `NAME=value` assignments, duration (default `10m`), diff-derived row, and optional header label (use the row label when absent). Derive the token from the declared command without evaluating it or parsing general shell grammar. Run the entire block in one tool call; do not carry shell variables between calls. Read its printed summary path and outcome for subsequent tools.
 
+      <!-- happy-path-shell -->
       ```bash
-      (cd "<abs worktree path>" && "$TO" -k 30s <duration> bash -c "$HP_CMD") >"$HP_DIR/transcript.log" 2>&1
-      EXIT=$?
+      HP_WORKTREE={{HP_WORKTREE}}
+      HP_CMD={{HP_COMMAND}}
+      HP_TOKEN={{HP_TOKEN}}
+      HP_DURATION={{HP_DURATION}}
+      HP_ROW={{HP_ROW}}
+      HP_HEADER={{HP_HEADER}}
+      HP_DIR=$(mktemp -d) || exit 1
+      HEAD=$(git -C "$HP_WORKTREE" rev-parse HEAD) || exit 1
+      HP_LABEL=$HP_ROW
+      if [[ "$HP_HEADER" != "$HP_ROW" ]]; then HP_LABEL="$HP_ROW (header: $HP_HEADER)"; fi
+      if ! TO=$(command -v timeout || command -v gtimeout); then
+        OUTCOME='happy-path: not run - no timeout binary'
+      elif [[ -z "$HP_TOKEN" || -z "${HP_CMD//[[:space:]]/}" ]] || ! (cd "$HP_WORKTREE" && command -v "$HP_TOKEN" >/dev/null); then
+        OUTCOME='happy-path: not run - command not found'
+      else
+        BEFORE=$(git -C "$HP_WORKTREE" status --porcelain --untracked-files=all) || exit 1
+        if (cd "$HP_WORKTREE" && "$TO" -k 30s "$HP_DURATION" bash -c "$HP_CMD") >"$HP_DIR/transcript.log" 2>&1; then
+          EXIT=0
+        else
+          EXIT=$?
+        fi
+        AFTER=$(git -C "$HP_WORKTREE" status --porcelain --untracked-files=all) || exit 1
+        if [[ "$BEFORE" != "$AFTER" ]]; then
+          OUTCOME="happy-path: failed - dirtied worktree: ${AFTER//$'\n'/; }"
+        elif [[ "$EXIT" == 0 ]]; then
+          OUTCOME='happy-path: passed'
+        elif [[ "$EXIT" == 75 ]]; then
+          OUTCOME="happy-path: not run - environment unavailable: $(tail -n 1 "$HP_DIR/transcript.log")"
+        elif [[ "$EXIT" == 124 || "$EXIT" == 137 ]]; then
+          OUTCOME="happy-path: failed - timed out after $HP_DURATION"
+        elif [[ "$EXIT" == 126 ]]; then
+          OUTCOME='happy-path: not run - not executable'
+        else
+          OUTCOME="happy-path: failed (exit $EXIT)"
+        fi
+      fi
+      { printf '%s\nhead: %s\nrow: %s\n' "$OUTCOME" "$HEAD" "$HP_LABEL"; if [[ -f "$HP_DIR/transcript.log" ]]; then printf '\n'; tail -n 200 "$HP_DIR/transcript.log"; fi; } >"$HP_DIR/summary.txt" || exit 1
+      printf 'summary: %s\noutcome: %s\n' "$HP_DIR/summary.txt" "$OUTCOME"
       ```
 
-   4. Re-snapshot status; any difference (tracked or untracked residue) is `failed - dirtied worktree: <paths>` regardless of exit code; never stage or commit the listed paths as deliverables - remove untracked residue and restore tracked residue (`git -C "<worktree>" checkout -- <paths>`) before the conformance dispatch, so the tree is clean when the audit-time input rule runs and the closure freshness rule never fires on happy-path artifacts at finish. Then classify the outcome per the table and write the summary:
-
-      ```bash
-      { echo "<outcome line per table>"; echo "head: $(git -C "<abs worktree path>" rev-parse HEAD)"; echo "row: <label>"; echo; tail -n 200 "$HP_DIR/transcript.log"; } >"$HP_DIR/summary.txt"
-      ```
+   3. If the block exits non-zero or its printed summary is missing/unreadable, stop verification and report the shell error; never dispatch conformance with the selected run omitted. Distinguish this runner failure from a command's `failed`/`not run` outcome recorded in a readable summary. Treat any status difference (tracked or untracked residue) as failed regardless of exit code. Never stage or commit the listed paths as deliverables; remove untracked residue and restore tracked residue (`git -C "<worktree>" checkout -- <paths>`) explicitly before the conformance dispatch, so the tree is clean when the audit-time input rule runs.
 
    | Condition | Outcome line |
    |---|---|
@@ -252,7 +284,7 @@ For the fan-out + worktree + patch-integration + conflict mechanics, see `dispat
    | any other non-zero | `happy-path: failed (exit <n>)` |
    | no header line and no diff-derived row | no run, no outcome line |
 
-   A timeout is `failed`, not `not run`: a consumer that never receives its message hangs, and the reviewer must see it; `not run` is reserved for a command that never executed. `timeout -k 30s` sends `TERM` then `KILL`; a script that does not trap `TERM` leaves its stack up, and the next run's exit 75 surfaces that. The full `transcript.log` stays in `$HP_DIR` for the human; the reviewer receives `summary.txt` only (outcome, `head:`, `row:`, 200-line tail). A `failed` or `not run` outcome never stops the flow and never becomes a repair item at this step - it is evidence for the audit; `$HP_DIR` and the outcome carry into the fix loop per `conformance-check.md`. Run sub-steps 3-4 (snapshot, run, re-snapshot, classify, summary) in one bash call, or substitute the literal `HP_DIR` and `TO` values into each later command: shell variables do not survive between tool calls.
+   A timeout is `failed`, not `not run`: a consumer that never receives its message hangs, and the reviewer must see it; `not run` is reserved for a command that never executed. `timeout -k 30s` sends `TERM` then `KILL`; a script that does not trap `TERM` leaves its stack up, and the next run's exit 75 surfaces that. The full `transcript.log` stays in `$HP_DIR` for the human; the reviewer receives `summary.txt` only (outcome, `head:`, `row:`, 200-line tail). A `failed` or `not run` outcome never stops the flow and never becomes a repair item at this step - it is evidence for the audit; `$HP_DIR` and the outcome carry into the fix loop per `conformance-check.md`. Never split the shell block across calls.
 
    Before marking verify complete, dispatch a fresh-context **`conformance-reviewer`** — its **own** dispatch, never fused into the step-2 review — to confront the deliverable (code **and** docs) against the *origin* — the spec **and** the original prompt — per `verification-before-completion/reference/conformance-check.md`. Pass the spec path, the verbatim original prompt, the full diff, and - when a run happened - `Happy path: <abs path to $HP_DIR/summary.txt> (<outcome>)` (`<outcome>` = the outcome line without its `happy-path: ` prefix). Follow that reference for the partition rule, concern decomposition, and fix-loop mechanics; do not reimplement them here. The fix loop reuses durable `Gn` gap indices as defined in conformance-check.md; it never calls `phase_tracker`. Call `phase_tracker({ action: "complete", phase: "verify" })` only when the reference says the handoff is durably complete: either a current `CONFORMS` result, or a current `## Closure / conformance` inventory whose carried-open concerns all come from valid deferred gaps, including `recommended: fix` gaps carried open because a declared precondition made the fix loop unavailable (`maxFixRounds: 0`, or no eligible named-branch worktree). A started positive-cap fix loop that blocks, fails, or exhausts its rounds with an open `fix` gap is escalation, not completion; on escalation, do not complete verify, stop and report.
 4. Summarize what was implemented (tasks completed, files changed, test counts, code-review verdict). Emit the `## Closure / conformance` block exactly as defined in `verification-before-completion/reference/conformance-check.md`: it must open with the sentinel (`status: CONFORMS (0 open)` or `status: GAPS (N open)`, then `audited-base: <full HEAD SHA>`, then - exactly when a happy-path run happened - `happy-path: <value of the reviewer's Happy path: line from the final audit, the text after Happy path: >`), then carry the exact durable concern schema by reference with no renamed or reformatted fields. `finishing-a-development-branch` Step 3.5 consumes that block verbatim.

package/skills/subagent-driven-development/code-quality-reviewer-prompt.md

@@ -23,11 +23,7 @@ Dispatch a subagent with the code-reviewer template:
 - Is the implementation following the file structure from the plan?
 - Did this implementation create new files that are already large, or significantly grow existing files? (Don't flag pre-existing file sizes — focus on what this change contributed.)
 
-**Code reviewer returns:** Strengths, Issues (Critical/Moderate/Minor), Assessment
-
-Emit finding IDs and the `Parallel-safe:` line per that contract, then the `Behaviour-change:` line.
-
-Footer order: `Parallel-safe:` when present (issue-bearing reviews only), then `Behaviour-change:` on **every** report including clean ones, then `TRAJECTORY:` when a re-review trigger fired - `TRAJECTORY:` stays the true final line. `Behaviour-change: yes` when applying any Critical or Moderate fix would alter observable behaviour - values, control flow, routing, emitted output, persisted state; `no` when every fix is structural or stylistic, and on clean reports.
+Read `Verdict:` and the footer lines from the report; `agents/code-reviewer.md` defines its format.
 
 ## Re-review: trajectory verdict
 

package/skills/subagent-driven-development/implementer-prompt.md

@@ -103,7 +103,7 @@ Dispatch a subagent with this prompt:
 
     **Testing:**
     - Do tests actually verify behavior (not just mock behavior)?
-    - Did I follow TDD — failing test first for production code?
+    - Did I follow TDD (step 2)?
     - Are tests comprehensive?
 
     If you find issues during self-review, fix them now before reporting.

package/skills/subagent-driven-development/spec-reviewer-prompt.md

@@ -91,32 +91,7 @@ Dispatch a subagent with this prompt:
 
     **Verify by reading code, not by trusting report.**
 
-    ### Finding IDs and fix-concurrency certification
-
-    Label every finding with a globally unique ID `F1..Fn`, numbered across the whole
-    report (no restart per severity section). Each finding carries:
-
-    - `touched-files:` — files a fix would edit (not just the evidence location), comma-separated, or the literal `none`
-    - `touched-resources:` — shared runtime resources a fix or its verification touches (DB/schema, port, fixture, external service, shared temp path), or the literal `none`
-
-    On any issue-bearing review, end the findings with one partition line (this is the
-    final line of the report unless a re-review trajectory verdict is also required — see below):
-
-    <!-- grammar identical to agents/conformance-reviewer.md (modulo G vs F id prefix) — change them together or not at all; writing-plans' plan-time Parallel-safe: line is a deliberately different free-text form, do NOT unify -->
-
-    ```
-    Parallel-safe: <group>[; <group>]*
-      <group> = <comma-separated finding-id list> " disjoint"
-              | <finding-id> " conflicts " <finding-id> " (" <reason> ")"
-    ```
-
-    Example: `Parallel-safe: F1,F3 disjoint; F2 conflicts F1 (both touch auth.ts)`
-
-    IDs inside a `disjoint` list are mutually parallel-safe (their fixes can run
-    concurrently). Any file OR runtime-resource overlap between two findings' fixes
-    forces `conflicts`. Runtime-resource disjointness is estimated over: DB/schema,
-    port, fixture, external service, shared temp path. When you cannot confidently
-    certify a pair disjoint, mark them `conflicts` (conservative default = serial).
+    Report in the output format `agents/spec-reviewer.md` defines in your system prompt.
 
     ## Re-review: trajectory verdict
 
@@ -144,8 +119,4 @@ Dispatch a subagent with this prompt:
 
     If you found no issues, report success as usual and omit this line.
     First reviews (no previous-report section) omit this line.
-
-    Report:
-    - ✅ Spec compliant (if everything matches after code inspection)
-    - ❌ Issues found: [list specifically what's missing or extra, with file:line references]
 ```