pitroom 0.6.0

package/skills/pitroom-debugging/find-polluter.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Bisection script to find which test creates unwanted files/state
+# Usage: ./find-polluter.sh <file_or_dir_to_check> <test_pattern>
+# Example: ./find-polluter.sh '.git' 'src/**/*.test.ts'
+
+set -e
+
+if [ $# -ne 2 ]; then
+  echo "Usage: $0 <file_to_check> <test_pattern>"
+  echo "Example: $0 '.git' 'src/**/*.test.ts'"
+  exit 1
+fi
+
+POLLUTION_CHECK="$1"
+TEST_PATTERN="$2"
+
+echo "🔍 Searching for test that creates: $POLLUTION_CHECK"
+echo "Test pattern: $TEST_PATTERN"
+echo ""
+
+# Get list of test files (find . emits ./-prefixed paths, so accept the
+# pattern written with or without a leading ./)
+TEST_PATTERN="${TEST_PATTERN#./}"
+# find -path can't match '**/' against zero directory levels, so a pattern
+# like src/**/*.test.ts would skip src/top.test.ts; also try the pattern
+# with '**/' collapsed to cover files directly under the base directory.
+TEST_FILES=$(find . \( -path "./$TEST_PATTERN" -o -path "./${TEST_PATTERN//\*\*\//}" \) | sort -u)
+if [ -z "$TEST_FILES" ]; then
+  TOTAL=0
+else
+  TOTAL=$(printf '%s\n' "$TEST_FILES" | wc -l | tr -d ' ')
+fi
+
+echo "Found $TOTAL test files"
+echo ""
+
+COUNT=0
+for TEST_FILE in $TEST_FILES; do
+  COUNT=$((COUNT + 1))
+
+  # Skip if pollution already exists
+  if [ -e "$POLLUTION_CHECK" ]; then
+    echo "⚠️  Pollution already exists before test $COUNT/$TOTAL"
+    echo "   Skipping: $TEST_FILE"
+    continue
+  fi
+
+  echo "[$COUNT/$TOTAL] Testing: $TEST_FILE"
+
+  # Run the test
+  npm test "$TEST_FILE" > /dev/null 2>&1 || true
+
+  # Check if pollution appeared
+  if [ -e "$POLLUTION_CHECK" ]; then
+    echo ""
+    echo "🎯 FOUND POLLUTER!"
+    echo "   Test: $TEST_FILE"
+    echo "   Created: $POLLUTION_CHECK"
+    echo ""
+    echo "Pollution details:"
+    ls -la "$POLLUTION_CHECK"
+    echo ""
+    echo "To investigate:"
+    echo "  npm test $TEST_FILE    # Run just this test"
+    echo "  cat $TEST_FILE         # Review test code"
+    exit 1
+  fi
+done
+
+echo ""
+echo "✅ No polluter found - all tests clean!"
+exit 0

package/skills/pitroom-debugging/root-cause-tracing.md

@@ -0,0 +1,169 @@
+# Root Cause Tracing
+
+## Overview
+
+Bugs often manifest deep in the call stack (git init in wrong directory, file created in wrong location, database opened with wrong path). Your instinct is to fix where the error appears, but that's treating a symptom.
+
+**Core principle:** Trace backward through the call chain until you find the original trigger, then fix at the source.
+
+## When to Use
+
+```dot
+digraph when_to_use {
+    "Bug appears deep in stack?" [shape=diamond];
+    "Can trace backwards?" [shape=diamond];
+    "Fix at symptom point" [shape=box];
+    "Trace to original trigger" [shape=box];
+    "BETTER: Also add defense-in-depth" [shape=box];
+
+    "Bug appears deep in stack?" -> "Can trace backwards?" [label="yes"];
+    "Can trace backwards?" -> "Trace to original trigger" [label="yes"];
+    "Can trace backwards?" -> "Fix at symptom point" [label="no - dead end"];
+    "Trace to original trigger" -> "BETTER: Also add defense-in-depth";
+}
+```
+
+**Use when:**
+- Error happens deep in execution (not at entry point)
+- Stack trace shows long call chain
+- Unclear where invalid data originated
+- Need to find which test/code triggers the problem
+
+## The Tracing Process
+
+### 1. Observe the Symptom
+```
+Error: git init failed in ~/project/packages/core
+```
+
+### 2. Find Immediate Cause
+**What code directly causes this?**
+```typescript
+await execFileAsync('git', ['init'], { cwd: projectDir });
+```
+
+### 3. Ask: What Called This?
+```typescript
+WorktreeManager.createSessionWorktree(projectDir, sessionId)
+  → called by Session.initializeWorkspace()
+  → called by Session.create()
+  → called by test at Project.create()
+```
+
+### 4. Keep Tracing Up
+**What value was passed?**
+- `projectDir = ''` (empty string!)
+- Empty string as `cwd` resolves to `process.cwd()`
+- That's the source code directory!
+
+### 5. Find Original Trigger
+**Where did empty string come from?**
+```typescript
+const context = setupCoreTest(); // Returns { tempDir: '' }
+Project.create('name', context.tempDir); // Accessed before beforeEach!
+```
+
+## Adding Stack Traces
+
+When you can't trace manually, add instrumentation:
+
+```typescript
+// Before the problematic operation
+async function gitInit(directory: string) {
+  const stack = new Error().stack;
+  console.error('DEBUG git init:', {
+    directory,
+    cwd: process.cwd(),
+    nodeEnv: process.env.NODE_ENV,
+    stack,
+  });
+
+  await execFileAsync('git', ['init'], { cwd: directory });
+}
+```
+
+**Critical:** Use `console.error()` in tests (not logger - may not show)
+
+**Run and capture:**
+```bash
+npm test 2>&1 | grep 'DEBUG git init'
+```
+
+**Analyze stack traces:**
+- Look for test file names
+- Find the line number triggering the call
+- Identify the pattern (same test? same parameter?)
+
+## Finding Which Test Causes Pollution
+
+If something appears during tests but you don't know which test:
+
+Use the bisection script `find-polluter.sh` in this directory:
+
+```bash
+./find-polluter.sh '.git' 'src/**/*.test.ts'
+```
+
+Runs tests one-by-one, stops at first polluter. See script for usage.
+
+## Real Example: Empty projectDir
+
+**Symptom:** `.git` created in `packages/core/` (source code)
+
+**Trace chain:**
+1. `git init` runs in `process.cwd()` ← empty cwd parameter
+2. WorktreeManager called with empty projectDir
+3. Session.create() passed empty string
+4. Test accessed `context.tempDir` before beforeEach
+5. setupCoreTest() returns `{ tempDir: '' }` initially
+
+**Root cause:** Top-level variable initialization accessing empty value
+
+**Fix:** Made tempDir a getter that throws if accessed before beforeEach
+
+**Also added defense-in-depth:**
+- Layer 1: Project.create() validates directory
+- Layer 2: WorkspaceManager validates not empty
+- Layer 3: NODE_ENV guard refuses git init outside tmpdir
+- Layer 4: Stack trace logging before git init
+
+## Key Principle
+
+```dot
+digraph principle {
+    "Found immediate cause" [shape=ellipse];
+    "Can trace one level up?" [shape=diamond];
+    "Trace backwards" [shape=box];
+    "Is this the source?" [shape=diamond];
+    "Fix at source" [shape=box];
+    "Add validation at each layer" [shape=box];
+    "Bug impossible" [shape=doublecircle];
+    "NEVER fix just the symptom" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
+
+    "Found immediate cause" -> "Can trace one level up?";
+    "Can trace one level up?" -> "Trace backwards" [label="yes"];
+    "Can trace one level up?" -> "NEVER fix just the symptom" [label="no"];
+    "Trace backwards" -> "Is this the source?";
+    "Is this the source?" -> "Trace backwards" [label="no - keeps going"];
+    "Is this the source?" -> "Fix at source" [label="yes"];
+    "Fix at source" -> "Add validation at each layer";
+    "Add validation at each layer" -> "Bug impossible";
+}
+```
+
+**NEVER fix just where the error appears.** Trace back to find the original trigger.
+
+## Stack Trace Tips
+
+**In tests:** Use `console.error()` not logger - logger may be suppressed
+**Before operation:** Log before the dangerous operation, not after it fails
+**Include context:** Directory, cwd, environment variables, timestamps
+**Capture stack:** `new Error().stack` shows complete call chain
+
+## Real-World Impact
+
+From debugging session (2025-10-03):
+- Found root cause through 5-level trace
+- Fixed at source (getter validation)
+- Added 4 layers of defense
+- 1847 tests passed, zero pollution

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

@@ -0,0 +1,138 @@
+---
+name: pitroom-driven-development
+description: Use when executing a written implementation plan - each task goes to a Pitroom worker in an isolated copy, a worker on another model reviews it, and you rule, apply and commit between tasks.
+---
+
+# Pitroom-Driven Development
+
+Execute a plan by giving each task to a fresh implementer worker in an isolated copy, a task review (spec compliance and code quality) by a worker on another model after each, and a whole-branch review at the end. You are the controller: you never write a task's code yourself; you rule on conflicts, apply patches and commit.
+
+**Why workers:** each gets exactly its task (Pitroom extracts it from the plan) and none of your conversation. Their tokens are cheap and your context stays free for coordination. A reviewer on a different backend is a second model, not the implementer grading itself.
+
+**Core principle:** fresh worker per task + task review on another model + whole-branch review = high quality at worker prices.
+
+**Narration:** between tool calls, at most one short line. `pitroom plan status` and the tool results carry the record.
+
+**Continuous execution:** do not pause to check in with your human partner between tasks. The only reasons to stop are the four below, or all tasks complete. "Should I continue?" prompts waste their time: they asked you to execute the plan.
+
+**Rulings, not stalls.** Conflicts, ambiguities, plan defects, a cap you would have asked to exceed: decide them. The spec is the binding authority, the plan is its argument, and your judgment settles what neither answers. Record every decision with `pitroom plan note PLAN "Task N: Ruling: <what you decided> — <why> — <what it costs if wrong>"` and keep going. A wrong ruling costs rework your human partner can see and undo; a session parked on a question costs their whole day.
+
+Four things stop you, and only these: an irreversible or destructive operation; a security-sensitive action; a side effect outside this branch that norms say you ask about first (a merge, a push, a publish); a plan so broken that every path forward is a guess.
+
+## Setup
+
+1. **Branch:** `pitroom-worktrees`. Never implement on main/master without explicit consent.
+2. **Where are we:** `pitroom plan status PLAN`. A task with a `Task N: complete` note is done: never re-dispatch it. A task with runs but no completion note is mid-loop: continue it from its last run and review. After compaction, trust `pitroom plan status` and `git log` over your memory.
+3. **Read the plan once**, and its Spec. Note the Global Constraints. Create a todo per task.
+4. **Pre-flight scan**, before Task 1. Its output is a table, not a verdict: one row for every pair of tasks that share a file or an interface (what one produces against what the other consumes), one row per task on whether its own text agrees with itself (its tests against its code, the files it creates against the files it later touches), and anything the plan mandates that the review rubric treats as a defect (a test that asserts nothing, duplicated logic). Rule on every finding and note the rulings. The table also tells you which tasks are independent (see Parallel tasks).
+5. **Worker setup:** tasks that run the project's tests need its dependencies inside the isolated copy: pass `--link node_modules` (or `.venv`, …) or set `link` in the config.
+
+## Tiers
+
+Every task names a tier (`**Worker:** cheap|standard|capable`), and `pitroom run --plan` uses it. The config maps tiers to workers (`pitroom config` shows `tiers`); an unconfigured tier falls back to the default worker with a warning. Escalating means the next tier up: cheap → standard → capable. Above capable is you, and you only rule; you do not write the code.
+
+## The task loop
+
+### 1. Implement
+
+```bash
+pitroom run -i --plan PLAN --step N --link node_modules --verify "<the task's test command>" --bg \
+  "<optional notes: interfaces or decisions from earlier tasks the brief cannot know, your resolution of an ambiguity>"
+```
+
+Pitroom gives the worker the implementer rules, the plan's context and Global Constraints, and Task N's text; never paste plan text yourself. The run joins the plan's group: follow it with `pitroom watch -g <plan name> --json` or `pitroom wait <run>`.
+
+### 2. Handle the status
+
+The report starts with `plan: … · STATUS <value>`:
+
+- **DONE:** review it (step 3).
+- **DONE_WITH_CONCERNS:** read OPEN ISSUES. Doubts about correctness or scope: resolve them first with `pitroom run --continue <run> "<guidance>"`. Observations: note them and review.
+- **NEEDS_CONTEXT:** `pitroom run --continue <run> "<the missing context>"`.
+- **BLOCKED:** a context problem → `--continue` with context; it needs more reasoning → a fresh run one tier up (`--tier`); too large → split it and note the ruling; the plan is wrong → rule, note, and re-dispatch with the ruling in the notes.
+- **unknown** (no status line): treat it as DONE_WITH_CONCERNS.
+
+Never make the same worker retry without changing something. A failing `verify:` line is a finding for the fix loop, not a reason to fix it yourself.
+
+### 3. Review
+
+```bash
+pitroom review <run>
+```
+
+A read-only worker on another backend gets one package: the brief, the implementer's report and the diff with context. It returns `SPEC PASS|FAIL`, `QUALITY APPROVED|NEEDS-FIXES` and the issues by severity. Never skip it, and never accept a review that lacks either verdict; the implementer's self-review never replaces it.
+
+- Don't pre-judge: never tell a reviewer to ignore something. A finding you think is a false positive enters the loop; you adjudicate at the cap.
+- CANNOT VERIFY items (requirements in unchanged code or across tasks): check each yourself before completing the task. A real gap is a failed spec review.
+
+### 4. The fix loop
+
+It triggers on SPEC FAIL, any Critical or Important finding, or a CANNOT VERIFY item you confirmed. Minor findings never enter the loop: note them (`pitroom plan note PLAN "Task N: minor (deferred): …"`) for the final review. A finding that conflicts with the plan's text is yours to rule on first (the spec wins), noted before you act.
+
+A round is one fix plus one scoped re-review. Five rounds at most per task:
+
+- **Rounds 1-3:** `pitroom run --continue <last run> "<the open findings, verbatim>"` (same session, same isolated copy), then `pitroom review <fix run>`. Pitroom sees a fix round and sends only its diff and the previous findings.
+- **Rounds 4-5:** a fresh implementer one tier up: `pitroom run -i --plan PLAN --step N --tier <next> "A prior worker attempted this task <R> times; you own it now. Open findings: …"`, `pitroom discard <old run>`, then `pitroom review <new run>`.
+- After each round: `pitroom plan note PLAN "Task N: fix round R/5 (X addressed, Y open — <one-liners>)"`.
+
+Never fix findings yourself: controller fixes skip review.
+
+**The breaker.** When round 5 still leaves findings open, stop and adjudicate each one:
+- The reviewer is wrong, or the point is contestable: park it — `Task N: parked — <finding> — Ruling: <why the code stands>`.
+- Real, but nothing downstream builds on it: park it the same way, saying it is real and deferred.
+- Real and load-bearing: rule on the smallest change that unblocks the dependent work, note it, and carry it into the next task's notes. Stop only if every path forward is a guess.
+
+Adjudicate only at the cap; every adjudication is a note. A silent discard is forbidden.
+
+### 5. Land the task
+
+When the review is clean, or every open finding is parked with a ruling at the cap:
+
+```bash
+pitroom apply <last run>        # checked apply; refuses on conflict
+<the task's tests, run by you>
+git add <the task's files> && git commit -m "<the plan's commit message>"
+pitroom plan note PLAN "Task N: complete (<base7>..<head7>, review clean)"
+```
+
+Mark the todo complete and move on. Never start a dependent task before this one is applied: its isolated copy is taken from your tree.
+
+## Parallel tasks
+
+Tasks the pre-flight table shows as independent (no shared file, no interface between them) may run at once: start each with `pitroom run -i --plan PLAN --step N --bg` (they share the plan's group), watch them with `pitroom watch -g <plan name> --json`, review each, then apply and commit them one at a time in plan order. When `pitroom apply` refuses a patch, look at what conflicts. If only generated files differ (such as a rebuilt `dist/`), apply the rest of the patch and rebuild them. If source hunks conflict, do not drop them: run the task again from the current tree with the conflict in its notes and review that run as usual, or resolve every hunk by hand and review the result with `pitroom review --range` before you commit. Everything that shares a file runs in sequence.
+
+## Waiting
+
+Never poll with short sleeps, and never sit in one silent, open-ended wait. While workers run, do your own bookkeeping: rulings, reading reports, the next task's notes. When idle, `pitroom wait <run> --timeout 540`; exit 75 means still running: post one line of status and call it again. `pitroom stop <run>` a worker that is clearly stuck, and redo its task.
+
+## Final review
+
+After the last task:
+
+```bash
+pitroom review --range "$(git merge-base <base> HEAD)..HEAD" --plan PLAN
+```
+
+It runs on the `capable` tier with the whole-branch rubric, and the package carries the plan and your notes, so the reviewer triages the deferred minors and parked findings. If it returns findings: ONE fix run with the complete list, not one run per finding (`pitroom run -i --tier capable --link node_modules "<all findings>"`), exactly one review of that fix (`pitroom review <fix run>`), then apply, test and commit. Adjudicate the residual findings as in the breaker. There is no second fix wave: residual load-bearing findings go to your human partner through `pitroom-finishing`.
+
+## Finish
+
+Collect every note containing `Ruling:` (`pitroom plan status PLAN` lists them) into your final message under "Rulings I made", in the order you made them, each with what it costs if wrong. The list is exhaustive: it is the only place the decisions you took on your human partner's behalf reach them. Then use `pitroom-finishing`.
+
+## Inline execution
+
+When Pitroom is unavailable or your human partner chose inline execution: execute the tasks yourself, in order, following each step exactly and running every verification the plan specifies, with `pitroom-tdd` and `pitroom-verification`. Stop and ask when blocked (a missing dependency, a failing test, an unclear instruction); don't guess. Review the branch with `pitroom-review` when Pitroom is available, then use `pitroom-finishing`.
+
+## Common rationalizations
+
+| Excuse | Reality |
+|---|---|
+| "Close enough on spec compliance" | A spec gap is not done. Fix it, or reach the cap and adjudicate. |
+| "I'll fix it myself, dispatching is overhead" | Controller fixes skip review and fill your context. Continue the worker. |
+| "One more round will converge" | Past the cap, rounds don't converge: the failure is structural. Adjudicate. |
+| "The reviewer will just find something new anyway" | Fix-round reviews see only the fix diff; they cannot wander. |
+| "This finding is obviously wrong, I'll drop it" | You adjudicate only at the cap, and every ruling is a note. |
+| "The fix was small, skip the re-review" | Unreviewed fixes are how regressions land. |
+| "The same model can review its own work" | `pitroom review` picks another backend when one is configured; configure `tiers` if it can't. |
+| "Notes are overhead" | Notes and run records are what survive compaction. Controllers without them re-dispatch finished tasks. |
+| "The worker said the tests pass" | Run them after applying. `pitroom-verification` |

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

@@ -0,0 +1,68 @@
+<!--
+Implementer brief for `pitroom run -i --plan PLAN --step N`. Pitroom fills the
+placeholders and wraps the result in its worker contract (rules + answer format).
+-->
+You are implementing Task {{STEP}}: {{TITLE}} of the plan {{PLAN_FILE}}.
+
+## Your brief
+
+This is your requirements document, with the exact values to use verbatim. Other workers handle the plan's other tasks; do only this one.
+
+<brief>
+{{BRIEF}}
+</brief>
+
+## Notes from the primary agent
+
+{{NOTES}}
+
+## Your job
+
+1. Implement exactly what the task specifies: nothing more (YAGNI), nothing less.
+2. Write the tests the task specifies. When the task says to use TDD: write the failing test, run it and watch it fail for the expected reason, write the minimal code, run it and watch it pass.
+3. While iterating, run the focused test for what you are changing; run the full relevant suite once before you answer.
+4. Self-review (below), fix what you find, then answer.
+
+The brief may contain commit steps. You never commit: skip them. The primary agent reviews your diff, applies it and commits.
+
+## You work alone
+
+Do all of this task's work yourself. Never delegate, never start other agents or `pitroom`, and never ask for a review: a reviewer on another model is already scheduled for your diff.
+
+## Code organization
+
+- Follow the file structure defined in the plan. Each file has one clear responsibility and a well-defined interface.
+- If a file you create grows beyond the plan's intent, stop and answer DONE_WITH_CONCERNS; do not split files on your own.
+- In existing code, follow the established patterns. Improve code you touch the way a good developer would; do not restructure anything outside your task.
+
+## When you are in over your head
+
+It is always fine to stop and say "this is too hard for me". Bad work is worse than no work. Answer BLOCKED or NEEDS_CONTEXT when:
+- the task needs an architectural decision with several valid approaches,
+- you need to understand code beyond what was provided and cannot find clarity,
+- you are unsure your approach is correct,
+- the task means restructuring code in ways the plan did not anticipate,
+- you keep reading file after file without making progress.
+
+Say specifically what you are stuck on, what you tried and what would unblock you. The primary agent can add context, give the task to a more capable worker, or split it.
+
+## Self-review before answering
+
+- Completeness: every requirement in the brief implemented? Edge cases?
+- Quality: clear names (what things do, not how), clean and maintainable?
+- Discipline: only what was requested, following the codebase's patterns?
+- Testing: do the tests verify real behaviour, not mocks? Is the test output pristine (no warnings or noise)?
+
+Fix what you find before answering.
+
+## Answer
+
+Start your answer with one status line:
+
+STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
+
+Then the usual answer format. In VERIFICATION give the commands you ran and their results; when the task required TDD add TDD EVIDENCE: the RED command with the relevant failing output (and why that failure was expected), then the GREEN command with the passing output. Put doubts about correctness (DONE_WITH_CONCERNS) and the specifics of BLOCKED or NEEDS_CONTEXT in OPEN ISSUES. Never silently hand over work you are unsure about.
+
+## If you are resumed with review findings
+
+Fix them, re-run the tests that cover the changed code, and answer again in the same format with a FIX REPORT in DETAILS: each finding, what you changed (file:line), the covering tests, the command and its output. Reviewers do not re-run tests; your answer is the evidence.

package/skills/pitroom-driven-development/re-review-prompt.md

@@ -0,0 +1,41 @@
+<!--
+Scoped re-review for `pitroom review <fix run>` (a follow-up of a run that was
+already reviewed). Pitroom writes the package and fills {{PACKAGE_FILE}}.
+-->
+You are re-reviewing one task's fix round. A previous review produced findings; the implementer has attempted to fix them. Your job is a verdict on each finding and an inspection of the fix diff, nothing else.
+
+## What to read
+
+One file holds everything; read it once: {{PACKAGE_FILE}}
+It contains, in order:
+1. BRIEF: the task that was requested.
+2. PREVIOUS FINDINGS: the previous review; its Critical and Important findings and spec gaps are under verification.
+3. FIX REPORT: what the implementer says it changed, with the tests it re-ran.
+4. FIX DIFF: only this fix round's changes, with 10 lines of context.
+
+Your working directory contains the code after the fix. You are read-only: do not change files, the index, HEAD or branches.
+
+## You work alone
+
+Do the whole re-review yourself. Never delegate or start other agents.
+
+## Scope
+
+Your scope is the previous findings and the fix diff. Give a verdict on every Critical and Important finding and every spec gap. Inspect the fix diff for problems the fix itself introduced. Do not re-review code the fix did not touch: an issue entirely outside the fix diff goes under OUT OF SCOPE and does not block the task; a whole-branch review happens after all tasks.
+
+## Tests
+
+The fix report is unverified claims: check that it names the covering tests and shows their output, and verify its claims against the diff. Do not re-run the suite. Run a focused test only when the code raises a specific doubt that no existing run answers.
+
+## Answer
+
+Your SUMMARY is exactly one line:
+SUMMARY: SPEC: PASS|FAIL · QUALITY: APPROVED|NEEDS_FIXES · ISSUES: critical=N important=N minor=N
+
+SPEC is PASS only when every finding under verification is ADDRESSED. QUALITY is NEEDS_FIXES when the fix diff introduced any Critical or Important problem. ISSUES counts the findings still open plus the new problems, by severity.
+
+In DETAILS, in this order:
+- FINDING VERDICTS: for each finding, in order, the finding in one line, then ADDRESSED or NOT ADDRESSED with file:line evidence. "Attempted" is not addressed: the specific defect must no longer exist.
+- NEW BREAKAGE: problems the fix introduced, with severity and file:line, or "none".
+- OUT OF SCOPE: issues entirely outside the fix diff, or "none".
+A file:line is the project file's path and its line number after the change (from the diff's hunk headers), never a line of the package file. No preamble and no closing summary.

package/skills/pitroom-driven-development/task-reviewer-prompt.md

@@ -0,0 +1,59 @@
+<!--
+Task review for `pitroom review <run>`. Pitroom writes the review package, fills
+{{PACKAGE_FILE}} and runs this read-only, by default on another worker.
+-->
+You are reviewing one task's implementation: first whether it matches its requirements, then whether it is well built. This is a task-scoped gate, not a merge review; a whole-branch review happens after all tasks.
+
+## What to read
+
+One file holds everything; read it once: {{PACKAGE_FILE}}
+It contains, in order:
+1. BRIEF: what was requested (for a plan task: the plan's context, its global constraints and the task).
+2. REPORT: what the implementer claims it built, with its test evidence.
+3. DIFF: the change under review, with 10 lines of context.
+
+Your working directory contains the code after this change. The diff's context lines are your view of the changed files: open a changed file only when a hunk you must judge is cut off mid-function, and say so. Do not crawl the codebase: look outside the diff only to check a concrete risk you can name (a changed contract, lock order, shared mutable state: then check its call sites), one focused check per named risk, and name both the risk and the check.
+
+You are read-only: do not change files, the index, HEAD or branches.
+
+## You work alone
+
+Do the whole review yourself. Never delegate or start other agents. If the diff is large, review it in passes and say so.
+
+## Do not trust the report
+
+The report is unverified claims: verify them against the diff. Design rationales in the report ("kept it simple per YAGNI") are the implementer grading its own work; judge the code on its merits. A stated rationale never lowers a finding's severity.
+
+## Tests
+
+The implementer ran the tests and reported the results. Do not re-run the suite to confirm them. Run a test only when the code raises a specific doubt that no existing run answers, and then only a focused test. Warnings or noise in the reported test output are findings. If the evidence is missing or garbled in the package, report that as a gap; do not regenerate it.
+
+## Part 1: Spec compliance
+
+Compare the diff with the brief:
+- Missing: requirements skipped, or claimed without being implemented.
+- Extra: features that were not requested, over-engineering.
+- Misunderstood: the right feature built the wrong way, or the wrong problem solved.
+
+If the brief lists several files each with its own change, check that every listed file has its hunk; a listed file the diff never touches is Missing. A requirement you cannot verify from this diff (it lives in unchanged code or spans tasks) is a CANNOT VERIFY item, not a reason to search wider.
+
+## Part 2: Code quality
+
+- Separation of concerns, error handling, DRY without premature abstraction, edge cases.
+- Tests verify real behaviour (not mocks) and cover the task's edge cases.
+- Each file has one clear responsibility; the plan's file structure is followed; the change does not create files that are already large or grow existing files much (pre-existing size is not a finding).
+
+Cite file:line for every finding, and for every check you would otherwise answer with a bare "yes". A file:line is the project file's path and its line number after the change (from the diff's hunk headers), never a line of the package file.
+
+## Calibration
+
+Critical: breaks behaviour, loses data, security. Important: the task cannot be trusted until it is fixed (incorrect or fragile behaviour, a missed requirement, verbatim duplication of logic, swallowed errors, tests that assert nothing). Coverage that could be broader and polish are Minor. If the plan explicitly mandates something this rubric calls a defect, report it as Important and label it plan-mandated: the human decides. Say what was done well before listing issues.
+
+## Answer
+
+Your SUMMARY is exactly one line:
+SUMMARY: SPEC: PASS|FAIL · QUALITY: APPROVED|NEEDS_FIXES · ISSUES: critical=N important=N minor=N
+
+SPEC is FAIL when anything is Missing, Extra or Misunderstood. QUALITY is NEEDS_FIXES when there is any Critical or Important issue.
+
+In DETAILS, in this order: SPEC FINDINGS (or "none"), CANNOT VERIFY (what the primary should check, or "none"), STRENGTHS, then CRITICAL, IMPORTANT and MINOR issues, each with file:line, what is wrong, why it matters and how to fix it if not obvious. No preamble and no closing summary.