@leing2021/super-pi 0.25.2 → 0.26.0

package/README.md

@@ -18,7 +18,7 @@ Install, describe what you want to build, then keep saying "continue." Super Pi
 pi install npm:@leing2021/super-pi
 ```
 
----
+> **Project trust (pi ≥ 0.79):** Pi asks before loading project-local settings, resources, and packages. On first use, approve the project trust prompt so Super Pi can read `.pi/settings.json` and load its skills/extensions. Use `pi --approve` for non-interactive runs.
 
 ## Highlights
 
@@ -73,7 +73,7 @@ You: /skill:03-work docs/plans/plan.md
 | **01-brainstorm** | Structured multi-round discovery, domain vocabulary persistence | `brainstorm_dialog` |
 | **02-plan** | TDD-gated implementation units, optional CEO Review | `plan_diff` |
 | **03-work** | Inline execution, checkpoint resume, strict TDD, stop-the-line | `session_checkpoint`, `task_splitter` |
-| **04-review** | Auto-assigned reviewers, five-axis findings, autofix loop | `review_router` |
+| **04-review** | Auto-assigned reviewers, six-axis findings (Standards + Spec), autofix loop | `review_router` |
 | **05-learn** | Pattern extraction → searchable solution artifacts | `pattern_extractor` |
 | **06-next** | Next-step recommendation + workflow status | `workflow_state` |
 | **07-worktree** | Isolated git worktree development | `worktree_manager` |
@@ -114,7 +114,7 @@ Super Pi is not a fork or wrapper. It extracts useful methods from the projects
 | [superpowers](https://github.com/obra/superpowers) | Strict TDD gates, design checklists, review discipline, and the idea that agents need hard gates instead of gentle suggestions. |
 | [compound-engineering-plugin](https://github.com/EveryInc/compound-engineering-plugin) | The five-step think → plan → build → review → learn loop and the knowledge-compounding backbone. |
 | [gstack](https://github.com/garrytan/gstack) | YC-style forcing questions, CEO Review cognitive frameworks, browser QA patterns, failure maps, and evidence-first validation. |
-| [mattpocock/skills](https://github.com/mattpocock/skills) | Context glossary (`CONTEXT.md`) for cross-session term persistence, lightweight ADR with three-condition threshold, and feedback-loop-first debug discipline. Adopted as reference templates embedded into existing skills — no new skills or tools. |
+| [mattpocock/skills](https://github.com/mattpocock/skills) | Context glossary (`CONTEXT.md`) for cross-session term persistence, lightweight ADR with three-condition threshold, feedback-loop-first debug discipline (full diagnosis loop with completion criteria and post-mortem handoff), deep-module vocabulary, the review Spec axis (plan-vs-diff with traceback to original wording), and the out-of-scope knowledge base. Adopted as self-contained `skills/references/` — no external path deps, no issue-tracker deps. |
 
 ---
 

package/extensions/ce-core/index.ts

@@ -1,6 +1,7 @@
 import { readFile } from "node:fs/promises"
 import path from "node:path"
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"
+import { CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent"
 import { Type } from "typebox"
 import { createArtifactHelperTool, type ArtifactType } from "./tools/artifact-helper"
 import { createAskUserQuestionTool, CUSTOM_SENTINEL } from "./tools/ask-user-question"
@@ -97,15 +98,17 @@ interface StrategySettings {
 }
 
 /**
- * Read settings from two locations:
- * 1. Project-level: {cwd}/.pi/settings.json (highest priority)
- * 2. Global-level: ~/.pi/agent/settings.json (fallback)
+ * Read settings from two locations (config dir honors pi's `CONFIG_DIR_NAME`,
+ * which defaults to `.pi` but is user-configurable since pi 0.79.7):
+ * 1. Project-level: {cwd}/{CONFIG_DIR_NAME}/settings.json (highest priority)
+ * 2. Global-level: ~/{CONFIG_DIR_NAME}/agent/settings.json (fallback)
  *
  * Project-level takes precedence; global-level is used as fallback.
  */
 async function readSettings(cwd: string): Promise<StrategySettings | null> {
+  const agentHome = process.env.HOME || "~"
   // Try project-level first
-  const projectPath = path.join(cwd, ".pi", "settings.json")
+  const projectPath = path.join(cwd, CONFIG_DIR_NAME, "settings.json")
   try {
     const content = await readFile(projectPath, "utf8")
     const projectSettings = JSON.parse(content) as StrategySettings
@@ -118,7 +121,7 @@ async function readSettings(cwd: string): Promise<StrategySettings | null> {
   }
 
   // Fallback to global-level
-  const globalPath = path.join(process.env.HOME || "~", ".pi", "agent", "settings.json")
+  const globalPath = path.join(agentHome, CONFIG_DIR_NAME, "agent", "settings.json")
   try {
     const content = await readFile(globalPath, "utf8")
     return JSON.parse(content) as StrategySettings
@@ -126,8 +129,8 @@ async function readSettings(cwd: string): Promise<StrategySettings | null> {
     // Global settings not found either
   }
 
-  // Try ~/.pi/settings.json as another fallback
-  const altGlobalPath = path.join(process.env.HOME || "~", ".pi", "settings.json")
+  // Try ~/{CONFIG_DIR_NAME}/settings.json as another fallback
+  const altGlobalPath = path.join(agentHome, CONFIG_DIR_NAME, "settings.json")
   try {
     const content = await readFile(altGlobalPath, "utf8")
     return JSON.parse(content) as StrategySettings
@@ -805,7 +808,19 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
     }
   })
 
-  // Tree summary prompt optimizer — keeps branch summaries focused
+  // Branch summary prompt optimizer — appends focus instructions to `/tree`
+  // navigation summaries. `SessionBeforeTreeResult.customInstructions` is
+  // consumed by pi (agent-session.js navigateTree), so this return shape is
+  // effective for branch summaries.
+  //
+  // NOTE on regular context compaction (manual `/compact`, threshold,
+  // overflow): pi's `session_before_compact` result only accepts `cancel` or
+  // a full `compaction` replacement — there is NO prompt-only injection
+  // field (`customInstructions` is an event *input*, not a return value).
+  // So we cannot append focus instructions to regular compaction summaries
+  // without replacing pi's entire summarizer. We deliberately do not hook
+  // `session_before_compact` to avoid dead handlers and needless emit()
+  // overhead on every compaction.
   pi.on("session_before_tree", async (_event, _ctx) => {
     return {
       customInstructions: COMPACTION_FOCUS_INSTRUCTIONS,

package/extensions/ce-core/tools/compaction-optimizer.ts

@@ -2,11 +2,23 @@
 // Compaction Prompt Optimizer
 // ============================================================================
 //
-// Hooks into `session_before_compact` to inject custom instructions that make
-// compaction summaries more focused and useful for coding agent context.
+// Focus instructions injected into pi's branch-summary prompts so summaries
+// stay useful for coding-agent continuation.
 //
-// This is a "prompt-only" optimization — it doesn't replace pi's compaction
-// flow, just adds focus instructions to the summarization prompt.
+// Consumed by the `session_before_tree` hook in `index.ts`, which returns
+// `{ customInstructions, replaceInstructions }`. This return shape IS
+// supported by pi (consumed in `agent-session.js` navigateTree →
+// SessionBeforeTreeResult) and appends focus instructions to summaries
+// generated on `/tree` navigation.
+//
+// Regular context compaction (manual `/compact`, threshold, overflow) is
+// NOT covered: pi's `SessionBeforeCompactResult` only accepts `cancel` or a
+// full `compaction` replacement — there is no prompt-only injection field
+// (`customInstructions` is an event *input*, not a return value). Appending
+// focus instructions there would require replacing pi's entire summarizer,
+// so we deliberately do not hook it.
+//
+// This is a "prompt-only" optimization; it does not replace pi's flows.
 
 /**
  * Custom instructions appended to compaction summarization prompts.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leing2021/super-pi",
-  "version": "0.25.2",
+  "version": "0.26.0",
   "private": false,
   "type": "module",
   "description": "Pi-native Compound Engineering package for iterative development workflows",
@@ -35,13 +35,13 @@
     "test": "bun test"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.74.0",
-    "@earendil-works/pi-tui": ">=0.74.0",
+    "@earendil-works/pi-coding-agent": ">=0.79.10",
+    "@earendil-works/pi-tui": ">=0.79.10",
     "typebox": ">=1.0.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.76.0",
-    "@earendil-works/pi-tui": "^0.76.0",
+    "@earendil-works/pi-coding-agent": "^0.80.0",
+    "@earendil-works/pi-tui": "^0.80.0",
     "bun-types": "^1.3.12"
   },
   "pi": {

package/skills/01-brainstorm/SKILL.md

@@ -63,14 +63,14 @@ Before summarizing, ensure the design answers:
 
 After mode-specific questions, check if the project has a `CONTEXT.md` at root.
 If not, and the brainstorm reveals 3+ domain-specific terms with ambiguous meanings,
-offer to create one using `references/context-glossary.md`. Update it inline during
-the session — don't batch. If it exists, cross-reference and flag conflicts:
+offer to create one using `references/context-glossary.md` (contract: `../references/domain-language.md`).
+Update it inline during the session — don't batch. If it exists, cross-reference and flag conflicts:
 
 > "Your CONTEXT.md defines 'cancellation' as X, but you seem to mean Y — which is it?"
 
 ## Stop conditions
 
-Stop and ask instead of guessing when: requirements conflict, success criteria unclear, task spans multiple systems, or user hasn't approved design.
+Stop and ask instead of guessing when: requirements conflict, success criteria unclear, task spans multiple systems, or user hasn't approved design. Before fleshing out an idea, grep `docs/out-of-scope/` for prior rejections — surface matches before proceeding.
 
 ## Approval gate
 

package/skills/01-brainstorm/references/premise-challenge.md

@@ -8,6 +8,11 @@ Before proposing solutions, challenge the premises. Run this after the diagnosti
 2. **What happens if we do nothing?** Real pain point or hypothetical one?
 3. **What existing code already partially solves this?** Map existing patterns, utilities, and flows that could be reused.
 4. **If the deliverable is a new artifact** (CLI binary, library, package, container image, mobile app): **how will users get it?** Code without distribution is code nobody can use.
+5. **External resource signal — verify intent before scope.** When the user mentions an existing resource ("I already have X", "I wrote a skill for Y", "we use Z elsewhere"), do not assume it means "include X in this project." It may mean the opposite: the problem is already solved and should be excluded. Reverse-verify with one question: "You mentioned X — do you want it incorporated here, or is it noting that X already handles this so we don't need to?" A wrong assumption here propagates through every downstream stage (plan, work, review) and surfaces only at merge — three gates that all trust the upstream.
+
+## Failure mode
+
+Skipping this check when the user references an external resource leads to scope creep in the opposite direction assumed: incorporating something the user considered already-handled. The later it surfaces, the costlier the rollback.
 
 ## Output format
 

package/skills/02-plan/SKILL.md

@@ -39,14 +39,15 @@ Every unit follows **RED → GREEN → REFACTOR**:
 
 ## Planning flow
 
-1. **Load context**: consume latest handoff before any broad file reads — `context_handoff load` or read `.context/compound-engineering/handoffs/latest.md`. If found, use `activeFiles` and `blocker` as starting point. If not found, proceed normally (new project).
+1. **Load context**: consume latest handoff before any broad file reads — `context_handoff load` or read `.context/compound-engineering/handoffs/latest.md`. If found, use `activeFiles` and `blocker` as starting point. If not found, proceed normally (new project). Read `CONTEXT.md` if it exists at root — see `../references/domain-language.md`.
 2. Read relevant brainstorm from `docs/brainstorms/`
 3. Run solution search (keywords → grep frontmatter → read top 3)
-4. Gather repository context
-5. **Source-driven check:** For each unit that involves framework/library APIs, add a note: "Verify against official docs before implementing."
-6. If plan exists: use `plan_diff` `compare` → review with user → `patch`
-6. If no plan: write new plan under `docs/plans/` using `references/plan-template.md`
-7. Structure work using `references/implementation-unit-template.md`
+4. Grep `docs/out-of-scope/` for prior rejections of features in this plan
+5. Gather repository context
+6. **Source-driven check:** For each unit that involves framework/library APIs, add a note: "Verify against official docs before implementing."
+7. If plan exists: use `plan_diff` `compare` → review with user → `patch`
+8. If no plan: write new plan under `docs/plans/` using `references/plan-template.md`
+9. Structure work using `references/implementation-unit-template.md`
 8. Verify every unit follows TDD gates
 
 ## Optional: CEO Review

package/skills/03-work/SKILL.md

@@ -24,6 +24,7 @@ See [shared pipeline instructions](../references/pipeline-config.md) for model r
 7. Use **`task_splitter`** to analyze dependencies before execution
 8. If in **worktree** (via `07-worktree`), execute inside it
 9. End by recommending `04-review`
+10. When designing/restructuring modules, use the deep-module vocabulary (`../references/module-design.md`) — evaluate depth and seam placement.
 
 > **Advanced:** If you need external child agent delegation (background runs, parallel audits), install `pi-subagents` separately. Super Pi does not require it.
 
@@ -69,7 +70,7 @@ If the same tool, command, or implementation unit fails 3 consecutive times, sto
 
 ## Workflow
 
-1. **Load context**: consume latest handoff before any broad file reads — `context_handoff load` or read `.context/compound-engineering/handoffs/latest.md`. If found, use `activeFiles`, `blocker`, `verification`, `activeRules` as starting point. If not found, proceed normally.
+1. **Load context**: consume latest handoff before any broad file reads — `context_handoff load` or read `.context/compound-engineering/handoffs/latest.md`. If found, use `activeFiles`, `blocker`, `verification`, `activeRules` as starting point. If not found, proceed normally. Read `CONTEXT.md` if it exists at root — see `../references/domain-language.md`.
 2. Detect input type (plan path vs bare prompt)
 3. Read implementation units if plan path
 4. Load `session_checkpoint` to skip completed units

package/skills/03-work/references/debug-discipline.md

@@ -2,52 +2,122 @@
 
 When stop-the-line triggers, follow this order. Skip phases only when explicitly justified.
 
-## Phase 1 — Build a feedback loop
+**Root principle:** a **tight loop** is the skill. A pass/fail signal that is fast, deterministic, and goes red on *this* bug. Everything else is mechanical — bisection, hypothesis-testing, instrumentation all just consume it. No tight loop, no amount of staring at code will save you.
 
-**This is the skill. Everything else is mechanical.**
+## Phase 1 — Build a tight loop
 
-If you have a fast, deterministic, agent-runnable pass/fail signal, you will find the cause.
-If you don't, no amount of staring at code will save you. Spend disproportionate effort here.
+**This is the skill. Everything else is mechanical.** Spend disproportionate effort here. Be aggressive, be creative, refuse to give up.
 
-### Strategies (try in order)
+### Ways to construct one — try in roughly this order
 
-1. **Failing test** at the seam closest to the bug
-2. **CLI invocation** with fixture input, diff against known-good output
-3. **Curl/HTTP script** against running dev server
-4. **Throwaway harness** — minimal subset exercising the bug path
-5. **Bisection** — `git bisect run` between known-good and known-bad states
+1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
+2. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
+3. **Curl / HTTP script** against a running dev server.
+4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.
+5. **Throwaway harness** — spin up a minimal subset (one service, mocked deps) that exercises the bug code path with a single function call.
+6. **Replay a captured trace** — save a real network request / payload / event log to disk; replay it through the code path in isolation.
+7. **Property / fuzz loop** — if the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
+8. **Bisection harness** — automate "boot at state X, check, repeat" so `git bisect run` can drive it between known-good and known-bad states.
+9. **Differential loop** — run the same input through old-version vs new-version (or two configs) and diff outputs.
+10. **HITL bash script** (last resort) — if a human must click, drive them with a structured script so the loop is still disciplined. Captured output feeds back to you.
 
-### Iterate on the loop itself
+### Tighten the loop
 
-- Faster? (Skip unrelated setup, narrow scope)
-- Sharper signal? (Assert the specific symptom, not "didn't crash")
-- More deterministic? (Pin time, seed RNG, isolate filesystem)
+Treat the loop as a product. Once you have *a* loop, tighten it on three axes:
 
-A 2-second deterministic loop is a debugging superpower.
-A 30-second flaky loop is barely better than no loop.
+- **Faster** — cache setup, skip unrelated init, narrow the test scope.
+- **Sharper signal** — assert the specific symptom, not "didn't crash".
+- **More deterministic** — pin time, seed RNG, isolate filesystem, freeze network.
 
-## Phase 2 — Reproduce
+A 30-second flaky loop is barely better than no loop; a 2-second deterministic one is a debugging superpower.
 
-Confirm the loop produces the **user-described** failure, not a different nearby failure.
+### Non-deterministic bugs
+
+The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's debuggable.
+
+### When you genuinely cannot build a loop
+
+Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
+
+### Completion criterion — a tight loop that goes red
+
+Phase 1 is done when you can name **one command** — a script path, a test invocation, a curl — that you have **already run at least once** (paste the invocation and its output), and that is:
+
+- [ ] **Red-capable** — drives the actual bug code path and asserts the **user's exact symptom**, so it can go red on this bug and green once fixed. Not "runs without erroring" — it must be able to *catch this specific bug*.
+- [ ] **Deterministic** — same verdict every run (flaky bugs: a pinned, high reproduction rate).
+- [ ] **Fast** — seconds, not minutes.
+- [ ] **Agent-runnable** — you can run it unattended.
+
+If you catch yourself reading code to build a theory before this command exists, **stop — jumping straight to a hypothesis is the exact failure this skill prevents.** No red-capable command, no Phase 2.
+
+## Phase 2 — Reproduce + minimise
+
+Run the loop. Watch it go red — the bug appears.
+
+Confirm:
+
+- [ ] The loop produces the failure mode the **user** described — not a different failure that happens to be nearby. Wrong bug = wrong fix.
+- [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, at a high enough rate to debug against).
+- [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
+
+### Minimise
+
+Once it's red, shrink the repro to the **smallest scenario that still goes red**. Cut inputs, callers, config, data, and steps **one at a time**, re-running the loop after each cut — keep only what is load-bearing for the failure.
+
+Why bother: a minimal repro shrinks the hypothesis space in Phase 3 (fewer moving parts left to suspect) and becomes the clean regression test in Phase 5.
+
+Done when **every remaining element is load-bearing** — removing any one of them makes the loop go green.
 
 ## Phase 3 — Hypothesise
 
-Generate 3-5 ranked hypotheses. Each must be falsifiable:
+Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.
+
+Each hypothesis must be **falsifiable**: state the prediction it makes.
 
-> "If <X> is the cause, then <Y> will make the bug disappear."
+> Format: "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."
 
-Show the ranked list to the user before testing. They often have domain knowledge
-that re-ranks instantly.
+If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.
+
+**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly ("we just deployed a change to #3"), or know hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't block on it — proceed with your ranking if the user is AFK.
 
 ## Phase 4 — Instrument
 
-One probe per hypothesis. Change one variable at a time.
+Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.**
+
+Tool preference:
 
-Tag debug logs with unique prefixes (e.g. `[DEBUG-a4f2]`) so cleanup is a single grep.
+1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.
+2. **Targeted logs** at the boundaries that distinguish hypotheses.
+3. Never "log everything and grep".
+
+**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.
+
+**Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.
 
 ## Phase 5 — Fix + regression test
 
-Write regression test BEFORE the fix — but only if a correct seam exists.
-If no correct seam exists, that itself is the finding. Note it.
+Write the regression test **before the fix** — but only if there is a **correct seam** for it.
+
+A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence.
+
+**If no correct seam exists, that itself is the finding.** Note it. The codebase architecture is preventing the bug from being locked down. Flag this for Phase 6.
+
+If a correct seam exists:
+
+1. Turn the minimised repro into a failing test at that seam.
+2. Watch it fail.
+3. Apply the fix.
+4. Watch it pass.
+5. Re-run the Phase 1 tight loop against the original (un-minimised) scenario.
+
+## Phase 6 — Cleanup + post-mortem
+
+Required before declaring done:
+
+- [ ] Original repro no longer reproduces (re-run the Phase 1 loop)
+- [ ] Regression test passes (or absence of correct seam is documented)
+- [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
+- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
+- [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
 
-After fix: remove all debug instrumentation (grep for tags).
+**Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling), capture it as a `docs/solutions/` artifact via `05-learn`, or flag it for the next planning cycle. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.

package/skills/04-review/SKILL.md

@@ -24,8 +24,9 @@ See [shared pipeline instructions](../references/pipeline-config.md) for model r
    - Extract keywords → `grep -rl "tags:.*keyword" docs/solutions/ ~/.pi/agent/docs/solutions/`
    - Read **frontmatter** only (first 15 lines) of matches → score by severity + tag relevance
    - Fully read top 3 candidates
-7. Produce structured findings using `references/findings-schema.md`
-8. **Autofixable findings:** apply and re-review (max 3 iterations)
+7. **Spec axis:** when a plan artifact exists, compare diff against it — report **missing** requirements, **scope creep** (unrequested behaviour), and **wrong implementation** (looks done but isn't). Also **trace back** to the user's original wording (brainstorm scope) to catch directional misunderstandings the plan itself encoded. Skip if no plan.
+8. Produce structured findings using `references/findings-schema.md`
+9. **Autofixable findings:** apply and re-review (max 3 iterations)
 
 ## Review discipline
 
@@ -35,6 +36,7 @@ Code review is **technical evaluation**, not social performance:
 - **No performative agreement:** verify before concurring
 - **Push back** with reasoning when findings are incorrect
 - **Evidence before assertions:** cite specific code, not principles
+- **Architecture axis:** audit module depth and seams using `../references/module-design.md`
 
 ## Handling findings
 
@@ -46,7 +48,7 @@ Code review is **technical evaluation**, not social performance:
 
 ## Workflow
 
-1. **Load context**: consume latest handoff before any broad file reads — `context_handoff load` or read `.context/compound-engineering/handoffs/latest.md`. If found, use `activeFiles`, `artifacts.plan` as starting point. If not found, proceed normally.
+1. **Load context**: consume latest handoff before any broad file reads — `context_handoff load` or read `.context/compound-engineering/handoffs/latest.md`. If found, use `activeFiles`, `artifacts.plan` as starting point. If not found, proceed normally. Read `CONTEXT.md` if it exists at root — see `../references/domain-language.md`.
 2. Determine diff scope from branch or explicit target
 3. Collect stats (files, insertions, deletions) → call `review_router`
 4. Read matching plan artifact

package/skills/04-review/references/reviewer-selection.md

@@ -24,3 +24,4 @@ All reviewers evaluate changes across five axes: correctness, readability, archi
 - **performance-reviewer**: Triggered when query, cache, database, or streaming files change. Reviews for N+1, unnecessary allocation, missing indexes.
 - **integration-reviewer**: Triggered when CI/CD, Docker, package.json, or config files change. Reviews for dependency conflicts, build breakage, deployment issues.
 - **thoroughness-reviewer**: Triggered for large diffs (5+ files or 300+ lines). Reviews for incomplete refactors, missed callers, inconsistent changes.
+- **spec-reviewer**: Triggered when a plan artifact exists. Reviews the diff against the plan — reports **missing** requirements, **scope creep** (behaviour in the diff not asked for), and **wrong implementation** (requirements that look done but aren't). Skip when no plan artifact is found. Additionally, **trace back to the user's original wording**: re-read the brainstorm artifact's scope statements and confirm the plan interpreted them correctly — a plan that faithfully implements a *misunderstood* requirement passes missing/scope-creep checks but still ships the wrong thing. Flag directional misunderstandings even if the diff matches the plan.

package/skills/05-learn/SKILL.md

@@ -21,6 +21,7 @@ See [shared pipeline instructions](../references/pipeline-config.md) for model r
   - **Project-specific** → `{project-root}/docs/solutions/` (only relevant to current project)
   - **Cross-project (global)** → `~/.pi/agent/docs/solutions/` (applicable to any project)
   - Default to **global** when uncertain.
+- **Out-of-scope branch:** if the request was rejected or already implemented, write to `docs/out-of-scope/` (template: `assets/out-of-scope-template.md`, convention: `../../docs/out-of-scope/README.md`) instead of `docs/solutions/`.
 - Make the result useful to future `02-plan` and `04-review` runs via the search strategy in `references/solution-search-strategy.md`.
 
 ## Workflow

package/skills/05-learn/assets/out-of-scope-template.md

@@ -0,0 +1,20 @@
+---
+title: <the request in one line>
+status: rejected | already-implemented
+date: <YYYY-MM-DD>
+related_adr: <ADR path if relevant, else omit>
+---
+
+# Out-of-Scope Entry
+
+## Request
+
+<what was asked for>
+
+## Disposition
+
+<rejected: why it was ruled out | already-implemented: where it lives in the code>
+
+## Trigger phrases
+
+<words a future request might use that should match this entry — enables grep-based matching by 01-brainstorm and 02-plan>

package/skills/references/domain-language.md

@@ -0,0 +1,55 @@
+# Domain Language — CONTEXT.md + ADR consumption contract
+
+A shared vocabulary layer that runs beneath every skill. Two artifacts hold it: `CONTEXT.md` (the glossary) and `docs/adr/` (architectural decisions). This file defines what they are and how every skill consumes them.
+
+## CONTEXT.md — the glossary
+
+A project-level glossary of domain terms. Lives at the repo root. Persists domain language across sessions so every skill speaks the project's vocabulary, not generic substitutes.
+
+### What it is
+
+- **Pure glossary** — definitions of domain terms only. One definition per term, 1–2 sentences.
+- **No implementation details** — not a spec, not a scratchpad, not a repository for decisions. Define what a term *is*, not what it *does*.
+- **Canonical term + _Avoid_ list** — pick one name, list aliases to discourage.
+
+### When to create
+
+Create `CONTEXT.md` when the user uses project-specific terms that have ambiguous or overloaded meanings, and no glossary exists yet. Skip for trivial features with no domain jargon.
+
+### Single vs multiple contexts
+
+- **Single context (default)** — one `CONTEXT.md` at repo root. Fits almost every repo.
+- **Multiple contexts (monorepo)** — a root `CONTEXT-MAP.md` points to per-context `CONTEXT.md` files (e.g. `src/ordering/CONTEXT.md`, `src/billing/CONTEXT.md`). Use only when the repo has genuinely separated domains.
+
+### Format
+
+See `skills/01-brainstorm/references/context-glossary.md` for the creation template.
+
+## ADR — architectural decision records
+
+Records of decisions that are hard to reverse. Live at `docs/adr/` (or per-context `docs/adr/` in a multi-context repo). Numbered: `0001-slug.md`.
+
+### When to create an ADR
+
+Only when **all three** are true:
+
+1. **Hard to reverse** — the cost of changing the decision later is meaningful.
+2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
+3. **Real trade-off** — there were genuine alternatives and you picked one for specific reasons.
+
+If any is missing, skip the ADR. Most decisions don't qualify.
+
+## Consumption rules (every skill)
+
+1. **Before broad project reads**, check if `CONTEXT.md` exists at the repo root (or the relevant context in a multi-context repo). If it exists, read it first so you use the project's vocabulary.
+2. **Respect ADRs** — before proposing a design that touches an area with existing ADRs, read them. Don't re-litigate a settled decision unless the friction is real enough to warrant reopening.
+3. **Update inline** — when a term is resolved during a session, update `CONTEXT.md` right there. Don't batch.
+4. **Flag conflicts** — if the user uses a term that conflicts with the glossary, surface it: "Your CONTEXT.md defines 'cancellation' as X, but you seem to mean Y — which is it?"
+5. **Challenge fuzzy language** — if the user uses an overloaded term, propose a precise canonical term.
+
+## Where this is used
+
+- **01-brainstorm** — creates/updates `CONTEXT.md` as domain terms emerge.
+- **02-plan** — reads `CONTEXT.md` for vocabulary; offers ADRs when a decision meets the three-condition threshold.
+- **03-work** — reads `CONTEXT.md` so test names and interface vocabulary match; respects ADRs in the area being touched.
+- **04-review** — checks whether the diff uses consistent domain vocabulary; flags ADR conflicts.

package/skills/references/module-design.md

@@ -0,0 +1,63 @@
+# Module Design — deep-module vocabulary
+
+A shared vocabulary for designing module shapes. Use these terms wherever code is being designed or restructured — `03-work` when building a module, `04-review` when auditing architecture. Consistent language is the whole point; don't drift into "component", "service", "API", or "boundary".
+
+## Glossary
+
+**Module** — anything with an interface and an implementation. Scale-agnostic: a function, class, package, or tier-spanning slice. _Avoid_: unit, component, service.
+
+**Interface** — everything a caller must know to use the module correctly: the type signature, but also invariants, ordering constraints, error modes, required configuration, performance characteristics. _Avoid_: API, signature (too narrow — they refer only to the type-level surface).
+
+**Implementation** — what's inside a module, its body of code. Distinct from **Adapter**: a module can have a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake).
+
+**Depth** — leverage at the interface: the amount of behaviour a caller (or test) can exercise per unit of interface they must learn. A module is **deep** when a large amount of behaviour sits behind a small interface, **shallow** when the interface is nearly as complex as the implementation.
+
+**Seam** _(Michael Feathers)_ — a place where you can alter behaviour without editing in that place; the *location* at which a module's interface lives. Where to put the seam is its own design decision, distinct from what goes behind it. _Avoid_: boundary (overloaded with DDD's bounded context).
+
+**Adapter** — a concrete thing that satisfies an interface at a seam. Describes *role* (what slot it fills), not substance (what's inside).
+
+**Leverage** — what callers get from depth: more capability per unit of interface they learn. One implementation pays back across N call sites and M tests.
+
+**Locality** — what maintainers get from depth: change, bugs, knowledge, and verification concentrate in one place rather than spreading across callers. Fix once, fixed everywhere.
+
+## Deep vs shallow
+
+**Deep module** = small interface + lots of implementation:
+
+```
+┌─────────────────────┐
+│   Small Interface   │  ← Few methods, simple params
+├─────────────────────┤
+│                     │
+│  Deep Implementation│  ← Complex logic hidden
+│                     │
+└─────────────────────┘
+```
+
+**Shallow module** = large interface + little implementation (avoid):
+
+```
+┌─────────────────────────────────┐
+│       Large Interface           │  ← Many methods, complex params
+├─────────────────────────────────┤
+│  Thin Implementation            │  ← Just passes through
+└─────────────────────────────────┘
+```
+
+## Principles
+
+- **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable parts — they just aren't part of the interface.
+- **The deletion test.** Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
+- **The interface is the test surface.** Callers and tests cross the same seam. If you want to test *past* the interface, the module is probably the wrong shape.
+- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a seam unless something actually varies across it.
+
+## Designing for testability
+
+1. **Accept dependencies, don't create them.** `function processOrder(order, paymentGateway)` is testable; `function processOrder(order)` that news up its own gateway is not.
+2. **Return results, don't produce side effects.** `function calculateDiscount(cart): Discount` is testable; `function applyDiscount(cart): void` that mutates is not.
+3. **Small surface area.** Fewer methods = fewer tests needed. Fewer params = simpler test setup.
+
+## Where this is used
+
+- **03-work** — when designing or restructuring a module, use these terms to evaluate depth and seam placement.
+- **04-review** — when auditing the architecture axis, flag shallow modules and missing seams using this vocabulary.