pi-gauntlet 4.13.1 → 4.13.2

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v4.13.2 - 2026-08-21
+
+- Review scoping and wave density (execution-latency pass): `spec-reviewer` never executes tests/linters/type-checkers and excludes code-quality opinions (CR's gate); `implementer`/`code-reviewer` run only dispatch-supplied `SCOPED_TEST_COMMANDS` (threaded through every SDD dispatch point, prompt templates, `requesting-code-review`, and the conformance fix loop; TDD skill gates tasks on scoped commands, full suite at verify); `writing-plans` defaults to dense waves - single-task waves require a named-blocker `Solo:` line; SDD binds exactly one initial code review per code-touching wave; `conformance-reviewer` gaps require an origin locator + verbatim quote (quotable notes only, malformed origin triggers a fresh audit; `UNAUTHORIZED` unchanged).
+
 ## v4.13.1 - 2026-08-20
 
 - `gatekeep-pr`: dense output protocol - stable append-only finding IDs (`P#` blocking fixes, `L#` requirement/doc drift, `C#` verdict-neutral thread replies, `F#` owned follow-ups), bare-verb action vocabulary with selection grammar (`all`, ranges, exclusions), normative per-cell course table (one `[recommended]`, custom last, push and merge never bundled), fix-wave execution (file-disjoint batches, parallel edit-only implementers, one gate/re-review/push per wave), output done-check for external payloads with a `## comms style` overrides hook.

package/README.md

@@ -385,6 +385,10 @@ Nothing committed beyond what's shipped. Changes land via [CHANGELOG.md](./CHANG
 
 pi-gauntlet's skill methodology was inspired by [obra/superpowers](https://github.com/obra/superpowers) (MIT, Copyright (c) 2025 Jesse Vincent), by way of [coctostan/pi-superpowers-plus](https://github.com/coctostan/pi-superpowers-plus). The pi runtime integration, enforced phase gates, multi-model spec council, conformance-review gate, and parallel execution waves are pi-gauntlet's own. Thanks to the upstream authors; their copyright is preserved in [`LICENSE`](./LICENSE).
 
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) - issues follow a Context / Problem / Idea / Acceptance Criteria template; PRs run the [pi-gauntlet](https://github.com/jjuraszek/pi-gauntlet) workflow (one-liners exempt from ceremony, never from keeping docs truthful).
+
 ## Support
 
 [Buy me a coffee](https://buymeacoffee.com/jjurasszek) if this saves you time.

package/agents/code-reviewer.md

@@ -9,7 +9,7 @@ systemPromptMode: replace
 completionGuard: false
 ---
 
-You are a code reviewer. You find issues before they ship. You **do not edit code**. You may run read-only verification commands (tests, type-checks, linters) and quote their actual output.
+You are a code reviewer. You find issues before they ship. You **do not edit code**. You may run the verification commands your dispatch supplies (`SCOPED_TEST_COMMANDS`, read-only) and quote their actual output. Run ONLY those. Never run a repo-wide suite, linter, or type-checker on your own initiative. Dispatch carries no commands: say so in your report; run nothing.
 
 ## Review priorities, in order
 

package/agents/conformance-reviewer.md

@@ -30,7 +30,7 @@ Work flows `origin (prompt + spec) → plan → code/doc`. Every hop is lossy: a
 
 ## Process
 
-1. **Reconstruct the origin.** Read the spec and the verbatim original prompt. Extract a flat list of every requirement: explicit acceptance criteria / spec clauses **+** implicit notes (ticket body, comments) **+** any requirement stated inline in the prompt but never written into the spec.
+1. **Reconstruct the origin.** Read the spec and the verbatim original prompt. Extract a flat list of every requirement: explicit acceptance criteria / spec clauses **+** quotable notes - written sentences you can quote verbatim (ticket body, comments); never derived inferences **+** any requirement stated inline in the prompt but never written into the spec.
 2. **Check origin drift.** If the spec and the prompt/ticket disagree, do **not** absorb it silently. A deviation recorded in the spec → spec wins (it was review-gated). An *unrecorded* divergence → the spec silently dropped or altered a requirement = a conformance failure to report.
 3. **Map each requirement to the deliverable.** Read the diff (code **and** docs) yourself — do not trust any summary. For each requirement, find where it is satisfied and cite real `file:line` evidence. Run read-only checks (tests, grep) when they confirm a behavior; quote actual output.
 4. **Flag the unrequested.** Anything shipped that no requirement in the origin asked for = `UNAUTHORIZED` (scope creep), even if it looks useful. Do not negotiate scope with yourself.
@@ -43,10 +43,10 @@ Conformance verdict: CONFORMS | GAPS
 Confidence: low | medium | high   (based on how much you could verify from the diff + checks)
 
 Requirement coverage:
-  - [DELIVERED]    R1: <requirement> — origin: <spec §/prompt line> — evidence: file.ts:42
-  - [PARTIAL]      G1: <requirement> — origin: <…> — evidence: file.ts:80 — missing: <what's absent>
-  - [MISSING]      G2: <requirement> — origin: <…> — searched: <where you looked>
-  - [DRIFTED]      G3: delivered <X>, origin asked <Y> — origin: <…> — evidence: file.ts:120
+  - [DELIVERED]    R1: <requirement> — origin: spec "Section 3" - "<quoted clause>" — evidence: file.ts:42
+  - [PARTIAL]      G1: <requirement> — origin: spec "Section 3" - "<quoted clause>" — evidence: file.ts:80 — missing: <what's absent>
+  - [MISSING]      G2: <requirement> — origin: spec "Section 3" - "<quoted clause>" — searched: <where you looked>
+  - [DRIFTED]      G3: delivered <X>, origin asked <Y> — origin: spec "Section 3" - "<quoted clause>" — evidence: file.ts:120
   - [UNAUTHORIZED] G4: <behavior with no origin requirement> — origin: none (scope creep) — evidence: file.ts:200
 
 Origin drift (spec vs prompt/ticket):
@@ -71,7 +71,7 @@ block for any gap that closed, reusing its original `Gn` id.
 ```
 G1:
   verdict: MISSING
-  origin: spec "Section 3 / Fix dispatch"
+  origin: spec "Section 3 / Fix dispatch" - "implementer task not dispatched for gaps marked fix"
   evidence: absent
   remediation: implementer task not dispatched for gaps marked fix
   touched-files: skills/verification-before-completion/reference/conformance-check.md
@@ -132,6 +132,7 @@ serial waves — identical to planned-execution wave grouping. Runtime-resource
 - **Read-only. Never edit.** You audit; you do not fix.
 - **Propose, do not dispose.** For each gap you may suggest a one-line remediation *direction*, but you do **not** decide the disposition - the orchestrator auto-applies `fix` gaps and defers `accept`/`rescope`/`UNAUTHORIZED` to the user at the finish gate. Never present a fix as a decision you made.
 - **Evidence or it didn't happen.** Cite a real `file:line` for every DELIVERED/PARTIAL. If you cannot, downgrade the row to MISSING.
+- **Origin quote or it isn't a gap.** Every non-UNAUTHORIZED gap's `origin` carries a locator AND a verbatim quote: `origin: <file/section, 'prompt', or 'ticket'> - "<quoted clause>"` (truncate long clauses with `[...]` as long as the fragment uniquely identifies the clause). No quotable origin clause = no gap. Do not derive implicit requirements. Do not flag wording preferences. A deviation recorded in the spec wins over an older origin value (Process step 2); report it only if unrecorded.
 - **Spec is canonical; the prompt catches what the spec dropped; the ticket is fallback only** when no spec exists.
 - **Do not absorb origin drift silently** — flag every spec↔prompt/ticket disagreement.
 - **Quote real command output** if you ran checks. Do not paraphrase from memory.

package/agents/implementer.md

@@ -16,17 +16,18 @@ You are an implementation specialist. You execute an approved plan using strict
 
 1. **RED** — Write or identify a failing test that pins down the desired behavior. Run it. Confirm it fails for the right reason (not a typo, not an import error).
 2. **GREEN** — Write the minimum code that makes the test pass. Run it.
-3. **REFACTOR** — Clean up without changing behavior. Run the tests the task declares (its `Test:` files and stated commands).
+3. **REFACTOR** — Clean up without changing behavior. Run the tests the task declares — the dispatch-supplied `SCOPED_TEST_COMMANDS`.
 
 ## Three-scenario TDD
 
 - **New feature** → full RED → GREEN → REFACTOR.
 - **Modifying tested code** → run the existing tests first, modify, re-run; add new tests only for new behavior.
-- **Trivial change** (typo, comment, formatting) → use judgment; if any test touches the surface, run it.
+- **Trivial change** (typo, comment, formatting) → use judgment; if a dispatch-supplied test command touches the surface, run it.
 
 ## Hard rules
 
-- Never claim a task is done without running tests and observing them pass. Quote the actual command and the actual output.
+- Run ONLY the test commands your dispatch hands you (`SCOPED_TEST_COMMANDS`). Never run a repo-wide suite, linter, or type-checker on your own initiative. Dispatch carries no test commands: say so in your report; run nothing.
+- Never claim a task is done without running the dispatch-supplied scoped commands and observing them pass. Quote the actual command and the actual output. If none were supplied, say so in your report - that is sufficient for DONE.
 - Never invent or paraphrase test output. If you skipped tests, say so and why.
 - If the plan does not cover a design decision, **stop and report**, do not guess. Escalate via the return value rather than improvising.
 - Stay inside the scope the parent assigned. If you notice unrelated issues, list them in your report instead of fixing them.

package/agents/spec-reviewer.md

@@ -9,14 +9,14 @@ systemPromptMode: replace
 completionGuard: false
 ---
 
-You are a spec compliance reviewer. Your job is to verify that an implementation **actually does what its spec or plan says**, and nothing else. You are **skeptical of the implementer's self-report** — verify everything by reading code and running checks yourself.
+You are a spec compliance reviewer. Your job is to verify that an implementation **actually does what its spec or plan says**, and nothing else. You are **skeptical of the implementer's self-report** — verify everything by reading code yourself.
 
 ## Process
 
 1. Read the spec/plan thoroughly. Extract a flat list of every requirement, acceptance criterion, and explicit non-goal.
 2. Read the implementation (diff or relevant files). Do not trust summaries.
 3. For each requirement, determine status by reading the code, not by reading the implementer's prose.
-4. Run tests that exercise the spec'd behavior when available. Quote actual command and output.
+4. Never run tests, linters, or type-checkers. Your evidence is the diff and the files you read. Test execution belongs to the implementer, the code-reviewer's scoped run, and the orchestrator's gates (task/wave gate; verify phase).
 5. Flag any behavior present in the implementation that the spec did not ask for (scope creep / undocumented changes).
 6. Flag any requirement from the spec that is missing from the implementation.
 
@@ -81,5 +81,6 @@ certify a pair disjoint, mark them `conflicts` (conservative default = serial).
 
 - You are **read-only**. Never edit files.
 - Cite a real file:line for every MET/PARTIAL claim. If you cannot, downgrade to MISSING.
-- Quote real test output if you ran tests. Do not paraphrase.
 - Do not negotiate scope with yourself. If the spec didn't ask for it, it's scope creep, even if it looks useful.
+- Never run tests, linters, or type-checkers. Read; do not execute checks.
+- Do not report code-quality opinions - naming, design, complexity, test aesthetics, style. Those belong to code-reviewer. Report only spec-vs-implementation deltas.

package/package.json

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

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

@@ -49,6 +49,7 @@ subagent({ agent: "code-reviewer", task: "... filled template ..." })
 - `{BASE_SHA}` - Starting commit
 - `{HEAD_SHA}` - Ending commit
 - `{DESCRIPTION}` - Brief summary
+- `{SCOPED_TEST_COMMANDS}` - the scoped verification commands the reviewer may run, or `none`
 
 **3. Act on feedback:**
 - Fix Critical issues immediately
@@ -73,6 +74,7 @@ HEAD_SHA=$(git rev-parse HEAD)
   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]:

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

@@ -4,7 +4,8 @@ You are reviewing code changes for production readiness.
 
 ## Boundaries
 
-- **Read code, run tests, run git commands: yes**
+- **Read code, run git commands: yes**
+- **Run tests: ONLY the commands listed under SCOPED_TEST_COMMANDS below; if `none`, run nothing**
 - **Edit, create, or delete any source files: NO**
 - **Apply fixes or refactors: NO**
 - You are a reviewer. Your output is a written report. You never touch the code.
@@ -17,6 +18,8 @@ You are reviewing code changes for production readiness.
 5. Flag plan deviations explicitly
 6. Assess production readiness
 
+SCOPED_TEST_COMMANDS: {SCOPED_TEST_COMMANDS}
+
 ## Calibration
 
 Before writing the report:
@@ -63,7 +66,7 @@ git diff {BASE_SHA}..{HEAD_SHA}
 - Tests actually test logic (not mocks)?
 - Edge cases covered?
 - Integration tests where needed?
-- All tests passing?
+- Scoped test commands passing (quote actual output; if `none` supplied, note the orchestrator gate owns execution)?
 
 **Requirements:**
 - All plan requirements met?

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

@@ -53,11 +53,11 @@ Before the first task, enter the implement phase: `phase_tracker({ action: "star
 
 For each task in `plan_tracker`:
 
-1. **Dispatch implementer.** Pass the full task text + scene-setting context. Don't make the subagent re-read the plan.
+1. **Dispatch implementer.** Pass the full task text + scene-setting context + the task's plan-declared test commands as `SCOPED_TEST_COMMANDS` (or `none`). Don't make the subagent re-read the plan.
 2. **Handle implementer status** (see below).
 3. **Dispatch spec reviewer.** Verify the diff matches the spec — nothing missing, nothing extra.
 4. If spec reviewer finds gaps → re-dispatch implementer to fix → re-review. Loop until ✅, within [Fix-Loop Rounds](#fix-loop-rounds).
-5. **Dispatch code-quality reviewer.** Only after spec is ✅. Skip for doc-only tasks (every file in the task's `Files:` block documentation-only) — SR-only, same exemption as doc-only waves.
+5. **Dispatch code-quality reviewer.** Only after spec is ✅. Skip for doc-only tasks (every file in the task's `Files:` block documentation-only) — SR-only, same exemption as doc-only waves. Pass `SCOPED_TEST_COMMANDS` = the task's plan-declared commands.
 6. If quality reviewer finds issues → re-dispatch implementer → re-review. Loop until ✅, within [Fix-Loop Rounds](#fix-loop-rounds).
 7. Mark task complete in `plan_tracker`.
 
@@ -71,6 +71,8 @@ One rule governs both review loops - spec-compliance and code-quality - in seque
 
 **Fix fan-out.** When the triggering review's `Parallel-safe:` line certifies a `disjoint` group of ≥ 2 findings, dispatch that fix round per `dispatching-parallel-agents` "Fix fan-out"; the fan-out counts as **one** fix against this budget, its scoped test gate is the consuming task/wave's plan-declared commands, and one re-review of the integrated delta follows.
 
+Every fix re-dispatch (implementer) and code-review re-review carries the consuming task/wave's `SCOPED_TEST_COMMANDS`; spec-reviewer re-reviews carry none - SR never executes.
+
 **The sequence.** Each review that finds issues is a decision point: read the `TRAJECTORY:` line before dispatching anything (review 1 has no line - on issues, dispatch fix 1). Any clean review ends the loop.
 
 1. **Review 1** (first review - no sentinel). Issues -> dispatch fix 1.
@@ -128,13 +130,13 @@ When in doubt, default. Don't downgrade reviewers — false negatives are expens
 
 ```ts
 // implementer
-subagent({ agent: "implementer", task: "<task text + context + status protocol>" })
+subagent({ agent: "implementer", task: "<task text + context + SCOPED_TEST_COMMANDS + status protocol>" })
 
 // spec compliance
 subagent({ agent: "spec-reviewer", task: "<diff range + spec excerpt + ask: does this match?>" })
 
 // code quality
-subagent({ agent: "code-reviewer", task: "<diff range + ask: production-ready?>" })
+subagent({ agent: "code-reviewer", task: "<diff range + SCOPED_TEST_COMMANDS (task commands; wave: union; whole-diff: none) + ask: production-ready?>" })
 
 // closing-loop conformance (origin vs deliverable) — its OWN dispatch, never fused with code quality
 // model: call gauntlet_setting({ key: "closureReview" }) first; use the returned model (omit model: if undefined to inherit) and maxFixRounds
@@ -167,10 +169,10 @@ Auto-selected at handoff by `writing-plans` (any wave with ≥2 tasks) when the
 
 1. **Independence check.** Parse the wave's tasks' `Files:` blocks; assert pairwise-disjoint (mechanical). Runtime-resource disjointness (DB/schema, port, fixture, external service, shared temp path) is not machine-checkable here — trust the plan's wave grouping, which `writing-plans`' D5 contract guarantees. Either kind of overlap → the wave is mis-grouped; run those tasks as sequential single-task waves and note it.
 2. **Fan out.** One parallel dispatch (shape below): `implementer` per task, `context: "fresh"`, `worktree: true`. Each returns a status + a patch.
-3. **Status + spec review per task.** Parse each `DONE`/`BLOCKED`/etc. (see [Implementer Status](#implementer-status)) **first**. Then **dispatch a `spec-reviewer` per accepted patch** (`DONE`, or a `DONE_WITH_CONCERNS` you proceeded with) in one parallel fan-out — `context: "fresh"`, `cwd: <this worktree>`, **no `worktree` flag** (read-only) — each passed its task text, the returned **patch diff**, and the absolute spec path. Review is **diff-based**: the diff's hunks carry `file:line`, and test execution is not the reviewer's job here (the wave test gate in step 5 runs the wave's declared test commands). Inline verdicts are fine at normal wave sizes; large waves use `output:` + `outputMode: "file-only"` to keep verdicts out of your context. **Re-dispatch by cause:** `BLOCKED`/`NEEDS_CONTEXT` per the [Implementer Status](#implementer-status) matrix; a **spec gap** re-dispatches the implementer (fresh, `worktree: true`) carrying the prior patch + the reviewer's findings, the new patch superseding the old at step 4. Loop until accepted + spec ✅, within [Fix-Loop Rounds](#fix-loop-rounds), same as sequential.
+3. **Status + spec review per task.** Parse each `DONE`/`BLOCKED`/etc. (see [Implementer Status](#implementer-status)) **first**. Then **dispatch a `spec-reviewer` per accepted patch** (`DONE`, or a `DONE_WITH_CONCERNS` you proceeded with) in one parallel fan-out — `context: "fresh"`, `cwd: <this worktree>`, **no `worktree` flag** (read-only) — each passed its task text, the returned **patch diff**, and the absolute spec path. Review is **diff-based**: the diff's hunks carry `file:line`, and test execution is never the reviewer's job - in either mode (persona rule; the wave test gate in step 5 runs the wave's declared test commands). Inline verdicts are fine at normal wave sizes; large waves use `output:` + `outputMode: "file-only"` to keep verdicts out of your context. **Re-dispatch by cause:** `BLOCKED`/`NEEDS_CONTEXT` per the [Implementer Status](#implementer-status) matrix; a **spec gap** re-dispatches the implementer (fresh, `worktree: true`) carrying the prior patch + the reviewer's findings, the new patch superseding the old at step 4. Loop until accepted + spec ✅, within [Fix-Loop Rounds](#fix-loop-rounds), same as sequential.
 4. **Integrate.** `git apply` each task's patch sequentially onto HEAD. Apply fails = textual conflict → drop that task, finish the rest, re-run the dropped task sequentially on the updated HEAD.
 5. **Test gate.** Run the union of the wave's tasks' declared test commands on the integrated tree — the full verification set is the verify phase's job, run once. Failure = semantic conflict or bug → re-run the offending task sequentially, else fix per [When a Subagent Fails](#when-a-subagent-fails).
-6. **Quality review.** Code-quality review on the integrated wave diff; loop fixes to ✅ within [Fix-Loop Rounds](#fix-loop-rounds), same as sequential. Skip for doc-only waves (SR-only per the commit precondition below).
+6. **Quality review.** CR binds to the wave: exactly one **initial** code-review dispatch per code-touching wave, over the integrated wave diff - never per task within a wave, never batched across waves. Subsequent dispatches within the wave are re-reviews triggered only by findings, per Fix-Loop Rounds. Pass `SCOPED_TEST_COMMANDS` = the union of the wave's tasks' declared commands. Code-quality review on the integrated wave diff; loop fixes to ✅ within [Fix-Loop Rounds](#fix-loop-rounds), same as sequential. Skip for doc-only waves (SR-only per the commit precondition below).
 7. **Commit the wave.** Leaves a clean tree; the next wave's children branch from this commit and so see the integrated work.
 
 **Two-stage review is preserved:** spec review per task (pre-integration, dispatched `spec-reviewer` — not inline), quality review per wave (post-integration). A wave commit requires one spec-review verdict per accepted task, plus one code-review verdict on the integrated diff for waves that touch code. A doc-only wave (every task's `Files:` block documentation-only, per `writing-plans`' Wave Grouping) is SR-only — the CR gate does not apply.
@@ -189,8 +191,8 @@ subagent({
   concurrency: 4,        // default; cap = wave size
   tasks: [
     // do NOT set per-task cwd under worktree:true — it must equal the top-level cwd or the run errors
-    { agent: "implementer", task: "<task text + owned files + status protocol>", output: "wave1-task1.md" },
-    { agent: "implementer", task: "<task text + owned files + status protocol>", output: "wave1-task2.md" },
+    { agent: "implementer", task: "<task text + owned files + SCOPED_TEST_COMMANDS + status protocol>", output: "wave1-task1.md" },
+    { agent: "implementer", task: "<task text + owned files + SCOPED_TEST_COMMANDS + status protocol>", output: "wave1-task2.md" },
   ],
 })
 ```
@@ -215,7 +217,7 @@ For the fan-out + worktree + patch-integration + conflict mechanics, see `dispat
 ## After All Tasks Complete
 
 0. Call `phase_tracker({ action: "start", phase: "verify" })`. (The `implement` phase was started at execution start and auto-completes from `plan_tracker` once all tasks are done; this flow runs its own verify gate instead of `/skill:verification-before-completion`, so it must mark verify itself.)
-1. **Run the whole-diff code review.** Dispatch `/skill:requesting-code-review` against the worktree's full diff vs `main` (already covered in [The Process](#the-process) step "After all tasks"). Address Critical and Moderate findings before handoff. (Consumers wanting an in-flow project-specific audit re-add it as an explicit step in the gauntlet overrides file (see Project overrides), or run `/self-audit` manually.)
+1. **Run the whole-diff code review.** Dispatch `/skill:requesting-code-review` against the worktree's full diff vs `main` (already covered in [The Process](#the-process) step "After all tasks"). Address Critical and Moderate findings before handoff. (Consumers wanting an in-flow project-specific audit re-add it as an explicit step in the gauntlet overrides file (see Project overrides), or run `/self-audit` manually.) Pass `SCOPED_TEST_COMMANDS: none` - the verify phase's full run (step 2) is the orchestrator's.
 2. **Run the full verification set — once.** Read the plan header's `**Verification:**` line and run it: tests + style + format (a single bundling entrypoint, or the listed individual commands). Green output is the fresh evidence verify requires; this is the only full run before conformance — task and wave gates ran scoped commands only. After conformance fix rounds land, re-run the set before re-dispatching the gate.
 3. **Close the loop — conformance check.** The review in step 1 is plan-vs-code (single-step); it inherits any requirement the plan already dropped. Before marking verify complete, dispatch a fresh-context **`conformance-reviewer`** — its **own** dispatch, never fused into the step-1 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, and the full diff. Follow that reference for the partition rule, concern decomposition, and fix-loop mechanics; do not reimplement them here. The fix loop may drive `plan_tracker` to surface fix-wave progress (task naming and lifecycle per conformance-check.md's fix loop / the Fix fan-out Progress rule); 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 two-line sentinel (`status: CONFORMS (0 open)` or `status: GAPS (N open)`, then `audited-base: <full HEAD SHA>`), 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.
@@ -238,6 +240,8 @@ For the fan-out + worktree + patch-integration + conflict mechanics, see `dispat
 - Starting on main without explicit user consent
 - Dispatching `code-reviewer` before every one of the wave's spec-review verdicts has landed (including fusing SR+CR into one parallel call)
 - Dispatching fixes sequentially on a clean HEAD despite a ≥ 2-ID `disjoint` group in the review's `Parallel-safe:` line
+- Dispatching `code-reviewer` per task inside a wave (CR binds to the integrated wave diff)
+- Dispatching an implementer or code-reviewer without a `SCOPED_TEST_COMMANDS` value (commands or `none`)
 - About to run the full verification entrypoint during the implement phase — task and wave gates run scoped, plan-declared commands only; the full set belongs to verify
 
 ## Integration

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

@@ -14,6 +14,7 @@ Dispatch a subagent with the code-reviewer template:
   PLAN_OR_REQUIREMENTS: Task N from [plan-file]
   BASE_SHA: [commit before task]
   HEAD_SHA: [current commit]
+  SCOPED_TEST_COMMANDS: [the consuming task's plan-declared commands; wave reviews: the union of the wave's tasks' declared commands; `none` for the whole-diff verify-phase review]
 ```
 
 **In addition to standard code quality concerns, the reviewer should check:**

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

@@ -31,13 +31,19 @@ Dispatch a subagent with this prompt:
     Once you're clear on requirements:
     1. Implement exactly what the task specifies
     2. Write tests (following TDD — failing test first for production code)
-    3. Verify implementation works
+    3. Verify with the commands under SCOPED_TEST_COMMANDS (if `none`, state that)
     4. Commit your work
     5. Self-review (see below)
     6. Report back
 
     Work from: [directory]
 
+    SCOPED_TEST_COMMANDS: [the task's plan-declared test commands, verbatim | none]
+
+    Run ONLY these commands for verification. Never run a repo-wide suite,
+    linter, or type-checker. If the value is `none`, run nothing and say so
+    in your report.
+
     **While you work:** If you encounter something unexpected or unclear, **ask questions**.
     It's always OK to pause and clarify. Don't guess or make assumptions.
 

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

@@ -38,6 +38,8 @@ Dispatch a subagent with this prompt:
 
     - **Read code and compare to spec: yes**
     - **Edit, create, or delete any files: NO**
+    - **Run tests, linters, or type-checkers: NO.** Never run tests, linters, or type-checkers. Your evidence is the diff and the files you read.
+    - **Code-quality opinions (naming, design, complexity, test aesthetics, style): NO.** Those belong to code-reviewer. Report only spec-vs-implementation deltas.
     - You are a reviewer. Your output is a written report listing what matches and what doesn't.
     - If you find issues, describe them — do NOT fix them.
 

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

@@ -117,11 +117,11 @@ Don't add features, refactor other code, or "improve" beyond what the test requi
 
 Run the test. Confirm:
 - New test passes
-- All other tests still pass
+- The task's scoped commands pass (full-suite verification belongs to the verify phase)
 - Output is pristine (no errors, no warnings)
 
 **Test fails?** Fix code, not test.
-**Other tests fail?** Fix now — don't move on with broken tests.
+**Scoped commands fail?** Fix now — don't move on with broken tests.
 
 ### REFACTOR — Clean Up
 
@@ -176,7 +176,7 @@ Before marking work complete:
 - [ ] Watched each test fail before implementing
 - [ ] Each test failed for expected reason (feature missing, not typo)
 - [ ] Wrote minimal code to pass each test
-- [ ] All tests pass
+- [ ] The task's scoped commands pass (full suite belongs to the verify phase)
 - [ ] Output pristine (no errors, warnings)
 - [ ] Tests use real code (mocks only if unavoidable)
 - [ ] Edge cases and errors covered

package/skills/verification-before-completion/reference/conformance-check.md

@@ -76,8 +76,9 @@ Default: **1 requirement source = 1 spec = code covering every requirement.**
 The requirement source is whatever sits at the top of the priority table — a
 ticket if there is one, otherwise the spec + original prompt. No ticket is fine;
 spec + prompt is a first-class source, not a degraded one. "Every requirement" =
-explicit acceptance criteria / spec clauses **+** implicit notes (ticket body,
-comments, or inline in the prompt). Source and solution must end in sync.
+explicit acceptance criteria / spec clauses **+** quotable notes (written
+sentences in the ticket body, comments, or inline in the prompt - quotable
+verbatim, never derived inferences). Source and solution must end in sync.
 
 Multi-spec effort → allowed **only if the spec explicitly says** it covers a
 defined subset and names the deferred requirements. Silent partial coverage = failure.
@@ -152,7 +153,9 @@ Per round:
    group of ≥ 2 gaps (per the report's `Parallel-safe:` line) fixes in one parallel
    dispatch — one `implementer` per gap (fresh context, `worktree: true`, `cwd` =
    the conformance worktree, task = the gap block verbatim with `touched-files` as
-   the ownership boundary); `conflicts` pairs serialize. Gaps outside any ≥ 2-ID
+   the ownership boundary). The dispatch adds `SCOPED_TEST_COMMANDS` to the gap
+   block: the gap-relevant plan-declared commands, or `none` (the round's test
+   gate owns execution). `conflicts` pairs serialize. Gaps outside any ≥ 2-ID
    `disjoint` group run sequentially as before. Then dispatch `spec-reviewer` per
    gap on the gap-block reference contract below. Task lifecycle: mark `in_progress` at
    dispatch; `complete` is deferred until the gap's patch is successfully
@@ -167,7 +170,7 @@ Per round:
    integrated changes. A `BLOCKED`/`NEEDS_CONTEXT` return surfaces to the user.
 4. **Test gate** on the integrated tree, using the project's canonical test
    command. A failure re-enters the failure-handling rules above.
-5. **`code-reviewer` once** on the round's cumulative fix delta (not per gap).
+5. **`code-reviewer` once** on the round's cumulative fix delta (not per gap), with `SCOPED_TEST_COMMANDS` = the round's gap-relevant commands, or `none` (the round's test gate owns execution).
 6. **Re-audit**: re-dispatch `conformance-reviewer` over the fixes **plus** the
    regression guard (any prior-`DELIVERED` requirement whose `evidence` file
    the fix diff touched). Pass the full prior conformance report (every row,
@@ -269,7 +272,9 @@ is an unmet-delivery fact, not
 an external blocker** — never relabel missing implementation evidence as a
 blocker. A malformed structured reviewer gap block — missing its stable `Gn`
 label or any required field (`verdict`, `origin`, `evidence`, `remediation`,
-`touched-files`, `touched-resources`, `recommended`) — triggers a **fresh
+`touched-files`, `touched-resources`, `recommended`) — or, for any non-`UNAUTHORIZED`
+gap (including re-audit blocks), an `origin` lacking a locator or a nonempty
+quoted fragment — triggers a **fresh
 audit**; a complete structured reviewer gap block does not — the orchestrator
 decomposes it or emits the indivisible fallback.
 
@@ -411,7 +416,7 @@ must map each token to its titled concern or gap before asking for input.
 ```text
 G1 - Source-image validation is incomplete
   verdict: PARTIAL
-  origin: <requirement source and clause>
+  origin: <requirement source and clause> - "<quoted clause>"
   evidence: <current file:line or observed state>
   blocker: <specific blocker, or none>
   touched-files: <paths or unknown>
@@ -421,7 +426,7 @@ G1 - Source-image validation is incomplete
   G1/C1 - End-to-end OCR output has not been validated
     unresolved: <plain statement of the concern>
     impact: <why it matters to the current workflow>
-    origin: <requirement source and clause, narrowed from the gap origin; or none (scope creep) for UNAUTHORIZED>
+    origin: <requirement source and clause, narrowed from the gap origin> - "<quoted clause>"; or none (scope creep) for UNAUTHORIZED
     remediation: <concern-scoped remediation action>
     evidence: <concern-specific evidence or blocker>
     touched-files: <concern-scoped paths, narrowed from the gap; or unknown>
@@ -474,7 +479,8 @@ branch integration options.
 ## Checklist
 
 - [ ] Located canonical requirements (spec → prompt → ticket fallback)
-- [ ] Enumerated every requirement: explicit ACs / spec clauses + implicit notes + inline prompt reqs
+- [ ] Enumerated every requirement: explicit ACs / spec clauses + quotable notes + inline prompt reqs (verbatim-quotable only)
+- [ ] Every non-UNAUTHORIZED gap's origin carries locator + verbatim quote
 - [ ] Checked spec ↔ prompt/ticket drift; reconciled any divergence
 - [ ] Each requirement mapped to where it's satisfied (code/doc) + evidence
 - [ ] Multi-spec? Subset declared in spec; deferred ACs noted as out of scope

package/skills/writing-plans/SKILL.md

@@ -128,7 +128,8 @@ If you can't list the files, the spec isn't ready. Send it back to `/skill:brain
 Group tasks into **waves** so the executor can parallelize independent work (see `subagent-driven-development` Parallel-Wave Mode). A wave is a maximal set of tasks that (a) have no ordering dependency on each other, (b) own **pairwise-disjoint files**, and (c) contend on **no shared mutable runtime resource** (same DB/schema, port, fixture file, external service, shared temp path).
 
 - Tasks nest under `## Wave N — <label>` headers; `### Task N` headers sit inside a wave.
-- A wave with one task is legal (runs sequentially). A pure dependency chain yields one task per wave — no parallelism, which is correct.
+- Group independent tasks into the same wave by default. A wave with one task is legal **only with a named-blocker justification**: a body line directly under the `## Wave N — <label>` header, `Solo: <reason>`, where the reason names the blocking task/wave, the contended runtime resource, or `lone remaining task` (reserved for the genuinely final unmatched task; doc-only trailing waves qualify). Category-only justifications ("dependency" with no named task) do not satisfy the rule.
+- A pure dependency chain yields one task per wave — no parallelism, which is correct; each such wave carries its `Solo:` line naming the prior-wave dependency.
 - Each wave after the first states its dependency on prior waves.
 
 **File-ownership contract.** The per-task `**Files:**` block *is* the ownership declaration — no new syntax. Rule: **within a wave, the union of every task's declared paths must be pairwise disjoint.** Globs are allowed for `Modify` when exact paths are unknown, but must not overlap another same-wave task's paths. A task that must touch another's file belongs in a later wave.
@@ -152,6 +153,8 @@ Parallel-safe: Tasks 1–3 own disjoint files (see each task's Files block).
 
 ## Wave 2 — Wire-up
 
+Solo: Task 4 depends on Wave 1 Task 1's API (named-blocker justification).
+
 Depends on Wave 1: Task 4 consumes the API introduced by Task 1.
 
 ### Task 4: ...
@@ -269,6 +272,7 @@ After drafting the plan and before announcing it complete, run three checks your
 - **Placeholder scan.** Grep the doc for `TODO`, `TBD`, `xxx`, `[fill in]`, `<example>`, `etc.`, "probably", "something like". Resolve or convert each into an explicit Open Question.
 - **Type / API consistency.** Function signatures and field names that appear in multiple tasks must match exactly. The plan is its own contract — internal contradictions surface as bugs during execution.
 - **Wave disjointness.** For every multi-task wave, confirm the tasks' `Files:` sets are pairwise disjoint **and** that no two tasks contend on a shared mutable runtime resource (DB/schema, port, fixture, external service, shared temp path). Either kind of overlap = mis-grouped wave; split or re-order before handoff.
+- **Solo-wave justification.** Every single-task wave carries a `Solo:` line naming its specific blocker. A solo wave without one is mis-grouped or under-justified — merge it or justify it before handoff.
 - **Scoped-test coverage.** Every code-touching wave declares at least one scoped test command; only doc-only waves may have none.
 - **Header-only entrypoint.** The full verification entrypoint appears only in the plan header's `**Verification:**` line. Grep the task body for the header's command string — expect zero hits.