agent-bober 0.12.0 → 0.17.0

package/scripts/sync-skills.mjs

@@ -10,7 +10,10 @@
 // Usage:  node scripts/sync-skills.mjs <skill-key>:<command-file> ...
 //   e.g.: node scripts/sync-skills.mjs bober.plan:bober-plan.md \
 //                                     bober.run:bober-run.md \
-//                                     bober.sprint:bober-sprint.md
+//                                     bober.sprint:bober-sprint.md \
+//                                     bober.graph:bober-graph.md \
+//                                     bober.onboard:bober-onboard.md \
+//                                     bober.impact:bober-impact.md
 
 import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { join, dirname } from "node:path";

package/scripts/sync-targets.json

@@ -0,0 +1,12 @@
+{
+  "//": "Projects that consume agent-bober's skills/agents. `npm run update-all` rebuilds the CLI once (shared via symlink) and re-inlines skills/agents into each target's .claude/. Add absolute project paths here. Auto-discovery (--discover) appends any initialized project it finds under the configured roots.",
+  "discoverRoots": [
+    "/Users/bober4ik/WebstormProjects",
+    "/Users/bober4ik/agent-bober-workspace"
+  ],
+  "targets": [
+    "/Users/bober4ik/WebstormProjects/solex-integration-demo",
+    "/Users/bober4ik/WebstormProjects/solex-integration-demo/apps/api",
+    "/Users/bober4ik/WebstormProjects/solex-integration-demo/solex-games-betbook (Copy)"
+  ]
+}

