agent-bober 0.12.0 → 0.17.0

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 + 10 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.15.0",
   "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

@@ -5,6 +5,249 @@ All notable changes to `agent-bober` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [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
+
+- **Claude Opus 4.8 support** ([#17](https://github.com/BOBER3r/agent-bober/pull/17)): the `opus` shorthand now resolves to `claude-opus-4-8` (1M context, adaptive thinking); added an `opus-4-7` shorthand to pin the previous model.
+- **`@anthropic-ai/sdk` upgraded `0.39.0` → `0.100.1`** to expose the Opus 4.8 request fields, with zero adapter behavior change.
+- **Anthropic prompt caching** (pattern borrowed from nousresearch/hermes-agent): ephemeral `cache_control` breakpoints on the system prompt + recent messages (system-and-last-3, capped at 4 per request), behind `providerConfig.promptCaching` — default **on** for Anthropic, no-op for other providers.
+- **`effort` control**: optional `ChatParams.effort` (`low` | `medium` | `high` | `xhigh` | `max`) forwarded as top-level `output_config.effort`; omitted when unset so the API default (`high` on Opus 4.8) applies. Non-Anthropic adapters ignore it.
+- **Mid-conversation system blocks**: a `SystemUpdateMessage` message variant renders to an Anthropic `mid_conv_system` content block with optional ephemeral `cache_control`; OpenAI and Google adapters handle it best-effort without error.
+- **`bober_list_pending_approvals`**: List all pending careful-flow checkpoints awaiting human
+  approval. Accepts optional `{ projectPath?: string }` (must be absolute when supplied; defaults
+  to cwd). Returns `[{ checkpointId, ageMs, prompt }]` — identical shape to `bober list-approvals
+  --json`. Backed by the new shared `listPendingApprovals(projectRoot)` helper in
+  `src/state/approval-state.ts`.
+- **`bober_approve_checkpoint`**: Approve a pending checkpoint over MCP by writing
+  `.bober/approvals/<id>.approved.json` with the same payload shape as `bober approve`
+  (`{ approvedAt, approverId, editDelta? }`). Accepts `{ checkpointId, projectPath?, editDelta? }`.
+  Guards with `pendingExists` before writing. Returns `{ approvedAt, checkpointId }`.
+- **`bober_reject_checkpoint`**: Reject a pending checkpoint over MCP by writing
+  `.bober/approvals/<id>.rejected.json` with the same payload shape as `bober reject`
+  (`{ rejectedAt, rejecterId, feedback }`). Accepts `{ checkpointId, projectPath?, feedback }`
+  (feedback required and non-empty). Guards with `pendingExists` before writing.
+  Returns `{ rejectedAt, checkpointId }`.
+- **`bober_list_projects`**: Enumerate bober projects under one or more search roots.
+  Accepts `{ searchRoots: string[] }`. Walks each root one level deep; returns
+  `[{ projectPath, name, mode?, hasActiveRuns, lastRunAt? }]` for every directory
+  containing `bober.config.json`. Unreadable roots are skipped with a stderr warning.
+  READ-ONLY — does not instantiate RunManager; reads `.bober/runs/*/state.json` directly.
+- **`bober_list_specs`**: List PlanSpecs in a project. Accepts `{ projectPath }`.
+  Reads `.bober/specs/*.json` with loose parsing (invalid files silently skipped).
+  Returns `[{ specId, title, status, sprintCount, completedAt? }]`.
+- **`bober_get_project_state`**: Aggregate per-project state counts for the cockpit sidebar.
+  Accepts `{ projectPath }`. Returns `{ configExists, activeRunCount, lastRunAt?,
+  openIncidentCount, pendingApprovalCount, specCount, mode? }`. READ-ONLY — does not
+  instantiate RunManager.
+- All six new tools accept an optional `projectPath` (required for discovery tools; optional
+  for approval tools). When supplied, `projectPath` must be absolute — a relative path returns
+  a soft-error JSON `{ error: "projectPath must be absolute" }` rather than throwing.
+- **`listPendingApprovals(projectRoot)`** helper extracted from
+  `src/cli/commands/list-approvals.ts` into `src/state/approval-state.ts`. Both the CLI and
+  the MCP tool `bober_list_pending_approvals` share this helper. Exported from
+  `src/state/index.ts` as `listPendingApprovals` / `PendingApprovalRow`.
+- **`readRunStatesFromDisk(projectRoot)`** helper added to `src/state/run-state.ts` as a
+  named alias for `listRunStateFiles`. Exported from `src/state/index.ts`. Cockpit discovery
+  tools use it to enumerate run states for arbitrary project roots without touching the
+  RunManager singleton.
+- MCP tool count: **23 → 29**.
+
+- **`bober_run_in_worktree`**: Start a pipeline inside an isolated git worktree on a new branch.
+  Input: `{ task: string, allowDirty?: boolean, keepOnSuccess?: boolean }`. Returns
+  `{ runId, branch, worktreePath, status: 'running' }` immediately (fire-and-forget like `bober_run`).
+  Multiple worktree runs can execute concurrently on the same project. Use `bober_get_run_status`
+  to track progress.
+- **`bober worktree run <task>`** CLI subcommand mirroring the MCP tool. Flags:
+  `--allow-dirty` (skip uncommitted-changes guard), `--keep-on-success` (retain worktree after success).
+  Prints `{ runId, branch, worktreePath, projectRoot }` JSON to stdout.
+- **`runInWorktree(task, projectRoot, config, opts)`** (`src/orchestrator/worktree.ts`): the shared helper
+  the CLI and MCP tool both use. Creates a git worktree under `<pipeline.worktreeRoot>/<runId>` on a
+  branch derived from `generator.branchPattern`, runs the pipeline inside it, and on success removes
+  the worktree per `pipeline.cleanupWorktreeOnSuccess`. On failure (or if `--keep-on-success`/`keepOnSuccess`)
+  the worktree is retained for debugging and its path is printed to stderr.
+- **`pipeline.worktreeRoot`** config field: directory (relative to projectRoot) under which
+  worktrees are created. Default `.bober/worktrees`.
+- **`pipeline.cleanupWorktreeOnSuccess`** config field: when true (default), remove the worktree
+  via `git worktree remove` after a successful run. On failure the worktree is always retained.
+- **`RunState.worktreePath`** and **`RunState.branch`** optional fields. Populated by `runInWorktree`
+  before the pipeline starts; surfaced in `bober_get_run_status` output.
+- **`RunManager.startRun(task, projectRoot, config, pipelineFn?, opts?)`** signature extended with
+  optional `opts: { runId?, worktreePath?, branch? }`. Existing 3- and 4-arg callers are unchanged.
+- **`git.ts`** helpers: `addWorktree`, `removeWorktree`, `isClean` shelling out to git CLI (no new deps).
+
+### Follow-ups (documented, NOT implemented this sprint)
+
+- Garbage collection of orphaned worktrees from prior failed runs (`bober worktree prune`).
+- Worktree-aware bober_status (the cockpit uses bober_get_run_status by runId instead).
+- Cross-worktree merge automation.
+
+- **`bober_subscribe_events`**: Subscribe to runId-scoped live events. Input: `{ runId: string, since?: string }`. Returns `{ subscriptionId, status: 'subscribed', startedAt }`. The server begins emitting `bober/events` notifications for every line appended to `.bober/history.jsonl` or `.bober/telemetry/<date>.jsonl` whose `runId` matches the subscription. The optional `since` parameter triggers a one-time backfill of pre-existing events with `timestamp > since`.
+- **`bober_unsubscribe_events`**: Unsubscribe from a runId-scoped event stream. Input: `{ subscriptionId: string }`. Releases file-watch handles when no other subscription is watching the same files. Returns `{ subscriptionId, status: 'unsubscribed' }` or a soft-error `{ error: 'Subscription not found: <id>' }`.
+- **`EventStreamManager`** (`src/mcp/event-stream.ts`): In-process class that tails `.bober/history.jsonl` and `.bober/telemetry/<date>.jsonl` using `fs.watch`. One file-watch handle is shared across all subscriptions watching the same file (reference-counted). Date roll-over is detected via a polling interval (5 s, `unref()`'d). Lines without an extractable `runId` (top-level or `details.runId`) are silently skipped. Per-subscription bounded queue (default 1000) drops the oldest events on overflow; a single `bober/events.dropped` notification with `{ subscriptionId, dropped: N }` is emitted once per overflow window. All diagnostic output is routed to `process.stderr` (stdout is reserved for the MCP JSON-RPC transport).
+- **`pipeline.eventQueueBound`** config field: per-subscription bounded queue limit. Default `1000`, minimum `1`. Readable by the server from `bober.config.json` and passed to `EventStreamManager` at startup.
+- **`bober_list_active_runs`**: Lists all runs tracked by the RunManager. Accepts optional `{ status?: 'running'|'completed'|'failed'|'aborted' }` filter. Returns a JSON array of RunState objects. Omit the filter to get all runs regardless of status.
+- **`bober_get_run_status`**: Fetches the full RunState for a specific run by `runId`. Input: `{ runId: string }` (required). Returns the complete RunState JSON or `{ error: 'Run not found: <runId>' }` when the runId is unknown.
+- **`bober_abort_run`**: Aborts a currently running pipeline run. Input: `{ runId: string, reason?: string }`. Flips `status` to `'aborted'`, persists `abortedAt` and `abortReason` to `state.json`, and returns `{ runId, status: 'aborted', abortedAt }`. Returns `{ error: 'Run not found: <runId>' }` for unknown runs, `{ error: 'Run is not active' }` for non-running runs. Note: this sprint flips state only; forceful in-flight subprocess termination (SIGTERM propagation) is deferred to a future hardening sprint.
+- **`RunState.status`** type union widened to include `'aborted'`; new optional fields `abortedAt?: string` and `abortReason?: string` added.
+
+## [0.14.0] — 2026-05-25
+
+Bober Vision — agent-bober becomes a four-mode software engineering teammate
+instead of a single-mode autopilot. The pipeline you already know is Mode 1;
+the other three modes share its scaffolding (planner, evaluator, audit log)
+but pause at different boundaries and operate at different blast radii.
+
+The headline change: it is now safe to delegate production-touching work.
+Careful-flow gates every meaningful boundary; Diagnose has a native vocabulary
+for incidents; Postmortem auto-synthesizes from the audit trail.
+
+See [VISION.md](./VISION.md) for the full design rationale and example flows.
+
+### Added
+
+- **Mode 1 — Autopilot** (unchanged): the existing generator-evaluator loop.
+  Use for spikes and greenfield. `bober run`.
+- **Mode 2 — Careful-flow**: checkpoint-gated execution. Every
+  research/plan/sprint boundary surfaces a diff and waits for approval via
+  CLI prompt, disk marker (`.bober/approvals/*.pending.json`), or GitHub PR.
+  Per-run audit log at `.bober/audits/<runId>.jsonl`. New CLI:
+  `bober approve <checkpointId>`, `bober reject <checkpointId>`,
+  `bober list-approvals`, `bober audit-show <runId>`.
+- **Mode 3 — Diagnose**: production-incident response. Generic observability
+  MCP plugin slots (any MCP server matching the schema can supply metrics
+  and logs). Structured incident timeline at `.bober/incidents/<id>/`.
+  Change-management gates around destructive actions. Playbook library
+  searchable by symptom. New CLI: `bober incident [start|status|end|list|abort]`,
+  `bober rollback <incidentId>`, `bober playbook [list|show|search]`.
+- **Mode 4 — Postmortem**: auto-synthesized from incident artifacts when an
+  incident transitions to `resolved`. Every claim has an inline citation
+  back to timeline/changelog/observations. Required sections enforced
+  (TL;DR, Impact, Timeline, Root Cause 5-Whys, Contributing Factors, What
+  Went Well, What Went Wrong, Action Items). New CLI:
+  `bober postmortem [generate|show] <incidentId>`.
+- **Behavioral discipline foundation** (verbatim port of obra/superpowers):
+  Iron Laws, Red Flags, Rationalization-Prevention tables, SessionStart
+  bootstrap, anti-pattern catalog, AGENTS.md contract. Surfaces as 9 new
+  universal skills: `bober.using-bober`, `bober.verify`, `bober.debug`,
+  `bober.code-review`, `bober.incident`, `bober.diagnose`, `bober.deploy`,
+  `bober.runbook`, `bober.postmortem`. Installed by `agent-bober init` and
+  copied to `.claude/commands/`.
+- **4 new agent definitions** in `agents/`: `bober-code-reviewer`,
+  `bober-diagnoser`, `bober-deployer`, `bober-postmortemer`.
+- **Opt-in local-only telemetry** (default OFF). When enabled, writes mode-0600
+  JSONL events to `.bober/telemetry/<date>.jsonl`. ESLint rule
+  (`no-restricted-imports` + `no-restricted-globals`) scoped to
+  `src/telemetry/**` blocks all network primitives at lint time. Privacy
+  invariant: only IDs, counts, durations, and enums in payloads; never
+  user-content strings. New CLI: `bober telemetry [status|purge|export]`.
+- **Config schema migration**: `bober config migrate` rewrites an existing
+  `bober.config.json` to explicitly include all new vision-era fields with
+  default values. Back-compat parsing handles missing fields automatically —
+  the migrate command is informative, not required.
+- **Mode + checkpoint config**: `pipeline.mode` (`autopilot` | `careful`,
+  default `autopilot`), `pipeline.checkpointMechanism` (`noop` | `disk` |
+  `cli` | `github-pr`, default `noop`). All optional; absence means autopilot.
+- **End-to-end correctness gate**: `tests/e2e/four-modes.test.ts` (11 tests)
+  exercises all four modes on a fixture project. Uses the real
+  `DiskCheckpointMechanism` (not a mock), spawns the real
+  `ExternalMcpServer` subprocess for the MCP protocol boundary, runs the
+  real incident lifecycle including `verifyResolution`, and validates the
+  auto-generated postmortem against the required-sections + citation rules.
+
+### Changed
+
+- `src/cli/commands/init.ts`: `UNIVERSAL_COMMANDS` extended with the 9 new
+  vision skills. `agentFiles` extended with the 4 new agent definitions.
+  All vision-era surfaces now ship with every brownfield/preset init.
+- `VISION.md`, `README.md`, `AGENTS.md` updated to document the four modes,
+  the careful-flow mechanisms, the incident lifecycle, the telemetry
+  guarantee, and the slash-command set.
+
+### Tests
+
+563 → **1115 tests passing** across 82 test files (4 pre-existing skipped).
+New test coverage includes: incident timeline + state machine, resolution
+verification, rollback (full + per-step gates), postmortem section/citation
+assertions, playbook search, careful-flow integration, observability MCP
+spawn, deployer change classification + ChangeEntry recording, config
+schema back-compat, telemetry writer (mode-0600, default-off, concurrency,
+privacy), CLI subcommands for config/telemetry.
+
+### Backward compatibility
+
+- Existing `bober.config.json` files (pre-vision) parse cleanly with the
+  extended schema — all new fields are optional and default to current
+  autopilot behavior. No migration required.
+- Existing CLI surface (`bober plan`, `bober sprint`, `bober eval`,
+  `bober run`, `bober graph`, etc.) is unchanged.
+- Telemetry defaults OFF. No network egress under any condition; enforced
+  statically by ESLint and verified at runtime.
+
+## [0.13.0] — 2026-05-24
+
+Graph (tokensave) integration — user-facing CLI commands and slash-command skills for code-graph workflows.
+
+### Added
+
+- **`agent-bober graph [init|sync|status]`** — manage the code graph index.
+  - `init`: runs `tokensave init`, writes `.bober/graph/manifest.json`. Exits 2 with platform-aware install hint when tokensave is missing.
+  - `sync [--force]`: re-indexes changed files (full re-index with `--force`). Updates manifest.
+  - `status [--json]`: prints `{ready, indexedFileCount, tokensaveVersion, lastSyncedHeadSha, stale}`. Human-readable or JSON.
+- **`agent-bober onboard`** — generate 5 onboarding markdown files in `.bober/onboarding/` using the code graph (architecture overview, hotspots, knowledge gaps, communities, README). Prints a summary table on completion.
+- **`agent-bober impact <symbol|file>`** — analyse the impact radius of a symbol or file. Writes `.bober/graph/impact/<slug>.md` with sections `# Impact: <target>`, `## Affected symbols`, `## Tests covering this symbol`.
+- **3 new universal skills** (installed in all presets and brownfield):
+  - `skills/bober.graph/SKILL.md` (`/bober-graph`) — code graph management
+  - `skills/bober.onboard/SKILL.md` (`/bober-onboard`) — onboarding doc generation
+  - `skills/bober.impact/SKILL.md` (`/bober-impact`) — impact analysis (with `argument-hint: <symbol|file>`)
+- **`scripts/e2e-graph-smoke.sh`** — end-to-end smoke test script (gates on tokensave binary availability).
+- Architecture document: [`.bober/architecture/arch-20260524-port-code-review-graph-architecture.md`](.bober/architecture/arch-20260524-port-code-review-graph-architecture.md)
+
+### Changed
+
+- All 3 graph commands respect `graph.enabled=false` — exit 1 with message: *"Graph integration is disabled. Enable via `graph.enabled: true` in bober.config.json."*
+- `src/cli/commands/init.ts` skill map: `bober.graph`, `bober.onboard`, `bober.impact` added to `UNIVERSAL_COMMANDS` — included in every preset and brownfield init.
+
+### KPI gate result
+
+60% combined reduction (synthetic-fixture baseline; real-pipeline measurement via `node scripts/run-kpi-gate.mjs`).
+
+### Tests
+
+549 → **563 tests passing** (added 14 tests: slug derivation, command success paths, disabled-graph paths, skill bundle frontmatter, init.ts skill inclusion).
+
 ## [0.12.0] — 2026-04-17
 
 Tuned for Claude Opus 4.7 — the model now follows instructions literally and

package/README.md

@@ -48,8 +48,42 @@ You describe a feature
 
 ---
 
+## Operating Modes
+
+agent-bober operates in four modes — pick the one that matches your situation. See
+[VISION.md](./VISION.md) for full documentation, worked examples, and configuration details.
+
+| Mode | When to Use | Entry Point |
+|------|-------------|-------------|
+| **Autopilot** | Feature spikes, greenfield work, no production risk | `bober run` |
+| **Careful-Flow** | Production behavior changes, want checkpoint approval | `bober run --mode careful` |
+| **Diagnose** | Production system is broken right now | `bober incident start` |
+| **Postmortem** | After resolving an incident, generate a retrospective | `bober postmortem generate` |
+
+---
+
 ## 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 + 10 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
@@ -58,10 +92,12 @@ npm install -g agent-bober
 npx agent-bober init
 ```
 
+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 10 slash commands (`/bober-plan`, `/bober-run`, etc.)
-- **Cursor / Windsurf** -- MCP server with 10 tools in the chat interface
+- **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"`)
 
@@ -114,6 +150,52 @@ Specialized workflows:
 
 ---
 
+## Graph (Tokensave) Integration
+
+> **Optional.** The graph is an opt-in enhancement — agent-bober's core pipeline (Researcher → Planner → Curator → Generator → Evaluator) works fully without it. Enable it only if you want semantic code search, impact analysis, and auto-generated onboarding docs.
+
+agent-bober integrates with [tokensave](https://github.com/aovestdipaperino/tokensave) to build a structural code graph that powers semantic search, impact analysis, and automated onboarding documentation.
+
+**Prerequisite — install the `tokensave` binary.** It is a native Rust binary, **not** an npm package, so `npm install -g agent-bober` does **not** install it. Install it separately:
+
+```bash
+# macOS (Homebrew)
+brew install aovestdipaperino/tap/tokensave
+# Windows (Scoop)
+scoop bucket add tokensave https://github.com/aovestdipaperino/scoop-bucket && scoop install tokensave
+# Any platform (Cargo / Rust)
+cargo install tokensave
+```
+
+Required version range: **`>=6.0.0-beta.1 <7.0.0`**. agent-bober verifies this on `agent-bober graph init` and prints the correct install hint if `tokensave` is missing or out of range. If the binary is absent, graph features degrade gracefully and the rest of the pipeline is unaffected.
+
+Once `tokensave` is installed, enable the graph by adding a `graph` section to `bober.config.json`:
+
+```json
+{
+  "graph": {
+    "enabled": true,
+    "languageTier": "core"
+  }
+}
+```
+
+Once enabled, three new CLI commands and slash commands become available:
+
+```bash
+agent-bober graph init         # Initialise the graph index
+agent-bober graph sync         # Re-index changed files (--force for full re-index)
+agent-bober graph status       # Check graph status (--json for machine-readable)
+agent-bober onboard            # Generate .bober/onboarding/ documentation
+agent-bober impact <symbol>    # Analyse impact radius and test coverage
+```
+
+In Claude Code, the same workflows are available as slash commands: `/bober-graph`, `/bober-onboard`, `/bober-impact`.
+
+For architecture details see: [`.bober/architecture/arch-20260524-port-code-review-graph-architecture.md`](.bober/architecture/arch-20260524-port-code-review-graph-architecture.md)
+
+---
+
 ## Multi-Provider Support
 
 agent-bober is **provider-agnostic**. Use any LLM provider for any agent role. Mix and match providers freely -- use one for planning, another for generation, a local model for evaluation.
@@ -129,6 +211,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`:
@@ -163,11 +271,18 @@ npx agent-bober run "feature" --provider openai
 
 Provider SDKs (`openai`, `@google/generative-ai`) are **optional peer dependencies** -- install only what you use. Only `@anthropic-ai/sdk` is required by default.
 
+### Anthropic features (Claude Opus 4.8)
+
+- **Latest model by default.** The `opus` shorthand resolves to **`claude-opus-4-8`** (1M context, adaptive thinking). Pin the previous generation with the `opus-4-7` shorthand.
+- **Prompt caching, on by default.** Multi-turn Anthropic calls reuse a cached system + recent-message prefix (ephemeral `cache_control`, system-and-last-3 strategy), cutting input-token cost. Disable per role with `"providerConfig": { "promptCaching": false }`.
+- **Effort control.** Set `effort` (`low` | `medium` | `high` | `xhigh` | `max`) to trade latency/cost against depth; when omitted, the API default applies (`high` on Opus 4.8). Other providers ignore it.
+- **Mid-conversation system updates.** Instructions can be revised mid-task without breaking the prompt cache (Anthropic `mid_conv_system` blocks).
+
 ---
 
 ## MCP Server (Cursor, Windsurf, etc.)
 
-agent-bober includes an MCP (Model Context Protocol) server that exposes all functionality as tools in any MCP-compatible IDE.
+agent-bober includes an MCP (Model Context Protocol) server that exposes **37 tools** across pipeline, run-management, careful-flow approvals, multi-project discovery, incident response, and graph in any MCP-compatible IDE.
 
 ### Setup for Cursor
 
@@ -218,6 +333,13 @@ Add to your Windsurf MCP configuration:
 | `bober_spec` | read | Read the current PlanSpec |
 | `bober_principles` | read/write | Read or set project principles |
 | `bober_config` | read/write | Read or update `bober.config.json` |
+| `bober_list_pending_approvals` · `bober_approve_checkpoint` · `bober_reject_checkpoint` | careful-flow | List / approve / reject checkpoint approvals (careful mode) |
+| `bober_list_active_runs` · `bober_get_run_status` · `bober_abort_run` · `bober_run_in_worktree` | run-mgmt | Manage concurrent and isolated-worktree runs |
+| `bober_subscribe_events` · `bober_unsubscribe_events` | events | Live run event stream |
+| `bober_get_project_state` · `bober_list_projects` · `bober_list_specs` | discovery | Multi-project state + spec discovery |
+| `bober_incident_start` · `bober_incident_status` · `bober_incident_list` · `bober_incident_abort` · `bober_rollback_start` · `bober_postmortem_get` · `bober_playbook_search` · `bober_playbook_list` | incident | Diagnose, roll back, postmortem, and search playbooks |
+
+*(37 tools total — the rows above summarize the additional categories beyond the core pipeline tools.)*
 
 ---
 
@@ -286,6 +408,20 @@ 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
 
@@ -300,6 +436,39 @@ npx agent-bober run "feature"                            # Full autonomous loop
 npx agent-bober mcp                                      # Start MCP server (Cursor/Windsurf)
 ```
 
+#### New Commands (Sprints 9–25)
+
+The following commands were added after the initial release. Full reference in [COMMANDS.md](./COMMANDS.md).
+
+```bash
+# Checkpoint approval (careful-flow mode)
+npx agent-bober list-approvals                        # List pending checkpoints
+npx agent-bober approve <checkpointId>                # Approve a checkpoint
+npx agent-bober approve <checkpointId> --edit <file>  # Approve with edit delta
+npx agent-bober reject <checkpointId>                 # Reject a checkpoint
+npx agent-bober audit show <runId>                    # Show audit log for a run
+
+# Incident response
+npx agent-bober incident start '<symptom>' --severity S2   # Start incident
+npx agent-bober incident status <incidentId>               # Check status
+npx agent-bober incident end <incidentId> --verified       # Mark resolved
+npx agent-bober incident list                              # List all incidents
+npx agent-bober incident abort <incidentId> --reason "..."  # Abort incident
+
+# Rollback
+npx agent-bober rollback <incidentId> --dry-run    # Preview rollback plan
+npx agent-bober rollback <incidentId>              # Execute rollback
+
+# Postmortem
+npx agent-bober postmortem generate <incidentId>   # Generate retrospective
+npx agent-bober postmortem show <incidentId>       # Print retrospective
+
+# Playbooks
+npx agent-bober playbook list                      # List all playbooks
+npx agent-bober playbook show <name>               # Show playbook content
+npx agent-bober playbook search '<symptom>'        # Search by symptom
+```
+
 #### Clarification gating
 
 When the planner can't fully decompose a feature without more information, it stops with `status: "needs-clarification"` instead of fabricating sprints. The CLI surfaces the open questions and you resolve them via `plan answer`. After the last question is answered the spec auto-promotes to `status: "ready"` and the next `sprint`/`run` proceeds. See the **Architecture** section for the full lifecycle.
@@ -342,6 +511,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.
@@ -405,7 +600,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 ------------------------------------------
@@ -417,6 +636,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
@@ -671,7 +891,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
@@ -693,6 +917,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.
@@ -747,6 +978,8 @@ bash scripts/run-eval.sh /path/to/project
 
 ## Contributing
 
+See [AGENTS.md](./AGENTS.md) for contributor discipline including the anti-slop pre-PR checklist.
+
 Contributions are welcome. To set up the development environment:
 
 ```bash