@event4u/agent-config 1.29.0 → 1.32.0

package/.agent-src/skills/judge-test-coverage/SKILL.md

@@ -147,6 +147,10 @@ as a follow-up for the implementer — the judge does not execute tools.
   model-pairing rules (`subagents.judge_model` one tier above implementer).
 - [`test-driven-development`](../test-driven-development/SKILL.md) —
   the write-the-test-first workflow that prevents most findings this judge makes.
+- [`testing-anti-patterns`](../testing-anti-patterns/SKILL.md) and its
+  sibling [`process-anti-patterns.md`](../testing-anti-patterns/process-anti-patterns.md) —
+  prevention layer this judge backs up; rationalization-table row numbers
+  are valid review citations.
 - Sibling judges: [`judge-bug-hunter`](../judge-bug-hunter/SKILL.md),
   [`judge-security-auditor`](../judge-security-auditor/SKILL.md),
   [`judge-code-quality`](../judge-code-quality/SKILL.md) — dispatched

package/.agent-src/skills/pest-testing/SKILL.md

@@ -22,6 +22,13 @@ Use this skill for all Laravel testing tasks, especially when working with:
 
 This skill extends `php-coder`, `laravel`, and `eloquent`.
 
+For prevention layers that fire **before** writing a test — TDD
+discipline, mock-isolation gates, and the 12 process rationalizations
+("I'll add the test after", "patch first, test later") — see
+[`test-driven-development`](../test-driven-development/SKILL.md),
+[`testing-anti-patterns`](../testing-anti-patterns/SKILL.md), and
+[`process-anti-patterns.md`](../testing-anti-patterns/process-anti-patterns.md).
+
 ## Procedure: Write Pest tests
 
 1. **Read the base skills first** — apply `php-coder`, `laravel`, and `eloquent` where relevant.
@@ -53,9 +60,9 @@ For bug fixes and new features, prefer test-driven development:
 
 ### Why test-first matters
 
-Tests written **after** impl pass immediately. Passing immediately proves nothing:
+Tests written **after** implementation pass immediately. Passing immediately proves nothing:
 - The test might test the wrong thing.
-- The test might test impl, not behavior.
+- The test might test implementation, not behavior.
 - You never saw it catch the bug — so you don't know if it would.
 
 ### Bug fix TDD
@@ -120,7 +127,7 @@ The test proves the fix works AND prevents regression.
 - For JSON APIs, assert:
     - exact relevant fields
     - error structure when applicable
-    - DB state after the request
+    - database state after the request
 - Do not only assert `200` — verify meaningful behavior.
 
 ## Validation tests
@@ -258,7 +265,7 @@ When reviewing or auditing existing tests, check for these anti-patterns:
 
 - Do not test private methods directly.
 - Do not over-mock Laravel internals.
-- Do not assert impl details when behavior assertions are enough.
+- Do not assert implementation details when behavior assertions are enough.
 - Do not write brittle tests tied to formatting or irrelevant response noise.
 - Do not create giant tests that cover many behaviors at once.
 - Do not skip authorization or validation coverage for important endpoints.
@@ -285,7 +292,7 @@ When generating Pest tests:
 - Don't use `readonly` or `final` on Pest test helper classes — it breaks mocking.
 - Don't add `use` statements for global classes (`Exception`, `DateTimeImmutable`) in Pest files — they're auto-imported.
 - The model forgets `$this->travel(5)->seconds()` for time-dependent tests — never rely on `now()` differing between lines.
-- Parallel tests share the DB — don't assume column values are null unless you explicitly set them.
+- Parallel tests share the database — don't assume column values are null unless you explicitly set them.
 
 ## Do NOT
 
@@ -297,7 +304,7 @@ When generating Pest tests:
 When generating new tests, focus on:
 - **Business logic**: calculations, status transitions, validation rules, data transformations
 - **Edge cases**: null, empty string, zero, negative numbers, boundary values, max length
-- **Error paths**: invalid input, missing deps, exception handling
+- **Error paths**: invalid input, missing dependencies, exception handling
 - **Different code branches**: if/else, early returns, fallback behavior
 
 What NOT to test:

