agent-bober 0.15.0 → 0.17.0

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.eval/SKILL.md

@@ -61,6 +61,15 @@ Determine the iteration number: if prior eval results exist for this contract in
 
 ## Step 3: Spawn the Evaluator Subagent
 
+**Panel mode (gated, off by default):** Read `config.evaluator.panel`. If `panel.enabled` is `true` AND `panel.lenses.length >= 2`, run the PANEL flow described in the inlined Lens Panel reference below (`<!-- Reference: lens-panel.md -->`):
+- Spawn ONE bober-evaluator with **MODE:deterministic** — runs the configured strategy suite exactly once.
+- Then spawn one bober-evaluator per lens with **MODE:lens:<name>** for each name in `panel.lenses`, bounded by `panel.maxConcurrent` concurrent spawns.
+- Collect each lens verdict; majority-vote: `passed = passCount > failCount`, **FAIL-CLOSED on tie** (tie → false).
+- Set `final.passed = deterministic.passed && reconciled.passed`.
+- Save the eval-result with `evaluator: "panel"` and a `lensVerdicts: [{ lens, passed, summary }]` array.
+
+OTHERWISE (panel disabled, or fewer than 2 lenses), spawn exactly ONE bober-evaluator with **MODE:full** exactly as described below — byte-identical to today's behaviour.
+
 Use the **Agent tool** to spawn an evaluator subagent.
 
 ```

package/skills/bober.eval/references/lens-panel.md

@@ -0,0 +1,115 @@
+# Lens Panel — Canonical Protocol Reference
+
+This document is the single source of truth for native panel orchestration in agent-bober.
+It embeds the five canonical lens focus fragments verbatim from
+`src/orchestrator/eval-lenses.ts` (the `LENS_CATALOG` literal) and documents the
+split fan-out, majority-vote/fail-closed reconciliation, and the `lensVerdicts` output shape.
+
+---
+
+## Lens Focus Fragments
+
+The following fragments are the exact strings returned by `resolveLensFocus(lens)` for each
+built-in lens. They MUST remain byte-for-byte identical to the corresponding entries in
+`LENS_CATALOG` — the drift gate (`src/orchestrator/lens-panel-parity.test.ts`) enforces this.
+
+### correctness
+
+```
+Focus on whether the implementation actually satisfies each success criterion verbatim. Check that all required behaviours exist, all edge cases are handled, and the contract's definitionOfDone is met.
+```
+
+### security
+
+```
+Focus on injection vulnerabilities, authentication and authorisation gaps, secret handling, unsafe input validation, and any path traversal or privilege escalation risks.
+```
+
+### regression
+
+```
+Focus on whether previously working behaviour still works after the changes. Verify that pre-existing tests pass, that no public API or config interface was broken, and that the sprint diff does not silently remove functionality.
+```
+
+### quality
+
+```
+Focus on principles violations, dead code, misleading naming, smells, duplicated logic, and whether the implementation follows the project's established patterns and conventions.
+```
+
+### simplicity
+
+```
+Focus exclusively on over-engineering in the production code: logic that reinvents the standard library, dependencies or hand-rolled code doing what a native platform feature already provides, abstractions with a single implementation, configuration nobody reads, dead flexibility, and code expressible in materially fewer lines. For each, name the location, what to cut, and what replaces it. Never flag tests, assertion-based self-checks, input validation at trust boundaries, error handling, security measures, or accessibility as deletable — minimalism governs production code, never the verification or safety discipline.
+```
+
+> The `simplicity` lens is the complexity-only counterpart to `quality`. `quality` asks
+> "does this follow our patterns and is it free of smells?"; `simplicity` asks "what can be
+> deleted, replaced by stdlib/native, or shrunk?" — and is forbidden from ever recommending the
+> removal of a test, a validation, or a safety measure. It pairs cleanly with the evaluator's
+> test/verification Iron Law: minimalism governs what is built, never what is verified.
+
+---
+
+## Native Panel Protocol
+
+### Split Fan-out
+
+When the native panel is active, the orchestrator spawns evaluators in two passes:
+
+1. **Deterministic evaluator (one instance):** runs the configured strategy suite exactly once
+   (build, typecheck, lint, unit-test, playwright, api-check, etc.). This produces the
+   deterministic verdict — objective, tool-based checks that do not depend on lens focus.
+
+2. **Qualitative evaluators (one per configured lens):** each evaluator receives the same
+   sprint diff and context but is instructed to judge the contract's success criteria
+   exclusively through its lens focus fragment. The strategy suite is **not** re-run for
+   these evaluators — they perform qualitative assessment only, using the results already
+   collected by the deterministic evaluator as supporting context.
+
+This split ensures strategies execute once (no duplicate CI cost) while each lens evaluates
+the diff independently.
+
+### Reconciliation — Majority Vote, Fail-Closed
+
+The lens verdicts are reconciled by `reconcile()` in
+`src/orchestrator/workflow/reconciler.ts` 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"`.
+- **Timestamp:** echoed verbatim from the input argument (pure function, ADR-4).
+
+### Combine
+
+The final sprint verdict combines both passes:
+
+```
+final.passed = deterministic.passed && reconciled.passed
+```
+
+Both must pass for the sprint to be accepted.
+
+### lensVerdicts Output Shape
+
+After reconciliation the orchestrator writes a `lensVerdicts` array into the saved
+`EvalResult` JSON and sets `evaluator = "panel"`. The array shape is:
+
+```ts
+lensVerdicts: Array<{
+  lens: string;    // e.g. "correctness", "security", "regression", "quality", "simplicity"
+  passed: boolean; // individual lens verdict
+  summary: string; // per-lens summary from the qualitative evaluator
+}>
+```
+
+This field is optional and backward-compatible: eval results produced before the panel
+feature (or by non-panel evaluators) simply omit it.

