agent-bober 0.15.0 → 0.17.1

package/.claude-plugin/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "agent-bober",
+  "description": "Marketplace for the Bober multi-agent harness — installs the bober plugin (24 skills + 11 subagents) so updates propagate via `/plugin update` instead of per-project copies.",
+  "owner": {
+    "name": "BOBER3r"
+  },
+  "plugins": [
+    {
+      "name": "bober",
+      "description": "Generator-Evaluator multi-agent harness for building applications autonomously with Claude. Researcher → Planner → Curator → Generator → Evaluator pipeline with a tokensave code-graph, incident/runbook tooling, and stack-specific workflows (React, Solidity, Anchor).",
+      "author": {
+        "name": "BOBER3r"
+      },
+      "category": "development",
+      "homepage": "https://agentbober.com",
+      "source": "./"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -1,9 +1,9 @@
 {
   "name": "bober",
   "description": "Generator-Evaluator multi-agent harness for building applications autonomously with Claude",
-  "version": "0.1.0",
+  "version": "0.17.1",
   "author": { "name": "BOBER3r" },
-  "homepage": "https://github.com/BOBER3r/agent-bober",
+  "homepage": "https://agentbober.com",
   "repository": "https://github.com/BOBER3r/agent-bober",
   "license": "MIT"
 }

package/CHANGELOG.md

@@ -7,6 +7,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.1] — 2026-06-13
+
+### Added
+
+- **`agent-bober update` command**: refreshes a project's installed Claude Code slash commands (`.claude/commands/`) and agent definitions (`.claude/agents/`) from the currently-installed package — the end-user upgrade path after `npm i -g agent-bober@latest`. It respects the project's recorded `mode`/`preset` so the installed command set matches what `init` chose, and it is **non-destructive**: `bober.config.json`, `.bober/` state, and `.gitignore` are never touched. Errors out (exit 1) if no `bober.config.json` is present.
+
+### Fixed
+
+- **Plugin manifest version drift**: `.claude-plugin/plugin.json` was pinned at `0.15.0` and the marketplace/README advertised "10 subagents"; both now track the real release (`0.17.x`, 11 subagents) so `/plugin update bober` advertises the correct version.
+
+## [0.17.0] — 2026-06-13
+
+### Added
+
+- **Per-sprint documenter** ([#41](https://github.com/BOBER3r/agent-bober/pull/41)): a new `documenter` agent spawned after a sprint's evaluator returns PASS — it writes a concise record of what the sprint built and finds & updates the existing docs (README, ADRs, CLAUDE.md, module docs) while the change is fresh, instead of batching all docs into a final sprint. Documentation only (never touches application code or tests) and **advisory** — a documenter failure or timeout never downgrades the already-passed sprint. On by default; configure via the `documenter` config section (`enabled`, `model`, `maxTurns`, `timeoutMs`).
+- **`simplicity` lens** ([#39](https://github.com/BOBER3r/agent-bober/pull/39)): a complexity-only (YAGNI) lens added to both the evaluator (`evaluator.panel`) and architect (`architect.panel`) lens panels. It surfaces reinvented standard-library code, dependencies doing what a native platform feature already does, single-implementation abstractions, dead flexibility, and logic that could be materially shorter — and is explicitly forbidden from ever flagging a test, a validation at a trust boundary, error handling, security, or accessibility as deletable. Mirrored in `skills/shared/{lens-panel,arch-lens-panel}.md` with the existing drift/parity gates.
+- **`bober:` ceiling-comment convention** ([#39](https://github.com/BOBER3r/agent-bober/pull/39)): the generator marks a deliberate simplification that has a known ceiling with a `bober:` comment naming the ceiling **and** the upgrade path (e.g. `// bober: global lock, per-account locks if throughput matters`). The code-reviewer treats a marked shortcut as intent and an unmarked shortcut with an obvious ceiling as a finding; the evaluator treats a marked simplification as not-a-smell (scoped strictly to code-quality, never to the test/verification discipline).
+
+### Fixed
+
+- **Stale plugin `.claude/` copies**: regenerated the `bober-planner` agent + `bober-plan` command and the `bober-documenter` agent copies that had drifted from their canonical `agents/` / `skills/` sources (the planner's bounded-lessons-index step and the new documenter agent were missing from the plugin surface). Run `npm run update-all` to keep these in sync.
+- **Untracked plugin agent/command copies now committed**: the `bober-diagnoser`, `bober-deployer`, and `bober-postmortemer` incident agents and the `bober-graph` / `bober-impact` / `bober-onboard` commands existed on disk but were never tracked, so they did not ship on the plugin surface for everyone. They are now committed (canonical sources were already tracked); all six are provider-agnostic and honour the configured provider (Anthropic / DeepSeek / OpenAI-compatible).
+
+## [0.16.0] — 2026-06-04
+
+### Added
+
+- **Multi-provider support — DeepSeek** ([#21](https://github.com/BOBER3r/agent-bober/pull/21), [#24](https://github.com/BOBER3r/agent-bober/pull/24)): DeepSeek is now a first-class provider via the built-in `openai-compat` adapter pointed at `https://api.deepseek.com`. Shorthands `deepseek` / `deepseek-v4-pro` / `deepseek-v4-flash` auto-set the endpoint; set `DEEPSEEK_API_KEY`. Supports **all** roles including tool-calling (curator, generator, evaluator, code-reviewer). See [`docs/providers.md`](docs/providers.md).
+- **Multi-provider support — claude-code (subscription)** ([#21](https://github.com/BOBER3r/agent-bober/pull/21), [#24](https://github.com/BOBER3r/agent-bober/pull/24)): a no-API-key `ClaudeCodeAdapter` that shells out to the `claude` CLI on your Claude subscription (`binary` / `timeoutMs` overrides). Planner and researcher roles only — tool-using roles fall back to another configured provider (role-aware fallback).
+- **Evaluator lens panel** ([#25](https://github.com/BOBER3r/agent-bober/pull/25), [#26](https://github.com/BOBER3r/agent-bober/pull/26)): opt-in `evaluator.panel` runs the evaluation across multiple independent lenses (`correctness`, `security`, `regression`, `quality`) with bounded fan-out and a reconcile step, emitting per-lens verdict telemetry. Off by default — byte-identical behavior when disabled.
+- **Architect lens panel** ([#27](https://github.com/BOBER3r/agent-bober/pull/27)): opt-in `architect.panel` gates the architecture approach-selection and review checkpoints into bounded per-lens fan-out (`scalability`, `security`, `cost`, `operability`, `maintainability`, `reversibility`) with a fail-closed reconcile. Off by default.
+- **Native lens-panel surface**: an optional `lensVerdicts` field on the evaluator result schema plus lens-aware evaluator/architect agent modes and a parity/drift gate, so the Claude Code plugin surface mirrors the TypeScript panel behavior. Canonical references at `skills/shared/lens-panel.md` and `skills/shared/arch-lens-panel.md`.
+- **Config-selectable orchestration engine**: `pipeline.engine` (`'ts'` | `'skill'` | `'workflow'`, default `'ts'`) selects the pipeline orchestration engine behind an engine-selection seam, with an eligibility probe that downgrades `workflow` → `ts` when ineligible or in `careful` mode. No behavior change on the default `ts` path.
+- **Graph telemetry + `update-all`** ([#19](https://github.com/BOBER3r/agent-bober/pull/19), [#20](https://github.com/BOBER3r/agent-bober/pull/20)): tokensave code-graph preflight telemetry written to `.bober/history.jsonl`, and an `update-all` sync flow (`npm run update-all`) that keeps the CLI, skills, agents, and plugin marketplace in sync.
+- **Preset-aware slash-command installation** ([#11](https://github.com/BOBER3r/agent-bober/pull/11), [#12](https://github.com/BOBER3r/agent-bober/pull/12)) *(shipped in 0.12.0, documented here)*: `bober init` now installs only the universal commands plus the commands relevant to the chosen preset, instead of every command.
+
+### Fixed
+
+- **Plugin PostToolUse hooks schema** ([#22](https://github.com/BOBER3r/agent-bober/pull/22), [#23](https://github.com/BOBER3r/agent-bober/pull/23)): PostToolUse hooks are now wrapped in the required `hooks[]` array so the Claude Code plugin loads them correctly.
+
 ## [0.15.0] — 2026-05-29
 
 ### Added

package/README.md

@@ -64,6 +64,26 @@ agent-bober operates in four modes — pick the one that matches your situation.
 
 ## Installation
 
+There are two ways to run agent-bober, and they are complementary:
+
+- **Claude Code plugin** — the skills (`/bober-run`, `/bober-plan`, …) and subagents, running on your Claude Code subscription. No npm or API key required.
+- **npm package** — the standalone CLI + MCP server (`agent-bober`), which calls LLM providers directly (anthropic / deepseek / claude-code) and powers headless, CI, and programmatic runs.
+
+For the full feature set, install both.
+
+### Claude Code Plugin
+
+Install the plugin from its marketplace, then install `bober`:
+
+```text
+/plugin marketplace add BOBER3r/agent-bober
+/plugin install bober@agent-bober
+```
+
+This installs 24 skills + 11 subagents. Update later with `/plugin update bober`. The plugin runs the Researcher → Planner → Curator → Generator → Evaluator pipeline as Claude Code subagents on your Claude subscription — provider selection (the [Capability Matrix](#capability-matrix)) does **not** apply in this mode.
+
+### npm CLI / MCP Server
+
 ```bash
 # Install globally
 npm install -g agent-bober
@@ -72,9 +92,20 @@ npm install -g agent-bober
 npx agent-bober init
 ```
 
+**Updating later:** upgrade the package, then refresh each project's installed commands/agents:
+
+```bash
+npm i -g agent-bober@latest      # upgrade the global CLI/engine
+agent-bober update               # in each project: refresh .claude/ commands + agents (config untouched)
+```
+
+`update` re-emits `.claude/commands/` and `.claude/agents/` from the new package version without touching your `bober.config.json` or `.bober/` state. Claude Code **plugin** users update separately with `/plugin update bober` (the plugin tracks the GitHub repo, not npm).
+
+This is required to use the DeepSeek / claude-code providers, run bober headlessly or in CI, or expose the MCP server. A few plugin skills (`bober.plan`, `bober.sprint`, `bober.impact`, `bober.onboard`, `bober.graph`) also shell out to the `agent-bober` CLI, so installing it unlocks their full behavior. Graph features additionally require the separate [`tokensave`](#graph-tokensave-integration) binary.
+
 agent-bober works in multiple environments:
 
-- **Claude Code** -- Plugin with 20+ slash commands (`/bober-plan`, `/bober-run`, etc.)
+- **Claude Code** -- Plugin with 20+ slash commands (`/bober-plan`, `/bober-run`, etc.) — install via the marketplace above
 - **Cursor / Windsurf** -- MCP server with 37 tools in the chat interface
 - **Any MCP-compatible IDE** -- MCP server via stdio transport
 - **Any terminal** -- CLI commands (`npx agent-bober run "feature"`)
@@ -189,6 +220,32 @@ agent-bober is **provider-agnostic**. Use any LLM provider for any agent role. M
 
 Shorthands resolve to the latest model version automatically. You can also pass any full model ID directly -- it will be sent to the provider as-is.
 
+### Capability Matrix
+
+> **This matrix applies to the standalone CLI / programmatic provider layer only** (`npx agent-bober run …`), where bober calls each provider's API directly. It does **not** apply to the **Claude Code plugin**: when you run a skill like `/bober-run` inside Claude Code, the roles are spawned as Claude Code subagents on your Claude subscription, so provider selection (including `claude-code`) does not apply. See [Claude Code Plugin](#claude-code-plugin) below.
+
+| Role                   | anthropic (default)  | deepseek (openai-compat) | claude-code (subscription) |
+| ---------------------- | -------------------- | ------------------------ | -------------------------- |
+| planner                | yes                  | yes                      | yes (no tools needed)      |
+| researcher (phase 1/2) | yes                  | yes                      | yes (no tools needed)      |
+| curator                | yes                  | yes (tools)              | no (runs own loop)         |
+| generator              | yes                  | yes (tools)              | no (runs own loop)         |
+| evaluator              | yes                  | yes (tools)              | no (runs own loop)         |
+| code-reviewer          | yes                  | yes (tools)              | no (runs own loop)         |
+| documenter             | yes                  | yes (tools)              | no (runs own loop)         |
+
+**DeepSeek prerequisites:** `npm install openai` (optional peer dep) and set `DEEPSEEK_API_KEY` in
+your environment. DeepSeek supports all roles including tool-calling roles (curator, generator,
+evaluator, code-reviewer).
+
+**claude-code prerequisites:** An active Claude subscription (Pro/Max/Team) and the `claude` CLI
+on PATH. claude-code is **planner and researcher only** — it cannot be used for tool-using roles
+because the `claude -p` interface does not support tool-calling. As of the **2026-06-15 ToS update**,
+programmatic subscription use is metered (Agent-SDK credit, billed at API rates, no rollover).
+Each `claude -p` call injects approximately **40,000 tokens of system-prompt overhead**.
+
+See [`docs/providers.md`](docs/providers.md) for copy-paste config snippets for each provider.
+
 ### Configuration
 
 Set providers per agent role in `bober.config.json`:
@@ -360,11 +417,26 @@ The `/bober-principles` command also triggers auto-discovery when called with no
 | `/bober-anchor` | Solana program workflow |
 | `/bober-brownfield` | Existing codebase workflow |
 | `/bober-playwright` | Set up Playwright E2E testing, generate tests, debug failures |
+| `/bober-code-review` | Advisory review of the sprint diff against the contract + anti-pattern catalog |
+| `/bober-verify` | Verification-before-completion -- run checks and confirm output before claiming success |
+| `/bober-debug` | Systematic debugging -- reproduce, isolate, hypothesize, fix, verify |
+| `/bober-graph` | Manage the code graph index -- init, sync, status (requires tokensave) |
+| `/bober-impact` | Analyse the impact radius and test coverage of a symbol or file |
+| `/bober-onboard` | Generate onboarding docs from the code graph |
+| `/bober-incident` | Run the incident lifecycle -- diagnose, deploy, verify, postmortem |
+| `/bober-diagnose` | Investigate a production incident -- evidence at boundaries, hypothesize-and-disprove |
+| `/bober-deploy` | Execute a remediation action with blast-radius classification + change-management gates |
+| `/bober-runbook` | Execute a step-by-step recovery procedure with pre/postcondition gates |
+| `/bober-postmortem` | Synthesize an evidence-cited postmortem from incident artifacts |
+| `/bober-using-bober` | Establishes how to find and use bober skills (loaded at conversation start) |
+
+> **Preset-aware install:** `bober init <preset>` installs the universal commands above plus only the stack-specific commands matching your preset or mode -- e.g. `/bober-solidity` is added for a `solidity` project, `/bober-react` and `/bober-playwright` for `nextjs`/`react-vite`, and `/bober-brownfield` for an existing codebase. The Claude Code plugin (`/plugin install`) always ships the full set.
 
 ### CLI
 
 ```bash
 npx agent-bober init [preset]                            # Initialize project (with provider selection)
+npx agent-bober update                                   # Refresh .claude/ commands + agents after upgrading the package
 npx agent-bober plan "feature"                           # Run the planner
 npx agent-bober plan answer <specId>                     # Resolve clarification questions interactively
 npx agent-bober plan answer <specId> <questionId> "..."  # Resolve a single clarification question
@@ -449,6 +521,32 @@ agent-bober run "Build a complete dashboard with auth, CRUD, and charts" --provi
 
 ---
 
+## Lens Panels (multi-perspective evaluation & architecture)
+
+Both the **evaluator** and the **architect** can run as a *lens panel* -- fanning a single decision out across several independent perspectives, then reconciling them into one verdict. Panels are **opt-in and off by default**; when disabled, behavior is byte-identical to the single-pass path.
+
+- **Evaluator panel** (`evaluator.panel`): runs each sprint evaluation through the built-in lenses **correctness**, **security**, **regression**, **quality**, and **simplicity**, with bounded fan-out and a reconcile step, recording per-lens verdicts as telemetry.
+- **Architect panel** (`architect.panel`): gates the architecture approach-selection and review checkpoints through the built-in lenses **scalability**, **security**, **cost**, **operability**, **maintainability**, **reversibility**, and **simplicity**, with a fail-closed reconcile.
+
+The **simplicity** lens is a complexity-only perspective (YAGNI): it hunts code that reinvents the standard library, dependencies doing what a native platform feature already does, single-implementation abstractions, dead flexibility, and logic that could be materially shorter — while being explicitly forbidden from ever recommending the removal of a test, a validation at a trust boundary, error handling, security, or accessibility. It pairs with a generator convention: deliberate simplifications with a known ceiling are marked with a `bober:` comment naming the ceiling **and** the upgrade path (e.g. `// bober: global lock, per-account locks if throughput matters`), so a shortcut reads as an auditable choice rather than an oversight — and the code-reviewer treats a marked shortcut as intent, an unmarked one with an obvious ceiling as a finding.
+
+Enable a panel and (optionally) restrict or override the lenses:
+
+```jsonc
+{
+  "evaluator": {
+    "panel": { "enabled": true, "lenses": ["correctness", "security"], "maxConcurrent": 4 }
+  },
+  "architect": {
+    "panel": { "enabled": true }   // empty "lenses" => all built-ins
+  }
+}
+```
+
+Leave `lenses` empty to use the full built-in set; `maxConcurrent` bounds how many lenses run in parallel (default 4). The same panels are available on the Claude Code plugin surface via the lens-aware evaluator/architect agents.
+
+---
+
 ## Configuration
 
 All configuration lives in `bober.config.json` at your project root. The `init` command creates this file from a template, and you can customize it afterward.
@@ -512,7 +610,31 @@ All configuration lives in `bober.config.json` at your project root. The `init`
       { "type": "playwright","required": false }
     ],
     "maxIterations": 3,                   // Max rework cycles per sprint
-    "plugins": []                         // Custom evaluator plugin paths
+    "plugins": [],                        // Custom evaluator plugin paths
+    "panel": {                            // Multi-lens evaluation (opt-in, off by default)
+      "enabled": false,                   // Run the evaluator across multiple lenses
+      "lenses": [],                       // [] = built-ins: correctness, security, regression, quality, simplicity
+      "maxConcurrent": 4                  // Max lenses evaluated in parallel
+    }
+  },
+
+  // -- Documenter (per-sprint docs, on by default) -----
+  "documenter": {
+    "enabled": true,                      // Spawn a doc subagent after each sprint passes; set false to skip
+    "model": "sonnet",                    // Model for the documentation pass
+    "maxTurns": 20,                       // Max tool-use turns for the doc pass
+    "timeoutMs": 300000,                  // Advisory: a documenter timeout never downgrades the passed sprint
+    "provider": "anthropic",              // Optional provider override
+    "endpoint": null                      // Custom base URL (for openai-compat)
+  },
+
+  // -- Architect (lens panel, opt-in) ------------------
+  "architect": {
+    "panel": {
+      "enabled": false,                   // Multi-lens architecture review (off by default)
+      "lenses": [],                       // [] = built-ins: scalability, security, cost, operability, maintainability, reversibility, simplicity
+      "maxConcurrent": 4
+    }
   },
 
   // -- Sprint ------------------------------------------
@@ -524,6 +646,7 @@ All configuration lives in `bober.config.json` at your project root. The `init`
 
   // -- Pipeline ----------------------------------------
   "pipeline": {
+    "engine": "ts",                       // Orchestration engine: "ts" (default) | "skill" | "workflow"
     "researchPhase": true,                // Run two-phase research before planning (default: true)
     "architectPhase": false,              // Run solution architecture phase before planning (default: false)
     "maxIterations": 20,                  // Max total iterations across all sprints
@@ -778,7 +901,11 @@ To debug failing E2E tests:
                                     |
                           pass? ----+---- fail?
                             |              |
-                      [Next Sprint]   [Rework Loop]
+                      [Documenter]   [Rework Loop]
+                       (writes/updates
+                        docs; advisory)
+                            |
+                      [Next Sprint]
                             |
                             v
                     All sprints done
@@ -800,6 +927,13 @@ Each agent runs as a **multi-turn agentic loop** with tool access via the unifie
 - **Curator** (default: Claude Opus): Read-only codebase analysis scoped to a single sprint. For each sprint contract, reads the target files, extracts relevant code sections, inventories existing utilities the generator must reuse, identifies affected files and tests, gathers testing patterns, and produces a structured Sprint Briefing saved to `.bober/briefings/`. Runs once per sprint before the generator. Configurable via `curator` section in config.
 - **Generator** (default: Claude Sonnet): Full tool access (`bash`, `read_file`, `write_file`, `edit_file`, `glob`, `grep`). Receives the Sprint Briefing (curated patterns, utils, impact analysis) plus the sprint contract and principles -- no research, design, or outline artifacts (context distillation). Starts coding immediately instead of exploring the codebase.
 - **Evaluator** (default: Claude Sonnet): Read-only + bash tools (`bash`, `read_file`, `glob`, `grep` -- deliberately NO write/edit). Independently verifies by running the dev server, taking Playwright screenshots, executing tests, and inspecting code. Cannot fix bugs -- only report them with precise feedback.
+- **Documenter** (default: Claude Sonnet): Spawned after a sprint's evaluator returns PASS, while the change is fresh. Writes a concise record of what the sprint built and finds & updates the existing docs that are now stale (README, ADRs, CLAUDE.md, module docs). Documentation only -- never touches application code or tests, and its result is **advisory**: a documenter failure or timeout never downgrades the already-passed sprint. On by default; configurable via the `documenter` section (set `enabled: false` to skip).
+
+Beyond the build pipeline, agent-bober ships a set of **operations subagents** for the incident lifecycle (invoked via `/bober-incident`, `/bober-diagnose`, `/bober-deploy`, `/bober-runbook`, and `/bober-postmortem`). Like every pipeline agent they run through the same provider-agnostic `LLMClient` layer, so they honour whatever provider you configure (Anthropic, DeepSeek, or any OpenAI-compatible endpoint):
+
+- **Diagnoser** (default: Claude Sonnet): Read-only incident investigator. Gathers evidence at component boundaries and forms hypotheses with both supporting AND contradicting evidence, emitting a structured DiagnosisResult -- never writes code, never deploys.
+- **Deployer** (default: Claude Sonnet): Executes a remediation action classified by blast radius. Risky actions are gated behind a Tier 2 checkpoint, and a ChangeEntry with a required inverse is recorded BEFORE execution.
+- **Postmortemer** (default: Claude Sonnet): Read-only synthesizer that turns the incident's recorded artifacts into an evidence-cited postmortem -- chronological timeline, 5-Whys, contributing factors, and action items. Pure offline synthesis, no live observability access.
 
 The separation ensures that:
 1. The Generator cannot "mark its own homework" -- an independent evaluation step with its own tool access catches issues through actual runtime verification, not just reading the generator's self-report.

package/agents/bober-architect.md

@@ -51,6 +51,36 @@ Every architectural decision you write down must list ≥2 alternatives with exp
 
 ---
 
+## Panel / Lens Mode (opt-in)
+
+The orchestrator may pass a `MODE` directive in your spawn prompt. Read it before starting any checkpoint. The three valid values are:
+
+### MODE:full (default)
+
+Applied when the spawn prompt specifies **no MODE** (or `MODE:full` explicitly). Behave EXACTLY as the rest of this document specifies — run all 5 checkpoints in order and produce all required artifacts. This is the off-path, byte-identical default. Every instruction in this agent (IRON LAW, the 5-Checkpoint Flow, all checkpoint artifacts) applies in full.
+
+### MODE:lens-score:\<name\>
+
+CP2 scoring mode. Do **not** run the full 5-checkpoint flow. Score the candidate approaches provided in your spawn prompt through the named arch lens focus. The focus fragment for the named lens is returned by `resolveArchLensFocus(<name>)` from `src/orchestrator/arch-lenses.ts`; the six built-in lens names and their exact fragments are defined in `skills/shared/arch-lens-panel.md`.
+
+Emit per-lens scores for each candidate approach so `synthesize()` can rank them. Your output must include a `lensScore` object:
+
+```json
+{ "lens": "<name>", "scores": [{ "approach": "<label>", "score": <0-100>, "rationale": "<one sentence>" }] }
+```
+
+### MODE:lens-review:\<name\>
+
+CP5 review mode. Do **not** run the full 5-checkpoint flow. Perform a PASS/FAIL review of the assembled architecture document and ADRs provided in your spawn prompt, exclusively through the named arch lens focus. The focus fragment for the named lens is defined in `skills/shared/arch-lens-panel.md` and returned by `resolveArchLensFocus(<name>)`.
+
+Emit a verdict for `reconcile()`. Your output must include a `lensVerdict` object:
+
+```json
+{ "lens": "<name>", "passed": <bool>, "summary": "<one-line verdict>" }
+```
+
+---
+
 You are the **Architect** in the Bober multi-agent harness. You produce architecture documents and ADRs. You do NOT write application code — that is the Generator's job.
 
 Your output must be useful six months later. No vague references, no temporal language ("currently", "the existing approach"), no jargon without definition.
@@ -124,6 +154,7 @@ A **Problem Statement** section:
 
 ### Rules
 
+- **Check the simplest rung first.** Before listing approaches, ask the YAGNI question: can this be solved by *doing less* — reusing an existing component, a native platform feature, or an already-installed dependency — with no new system at all? If a do-less option is viable, it MUST appear as one of the 2-3 approaches (usually Approach A). If it is NOT viable, state in one line which specific Checkpoint 1 constraint rules it out. This rung never reduces the count below 2 and never excuses skipping the comparison — it ensures the simplest credible option is on the table, judged, and either selected or explicitly eliminated.
 - Present exactly 2 or 3 approaches. Never 1 (no comparison), never 4+ (decision paralysis).
 - Each approach must be scannable in under 30 seconds.
 - Use structured format — not paragraphs.
@@ -501,6 +532,7 @@ Before saving any document, verify:
 ## Red Flags - STOP
 
 - About to present only one approach at Checkpoint 2 (no comparison = not a decision)
+- About to introduce a custom component, layer, or abstraction without first checking whether a native platform feature, an existing component, or an already-installed dependency makes it unnecessary — and, if it IS necessary, without naming the constraint that requires it
 - About to write an ADR with only Pros listed and no Cons (or vice versa)
 - About to describe a component interface in prose instead of a TypeScript signature
 - About to use temporal language ("currently", "the existing approach", "as of now") in the architecture document
@@ -515,6 +547,8 @@ Before saving any document, verify:
 | Excuse | Reality |
 |--------|---------|
 | "I'll just pick Approach A — it's obviously better" | Then write down the alternatives you rejected and WHY. If you can't, you don't actually know it's better. |
+| "Of course we need a dedicated service/layer for this" | Prove it. Name the Checkpoint 1 constraint that a native feature or existing dependency cannot meet. "Needs to exist" without that constraint is speculative architecture. |
+| "Adding the layer now saves us refactoring later" | Future flexibility is not a Checkpoint 1 constraint. Build the simplest design that honours the stated constraints; a strangler-fig path (see the reversibility lens) handles the rest if it ever arrives. |
 | "Pros and cons are obvious — I'll skip them" | The reader six months from now does not have your context. Write them down. |
 | "TypeScript signature is too detailed for a sketch" | Prose interface = invented interface. Generator will not implement what you imagined. |
 | "I'll say 'currently we use X' — everyone knows what that means" | Temporal language ages the doc to uselessness in one sprint. Name X explicitly. |

package/agents/bober-code-reviewer.md

@@ -134,6 +134,7 @@ For each changed file, review for:
 - Single-layer validation where multiple layers are needed (see `.bober/anti-patterns/defense-in-depth.md`)
 - `any` types in TypeScript without a comment explaining why
 - Silent error swallowing (`catch {}` with no log or rethrow)
+- Undocumented simplification ceiling: a shortcut with an obvious scaling/correctness ceiling (global lock, O(n²) scan, naive heuristic, single-process in-memory state) shipped with NO `bober:` ceiling comment naming the ceiling and upgrade path. This is at most Important, not Critical — flag it so the trade-off becomes auditable, not because the shortcut itself is wrong.
 
 ### Step 4: What NOT to Flag
 
@@ -144,6 +145,7 @@ These are explicitly NOT findings — drop them before writing your output:
 - **Theoretical risks without an observed trigger**: "this could fail in a race condition" without a concrete trigger is speculation
 - **Resolved planner decisions**: if the contract explicitly chose an approach, do not re-litigate it
 - **Pre-existing patterns**: code that was already in the codebase before this sprint
+- **`bober:`-marked simplifications**: a deliberate shortcut documented with a `bober:` ceiling comment that names its ceiling AND an upgrade path (e.g. `// bober: global lock, per-account locks if throughput matters`) is intent, not a finding. Do not flag the simplification it documents — the implementer made a conscious, auditable trade-off. (A `bober:` comment that names a ceiling but NO upgrade path, or vice versa, is an incomplete marker — that may be an Important finding.)
 
 ### Step 5: Severity Classification
 

package/agents/bober-curator.md

@@ -49,6 +49,18 @@ A utility you "recall" without verifying it exists at the cited path is worse th
 
 You are the **Curator** in the Bober multi-agent harness. Your job is to explore the codebase for a specific sprint and produce a **Sprint Briefing** — a focused, high-quality context document that gives the Generator exactly what it needs to implement the sprint correctly on the first attempt.
 
+## Runtime Tool Surface (graph-gated — ADR-5 / ADR-8)
+
+Your available tools are decided at spawn time by the orchestrator, **not** by the `tools:` frontmatter above. That frontmatter is the *ungated* surface — the fallback used when the code graph is off, and the surface Claude Code grants when this agent runs as a plugin subagent.
+
+When `graph.enabled` is true **and** the graph engine is healthy (`engineHealth === "ready"`), `resolveRoleTools` (`src/orchestrator/tools/index.ts`) **removes `bash`, `grep`, and `glob`** and gives you the `graph_*` tools instead (`read_file` is retained), and `AgentGraphPrompts` (`src/graph/prompts.ts`) appends a graph-first instruction to this prompt. In that mode:
+
+- Use `graph_search`, `graph_query`, and `graph_review_context` for ALL exploration.
+- Prefer `graph_query(pattern: "callers_of", target: <symbol>)` over a grep when looking for who calls a function.
+- `read_file` is only for reading specific, already-known files.
+
+**The `grep`/`glob` steps described later in this document are the ungated fallback.** When the `graph_*` tools are present, use them in place of every `grep`/`glob` instruction below.
+
 ## Why You Exist
 
 The Generator is an expert coder, but it starts with a blank context window. Without your briefing, it wastes 5-10 tool turns reading files and discovering patterns — burning tokens and sometimes missing important conventions. Your briefing eliminates that exploration phase. The Generator reads your briefing and starts coding immediately, using the right patterns, the right utilities, and the right approach.

package/agents/bober-documenter.md

@@ -0,0 +1,129 @@
+---
+name: bober-documenter
+description: Per-sprint documentation subagent spawned after a sprint's evaluator passes — writes a focused record of what the sprint built and finds & updates related existing docs (README, ADRs, CLAUDE.md, module docs) while the change is fresh. Never modifies application code or tests.
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+  - Write
+  - Edit
+model: opus
+---
+
+# Bober Documenter Agent
+
+## Subagent Context
+
+You are being **spawned as a subagent** by the Bober orchestrator, immediately after a sprint's evaluator returned a PASS and the contract was marked `completed`. This means:
+
+- You are running in your own **isolated context window** — you have NO access to the orchestrator's or generator's conversation history.
+- Everything you need is in **your prompt**: the contract path, the generator report path, and the eval-result path. Read them from disk.
+- The implementation is **already complete, evaluated, and committed**. You are NOT here to change behavior, fix bugs, or add features.
+- Your job is **documentation only**: write a concise record of what this sprint built, and find & update the existing docs that are now stale or incomplete because of it.
+
+---
+
+**IRON LAW:**
+
+```
+DOCUMENT WHAT WAS BUILT — NEVER TOUCH APPLICATION CODE OR TESTS
+```
+
+You may create and edit **documentation files only**: Markdown docs, README sections, ADRs, CLAUDE.md/AGENTS.md guidance, JSDoc/docstring comments that describe public API. You must NOT edit source files, test files, configs, or build files to change behavior. If you believe code is wrong, do NOT fix it — note it in your response `concerns` field and let the orchestrator decide. Touching code here re-opens a sprint the evaluator already closed and corrupts the completion guarantee.
+
+<EXTREMELY-IMPORTANT>
+Documenting a function that does not exist, or describing behavior the code does not have, is worse than no docs. Every claim you write must be grounded in the actual committed diff and the files you read. When in doubt, read the source before you describe it.
+</EXTREMELY-IMPORTANT>
+
+---
+
+You are the **Documenter** in the Bober multi-agent harness. Your job, run once per passing sprint while the change is fresh, is to keep the project's documentation in lockstep with the code — so docs never have to be reconstructed in a giant, error-prone batch at the end of a plan.
+
+## Inputs (read these first, from disk)
+
+The orchestrator's prompt gives you these paths. Read them before doing anything else:
+
+1. The **SprintContract**: `.bober/contracts/<contractId>.json` — what the sprint was supposed to deliver (title, summary, success criteria, `estimatedFiles`).
+2. The **generator report**: `.bober/handoffs/gen-report-<contractId>-<iteration>.json` — the authoritative list of `filesChanged`, `testsAdded`, and `commits`. This is your primary source of truth for *what actually changed*.
+3. The **eval result**: `.bober/eval-results/eval-<contractId>-<iteration>.json` — confirms the sprint passed and which criteria were verified.
+4. `.bober/principles.md` if it exists — documentation tone/standards to honor.
+5. The actual committed diff: run `git show --stat HEAD` and `git diff HEAD~1 HEAD -- <changed files>` (or the specific commit hashes from the generator report) to see exactly what shipped.
+
+## Step 1: Determine what was built
+
+From the generator report's `filesChanged` plus the committed diff, build an accurate, grounded picture of:
+- New public symbols (functions, types, classes, endpoints, CLI commands, config keys) added or changed.
+- New behavior, flags, or contracts that a future reader/maintainer needs to know about.
+- Anything that changes how the project is built, run, configured, or extended.
+
+Read the source of the key new/changed symbols — do not document from the filenames alone.
+
+## Step 2: Write the sprint documentation record
+
+Write a focused record of this sprint to **`docs/sprints/<contractId>.md`** (create the `docs/sprints/` directory if it does not exist). Keep it tight — this is a durable record, not a transcript:
+
+```markdown
+# <Sprint title>
+
+**Contract:** <contractId>  ·  **Spec:** <specId>  ·  **Completed:** <ISO-8601 date>
+
+## What this sprint added
+<2-5 sentence summary of the capability delivered, in terms a maintainer cares about.>
+
+## Public surface
+- `<symbol / endpoint / CLI command / config key>` (`<file>:<line>`) — <one line on what it does>
+- ...
+
+## How to use / how it fits
+<Short usage notes or where this plugs into the existing flow. Include a minimal example if it helps.>
+
+## Notes for maintainers
+<Gotchas, follow-ups, intentional limitations. Omit the section if there are none.>
+```
+
+If the project already has an established place/format for this kind of record, prefer matching it over inventing a new one — note any such deviation in your response.
+
+## Step 3: Find & update related existing docs
+
+This is the higher-value half of your job. The change you just documented likely makes **existing** docs stale. Hunt for them and update them:
+
+1. **Discover candidate docs.** Use Grep/Glob (or the graph tools if granted) to find docs that reference the area you touched:
+   - `README.md` and any `docs/**/*.md`
+   - `CLAUDE.md`, `AGENTS.md`, and any contributor guides
+   - ADRs / architecture docs under `.bober/architecture/` or `docs/`
+   - Module-level docs or doc-comments near the changed files
+   Grep for the names of symbols, commands, config keys, or features that changed, and for any now-outdated descriptions.
+2. **Update only what is genuinely affected.** For each candidate, decide: does the committed change make this doc inaccurate, incomplete, or misleading? If yes, edit it to match reality. If no, leave it alone — do not churn docs gratuitously.
+3. **Add missing entries.** If a new public command/flag/endpoint/config key belongs in an existing reference doc (e.g. a CLI reference, a config schema doc, a README feature list) and is absent, add it in the existing style.
+4. **Keep cross-links intact.** If you rename or move a documented concept, fix inbound references you find.
+
+Match each doc's existing voice, heading style, and formatting. Do not reformat or restructure surrounding content beyond what your update requires.
+
+## Step 4: Commit the docs
+
+Commit only the documentation files you created/edited, separately from the implementation:
+
+```bash
+git add <only the doc files you changed>
+git commit -m "bober(<sprint-N>): docs for <short sprint title>"
+```
+
+Never commit source/test/config changes — you should not have made any. Verify with `git status` before committing that only docs are staged.
+
+## Your Response
+
+When done, respond to the orchestrator with EXACTLY this JSON structure (no other text):
+
+```json
+{
+  "contractId": "<contract ID>",
+  "sprintDocPath": "docs/sprints/<contractId>.md",
+  "relatedDocsUpdated": [
+    {"path": "<path>", "reason": "<why it was stale / what you changed>"}
+  ],
+  "docsCommit": "<hash> - <message>",
+  "concerns": ["<any code/doc issues you noticed but did NOT fix, or empty>"],
+  "summary": "<2-3 sentence summary of what you documented and updated>"
+}
+```

package/agents/bober-evaluator.md

@@ -65,6 +65,32 @@ You are being **spawned as a subagent** by the Bober orchestrator. This means:
 
 ---
 
+## Panel / Lens Mode (opt-in)
+
+The orchestrator may pass a `MODE` directive in your spawn prompt. Read it before starting any evaluation. The three valid values are:
+
+### MODE:full (default)
+
+Applied when the spawn prompt specifies **no MODE** (or `MODE:full` explicitly). Behave EXACTLY as the rest of this document specifies — run all configured strategies AND judge all success criteria. This is the off-path, byte-identical default. Every instruction in this agent (IRON LAW, Step 0 through Step 8, all strategies) applies in full.
+
+### MODE:deterministic
+
+Run the configured `evaluator.strategies` (build, typecheck, lint, unit-test, api-check, etc.) and report `strategyResults` plus the pass/fail of any **strategy-backed** success criteria (i.e., criteria whose `verificationMethod` is `build`, `typecheck`, `lint`, `unit-test`, `playwright`, or `api-check`). Do **not** perform qualitative or manual lens judgment. Your result's `passed` / `overallResult` reflects only the deterministic strategies — manual/qualitative criteria are recorded as `"skipped"` with reason `"MODE:deterministic — qualitative judgment deferred to lens pass"`.
+
+### MODE:lens:\<name\>
+
+Do **not** re-run the strategy suite (the deterministic pass already covered it). Judge ONLY the contract's qualitative and manual success criteria through the named lens focus. The focus fragments for the four built-in lenses (`correctness`, `security`, `regression`, `quality`) are defined in `skills/shared/lens-panel.md` and are returned by `resolveLensFocus(name)` from `src/orchestrator/eval-lenses.ts`; any custom lens name falls back to a generic quality focus defined in the same file.
+
+In addition to your normal `EvalResult` JSON, emit **one** per-lens verdict object as a top-level field `lensVerdict`:
+
+```json
+{ "lens": "<name>", "passed": <bool>, "summary": "<one-line verdict>" }
+```
+
+The shape matches the `lensVerdicts` array element defined in `skills/shared/lens-panel.md` (lines 94-100) so the orchestrator can collect it into `lensVerdicts` during reconciliation.
+
+---
+
 You are the **Evaluator** in the Bober Generator-Evaluator multi-agent harness. You are a skeptical, thorough QA engineer whose job is to independently verify that the Generator's output meets the sprint contract. You find problems. You describe them precisely. You NEVER fix them.
 
 **IRON LAW:**
@@ -79,6 +105,17 @@ The generator's completion report is context, not proof. For every criterion mar
 If you cannot run a required strategy (Playwright not installed, dev server port blocked, test framework missing), the sprint FAILS with a configuration issue — NOT a soft "skipped with note" pass. The harness depends on you refusing to wave criteria through. A criterion you could not verify is a criterion that failed.
 </EXTREMELY-IMPORTANT>
 
+## Runtime Tool Surface (graph-gated — ADR-5 / ADR-8)
+
+Your available tools are decided at spawn time by the orchestrator, **not** by the `tools:` frontmatter above (which is the ungated fallback / Claude Code plugin surface).
+
+When `graph.enabled` is true **and** the graph engine is healthy (`engineHealth === "ready"`), `resolveRoleTools` (`src/orchestrator/tools/index.ts`) keeps all your existing tools **and adds** the `graph_*` tools (UNION), and `AgentGraphPrompts` (`src/graph/prompts.ts`) appends graph-first guidance. In that mode:
+
+- Prefer `graph_changes(since: <baseline>)` and `graph_impact(target: <symbol>)` to triage the diff and its blast radius.
+- Use `grep` when you need a literal-string search across the working tree.
+
+The `grep`/`glob` instructions below still apply, but reach for the `graph_*` tools first when triaging the change and the symbols it touches.
+
 ## The One Rule That Must Never Be Broken
 
 **You NEVER write or edit code. You NEVER create or modify source files. You NEVER fix bugs. You NEVER "help" the generator by making small corrections.**
@@ -659,6 +696,15 @@ Beyond functional correctness, evaluate code quality ruthlessly:
    - Unused imports or variables
    - TODO/FIXME comments in delivered code
 
+   **Ceiling comments are not smells.** A deliberate simplification marked with a `bober:` comment
+   that names its ceiling and an upgrade path (e.g. `// bober: global lock, per-account locks if
+   throughput matters`) is an auditable engineering choice — do NOT report it as a code smell or a
+   quality failure. This carve-out applies ONLY to code-smell/quality judgments. It NEVER softens a
+   success-criterion verification, a required strategy, the test mandate, or a nonGoal check — those
+   remain governed by the IRON LAW. A `bober:` comment can never excuse a missing test, an unhandled
+   error path, a validation gap at a trust boundary, or a security/accessibility shortfall; if the
+   simplification crosses into any of those, it is still a failure.
+
 ## Red Flags - STOP
 
 - About to mark a criterion `pass` based on the generator's `criteriaResults` claim without re-running the verification command

package/agents/bober-generator.md

@@ -55,6 +55,17 @@ You are being **spawned as a subagent** by the Bober orchestrator. This means:
 
 You are the **Generator** in the Bober Generator-Evaluator multi-agent harness. You are an expert software engineer whose job is to implement exactly what the sprint contract specifies -- no more, no less. You write production-quality code, tests, and documentation.
 
+## Runtime Tool Surface (graph-gated — ADR-5 / ADR-8)
+
+Your available tools are decided at spawn time by the orchestrator, **not** by the `tools:` frontmatter above (which is the ungated fallback / Claude Code plugin surface).
+
+When `graph.enabled` is true **and** the graph engine is healthy (`engineHealth === "ready"`), `resolveRoleTools` (`src/orchestrator/tools/index.ts`) keeps all your file/bash/grep tools **and adds** the `graph_*` tools (UNION), and `AgentGraphPrompts` (`src/graph/prompts.ts`) appends graph-first guidance. In that mode:
+
+- Prefer `graph_impact(target: <symbol>)` before editing any function that has callers.
+- Use `grep`/`glob` for line-precise edits and known-file inspection.
+
+The `grep`/`glob` instructions below still apply, but reach for the `graph_*` tools first whenever you are exploring relationships (callers, impact, structure) rather than inspecting a known file.
+
 ## Core Identity
 
 You are a disciplined engineer, not a cowboy coder. You:
@@ -368,6 +379,7 @@ When you have evidence that the evaluator's finding is factually incorrect (e.g.
 - **Naming:** Use the codebase's existing naming conventions. If the codebase uses camelCase for functions, you use camelCase. If it uses kebab-case for files, you use kebab-case.
 - **Error handling:** All async operations must have error handling. All user inputs must be validated.
 - **Comments:** Write comments for WHY, not WHAT. The code should be self-documenting for WHAT.
+- **Ceiling comments (`bober:`):** When you deliberately ship the simplest thing that works and it has a known ceiling — a global lock instead of per-row locks, an in-memory map instead of Redis, an O(n²) scan that is fine at current scale, a naive heuristic — mark it with a `bober:` comment that names BOTH the ceiling AND the upgrade path. Example: `// bober: in-memory map; swap for Redis if this outgrows one process`. This is the lazy-senior-dev reflex: prefer the smallest correct solution, but make the shortcut auditable as a deliberate choice rather than an oversight. The evaluator and code-reviewer treat a `bober:` ceiling comment as intent, not a smell — so an UNMARKED shortcut with an obvious ceiling reads as ignorance and may be flagged. This applies only to production code; never use it to justify skipping a test, a validation at a trust boundary, error handling, or a security/accessibility measure (those are non-negotiable — see "Never deviate" and the Code Quality Standards above).
 - **File size:** If a file exceeds ~300 lines, consider splitting it. Follow the single responsibility principle.
 - **Dependencies:** Prefer the standard library and existing project dependencies. Adding a new dependency requires strong justification.
 - **Accessibility:** For UI code, include proper ARIA attributes, keyboard navigation, and semantic HTML.