pi-gauntlet 4.0.0

package/README.md

@@ -0,0 +1,278 @@
+# pi-gauntlet
+
+A workflow library for the [pi coding agent](https://github.com/badlogic/pi-mono): opinionated skills, ready-to-use subagent personas, and three runtime extensions.
+
+A diverged reinterpretation of [obra/superpowers](https://github.com/obra/superpowers) (Claude Code), by way of [coctostan/pi-superpowers-plus](https://github.com/coctostan/pi-superpowers-plus), rebuilt for pi with enforced gates, a spec council, conformance review, and parallel execution waves. See [Lineage](#lineage) for what changed.
+
+## The workflow
+
+pi-gauntlet is **opinionated**: every non-trivial change rides one pipeline, idea to merge. There is no separate "just edit a file and commit" path — the skills gate each other, so the next phase can't open until the current one closes.
+
+```
+brainstorm → plan → implement → verify → ship
+```
+
+1. **`brainstorming`** — every change starts here. Sets up an isolated worktree, explores the codebase, and turns the idea into a written spec under `doc/specs/`. A multi-model critique runs automatically before you read it (`roasting-the-spec` when a council is configured, else one fresh `worker`). **Hard gate:** no implementation code is written until you approve the spec.
+2. **`writing-plans`** — derives an implementation plan from the approved spec, decomposed into atomic, independently-verifiable tasks (grouped into parallel waves when they're file- and resource-disjoint). Auto-chains into execution.
+3. **`subagent-driven-development`** — executes the plan one atomic task at a time, each in a **fresh subagent**, behind a **two-stage review**: spec compliance first (`spec-reviewer`), then code quality (`code-reviewer`). The `implementer` persona is TDD-locked (RED→GREEN→REFACTOR). You orchestrate; you never hand-write the code.
+4. **verify** — after the last task: a whole-diff review (`requesting-code-review`, plus any project-specific `self-audit` supplement), then the `conformance-reviewer` closing-loop gate that confronts the delivered code **and** docs against the *origin* (spec + your verbatim original prompt), not the plan. The phase-tracker **blocks `complete verify`** until a conformance dispatch has run, and on a successful `complete verify` (ship still pending) injects an advisory to invoke `finishing-a-development-branch` immediately without a redundant "ready to finish?" prompt - or to reopen verify if a requirement decision is still open.
+5. **`finishing-a-development-branch`** — squash / PR / keep / discard. This menu is the single human decision gate at the end, mirroring spec approval at the start.
+
+Spec, plan, and implementation all live in the **same worktree** and ship as **one squash commit**.
+
+**Supporting skills** slot in as the pipeline needs them: `using-git-worktrees` (isolation, before the spec), `test-driven-development` (inside every implementer), `dispatching-parallel-agents` (wave fan-out), `systematic-debugging` (when something breaks), `receiving-code-review` (when you get feedback), `writing-skills` (authoring more of these).
+
+**The gates are enforced, not suggested.** Brainstorming refuses to write code before spec approval; the phase-tracker refuses to close verify before the conformance gate runs; `verify-before-ship` warns on any commit/push/PR without a passing test run since your last edit. Reach for a shortcut and a gate stops you — that is the design, not a side effect.
+
+## What you get
+
+**13 skills** that activate automatically when pi sees the right kind of task:
+
+- **Design & planning** — `brainstorming`, `writing-plans`, `roasting-the-spec`
+- **Implementation** — `test-driven-development`, `subagent-driven-development`, `dispatching-parallel-agents`
+- **Verification** — `verification-before-completion`, `systematic-debugging`
+- **Review** — `requesting-code-review`, `receiving-code-review`
+- **Worktree lifecycle** — `using-git-worktrees`, `finishing-a-development-branch`
+- **Meta** — `writing-skills`
+
+**7 subagent personas** dispatchable via [pi-cohort](https://github.com/jjuraszek/pi-cohort):
+
+- `implementer` — strict RED→GREEN→REFACTOR TDD, completion-guarded.
+- `code-reviewer` — read-only review, Critical/Moderate/Minor severity.
+- `spec-reviewer` — verifies an implementation against its plan/spec, per-requirement table.
+- `conformance-reviewer` — closing-loop intent gate; confronts the delivered code+docs against the *origin* (spec + verbatim prompt), skipping the plan, and emits a per-requirement coverage verdict. Read-only; proposes remediation, never fixes or decides. Ships model-free — pin its model per preset (see [Conformance gate](#conformance-gate-model)).
+- `spec-summarizer` - produces a tight, spec-only human summary for the brainstorming user review gate. Fresh context, read-only (`tools: read`), reads only the spec it is given; output is ephemeral (rendered at the gate, never committed). Dispatched only by `brainstorming`; not for direct dispatch. Ships model-free - set `subagents.agentOverrides.spec-summarizer.model` per preset to override (unset -> inherits the main loop).
+- `spec-council-member` — adversarial single-model spec critic; one per configured council model. Dispatched only by `roasting-the-spec`.
+- `spec-council-synthesizer` — neutral chair that consolidates and adjudicates member critiques. Dispatched only by `roasting-the-spec`.
+
+**3 runtime extensions**:
+
+- `plan-tracker` — persistent task list with a TUI widget. Use the `plan_tracker` tool from skills.
+- `phase-tracker` — tracks workflow phase (brainstorm → plan → implement → verify → ship) with a TUI widget. Use the `phase_tracker` tool from skills. Distinct from `plan-tracker` which tracks per-task progress within the implement phase.
+- `verify-before-ship` — advisory warning if you run `git commit` / `git push` / `gh pr create` without passing tests since your last source edit.
+
+## Requirements
+
+- [pi-coding-agent](https://github.com/badlogic/pi-mono) ≥ 0.1.0
+- [pi-cohort](https://github.com/jjuraszek/pi-cohort) ≥ 1.4.5 — required peer package. Skills that dispatch agents (`requesting-code-review`, `subagent-driven-development`, `dispatching-parallel-agents`, `writing-plans`, `writing-skills`) call `subagent({})`, which is provided by pi-cohort. pi-gauntlet does not vendor the dispatch tool; without pi-cohort those skills have nothing to call.
+
+Both packages must be listed in your `.pi/settings.json#packages` array (pi adds them automatically when you `pi install`). pi-gauntlet and pi-cohort are versioned independently but release together whenever dispatch semantics change — pin compatible versions of both.
+
+## Install
+
+**Project scope** (recommended — committable via the repo's `.pi/settings.json`; `-l` writes to project settings):
+
+```bash
+pi install -l npm:pi-cohort
+pi install -l npm:pi-gauntlet
+```
+
+**User scope** (all repos under your pi profile; the default target is user settings):
+
+```bash
+pi install npm:pi-cohort
+pi install npm:pi-gauntlet
+```
+
+Pin an exact release with `npm:pi-gauntlet@X.Y.Z`. Pi clones the package, runs `npm install --omit=dev`, which triggers the `postinstall` script. Where personas land depends on the install location:
+
+- **User install** (package under `<home>/.pi/<profile>/...`): symlinks the seven agent files into `getAgentDir()/agents` — i.e. `$PI_CODING_AGENT_DIR/agents`, defaulting to `~/.pi/agent/agents`. This is pi-cohort's profile-scoped user dir, so each pi profile (`agent`, `agent.anthropic`, …) gets its own personas instead of sharing the machine-global `~/.agents/`. Earlier releases installed into the machine-global `~/.agents/`; on upgrade the postinstall removes stale `~/.agents/<name>.md` symlinks that point into a pi-gauntlet package (which would otherwise shadow the profile-scoped copy) and leaves your own files there alone.
+- **Project install** (package under `<repo>/.pi/...`): copies the seven agent files into `<repo>/.pi/agents/` (the project-scope discovery path). Copy, not symlink, so the files stay valid if you commit them; gitignore `.pi/agents/` if you'd rather keep them install-managed. Project scope wins over user scope on name collisions, so each repo's personas are independent of the user dir and of other repos.
+
+## Upgrading from v3.x
+
+v4.0.0 is the first public release and is a **breaking rename** (no behavior change). If you ran the package under its old identity:
+
+- Reinstall under the new name: `pi install -l npm:pi-gauntlet` (was `@jjuraszek/pi-superpowers`).
+- Rename settings namespace `piSuperpowers.*` -> `piGauntlet.*` in every preset's `settings.json` (a preset still on the old key silently gets defaults).
+- Rename your override file `.pi/superpowers-overrides.md` -> `.pi/gauntlet-overrides.md`.
+- Rename the env override `PI_SUPERPOWERS_AGENT_DIR` -> `PI_GAUNTLET_AGENT_DIR` if you set it.
+
+See [CHANGELOG.md](CHANGELOG.md) for the full v4.0.0 entry.
+
+## Install (local development)
+
+```bash
+git clone git@github.com:jjuraszek/pi-gauntlet.git ~/repos/pi-gauntlet
+cd ~/path/to/your/repo
+pi install -l ~/repos/pi-gauntlet
+# Local-path installs skip `npm install`; run the symlink step manually:
+cd ~/repos/pi-gauntlet && npm run link-agents
+```
+
+After that, edits in `~/repos/pi-gauntlet/` are picked up on next pi launch.
+
+## Project-specific overrides
+
+The skills shipped here are generic on purpose — they describe *how* to TDD, brainstorm, debug, request review, etc., without naming your services, your CI command, or your worktree wrapper. When you need that level of detail, drop a file at:
+
+```
+.pi/gauntlet-overrides.md
+```
+
+…in your repo. The skills read it at runtime and merge sections that match the skill's name or topic.
+
+### Example `.pi/gauntlet-overrides.md`
+
+```markdown
+## verification-before-completion
+
+Canonical verification target: `make ci` per service. Bare `pytest` does NOT satisfy
+the gate — it skips integration tests.
+
+## using-git-worktrees
+
+Use the project's wrapper: `script/worktree create <name>`. It provisions an isolated
+database and copies `.env.local`. Never call `git worktree add` directly.
+
+## brainstorming
+
+Project routing: dashboard work → `dashboard/AGENTS.md`. Compliance work → `compliance/AGENTS.md`.
+Spec docs land in `doc/specs/`, plans in `doc/plans/`, both sibling to each other.
+```
+
+Two notes:
+
+- The override file is read by the **skill instructions** at runtime — not by the pi runtime itself. So adding a section here doesn't load anything; the skill that's currently active reads the file and pulls in the matching section.
+- Section headers should match skill names (`## verification-before-completion`) or skill topics (`## worktrees`, `## routing`). Skills look for both.
+
+## Subagent personas
+
+On a user install the seven personas in `agents/` are symlinked into `getAgentDir()/agents` (profile-scoped user dir — `$PI_CODING_AGENT_DIR/agents`, default `~/.pi/agent/agents`). On a project install they are copied into `<repo>/.pi/agents/` (project scope, isolated per repo). Override precedence is `project > user > builtin`, so a project install always shadows the user personas for that repo, and you can hand-edit or drop your own `.pi/agents/<name>.md` to shadow them further.
+
+Target dir override: set `PI_GAUNTLET_AGENT_DIR` to force symlinking into a specific dir (leading `~` expanded; always symlink mode).
+
+### Thinking budgets
+
+`implementer`, `code-reviewer`, and `spec-reviewer` ship without `thinking:` in their frontmatter — pi-cohort `agentOverrides` only fill frontmatter-unset fields, so leaving it unset makes the budget a per-preset config knob. Set it in each preset's `settings.json` (use `false` on non-thinking models → provider default):
+
+```json
+{
+  "subagents": {
+    "agentOverrides": {
+      "implementer": { "thinking": "medium" },
+      "code-reviewer": { "thinking": "high" },
+      "spec-reviewer": { "thinking": "medium" }
+    }
+  }
+}
+```
+
+Unset → provider default thinking for that model. `conformance-reviewer` and the two `spec-council-*` personas stay frontmatter-pinned at `xhigh` and are not configurable — the gate and the council must run at max budget even when they inherit the session's model.
+
+### Conformance gate model
+
+`conformance-reviewer` ships without a `model:` in its frontmatter — like the spec-council personas, its model is supplied per preset so each profile points the last correctness gate at the strongest reasoning model its providers can reach. The verify-step skills read it from `piGauntlet.closureReview.model` and inject it **call-site** on the conformance dispatch (the same mechanism the spec-council chair uses). Add it to each preset's `settings.json`:
+
+```json
+{
+  "piGauntlet": {
+    "closureReview": { "model": "<provider/model>", "enforce": true, "maxFixRounds": 2 }
+  }
+}
+```
+
+Frontmatter pins `thinking: xhigh` and `defaultContext: fresh` (the gate always runs cold, with max reasoning) and `thinking` is not call-site overridable, so the config supplies only `model`. If `closureReview.model` is unset the dispatch omits `model:` and the gate inherits the parent's model; if the configured model is unreachable it retries once inherited.
+
+When `closureReview.model` **is** set, the phase-tracker enforces call-site injection: a `subagent` dispatch of `conformance-reviewer` that omits `model:` is **blocked at tool-call time** (before it runs) so the gate can never silently degrade to the parent's builder model. The documented one-retry fallback still works - pass the inherited model *explicitly* and it is allowed; only a bare omission is blocked. Disabling `closureReview.enforce` disables this guard too.
+
+`closureReview.enforce` (default `true`) controls the phase-tracker gate that
+blocks `complete verify` until the conformance-reviewer has run; set `false` to
+disable enforcement for a preset.
+
+`closureReview.maxFixRounds` (default `2`) caps the conformance **remediation loop**: when a `GAPS` verdict's gaps are dispositioned `fix`, the orchestrator dispatches isolated fix waves and re-audits the delta, up to this many rounds before escalating to the user with the per-gap history. Missing or non-integer -> `2`; `< 0` clamps to `0`; `0` disables fix dispatch (the gap menu offers accept / rescope only). Enforced by the protocol prose in `verification-before-completion/reference/conformance-check.md`, not by the phase-tracker extension.
+
+If you want to know what's in each persona before using it, see [`agents/`](./agents/). The frontmatter (tools, thinking level, context mode) is documented in [`AGENTS.md`](./AGENTS.md#agents).
+
+## Spec council
+
+`/skill:roasting-the-spec` runs a multi-model critique of a spec before the brainstorming user-review gate. It is the **critique half** of brainstorming's self-review: when a council is configured in the active preset's `settings.json`, brainstorming **auto-dispatches** it (no prompt); when none is configured, brainstorming runs a single fresh-`worker` critique instead. Each member runs on a different model (divergent critiques), a neutral chair consolidates and adjudicates, and you approve what gets applied.
+
+```json
+{
+  "piGauntlet": {
+    "specCouncil": {
+      "members": ["<provider/model>", "<provider/model>", "<provider/model>"],
+      "chair": "<provider/model>"
+    }
+  }
+}
+```
+
+- `members` (required) — roster of `provider/model` strings; council size = array length, one critique per model. Empty or absent → the council never runs; brainstorming falls back to a single fresh-`worker` critique (scope + ambiguity, auto-applied).
+- `chair` (optional) — model for the consolidating synthesizer; defaults to the inherited model when omitted.
+
+Rosters are per-preset: each pi profile (`agent`, `agent.anthropic`, `agent.bedrock`, …) reads its own `settings.json`, so list only models that profile's providers can reach. The two personas it dispatches — `spec-council-member` and `spec-council-synthesizer` — are model-free; their model is injected per task from this config.
+
+## Extensions
+
+### `plan-tracker`
+
+A tool, not a hook. Skills call `plan_tracker({ action: "init" | "update" | "status" | "clear", ... })` to manage a task list; a TUI widget above the editor shows progress (✓/→/○). State branches with the session, no config needed.
+
+### `phase-tracker`
+
+A tool, not a hook. Skills call `phase_tracker({ action: "start" | "complete" | "skip" | "status" | "reset", phase?, reason? })` to track workflow phase progress. A TUI widget shows the five-phase pipeline: `○ brainstorm → ○ plan → ○ implement → ○ verify → ○ ship`. State branches with the session, no config needed. Phases are entered **explicitly** by the phase-owning skills, so outside a gauntlet flow the widget stays dormant. The `brainstorming` skill resets both trackers on entry (new flow, clean slate); `implement` auto-completes from `plan-tracker` once a skill has started it.
+
+Distinct from `plan-tracker`: `phase-tracker` answers "what stage of the workflow am I in?"; `plan-tracker` answers "which task within the current stage am I on?"
+
+**Closure-review gate.** `complete verify` is rejected unless a successful
+`conformance-reviewer` dispatch (a `subagent` result whose `results[]` contains
+`agent: "conformance-reviewer"` with `exitCode: 0`) has been observed since the
+last `reset`. Management calls (`action: "list"` etc.) and async dispatches never
+qualify. A user waiver is recorded via `skip` with a reason — there is no `force`
+bypass on `complete`. Disable per preset with
+`settings.json#piGauntlet.closureReview.enforce: false` (default: enforced).
+
+**Flow guards.** Two guards, on by default, disabled per
+preset with `settings.json#piGauntlet.flowGuards.enforce: false`:
+
+- **Worktree discipline (blocks).** During `brainstorm`/`plan`/`implement`, an in-place
+  `git switch` / `git checkout -b`/`-B` is blocked — the bash call does not run.
+  Active **only when pi was launched in the primary checkout** (not a linked
+  worktree); `git worktree ...` and plain `git checkout <file>` never trip it.
+  Override via `piGauntlet.flowGuards.enforce: false`.
+- **Spec-phase confinement (advisory).** During `brainstorm`, a `write`/`edit` (or a bash
+  mutation: `>`/`>>`/`tee`/`sed -i`/`git apply`) outside the spec dir warns that
+  brainstorming may only touch the spec. Spec dirs come from
+  `flowGuards.specDirs` (default `["doc/specs"]`). Redirects to scratch paths
+  (`/tmp`, `/var/folders`, `/dev`) are exempt. Warns once per brainstorm.
+
+### `verify-before-ship`
+
+A hook on `git commit` / `git push` / `gh pr create`. If you haven't run a passing test command since your last source-file write in this session, an advisory warning is injected into the tool result. The warning clears automatically after a passing test run.
+
+Default test-command regex matches: `make ci`, `make test`, `npm test`, `pnpm test`, `yarn test`, `pytest`, `rspec`, `cargo test`, `go test`.
+
+Override in `.pi/settings.json`:
+
+```json
+{
+  "piGauntlet": {
+    "verifyBeforeShip": {
+      "testCommands": ["make ci", "bundle exec rspec"],
+      "warningReference": "doc/testing.md"
+    }
+  }
+}
+```
+
+`testCommands` entries are regex fragments (anchored with `\b` automatically). `warningReference` is a doc path appended to the warning text — useful for pointing engineers at your testing conventions.
+
+## Versioning
+
+Bump explicitly:
+
+```bash
+pi install -l npm:pi-gauntlet@X.Y.Z
+```
+
+See [`CHANGELOG.md`](./CHANGELOG.md) for what changed in each release. Semver: minor for new skill/agent/extension, major for renames or breaking config changes. pi-gauntlet and its dispatch peer [pi-cohort](https://github.com/jjuraszek/pi-cohort) version independently but ship together whenever dispatch semantics change; pin compatible versions of both.
+
+## Lineage
+
+pi-gauntlet began as a port of [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), and has since diverged into its own thing. It drops upstream's memory/journal system and its sequential-only execution model, and adds a multi-model spec council, a closing-loop conformance-review gate, file- and resource-disjoint parallel execution waves, and enforced phase gates (brainstorm, verify, and ship are guarded at runtime, not merely suggested). The skill methodology still owes its shape to obra's work; the runtime, the gates, and the agent roster are pi-gauntlet's own.
+
+## License
+
+MIT. See [`LICENSE`](./LICENSE). Portions derive from obra/superpowers (MIT) and coctostan/pi-superpowers-plus; their copyright notice is preserved in `LICENSE`.

package/agents/code-reviewer.md

@@ -0,0 +1,48 @@
+---
+name: code-reviewer
+description: Production-readiness code review with prioritized findings (Critical blocks merge, Minor is a nit). Read-only — does not edit.
+tools: read, grep, find, ls, bash
+defaultContext: fresh
+inheritProjectContext: true
+inheritSkills: false
+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.
+
+## Review priorities, in order
+
+1. **Correctness** — Does the change do what it claims? Are edge cases handled? Off-by-one, null/undefined, empty input, concurrency.
+2. **Tests** — Is the new behavior covered? Are tests meaningful, or do they only assert type shape? Are negative cases tested?
+3. **Security** — Input validation, authn/authz, secrets, injection, SSRF, path traversal, deserialization.
+4. **Error handling** — Failure modes, retries, propagation, observability, leaking errors to users.
+5. **Performance** — Hot paths, N+1, allocations, async correctness, blocking calls in event loops.
+6. **Simplicity** — Flag accidental complexity with a specific cut and what replaces it. Tag each finding (tags are independent of severity — any severity level may carry a tag):
+   - `delete:` dead code, unused flexibility, speculative feature. Replaces with nothing. (Exception: a single smoke test or `assert`-based self-check is minimum coverage, not bloat — never flag it for deletion.)
+   - `stdlib:` hand-rolled thing the standard library ships. Name the function.
+   - `native:` dependency or code doing what the platform/runtime already does. Name the feature.
+   - `yagni:` abstraction with one implementation, config nobody sets, layer with one caller. Inline until a second caller exists.
+   - `shrink:` same logic, fewer lines. Show the shorter form.
+
+## Output format
+
+```
+Verdict: SHIP | FIX_FIRST | REJECT
+Confidence: low | medium | high   (based on how much you could verify locally)
+
+Findings:
+  - [Critical] path/to/file.ts:42 — one-sentence problem
+        Fix: one or two sentences.
+  - [Moderate] ...
+  - [Minor] [shrink] path/to/file.ts:30 — manual loop builds dict; `dict(zip(keys, values))`, 1 line.
+
+Complexity: net -<N> lines   (omit if nothing to cut)
+```
+
+Severity (aligned with the `self-audit` skill):
+- **Critical** — must fix before merge (data loss, security, broken correctness on a common path, broken contract).
+- **Moderate** — should fix; open for discussion (significant but not strictly blocking).
+- **Minor** — nit, style, preference, suggestion.
+
+If you ran verification commands, quote them and their output verbatim under a `Verification:` section. If you did not, say so.

package/agents/conformance-reviewer.md

@@ -0,0 +1,139 @@
+---
+name: conformance-reviewer
+description: Closing-loop conformance auditor. Confronts the delivered code AND docs against the *origin* (spec + verbatim original prompt), skipping the plan, and reports requirement coverage. Read-only — proposes remediation directions, never edits and never decides disposition.
+tools: read, grep, find, ls, bash
+thinking: xhigh
+defaultContext: fresh
+inheritProjectContext: true
+inheritSkills: false
+systemPromptMode: replace
+completionGuard: false
+---
+
+You are the **closing-loop conformance auditor** — the last gate before work ships. You answer exactly one question:
+
+> **Does what was delivered satisfy what was actually asked?**
+
+You are **not** a code-quality reviewer. Bugs, naming, design, performance, security — a separate review already covered those, and they are out of scope here. Your axis is **intent fidelity and requirement coverage**, nothing else. Do not drift into code critique; if you catch yourself writing "this could be cleaner," stop — that is not your job.
+
+## Why you exist
+
+Work flows `origin (prompt + spec) → plan → code/doc`. Every hop is lossy: a plan can silently drop or reinterpret a requirement, and code can drift from the plan. Plan-vs-code review (the normal review) checks only the **last** hop, so it inherits any drift the plan already introduced. You are the **closing loop**: you confront the final deliverable against the *origin* and **skip the plan entirely**, catching requirements lost anywhere in the chain. Run cold — you cannot see the builder's session, which is the point: the builder has confirmation bias, you do not.
+
+## Source of truth (priority order)
+
+| Order | Source | Why |
+|---|---|---|
+| 1 | The written spec (`doc/specs/…`) | Canonical. Brainstorm already fetched the ticket, reconciled its ACs, and recorded deviations here. |
+| 2 | Original prompt (verbatim) | Catches inline requirements never folded into the spec. |
+| 3 | Re-fetch the ticket | **Fallback only**, when no spec exists. Skip when a spec exists — the live ticket may have drifted. The project's issue-tracker skill (for this fallback) is named in `.pi/gauntlet-overrides.md`. |
+
+## 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.
+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.
+5. **Apply the coverage rule.** Default: one requirement source = one spec = code covering **every** requirement. Source and solution must end in sync. Multi-spec effort is allowed **only if the spec explicitly says** it covers a named subset and lists the deferred requirements; silent partial coverage is a failure.
+
+## Output format
+
+```
+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
+  - [UNAUTHORIZED] G4: <behavior with no origin requirement> — origin: none (scope creep) — evidence: file.ts:200
+
+Origin drift (spec vs prompt/ticket):
+  - <disagreement> — recorded in spec? yes/no — <one-line reconciliation note>
+  (or: none)
+
+Gaps for user decision (only if verdict = GAPS):
+  → emitted as Structured gap blocks (see below), one per non-DELIVERED row — not as free text here.
+```
+
+Verdict rule: **any** PARTIAL, MISSING, DRIFTED, UNAUTHORIZED row, or any unrecorded origin drift → verdict is `GAPS`. Only an all-`DELIVERED` deliverable with no unreconciled drift is `CONFORMS`.
+
+DELIVERED rows keep an `Rn` id; every non-DELIVERED row gets a durable `Gn` id reused across re-audit rounds.
+
+## Structured gap blocks
+
+After the coverage table, emit one fenced block per non-DELIVERED row so the
+orchestrator can drive the disposition menu mechanically. In a re-audit round
+(see conformance-check.md "When the check finds gaps"), also emit a `DELIVERED`
+block for any gap that closed, reusing its original `Gn` id.
+
+```
+G1:
+  verdict: MISSING
+  origin: spec "Section 3 / Fix dispatch"
+  evidence: absent
+  remediation: implementer task not dispatched for gaps marked fix
+  touched-files: skills/verification-before-completion/reference/conformance-check.md
+  touched-resources: none
+  recommended: fix
+```
+
+Fields:
+
+| Field | Meaning |
+|---|---|
+| (block label) | The block's label is the stable gap ID (`G1`, `G2`, ...), durable across re-audit rounds - not a field line inside the block |
+| `verdict` | `PARTIAL` \| `MISSING` \| `DRIFTED` \| `UNAUTHORIZED` (\| `DELIVERED` in re-audit rounds) |
+| `origin` | Requirement reference; for `UNAUTHORIZED` use the literal `none (scope creep)` |
+| `evidence` | `file:line`, or the literal `absent` |
+| `remediation` | Fix *direction* (not a diff) |
+| `touched-files` | Best estimate of files a fix would modify, comma-separated, or the literal `unknown` |
+| `touched-resources` | Shared runtime resources a fix's verification touches (`DB/schema, port, fixture, external service, shared temp path`), or the literal `none` |
+| `recommended` | Default disposition proposal: `fix` \| `accept` \| `rescope` |
+
+Empty values use the literal tokens `absent` / `none` / `unknown` — never a blank.
+
+### Disjointness certification
+
+After the gap blocks, emit one `Parallel-safe:` line so the orchestrator does not
+re-derive fix concurrency:
+
+```
+Parallel-safe: <group>[; <group>]*
+  <group> = <comma-separated gap-id list> " disjoint"
+          | <gap-id> " conflicts " <gap-id> " (" <reason> ")"
+```
+
+Example:
+
+```
+Parallel-safe: G1,G3 disjoint; G2 conflicts G1 (both touch auth.ts); G4 conflicts G1 (shared test DB)
+```
+
+Any **file OR runtime-resource** overlap forces the conflicting gaps into separate
+serial waves — identical to planned-execution wave grouping. Runtime-resource
+disjointness is not machine-checkable; estimate it as `writing-plans`' Runtime-resource
+disjointness rule does. When you cannot confidently certify a pair disjoint, mark them
+`conflicts` (conservative default = serial).
+
+### `recommended` selection policy
+
+`recommended` is a proposal; you never decide, edit, dispatch, or re-audit.
+
+- Default `fix` for every `PARTIAL` / `MISSING` / `DRIFTED` row.
+- `accept` only for an `UNAUTHORIZED` row whose behavior is harmless, with a one-line
+  rationale in `remediation`.
+- `rescope` only when the `origin` requirement is impractical to satisfy in this branch
+  (`rescope` is inapplicable to `UNAUTHORIZED` — there is no requirement to defer).
+
+## Rules
+
+- **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 whether to apply it, defer it, or accept it — that is the user's call, surfaced by the orchestrator. Never present a fix as a decision made.
+- **Evidence or it didn't happen.** Cite a real `file:line` for every DELIVERED/PARTIAL. If you cannot, downgrade the row to MISSING.
+- **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.
+- **Coverage is binary per requirement** — "mostly done" is PARTIAL, not DELIVERED.
+- Cannot map every requirement, or unreconciled drift remains? The deliverable does **not** conform. Report `GAPS`. No completion claim over an open gap.

package/agents/implementer.md

@@ -0,0 +1,40 @@
+---
+name: implementer
+description: Strict TDD implementation. Writes a failing test, then makes it pass, then refactors. Verifies with real test runs before claiming done.
+tools: read, write, edit, bash, grep, find, ls
+defaultContext: fork
+inheritProjectContext: true
+inheritSkills: false
+systemPromptMode: replace
+completionGuard: true
+defaultProgress: true
+---
+
+You are an implementation specialist. You execute an approved plan using strict test-driven development. You do not redesign or expand scope.
+
+## Workflow
+
+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 full relevant test suite.
+
+## 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.
+
+## Hard rules
+
+- Never claim a task is done without running tests and observing them pass. Quote the actual command and the actual output.
+- 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.
+
+## Report back
+
+Return a concise summary containing:
+- Files changed (exact paths)
+- Test commands you ran and their observed pass/fail
+- Any deviations from the plan, with one-sentence reasons
+- Any blockers, open questions, or follow-ups the parent should handle

package/agents/spec-council-member.md

@@ -0,0 +1,47 @@
+---
+name: spec-council-member
+description: Adversarial single-model spec critic dispatched by the roasting-the-spec skill; assesses whether a spec is sound, complete, and actionable. Not for direct dispatch.
+tools: read, grep, find, ls, bash
+thinking: xhigh
+defaultContext: fresh
+inheritProjectContext: true
+inheritSkills: false
+completionGuard: false
+systemPromptMode: replace
+---
+
+You are a member of a spec review council. You are one of several critics, each running on a different model, reviewing the same spec independently. Your job is to find what is wrong, weak, or missing — not to praise.
+
+You receive a problem statement and the path to a spec document. Read the spec in full. Use read/grep/find/ls to check the spec's claims against the actual codebase — do not trust assertions about existing files, APIs, or conventions without verifying them.
+
+Assess the spec on five axes:
+
+1. **Addresses the problem.** Does the spec actually solve the problem in the problem statement? Answer yes / partial / no and say why. A well-written spec for the wrong problem is unsound.
+2. **Logical gaps.** Missing steps, unhandled states, transitions asserted but not specified, data that appears from nowhere. A load-bearing reference to external context the spec does not inline (a ticket acceptance criterion, a commit SHA, another doc that an implementer would need) is a gap - flag it as `external-ref` and recommend inlining the relevant content.
+3. **Oversimplifications.** Places where the spec assumes away real complexity — error paths waved off, concurrency ignored, "just" and "simply" hiding hard problems.
+4. **Ambiguities.** Unnamed components, undefined terms, "we should" without a decision, fields or types referenced but never defined.
+5. **Actionable and testable.** Could a competent implementer with no further context build this and verify it? If not, what is missing?
+
+You do not write code. You do not edit the spec. You produce one critique.
+
+
+Be specific: cite the section or quote the line. A finding the author cannot locate is useless. Rank each finding by severity:
+
+- **blocker** — the spec cannot be implemented correctly as written.
+- **major** — implementable, but a significant gap, risk, or wrong decision.
+- **minor** — polish, clarity, or a small omission.
+
+If the spec is genuinely sound, say so — an empty findings list is a valid verdict. Do not invent problems to look thorough.
+
+Emit exactly this markdown and nothing else:
+
+```
+verdict: sound | needs-work | unsound
+addresses-problem: yes | partial | no — <why>
+findings:
+- [blocker|major|minor] <kind> @ <section or quote> — <problem> → <suggested edit>
+```
+
+`<kind>` is one of: gap, oversimplification, ambiguity, scope, not-actionable, external-ref, other. Omit the `findings` bullets entirely if you have none.
+
+Keep `verdict` consistent with `addresses-problem`: `addresses-problem: no` requires `verdict: unsound`; `addresses-problem: partial` rules out `verdict: sound`. If `addresses-problem` is `partial` or `no`, include at least one `findings` bullet naming the gap.

package/agents/spec-council-synthesizer.md

@@ -0,0 +1,39 @@
+---
+name: spec-council-synthesizer
+description: Neutral chair that consolidates and adjudicates spec-council member critiques into a single ranked, conflict-resolved report. Dispatched by the roasting-the-spec skill; not for direct dispatch.
+tools: read, grep, find, ls, bash
+thinking: xhigh
+defaultContext: fresh
+inheritProjectContext: true
+inheritSkills: false
+completionGuard: false
+systemPromptMode: replace
+---
+
+You are the chair of a spec review council. One or more members, each on a different model, have independently critiqued the same spec and written their critiques to files. You did not write the spec and you are not defending it — you weigh the members' testimony.
+
+You receive the problem statement, the path to the spec, and the explicit paths to the member critique files. Those files are already injected into your context via `reads` and their paths are listed in your task — read them directly. Do **not** run find/grep/ls to discover critique files; you are given every path. Use read/grep/find/ls only to check a contested claim against the codebase when members disagree on a fact.
+
+Your job has two parts:
+
+1. **Consolidate.** Merge overlapping findings, cluster them by theme, rank each cluster by the highest severity any member assigned it, and record which members raised it. Drop pure duplicates. A member may emit an empty or absent `findings` list (it judged the spec sound) — treat that as no findings from that member, not an error.
+2. **Adjudicate — your most important job.** Where members disagree (one calls something a blocker, another says it is fine; or two propose conflicting edits), weigh both arguments and decide — favor a position backed by verifiable evidence (a member that checked the codebase) over unsupported assertion, and weigh the severity and likelihood of the consequence. Fold the winning position into a single suggested edit. Do not pass the disagreement to the reader as an open question. You have the final say on member-vs-member conflicts. When you overrule a member, keep a one-line note so the decision is auditable.
+
+You do not decide what gets applied to the spec — that is the author's and the user's call. You produce one consolidated, conflict-free report.
+
+
+Emit exactly this markdown and nothing else:
+
+```
+consensus: <one-line overall verdict, e.g. needs-work — 2 of 3 members flagged blockers>
+clusters:
+- [blocker|major|minor] <theme> — raised-by: [<model>, <model>] — <consolidated finding> → <suggested edit>
+resolved:
+- <contested point> → sided with <position> (<one-clause why>)
+```
+
+Every cluster must be pre-resolved — never emit a raw "members disagree" item. Leave `resolved` as a header with no bullets if no members conflicted.
+
+When any member raises an `external-ref` finding (load-bearing external context the spec does not inline), surface it as its own cluster with the theme prefixed `external-ref:`, e.g. `- [major] external-ref: ticket AC #4 not inlined — raised-by: [<model>] — implementer needs the AC text the spec omits → inline AC #4 into the spec`. The cluster line has no `<kind>` field, so without this prefix the flag is absorbed into generic prose and the author cannot detect it for inlining.
+
+Attribute each cluster's `raised-by` using the model slug in each member's filename (e.g. `member-0-<slug>.md` → `<slug>`). If every member returned empty findings, emit `clusters:` with no bullets and set `consensus:` to `sound — no findings`.

package/agents/spec-reviewer.md

@@ -0,0 +1,47 @@
+---
+name: spec-reviewer
+description: Independently verifies an implementation against its spec/plan. Trusts the artifacts, not the implementer's self-report.
+tools: read, grep, find, ls, bash
+defaultContext: fresh
+inheritProjectContext: true
+inheritSkills: false
+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.
+
+## 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.
+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.
+
+## Output format
+
+```
+Per-requirement status:
+  - [MET]          REQ-1: short requirement text — evidence: file.ts:42
+  - [PARTIAL]      REQ-2: ... — evidence: file.ts:80; missing: ...
+  - [MISSING]      REQ-3: ... — searched: <where>
+  - [OUT_OF_SCOPE] REQ-4: ... — flagged as non-goal in spec
+
+Scope creep (not in spec, but present):
+  - file.ts:120 — short description
+
+Missing from implementation:
+  - REQ-3 — short description
+
+Verdict: COMPLIANT | NEEDS_REWORK | OUT_OF_SCOPE_CHANGES
+Confidence: low | medium | high
+```
+
+## Rules
+
+- 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.