package/skills/bober.plan/SKILL.md

@@ -77,6 +77,12 @@ Read the following files if they exist (skip those that do not):
 3. `package.json` — dependencies, scripts, project metadata
 4. `tsconfig.json` — TypeScript configuration
 5. Any files listed in `planner.contextFiles` from the config
+6. **Learn from past sprint outcomes (bounded memory):** Load the distilled lessons index via
+   `retrieveRelevantLessons(projectRoot, keywords, { topK })`, deriving `keywords` from the feature
+   title/description. This reads ONLY the bounded `.bober/memory/INDEX.md` and returns at most
+   `topK` deterministically-ranked lessons. **Do NOT read `.bober/history.jsonl` directly** — the raw
+   history is unbounded and is intentionally off-limits to the planner. Use the returned lessons to
+   avoid repeating past failure patterns when shaping sprints.
 
 Survey the project structure:
 - Use Glob with patterns appropriate to the stack to understand the file layout (e.g., `src/**/*.ts`, `contracts/**/*.sol`, `programs/**/*.rs`, `app/**/*`, `pages/**/*`)

package/skills/bober.run/SKILL.md

@@ -52,7 +52,7 @@ ORCHESTRATOR (you — this session)
   │     │       └─ Add evaluator feedback to handoff
   │     │       └─ Go to 4b (spawn FRESH generator with feedback)
   │     │