package/.agent-src/skills/quality-tools/SKILL.md

@@ -34,6 +34,10 @@ If both PHP and JS/TS files changed → run **both** pipelines.
 - `verify-before-complete` rule — timing: run quality tools ONCE at the end, not after each edit
 - `php-coding` rule → PHPStan section — inline ignores, PHPDoc rules
 - `verify-before-complete` rule — must run quality checks before claiming work is done
+- [`testing-anti-patterns`](../testing-anti-patterns/SKILL.md) and
+  [`process-anti-patterns.md`](../testing-anti-patterns/process-anti-patterns.md) —
+  test-side rationalizations these tools cannot catch (e.g. "CI is red,
+  patch first, test later").
 
 ---
 

package/.agent-src/skills/refine-prompt/SKILL.md

@@ -126,6 +126,16 @@ The rubric (5 dimensions × 0–2, sum / 10) and band thresholds
 (`high ≥ 0.8`, `medium 0.5–0.79`, `low < 0.5`) are owned by
 `confidence.py`. Do not re-derive them in prose.
 
+### 6. Self-review (3-scan checklist)
+
+Before emitting the envelope, run these three scans. Each is a fast pass; failure blocks emission.
+
+1. **Spec coverage** — every concrete signal from step 2 (constraints) and step 3 (assumptions) is reflected somewhere in the AC list. Walk the constraint list top-to-bottom; each must anchor at least one AC bullet or appear in the *Assumptions* block.
+2. **Placeholder / TODO scan** — the rendered envelope contains no `<placeholder>`, `TODO`, `FIXME`, `tbd`, `???`, `XXX` strings. The literal angle-bracket placeholders in the template (`<one sentence …>`, `<bullet>`) must be replaced with concrete text before emission.
+3. **Type / shape consistency** — every named file, module, route, or command in the AC matches the project's existing conventions. If the prompt names `auth.service.ts` but the codebase uses `AuthService.php`, surface the mismatch in *Assumptions* rather than adopting the prompt's spelling.
+
+Source: adapted from `obra/superpowers` `writing-plans/SKILL.md` § Self-Review (v5.1.0).
+
 ## Band-action mapping
 
 The `refine` dispatcher step in `directives/backend/refine.py` reads

package/.agent-src/skills/refine-ticket/SKILL.md

@@ -250,6 +250,18 @@ open questions surfaced>
 The "Refined ticket" section is wrapped in a **copyable Markdown box**
 so the user can grab it verbatim.
 
+## Self-review (3-scan checklist)
+
+Run these three scans on the rendered output before the close-prompt. Each is a fast pass; failure blocks emission and forces a fix.
+
+1. **Spec coverage** — every AC bullet and constraint from the original ticket (and every parent-AC line surfaced via `fold_parent_context`) is reflected in the rewritten ticket, the Top-5 risks, or the *Open questions* section. Nothing from the input vanishes silently.
+2. **Placeholder / TODO scan** — no `<placeholder>`, `TODO`, `FIXME`, `tbd`, `???`, `XXX` strings remain. The angle-bracket placeholders in the template (`<rewritten title>`, `<risk>`, `<one paragraph>`) must be replaced with concrete prose before the close-prompt fires.
+3. **Type / shape consistency** — every module, file, route, or domain term cited in the rewritten ticket and Top-5 risks matches `repo_context.context_docs` and `recent_branches` vocabulary. Invented terms are flagged in *Open questions* or replaced with the project's actual term.
+
+Self-review is mechanical (gaps, leftovers, naming drift); persona voices and orchestration outputs handle reasoning critique. Both run; neither replaces the other.
+
+Source: adapted from `obra/superpowers` `writing-plans/SKILL.md` § Self-Review (v5.1.0).
+
 ## Close-prompt (mandatory final step)
 
 **Probe write access first (Phase F6).** Before rendering, do a

package/.agent-src/skills/{repomix → repomix-packer}/SKILL.md

@@ -1,12 +1,12 @@
 ---
-name: repomix
+name: repomix-packer
 description: "Use when packaging a codebase to a single AI-friendly file for LLM analysis — local or remote, XML/Markdown/JSON, token counting, gitignore filtering, peer-side `repomix` CLI."
 source: package
 ---
 
 > **Pinned upstream:** `repomix` CLI (npm: `repomix`, brew: `repomix`). Re-verify per minor bump. Repomix is an **optional dependency** — this skill never installs it silently.
 
-# repomix
+# repomix-packer
 
 Wraps the upstream [`yamadashy/repomix`](https://github.com/yamadashy/repomix) CLI for codebase-snapshot workflows: pack a local or remote repo into a single XML / Markdown / JSON file with token counts and secret detection, then feed it to an LLM for review, audit, or migration scoping.
 
@@ -25,7 +25,7 @@ Do NOT use when:
 
 ## Procedure: Snapshot a repo for LLM review
 
-### Step 0: Verify repomix is installed (peer-side)
+### 1. Inspect: verify `repomix` is installed (peer-side)
 
 ```bash
 repomix --version
@@ -41,7 +41,7 @@ npm install -g repomix
 brew install repomix
 ```
 
-### Step 1: Decide local vs remote
+### 2. Decide local vs remote
 
 ```bash
 # Local: pack the current directory.
@@ -54,7 +54,7 @@ npx repomix --remote owner/repo
 npx repomix --remote https://github.com/owner/repo/commit/<sha>
 ```
 
-### Step 2: Filter the snapshot to the smallest useful slice
+### 3. Filter the snapshot to the smallest useful slice
 
 ```bash
 # Include patterns
@@ -67,7 +67,7 @@ repomix -i "tests/**,*.test.js"
 repomix --remove-comments
 ```
 
-### Step 3: Pick the output format and destination
+### 4. Pick the output format and destination
 
 ```bash
 repomix --style markdown -o snapshot.md   # human-readable
@@ -76,7 +76,7 @@ repomix --style json -o snapshot.json     # programmatic post-processing
 repomix --copy                            # also copy to clipboard
 ```
 
-### Step 4: Verify token budget and secrets
+### 5. Verify token budget and secrets
 
 Repomix prints per-file and total token counts and runs Secretlint on the output. Check the totals against the target LLM context window:
 
@@ -88,7 +88,7 @@ Repomix prints per-file and total token counts and runs Secretlint on the output
 
 If Secretlint flags anything, STOP — sanitize the input or add the offending paths to `.repomixignore` before re-packing. Never use `--no-security-check` on an unfamiliar codebase.
 
-### Step 5: Hand the snapshot to the consumer skill
+### 6. Hand the snapshot to the consumer skill
 
 Most workflows that call this skill pass the snapshot to:
 

package/.agent-src/skills/roadmap-writing/SKILL.md

@@ -131,6 +131,11 @@ to every roadmap you author.
   template rule 13 + [`scope-control`](../../rules/scope-control.md#git-operations--permission-gated).
 * Plan automatic branch switches mid-roadmap (template rule 14).
 * Ship a phase without checkboxes (`roadmap-progress-sync` Iron Law #2).
+* Write merge, push, or commit steps into the roadmap. Roadmaps plan
+  **work**; merge / push / commit are delivery decisions owned by the
+  user (`commit-policy` Iron Law). A roadmap is "implementation-complete"
+  once its checkboxes are ticked and verification has been run — merge
+  timing is tracked outside the roadmap.
 * Use ALL-CAPS Iron-Law fenced blocks — those belong in
   [`kernel-membership`](../../../docs/contracts/kernel-membership.md)-listed
   rules, not roadmaps.
@@ -149,6 +154,10 @@ to every roadmap you author.
 - **Author-during-execution branch switches** — the agent should not
   propose a new branch mid-roadmap; that decision is fenced to
   authoring time.
+- **Merge / commit steps in roadmap body** — checkboxes like
+  "merge PR #X" or "commit phase Y" couple roadmap closure to git
+  operations the user has not authorized. Roadmap completion is
+  decoupled from delivery; ship-the-PR is its own decision.
 
 ## Examples
 

package/.agent-src/skills/rule-writing/SKILL.md

@@ -128,6 +128,27 @@ the PR or split by responsibility.
 * Run the full CI pipeline locally (see `Taskfile.yml` in this repo for
   the script list) — must exit 0 except for tolerated warnings.
 
+### 6. Governance baseline (when introducing a new linter check)
+
+**Advisory, reviewer-checked — no CI gate.** When the same PR adds a
+new check to `scripts/skill_linter.py` (or strengthens an existing one)
+such that previously-clean rules now warn, the PR body MUST record the
+pre-existing violations on `main` in a Markdown table:
+
+```markdown
+### Pre-existing baseline (informational)
+
+| Code | Count on main | Bucket |
+|---|---:|---|
+| {new_code} | N | (a) genuine fix · (b) accept · (c) check too aggressive |
+```
+
+Forward-only: the new check applies to **the rule under review** and to
+**future** edits. The baseline table is informational so reviewers can
+distinguish genuine debt from acceptable carry-overs without diffing the
+full lint output. See `agents/analysis/lint-warning-triage.md` for the
+3-bucket reference.
+
 ## Frontmatter shape
 
 ```yaml

package/.agent-src/skills/skill-writing/SKILL.md

@@ -59,6 +59,25 @@ Ask: **"Does the model need this to do its job correctly?"**
 * If the model knows it but does it wrong in THIS project → **Rule or Guideline**
 * If the model needs a multi-step workflow to get it right → **Skill**
 
+### Skills and commands share the `.claude/skills/` namespace
+
+Skills (`.agent-src.uncompressed/skills/{name}/SKILL.md`) AND commands
+(`.agent-src.uncompressed/commands/{name}.md`) both project into
+`.claude/skills/` (`scripts/compress.py` → `generate_claude_skills` +
+`generate_claude_commands`). Claude treats the directory as native
+skills.
+
+* Same-name collision: skill wins, command is skipped
+  (`generate_claude_commands` honors this). Don't reuse a command's
+  slug for a skill unless the command should retire.
+* Both compete on `description` for routing. A weak skill description
+  is shadowed by a stronger same-domain command — and vice versa.
+  Trigger phrasing must be precise (§ 1b below).
+* Workflow has both "user types `/foo`" path AND "model picks this up
+  from intent" path → author the skill first, let the command delegate
+  via `skills:` frontmatter. Two artifacts with the same trigger
+  surface fight each other in the router.
+
 ### When "Nothing" is the right answer
 
 Do NOT create a skill or rule for:

package/.agent-src/skills/subagent-orchestration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: subagent-orchestration
-description: "Use when orchestrating implementer/judge subagents — six modes (do-and-judge, do-in-steps, do-in-parallel, do-competitively, judge-with-debate, do-in-worktrees) — models from .agent-settings.yml."
+description: "Use when orchestrating implementer/judge subagents — seven modes (do-and-judge ±two-stage, do-in-steps/parallel/worktrees, do-competitively, judge-with-debate) — models from .agent-settings.yml."
 source: package
 ---
 
@@ -44,7 +44,7 @@ judge is a fresh pair of eyes. If `.agent-settings.yml` resolves to
 identical implementer and judge models, surface the mismatch before
 running — do not silently continue.
 
-## The six modes
+## The seven modes
 
 Each mode has a decision row: when to use, when not, and the expected
 model pairing. Defaults come from
@@ -60,7 +60,34 @@ back to the user.
 |---|---|---|
 | Single-change task with non-trivial risk | Tiny fix, or spike/exploration | implementer = session; judge = one tier up |
 
-### 2. do-in-steps
+### 2. do-and-judge-two-stage
+
+Implementer produces a diff; **two judges run sequentially** — first a
+spec-compliance reviewer (does the diff satisfy the stated spec /
+acceptance criteria?), then a code-quality reviewer (is the diff well-
+written for the codebase it lands in?). The orchestrator only proceeds
+to stage two if stage one returns `DONE` or `DONE_WITH_CONCERNS`. A
+stage-one `BLOCKED` shortcuts the loop — there is no point quality-
+reviewing a diff that does not satisfy the spec.
+
+| When to use | When not | Model pairing |
+|---|---|---|
+| Spec is contested or AC are detailed; diff size makes one judge prone to missing one axis (correctness vs craft) | Spec is one sentence, or the diff is one line (collapse to mode 1) | implementer = session; spec-judge = one tier up; quality-judge = same tier as spec-judge, fresh context |
+
+**Why two stages, not one judge with both rubrics:** combining the
+rubrics in one prompt reliably regresses one of them — the judge "spends
+attention" on whichever rubric appears last. Splitting the prompts
+forces each judge to commit fully to its rubric.
+
+**Stage-routing rule:**
+- Stage-1 returns `DONE` → run stage-2.
+- Stage-1 returns `DONE_WITH_CONCERNS` → run stage-2; concerns carry
+  forward to the final envelope.
+- Stage-1 returns `NEEDS_CONTEXT` → pause; stage-2 does not run.
+- Stage-1 returns `BLOCKED` → final verdict is `BLOCKED`; stage-2
+  does not run (saves cost).
+
+### 3. do-in-steps
 
 Plan is split into N steps; judge runs **between** steps. A step that
 fails judgment is revised before the next step starts. Used for
@@ -70,7 +97,7 @@ multi-file changes where a mid-plan mistake would cascade.
 |---|---|---|
 | Multi-step plan with ordered dependencies | Single-step change, or when steps are independent (use `do-in-parallel`) | implementer = session; judge = one tier up |
 
-### 3. do-in-parallel
+### 4. do-in-parallel
 
 Independent slices run concurrently. No judge per slice — judge runs
 once on the aggregated result. Parallelism capped by
@@ -80,7 +107,7 @@ once on the aggregated result. Parallelism capped by
 |---|---|---|
 | Independent slices (different files, non-overlapping) | Any slice touches shared state | implementer = session; judge = one tier up, run once |
 
-### 4. do-competitively
+### 5. do-competitively
 
 Multiple implementers produce candidate diffs for the **same** slice.
 Judge picks the winner and rejects the losers. Expensive — use only
@@ -90,7 +117,7 @@ when the solution space is genuinely broad.
 |---|---|---|
 | Broad solution space (algorithm choice, API shape) | Well-defined problem with one good answer | implementers = same tier (≥2 instances); judge = one tier up |
 
-### 5. judge-with-debate
+### 6. judge-with-debate
 
 Two judges each produce a verdict; a meta-judge reconciles
 disagreements. Used for high-stakes changes (security, data
@@ -100,7 +127,7 @@ migration, public API) where a single judge is too easy to fool.
 |---|---|---|
 | Security, data integrity, public API change | Routine internal refactor | judges = same tier (2x); meta-judge = one tier up |
 
-### 6. do-in-worktrees
+### 7. do-in-worktrees
 
 Cross-wing or cross-skill chain executed across isolated git
 worktrees — each handoff in the chain runs in its own worktree, so
@@ -130,7 +157,44 @@ end produces a single integration PR.
 **Anti-pattern:** do not use for fast iteration loops where each
 step is under ~30 minutes. The branch-creation, context-switch, and
 worktree-cleanup cost dominates. Stick with mode 1 (do-and-judge)
-or mode 2 (do-in-steps) for those.
+or mode 3 (do-in-steps) for those.
+
+## Status taxonomy — every subagent return uses one envelope
+
+Every implementer or judge return must conform to
+[`schemas/subagent-status.json`](schemas/subagent-status.json). Four
+statuses, no free-form alternatives:
+
+| Status | Meaning | Required keys (beyond `status`, `summary`) |
+|---|---|---|
+| `DONE` | Work shipped, all gates green. | `evidence[]` |
+| `DONE_WITH_CONCERNS` | Work shipped but caller must act on concerns. | `evidence[]`, `concerns[]` |
+| `NEEDS_CONTEXT` | Paused; caller can unblock by answering. | `blocking_question` |
+| `BLOCKED` | No path forward exists. | `blocking_reason` |
+
+**Why a fixed taxonomy:** orchestrators (`/do-and-judge`, `/do-in-steps`)
+route on status. Free-form "kind of done" returns force the orchestrator
+to interpret prose, which silently regresses the two-revision ceiling and
+the judge-rejected-do-not-apply rule. The schema makes routing mechanical.
+
+**Tests:** `tests/test_subagent_status_schema.py` exercises all four
+statuses plus rejection cases (missing required keys, unknown status,
+extra fields, conditional-key violations).
+
+**Distinguishing `NEEDS_CONTEXT` from `BLOCKED`:** `NEEDS_CONTEXT` means
+*"you, the caller, can fix this by telling me X"*. `BLOCKED` means
+*"no input from you unblocks this — escalate or rescope"*. If a subagent
+is unsure, it picks `BLOCKED` and the caller can downgrade.
+
+## Dispatch prompts — externalized
+
+Each mode's literal dispatch template lives under
+[`prompts/{mode}.md`](prompts/README.md). The orchestrator loads the
+matching prompt at dispatch time and substitutes `{{placeholders}}`.
+Edits to a prompt do not bloat this skill against the 400-line sunset
+trigger; `tests/test_subagent_prompt_loading.py` confirms each of the
+seven modes resolves to a loadable prompt that cites all four taxonomy
+statuses.
 
 ## Procedure
 
@@ -158,9 +222,10 @@ same context, **stop** and report. Do not improvise.
 
 ### 3. Pick the mode
 
-Match task shape to one of the five modes. When two modes could fit,
-prefer the cheaper one (`do-and-judge` < `do-in-steps` < `do-in-parallel`
-< `do-competitively` < `judge-with-debate`).
+Match task shape to one of the seven modes. When two modes could fit,
+prefer the cheaper one (`do-and-judge` < `do-and-judge-two-stage` <
+`do-in-steps` < `do-in-parallel` < `do-competitively` <
+`judge-with-debate` < `do-in-worktrees`).
 
 ### 4. Dispatch
 
@@ -195,7 +260,7 @@ the judge verdict.
 
 ## Output format
 
-1. **Mode chosen** — one of the five, with the one-line reason
+1. **Mode chosen** — one of the seven, with the one-line reason
 2. **Model pairing** — implementer model / judge model (resolved)
 3. **Verdict** — applied / revised / handed back
 4. **Evidence** — diff summary, test output, or judge transcript

package/.agent-src/skills/subagent-orchestration/prompts/README.md

@@ -0,0 +1,29 @@
+# Subagent dispatch prompts
+
+One file per mode in [`SKILL.md`](../SKILL.md) § *The seven modes*. Each
+prompt is the **literal template** the orchestrator hands to the
+subagent on dispatch — externalized so prompt edits do not bloat the
+skill above the 400-line sunset trigger.
+
+| Mode | File |
+|---|---|
+| do-and-judge | [`do-and-judge.md`](do-and-judge.md) |
+| do-and-judge-two-stage | [`do-and-judge-two-stage.md`](do-and-judge-two-stage.md) |
+| do-in-steps | [`do-in-steps.md`](do-in-steps.md) |
+| do-in-parallel | [`do-in-parallel.md`](do-in-parallel.md) |
+| do-competitively | [`do-competitively.md`](do-competitively.md) |
+| judge-with-debate | [`judge-with-debate.md`](judge-with-debate.md) |
+| do-in-worktrees | [`do-in-worktrees.md`](do-in-worktrees.md) |
+
+## Contract
+
+Every prompt cites the status taxonomy in
+[`../schemas/subagent-status.json`](../schemas/subagent-status.json) and
+ends with the **return-envelope** instruction so the subagent's reply
+validates against `tests/test_subagent_status_schema.py`.
+
+## Loading
+
+`tests/test_subagent_prompt_loading.py` asserts that every mode named
+in `SKILL.md` § *The seven modes* has a loadable prompt file under this
+directory and that each prompt mentions all four status enum values.

package/.agent-src/skills/subagent-orchestration/prompts/do-and-judge-two-stage.md

@@ -0,0 +1,121 @@
+# Prompt — do-and-judge-two-stage
+
+Mode reference: [`../SKILL.md`](../SKILL.md) § *2. do-and-judge-two-stage*.
+
+## Implementer prompt
+
+```
+You are the implementer in a do-and-judge-two-stage loop. Two judges
+will review your diff in sequence: first SPEC COMPLIANCE, then CODE
+QUALITY. Spec failure shortcuts the loop — quality is not reviewed if
+spec is wrong.
+
+TASK: {{task_description}}
+ACCEPTANCE CRITERIA: {{acceptance_criteria}}
+CONTEXT FILES: {{file_paths}}
+
+CONSTRAINTS:
+- Hit every AC literally; do not "interpret" them away.
+- Do not silently expand scope; AC are the contract.
+- Write tests that map 1:1 to the AC so the spec-judge can verify.
+
+ON COMPLETION, return ONE envelope per schemas/subagent-status.json:
+  - DONE                — every AC satisfied, tests pass; evidence[]
+                          maps each AC to the test that exercises it.
+  - DONE_WITH_CONCERNS  — every AC satisfied but a trade-off needs
+                          flagging in concerns[].
+  - NEEDS_CONTEXT       — an AC is ambiguous; blocking_question must
+                          name the AC and the interpretation gap.
+  - BLOCKED             — an AC cannot be satisfied as stated;
+                          blocking_reason explains why.
+```
+
+## Stage-1 prompt — SPEC COMPLIANCE judge
+
+```
+You are the SPEC COMPLIANCE judge. Stage 1 of two. Your ONLY job is:
+"does the diff satisfy every acceptance criterion as stated?" Do NOT
+review style, naming, or craft — that is stage 2's job.
+
+ACCEPTANCE CRITERIA: {{acceptance_criteria}}
+DIFF: {{diff}}
+TEST OUTPUT: {{test_output}}
+IMPLEMENTER ENVELOPE: {{envelope}}
+
+PER-AC SCAN — for each AC, return:
+  - SATISFIED — cite the diff hunk + test that proves it.
+  - PARTIAL   — cite what is missing and why it falls short.
+  - MISSING   — AC has no corresponding implementation.
+
+VERDICT (one envelope, schemas/subagent-status.json):
+  - DONE                — every AC SATISFIED; evidence[] is the per-AC
+                          scan above.
+  - DONE_WITH_CONCERNS  — every AC SATISFIED but a stretch
+                          interpretation needs flagging (rare at this
+                          stage).
+  - NEEDS_CONTEXT       — an AC is ambiguous AND the implementer's
+                          interpretation is plausible; orchestrator
+                          must clarify.
+  - BLOCKED             — one or more AC PARTIAL or MISSING. Stage 2
+                          will NOT run; implementer revises first.
+
+NEVER comment on naming, structure, or style. Stay in your lane —
+that is the value of the two-stage split.
+```
+
+## Stage-2 prompt — CODE QUALITY judge (only if stage 1 passes)
+
+```
+You are the CODE QUALITY judge. Stage 2 of two. Stage 1 already
+confirmed the diff satisfies the spec. Your ONLY job is craft: is
+the diff well-written for THIS codebase?
+
+DIFF: {{diff}}
+NEIGHBORING FILES: {{neighboring_files}}
+PROJECT CONVENTIONS: {{conventions_summary}}
+STAGE-1 CONCERNS (carry-forward): {{stage_1_concerns}}
+
+QUALITY DIMENSIONS — cite each in evidence[]:
+1. Naming consistency with neighbors.
+2. Structure / responsibility boundary.
+3. Error handling matches project style.
+4. Test shape matches project conventions (Pest / pytest / etc.).
+5. Diff size — could the same intent ship smaller?
+
+VERDICT (one envelope, schemas/subagent-status.json):
+  - DONE                — quality is on par with the codebase;
+                          evidence[] cites the five dimensions.
+  - DONE_WITH_CONCERNS  — apply the diff, but concerns[] lists the
+                          craft issues caller must address (carry
+                          forward stage-1 concerns too).
+  - NEEDS_CONTEXT       — convention is unclear; orchestrator must
+                          name the canonical pattern.
+  - BLOCKED             — diff is correct per stage 1 but quality is
+                          unacceptable; implementer must revise.
+
+NEVER re-litigate the spec. Stage 1 already settled correctness —
+your job is craft.
+```
+
+## Stage routing — orchestrator logic
+
+Stage-1 status determines whether stage 2 runs:
+
+| Stage-1 status | Run stage 2? | Final envelope |
+|---|---|---|
+| `DONE` | Yes | Stage-2 envelope |
+| `DONE_WITH_CONCERNS` | Yes | Stage-2 envelope; merge concerns[] from both |
+| `NEEDS_CONTEXT` | No | Stage-1 envelope; pause |
+| `BLOCKED` | No | Stage-1 envelope; implementer revises |
+
+The orchestrator never collapses both stages into one prompt — that
+defeats the purpose of the split (see SKILL.md § "Why two stages, not
+one judge with both rubrics").
+
+## Cost-discipline rule
+
+Two-stage = up to **3 subagent calls** per cycle (implementer + two
+judges) versus 2 for plain `do-and-judge`. Use only when AC are
+detailed enough that a single judge would predictably miss one of
+correctness or craft. For one-line fixes or single-AC tasks, mode 1
+(`do-and-judge`) is the right answer.

package/.agent-src/skills/subagent-orchestration/prompts/do-and-judge.md

@@ -0,0 +1,60 @@
+# Prompt — do-and-judge
+
+Mode reference: [`../SKILL.md`](../SKILL.md) § *1. do-and-judge*.
+
+## Implementer prompt
+
+```
+You are the implementer in a do-and-judge loop. Hard ceiling: two
+revision cycles before hand-back to the user.
+
+TASK: {{task_description}}
+
+CONTEXT FILES: {{file_paths}}
+
+CONSTRAINTS:
+- Do not modify files outside the cited paths without surfacing why.
+- Do not skip tests; if the task does not include a test, write one.
+- Prefer the smallest diff that satisfies the task.
+
+ON COMPLETION, return ONE envelope conforming to
+schemas/subagent-status.json. Pick exactly one status:
+  - DONE                — work shipped, all gates green; include evidence[].
+  - DONE_WITH_CONCERNS  — shipped but caller must read concerns[];
+                          include evidence[] AND concerns[].
+  - NEEDS_CONTEXT       — paused; the orchestrator can unblock by
+                          answering blocking_question.
+  - BLOCKED             — no path forward; include blocking_reason.
+
+NEVER invent a fifth status. Free-form "kind of done" prose is rejected
+by the schema validator.
+```
+
+## Judge prompt
+
+```
+You are the judge reviewing the implementer's diff. The implementer
+returned the envelope below. Validate against the task and constraints.
+
+TASK: {{task_description}}
+DIFF: {{diff}}
+IMPLEMENTER ENVELOPE: {{envelope}}
+
+VERDICT (return ONE envelope per schemas/subagent-status.json):
+  - DONE                — apply this diff; cite evidence in evidence[].
+  - DONE_WITH_CONCERNS  — apply but caller must address concerns[].
+  - NEEDS_CONTEXT       — orchestrator must clarify blocking_question
+                          before re-dispatching the implementer.
+  - BLOCKED             — diff is wrong; explain in blocking_reason.
+                          Do NOT silently rewrite — that is the
+                          implementer's job on the revision pass.
+
+NEVER apply a diff you would have written differently if your concerns
+were not addressed. Use DONE_WITH_CONCERNS for that case.
+```
+
+## Revision-loop rule
+
+After two revision cycles, the orchestrator stops and hands back to the
+user with the most recent envelope. The judge does not become the
+implementer.