package/scripts/update-all.mjs

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+// ─────────────────────────────────────────────────────────────────────────
+// update-all — propagate an agent-bober change to every consuming project.
+//
+// agent-bober is distributed two ways at once:
+//   1. CLI/engine code  → ONE copy, shared via npm symlink. `npm run build`
+//      recompiles src→dist and every symlinked project picks it up for free.
+//   2. Skills/agents     → COPIED into each project's .claude/ by `init`
+//      (skills are inlined: SKILL.md + sorted references concatenated into a
+//      single .claude/commands/<name>.md). These copies go stale on every
+//      skill edit and must be re-emitted per project.
+//
+// This script does both: build once, then re-inline skills + copy agents into
+// every target listed in scripts/sync-targets.json. The inlining format is
+// kept byte-identical to src/cli/commands/init.ts (installClaudeCommands) so a
+// synced project is indistinguishable from a freshly `init`-ed one.
+//
+// Usage:
+//   node scripts/update-all.mjs                # build + sync all targets
+//   node scripts/update-all.mjs --check        # dry-run: report drift, write nothing
+//   node scripts/update-all.mjs --skills-only  # skip the build
+//   node scripts/update-all.mjs --no-build     # alias of --skills-only
+//   node scripts/update-all.mjs --discover     # add initialized projects under discoverRoots to the registry
+//   node scripts/update-all.mjs /abs/path ...  # sync ONLY these paths (ignore registry)
+// ─────────────────────────────────────────────────────────────────────────
+
+import { readFile, writeFile, readdir, mkdir, stat } from "node:fs/promises";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execSync } from "node:child_process";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(__dirname, "..");
+const SKILLS_ROOT = join(PKG_ROOT, "skills");
+const AGENTS_ROOT = join(PKG_ROOT, "agents");
+const TARGETS_FILE = join(__dirname, "sync-targets.json");
+
+// Skill-dir → command-file map. MUST match installClaudeCommands in
+// src/cli/commands/init.ts. Derived at runtime from skills/ so it can never
+// drift: every skills/bober.X dir maps to bober-X.md.
+async function buildSkillMap() {
+  const entries = await readdir(SKILLS_ROOT, { withFileTypes: true });
+  const map = {};
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    if (!e.name.startsWith("bober.")) continue;
+    // bober.code-review → bober-code-review.md
+    const cmd = e.name.replace(/\./g, "-") + ".md";
+    map[e.name] = cmd;
+  }
+  return map;
+}
+
+// Re-create the inlined command file for one skill, byte-identical to init.ts.
+async function inlineSkill(skillDir) {
+  const srcSkill = join(SKILLS_ROOT, skillDir, "SKILL.md");
+  let content = await readFile(srcSkill, "utf-8");
+
+  const refsDir = join(SKILLS_ROOT, skillDir, "references");
+  try {
+    const refFiles = await readdir(refsDir);
+    for (const refFile of refFiles.sort()) {
+      if (!refFile.endsWith(".md")) continue;
+      const refContent = await readFile(join(refsDir, refFile), "utf-8");
+      content += `\n\n---\n\n<!-- Reference: ${refFile} -->\n\n${refContent}`;
+    }
+  } catch {
+    // No references directory — fine.
+  }
+  return content;
+}
+
+async function isDir(p) {
+  try {
+    return (await stat(p)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function fileEquals(path, expected) {
+  try {
+    return (await readFile(path, "utf-8")) === expected;
+  } catch {
+    return false; // missing → counts as changed
+  }
+}
+
+// Sync skills + agents into ONE project. Returns a per-target report.
+async function syncTarget(projectRoot, { check }) {
+  const claudeDir = join(projectRoot, ".claude");
+  const commandsDir = join(claudeDir, "commands");
+  const agentsDir = join(claudeDir, "agents");
+
+  const report = { projectRoot, commandsChanged: [], agentsChanged: [], skipped: false };
+
+  // A target must already be a project (have a .claude/ or bober.config.json).
+  // We never create .claude from scratch here — that's init's job.
+  if (!(await isDir(claudeDir)) && !(await fileEquals(join(projectRoot, "bober.config.json"), "__never__"))) {
+    // bober.config.json may exist even if .claude doesn't; tolerate either.
+    if (!(await isDir(claudeDir))) {
+      const hasCfg = await readFile(join(projectRoot, "bober.config.json"), "utf-8").then(() => true).catch(() => false);
+      if (!hasCfg) {
+        report.skipped = true;
+        report.reason = "no .claude/ and no bober.config.json — not an agent-bober project";
+        return report;
+      }
+    }
+  }
+
+  const skillMap = await buildSkillMap();
+
+  // ── Commands (inlined skills) ──────────────────────────────────────
+  if (!check) await mkdir(commandsDir, { recursive: true });
+  for (const [skillDir, commandFile] of Object.entries(skillMap)) {
+    let content;
+    try {
+      content = await inlineSkill(skillDir);
+    } catch {
+      continue; // SKILL.md missing — skip, mirrors init's behaviour
+    }
+    const dest = join(commandsDir, commandFile);
+    if (!(await fileEquals(dest, content))) {
+      report.commandsChanged.push(commandFile);
+      if (!check) await writeFile(dest, content, "utf-8");
+    }
+  }
+
+  // ── Agents (verbatim) ──────────────────────────────────────────────
+  if (!check) await mkdir(agentsDir, { recursive: true });
+  let agentFiles = [];
+  try {
+    agentFiles = await readdir(AGENTS_ROOT);
+  } catch {
+    /* no agents dir in package — unusual but tolerate */
+  }
+  for (const agentFile of agentFiles) {
+    if (!agentFile.endsWith(".md")) continue;
+    const content = await readFile(join(AGENTS_ROOT, agentFile), "utf-8");
+    const dest = join(agentsDir, agentFile);
+    if (!(await fileEquals(dest, content))) {
+      report.agentsChanged.push(agentFile);
+      if (!check) await writeFile(dest, content, "utf-8");
+    }
+  }
+
+  return report;
+}
+
+// Walk discoverRoots and return any initialized project (has a bober-plan.md
+// command — the marker that init ran there). Bounded depth to stay safe/fast.
+async function discover(roots) {
+  const found = new Set();
+  async function walk(dir, depth) {
+    if (depth > 4) return;
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    // Initialized? marker file present.
+    const marker = join(dir, ".claude", "commands", "bober-plan.md");
+    if (await readFile(marker, "utf-8").then(() => true).catch(() => false)) {
+      found.add(dir);
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      if (e.name === "node_modules" || e.name === ".git" || e.name === "dist") continue;
+      await walk(join(dir, e.name), depth + 1);
+    }
+  }
+  for (const r of roots) await walk(r, 0);
+  return [...found];
+}
+
+async function loadRegistry() {
+  const raw = JSON.parse(await readFile(TARGETS_FILE, "utf-8"));
+  return raw;
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const flags = new Set(argv.filter((a) => a.startsWith("--")));
+  const pathArgs = argv.filter((a) => !a.startsWith("--"));
+  const check = flags.has("--check");
+  const skillsOnly = flags.has("--skills-only") || flags.has("--no-build");
+
+  // ── Optional: discovery mode (mutates the registry, then exits) ─────
+  if (flags.has("--discover")) {
+    const reg = await loadRegistry();
+    const discovered = await discover(reg.discoverRoots ?? []);
+    const before = new Set(reg.targets);
+    for (const d of discovered) before.add(d);
+    reg.targets = [...before].sort();
+    await writeFile(TARGETS_FILE, JSON.stringify(reg, null, 2) + "\n", "utf-8");
+    console.log(`Discovered ${discovered.length} initialized project(s); registry now has ${reg.targets.length}:`);
+    for (const t of reg.targets) console.log(`  - ${t}`);
+    return;
+  }
+
+  // ── 1. Build the CLI (the shared half) ─────────────────────────────
+  if (!skillsOnly && !check) {
+    console.log("▸ Building CLI (src → dist)…");
+    execSync("npm run build", { cwd: PKG_ROOT, stdio: "inherit" });
+    console.log("  ✓ dist rebuilt — every symlinked project now runs current code.\n");
+  } else if (check) {
+    console.log("▸ --check: dry run, nothing will be written.\n");
+  } else {
+    console.log("▸ --skills-only: skipping build.\n");
+  }
+
+  // ── 2. Resolve targets ─────────────────────────────────────────────
+  let targets;
+  if (pathArgs.length > 0) {
+    targets = pathArgs.map((p) => resolve(p));
+  } else {
+    const reg = await loadRegistry();
+    targets = reg.targets ?? [];
+  }
+  if (targets.length === 0) {
+    console.error("No targets. Add paths to scripts/sync-targets.json or pass them as args (or run --discover).");
+    process.exit(1);
+  }
+
+  // ── 3. Sync skills + agents into each target ───────────────────────
+  console.log(`▸ Syncing skills + agents into ${targets.length} project(s):\n`);
+  let totalChanged = 0;
+  for (const t of targets) {
+    const r = await syncTarget(t, { check });
+    if (r.skipped) {
+      console.log(`  ⊘ ${t}\n      skipped: ${r.reason}`);
+      continue;
+    }
+    const n = r.commandsChanged.length + r.agentsChanged.length;
+    totalChanged += n;
+    if (n === 0) {
+      console.log(`  ✓ ${t}\n      already up to date`);
+    } else {
+      console.log(`  ${check ? "✎" : "✓"} ${t}`);
+      if (r.commandsChanged.length) console.log(`      commands ${check ? "would update" : "updated"}: ${r.commandsChanged.length} (${r.commandsChanged.slice(0, 5).join(", ")}${r.commandsChanged.length > 5 ? ", …" : ""})`);
+      if (r.agentsChanged.length) console.log(`      agents ${check ? "would update" : "updated"}: ${r.agentsChanged.length} (${r.agentsChanged.join(", ")})`);
+    }
+  }
+
+  console.log(
+    `\n${check ? "Drift check complete" : "Sync complete"}: ${totalChanged} file(s) ${check ? "out of date" : "written"} across ${targets.length} project(s).`,
+  );
+  if (check && totalChanged > 0) process.exitCode = 1; // CI-friendly: drift → nonzero
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/skills/bober.architect/SKILL.md

@@ -106,6 +106,13 @@ Wait for user response. If (B) or (C): respawn the subagent with the user's feed
 
 ## Step 6: Checkpoint 2 — Approach Selection
 
+**Panel mode (gated, off by default):** Read `config.architect?.panel`. If `panel.enabled` is `true` AND `panel.lenses.length >= 2`, run the PANEL flow described in the inlined Lens Panel reference below (`<!-- Reference: arch-lens-panel.md -->`):
+- First spawn a generate-approaches subagent (producing 2–3 candidate approaches that satisfy the Checkpoint 1 constraints).
+- Then spawn one bober-architect subagent per lens in **MODE:lens-score:\<name\>** for each name in `panel.lenses`, bounded by `panel.maxConcurrent` concurrent spawns. Each scorer receives the same candidate set and scores them exclusively through its lens focus fragment (see `resolveArchLensFocus(lens)` in the reference).
+- Call `synthesize()` (see `src/orchestrator/synthesizer.ts`) to aggregate per-lens scores and produce the ranked winner with dissent. Proceed with the highest-scoring approach as the selected approach.
+
+OTHERWISE (panel disabled, or fewer than 2 lenses), spawn exactly ONE bober-architect subagent as described below — byte-identical to today's behaviour.
+
 Spawn a subagent with the approved Problem Statement included:
 
 ```
@@ -295,6 +302,12 @@ Handle (B)/(C) by respawning with feedback.
 
 ## Step 9: Checkpoint 5 — Final Assembly
 
+**Panel mode (gated, off by default):** Read `config.architect?.panel`. If `panel.enabled` is `true` AND `panel.lenses.length >= 2`, run the PANEL flow described in the inlined Lens Panel reference below (`<!-- Reference: arch-lens-panel.md -->`):
+- Spawn one bober-architect subagent per lens in **MODE:lens-review:\<name\>** for each name in `panel.lenses`, bounded by `panel.maxConcurrent` concurrent spawns. Each reviewer receives the assembled architecture document and ADRs and produces a PASS/FAIL verdict exclusively through its lens focus fragment.
+- Call `reconcile()` (see `src/orchestrator/workflow/reconciler.ts`) to aggregate verdicts: strict majority (`passCount > failCount`), **fail-closed on tie** (tie → false). Record the reconciled verdict (including `lensVerdicts` array) in the assembly output.
+
+OTHERWISE (panel disabled, or fewer than 2 lenses), spawn exactly ONE bober-architect subagent as described below — byte-identical to today's behaviour.
+
 Spawn a subagent to compile the complete architecture document:
 
 ```

package/skills/bober.architect/references/arch-lens-panel.md

@@ -0,0 +1,126 @@
+# Arch Lens Panel — Canonical Protocol Reference
+
+This document is the single source of truth for native architect panel orchestration in agent-bober.
+It embeds the seven canonical arch lens focus fragments verbatim from
+`src/orchestrator/arch-lenses.ts` (the `ARCH_LENS_CATALOG` literal) and documents the
+CP2 synthesis panel and CP5 reconcile panel protocols.
+The drift gate (`src/orchestrator/arch-lens-panel-parity.test.ts`) enforces byte-exact parity.
+
+---
+
+## Lens Focus Fragments
+
+The following fragments are the exact strings returned by `resolveArchLensFocus(lens)` for each
+built-in arch lens. They MUST remain byte-for-byte identical to the corresponding entries in
+`ARCH_LENS_CATALOG` — the drift gate (`src/orchestrator/arch-lens-panel-parity.test.ts`) enforces this.
+
+### scalability
+
+```
+Focus on whether the proposed architecture can handle projected load growth. Evaluate horizontal and vertical scaling paths, bottlenecks, stateful vs stateless components, and whether partitioning or sharding strategies are available when needed.
+```
+
+### security
+
+```
+Focus on the threat surface introduced by this architecture. Evaluate trust boundaries, data flows across zones, authentication and authorisation enforcement points, secrets management, and exposure of internal services.
+```
+
+### cost
+
+```
+Focus on the total cost of ownership implied by this architecture. Evaluate compute, storage, and egress costs at projected scale, licensing or SaaS subscription expenses, and the operational overhead of running, monitoring, and scaling the system.
+```
+
+### operability
+
+```
+Focus on how easy it will be to operate this architecture in production. Evaluate observability (metrics, logs, traces), deployment complexity, rollout and rollback procedures, on-call burden, and the blast radius of common failure modes.
+```
+
+### maintainability
+
+```
+Focus on how easy it will be to change and extend this architecture over time. Evaluate coupling between components, clarity of boundaries, documentation needs, onboarding friction for new contributors, and the risk of accruing technical debt.
+```
+
+### reversibility
+
+```
+Focus on how difficult or costly it would be to undo or replace this architectural decision. Evaluate lock-in to vendors or proprietary technologies, data migration complexity, and whether a strangler-fig or incremental migration path exists if the approach needs to change.
+```
+
+### simplicity
+
+```
+Focus on whether this is the simplest architecture that satisfies the Checkpoint 1 constraints. Challenge whether each component needs to exist, whether a native platform feature or an already-present dependency removes a proposed custom layer, whether two components should collapse into one, and whether any abstraction is speculative — added for a use case absent from the problem statement. Reward the smallest design that honours every hard constraint; penalise layers introduced for unproven future flexibility, but never at the expense of a stated constraint.
+```
+
+> The `simplicity` lens enforces the top rung of the YAGNI ladder at design time: "does this
+> component need to exist at all?". It is constraint-bounded by construction — it may never
+> recommend dropping a layer that a Checkpoint 1 hard constraint requires. This keeps it
+> consistent with the architect's IRON LAW (every decision must cite the constraint that
+> eliminates the rejected alternative): a simplification that violates a constraint is not simpler,
+> it is wrong.
+
+---
+
+## Native Architect Panel Protocol
+
+### CP2 Synthesis Panel
+
+At Checkpoint 2 (candidate generation + scoring), the orchestrator runs the synthesis panel:
+
+1. **Generate candidates:** The architect produces 2–3 candidate approaches that satisfy the
+   Checkpoint 1 constraints.
+
+2. **Lens scorer fan-out (one per lens):** The orchestrator spawns one scorer subagent per
+   configured arch lens (scalability, security, cost, operability, maintainability, reversibility,
+   simplicity), bounded by `maxConcurrent`. Each scorer receives the same candidate set and is instructed to
+   score the candidates exclusively through its lens focus fragment (the exact string returned by
+   `resolveArchLensFocus(lens)` from `src/orchestrator/arch-lenses.ts`).
+
+3. **Synthesis:** `synthesize()` in `src/orchestrator/synthesizer.ts` aggregates the per-lens
+   scores and produces a ranked winner with dissent. The highest-scoring approach across lenses
+   becomes the recommended architecture; any lens that preferred a different candidate is recorded
+   as a dissenting voice in the synthesis output.
+
+### CP5 Reconcile Panel
+
+At Checkpoint 5 (review pass), the orchestrator runs the reconcile panel:
+
+1. **Lens reviewer fan-out (one per lens):** The orchestrator spawns one reviewer subagent per
+   configured arch lens. Each reviewer receives the assembled architecture document and ADRs, and
+   is instructed to produce a PASS/FAIL verdict exclusively through its lens focus fragment.
+
+2. **Reconciliation — fail-closed on tie:** `reconcile()` in
+   `src/orchestrator/workflow/reconciler.ts` aggregates the per-lens verdicts using the following
+   semantics:
+
+   - **Inputs:** the array of per-lens `EvalResult` objects (`lensVerdicts`).
+   - **Require non-empty:** an empty array throws `"reconcile: lensVerdicts must be non-empty"`.
+   - **Vote count:** `passCount` = number of lenses where `passed === true`;
+     `failCount` = total − passCount.
+   - **Verdict:** `passed = passCount > failCount` (strict majority).
+     - **Fail-closed on tie:** when `passCount === failCount` the panel verdict is `false`.
+   - **Details:** union of all failing lens details, de-duplicated by `(criterion, message)` key.
+   - **Feedback:** failing lenses' feedback joined with `\n`; `"All lenses passed."` when all pass.
+   - **Summary:** `"Panel verdict: ${passCount}/${n} lenses passed"`.
+   - **Score:** `Math.round((100 * passCount) / n)`.
+   - **Evaluator tag:** `evaluator = "panel"`.
+
+### lensVerdicts Output Shape
+
+After reconciliation the orchestrator writes a `lensVerdicts` array into the saved result.
+The array shape is:
+
+```ts
+lensVerdicts: Array<{
+  lens: string;    // e.g. "scalability", "security", "cost", "operability", "maintainability", "reversibility", "simplicity"
+  passed: boolean; // individual lens verdict
+  summary: string; // per-lens summary from the scorer or reviewer subagent
+}>
+```
+
+This field is optional and backward-compatible: results produced before the panel feature
+(or by non-panel architect runs) simply omit it.

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

@@ -0,0 +1,186 @@
+---
+name: bober-code-review
+description: Use when completing a sprint, after evaluator pass — spawns bober-code-reviewer subagent to audit the sprint diff against the contract and anti-pattern catalog, producing an advisory ReviewResult written to .bober/reviews/<contractId>-review.md.
+argument-hint: "[contract-id]"
+---
+
+> Adapted from [obra/superpowers](https://github.com/obra/superpowers) — MIT License.
+> Original: skills/requesting-code-review/.
+> Adaptations: agent name (bober-code-reviewer), advisory-only contract, ReviewResult JSON schema, anti-pattern citations from .bober/anti-patterns/.
+
+# bober.code-review — Advisory Code Review Orchestrator
+
+You are the **orchestrator** for a standalone code review run. You do NOT review the code yourself. You spawn the code reviewer as a subagent using the **Agent tool**, then process and save its results to `.bober/reviews/<contractId>-review.md`.
+
+The code reviewer subagent runs in its own isolated context window. It receives ONLY the information you explicitly pass in its prompt.
+
+**Integration with bober pipeline:** In the automated pipeline, bober-code-reviewer is spawned automatically after `runEvaluatorAgent` returns `passed: true` in `src/orchestrator/pipeline.ts`. This skill is for standalone runs — when you want to trigger a review manually outside the normal pipeline flow.
+
+## When to Request Review
+
+**Mandatory in pipeline:** The orchestrator triggers code review automatically after each sprint evaluator pass. You do not need to invoke this skill for normal pipeline runs.
+
+**Use this skill manually when:**
+- You completed a sprint manually (outside the pipeline) and want advisory feedback
+- You want to re-review a sprint with a different anti-pattern focus
+- You want to review a specific file range that the pipeline did not cover
+
+## What the Reviewer Checks
+
+**What to check — findings the reviewer WILL surface:**
+
+- **DRY violations**: New code that duplicates an existing utility verbatim. Cite the duplicate location with file:line evidence.
+- **YAGNI violations**: Abstractions added for future use cases not in the contract. Config options wired but never read.
+- **Dead code**: Functions defined but never called; exports with zero import sites in the diff.
+- **Missing tests**: Changed behavior with no new test coverage; tests that only check the happy path.
+- **Anti-pattern matches** from `.bober/anti-patterns/`:
+  - Testing Mock Behavior, Test-Only Methods in Production → `.bober/anti-patterns/testing-anti-patterns.md`
+  - Arbitrary-delay waiting (`setTimeout`/`sleep`) → `.bober/anti-patterns/condition-based-waiting.md`
+  - Symptom-fix instead of root-cause → `.bober/anti-patterns/root-cause-tracing.md`
+  - Single-layer validation (missing defense-in-depth) → `.bober/anti-patterns/defense-in-depth.md`
+- **Silent error swallowing**: `catch {}` with no log or rethrow; errors absorbed without surfacing
+- **TypeScript `any` types** without a comment explaining why
+
+**What NOT to flag — the reviewer MUST drop these:**
+
+- Style preferences (indentation, line length, trailing commas when file is internally consistent)
+- Naming opinions when the name is consistent with the surrounding file
+- Theoretical risks without an observed trigger (speculation without evidence)
+- Decisions the planner already resolved — re-litigating settled choices is scope creep
+- Pre-existing code that was NOT changed in this sprint
+
+## Acting on Feedback
+
+Because the review is advisory (it never blocks sprint completion), severity signals what to do NEXT:
+
+- **Critical**: Warrants a dedicated fix sprint. The finding has file:line evidence and an observed trigger. Prioritize addressing this before the next feature sprint.
+- **Important**: Address before shipping this feature broadly. Worth tracking in the backlog.
+- **Minor**: Note for future housekeeping. Do not delay other work for these.
+
+Even Critical findings do NOT trigger a generator retry. The sprint is complete. The review surfaces information for planning the next sprint.
+
+## Process Flow
+
+### Step 1: Identify the Target Contract
+
+**If a contract ID was provided as an argument:**
+- Load the contract from `.bober/contracts/<contractId>.json`
+- Verify the contract status is `passed` — review runs after evaluator pass
+
+**If no contract ID was provided:**
+- Find the most recently passed contract from `.bober/contracts/`
+- If no passed contracts exist, tell the user there is nothing to review
+
+Read the contract and its parent PlanSpec.
+
+### Step 2: Gather Context
+
+Read `bober.config.json` for commands and evaluator config.
+Read `.bober/principles.md` if it exists.
+
+Check the git status:
+```bash
+git log --oneline -5
+git diff HEAD~1 --stat
+```
+
+### Step 3: Spawn the Code Reviewer Subagent
+
+Use the **Agent tool** to spawn a code reviewer subagent.
+
+```
+Agent tool call:
+  description: "Code Review: <sprint title>"
+  subagent_type: bober-code-reviewer
+  mode: auto
+  prompt: <the full prompt below>
+```
+
+**Build the reviewer prompt with ALL of these sections:**
+
+```
+You are the Bober Code Reviewer subagent. You have been spawned to advisory-review a sprint that already passed evaluation.
+
+## Sprint Contract
+<paste the full SprintContract JSON from .bober/contracts/<contractId>.json>
+
+## Evaluation Result (Already Passed)
+<paste the EvaluationRunResult JSON — key fields: passed: true, summary, score>
+
+## Project Configuration
+Commands:
+<paste the commands section from bober.config.json>
+
+## Project Root
+<absolute path to the project root>
+
+## Context
+- Contract ID: <contractId>
+- Spec ID: <specId>
+- Review is ADVISORY ONLY — findings do not block completion or trigger retries
+
+## Anti-Pattern Catalog
+The catalog index is at .bober/anti-patterns/README.md. Consult it BEFORE classifying severity.
+Catalogued anti-patterns:
+- Testing anti-patterns → .bober/anti-patterns/testing-anti-patterns.md
+- Condition-based waiting → .bober/anti-patterns/condition-based-waiting.md
+- Root-cause tracing → .bober/anti-patterns/root-cause-tracing.md
+- Defense in depth → .bober/anti-patterns/defense-in-depth.md
+
+## Your Task
+Review the sprint diff. Produce a ReviewResult JSON. Output ONLY the JSON — no text outside it.
+```
+
+### Step 4: Process and Save the Result
+
+When the subagent returns:
+
+1. Parse the ReviewResult JSON from its response
+2. Render the markdown review document (6 required sections):
+
+```markdown
+# Code Review: <contractId>
+
+## Summary
+
+<paste summary field>
+
+## Critical
+
+<for each finding in critical array: description + evidence>
+<if empty: "No critical findings.">
+
+## Important
+
+<for each finding in important array>
+<if empty: "No important findings.">
+
+## Minor
+
+<for each finding in minor array>
+<if empty: "No minor findings.">
+
+## Approved Areas
+
+<for each item in approvedAreas: bullet>
+<if empty: "No areas specifically called out.">
+```
+
+3. Save to `.bober/reviews/<contractId>-review.md`
+4. Report a summary to the user: counts of critical/important/minor findings
+
+## Red Flags - STOP
+
+- About to spawn the reviewer before checking that the sprint status is `passed`
+- About to save a review for a contract that never passed evaluation
+- About to treat Critical findings as blocking (they are advisory — the sprint is done)
+- About to skip reading `.bober/anti-patterns/README.md` before the reviewer prompt
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "The sprint passed, so there is nothing to review" | Passing evaluation is a correctness bar, not a quality bar. Code review adds a separate signal. |
+| "Critical findings mean I should trigger a rework" | No. Advisory means advisory. The sprint is complete. Plan a fix sprint if needed. |
+| "The reviewer ran out of context — I will skip saving the file" | Save what you have. An empty review with just a Summary is better than no record. |
+| "Different words so rule doesn't apply" | Spirit over letter. |