-  │     └─ 4e. If PASSED: update contract status, log, next sprint
+  │     └─ 4e. If PASSED: update contract status, log, spawn documenter (per-sprint docs), next sprint
   │
   └─ 5. Final summary
 ```
@@ -443,6 +443,15 @@ When done, respond with EXACTLY this JSON structure (no other text):
 
 ### 3f. Spawn the Evaluator Subagent
 
+**Panel mode (gated, off by default):** Read `config.evaluator.panel`. If `panel.enabled` is `true` AND `panel.lenses.length >= 2`, run the PANEL flow described in the inlined Lens Panel reference below (`<!-- Reference: lens-panel.md -->`):
+- Spawn ONE bober-evaluator with **MODE:deterministic** — runs the configured strategy suite exactly once.
+- Then spawn one bober-evaluator per lens with **MODE:lens:<name>** for each name in `panel.lenses`, bounded by `panel.maxConcurrent` concurrent spawns.
+- Collect each lens verdict; majority-vote: `passed = passCount > failCount`, **FAIL-CLOSED on tie** (tie → false).
+- Set `final.passed = deterministic.passed && reconciled.passed`.
+- Save the eval-result with `evaluator: "panel"` and a `lensVerdicts: [{ lens, passed, summary }]` array.
+
+OTHERWISE (panel disabled, or fewer than 2 lenses), spawn exactly ONE bober-evaluator with **MODE:full** exactly as described below — byte-identical to today's behaviour.
+
 Use the **Agent tool** to spawn an evaluator subagent.
 
 **How to call the Agent tool:**
@@ -547,20 +556,30 @@ When done, respond with EXACTLY this JSON structure (no other text):
    ```json
    {"event":"sprint-completed","contractId":"...","specId":"...","iteration":N,"timestamp":"..."}
    ```
-4. **Check if the plan is now fully complete.** Read the PlanSpec's `sprints` array to get the total sprint count. Count how many of those contracts now have `status: "completed"`. If ALL sprints are completed (N/N):
+4. **Spawn the Documenter subagent — write docs now, per-sprint, while the change is fresh.** Do NOT defer documentation to a final sprint. Use the Agent tool with `subagent_type: bober-documenter` and `mode: auto`:
+   ```
+   You are the Bober Documenter subagent. Sprint <N> just PASSED evaluation and was marked complete. Write its documentation and update related docs while the change is fresh.
+
+   Read from disk: .bober/contracts/<contractId>.json, .bober/handoffs/gen-report-<contractId>-<iteration>.json, .bober/eval-results/eval-<contractId>-<iteration>.json, and .bober/principles.md if it exists.
+
+   Follow your agent instructions: determine what was built from the committed diff, write the sprint record to docs/sprints/<contractId>.md, find & update related existing docs (README, ADRs, CLAUDE.md, module docs) made stale by the change, and commit ONLY the doc files separately. Do NOT modify application code or tests. Respond with the JSON structure defined in your agent spec.
+   ```
+   After it returns: parse the JSON. If it crashed, do NOT fail the sprint (it already passed) — log `{"event":"sprint-docs-failed","contractId":"...","timestamp":"..."}` and continue. Carry any non-empty `concerns` into the milestone print.
+5. **Check if the plan is now fully complete.** Read the PlanSpec's `sprints` array to get the total sprint count. Count how many of those contracts now have `status: "completed"`. If ALL sprints are completed (N/N):
    - Update the PlanSpec: set `status` to `"completed"` and `completedAt` to current ISO-8601 timestamp. Save to `.bober/specs/<specId>.json`. **The `status` field MUST remain in the first 10 lines of the JSON** so future runs can skip it with a partial read.
    - Update `.bober/progress.md` — change the plan's status line to `completed (N/N sprints)`.
    - Log event: `{"event":"plan-completed","specId":"...","sprintsCompleted":N,"timestamp":"..."}`
-5. Print milestone:
+6. Print milestone:
    ```
    === Sprint <N>/<total> PASSED ===
    Title: <title>
    Iteration: <M>
    Progress: [=====>    ] <N>/<total> sprints complete
+   Docs: <sprintDocPath> (+ <count> related docs updated)
    Next: <next sprint title>
    ```
    If all sprints are done, print `=== PLAN COMPLETE ===` instead of "Next:".
-6. Move to next sprint.
+7. Move to next sprint.
 
 **On FAIL with retries remaining:**
 1. Check if iteration < `evaluator.maxIterations` (default: 3).