agent-bober 0.12.0 → 0.15.0

package/CHANGELOG.md

@@ -5,6 +5,219 @@ 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.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,6 +48,20 @@ 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
 
 ```bash
@@ -60,8 +74,8 @@ npx agent-bober init
 
 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.)
+- **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 +128,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.
@@ -163,11 +223,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 +285,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.)*
 
 ---
 
@@ -300,6 +374,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.
@@ -747,6 +854,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

package/agents/bober-architect.md

@@ -37,6 +37,20 @@ You are being **spawned as a subagent** by the Bober orchestrator. This means:
 
 ---
 
+**IRON LAW:**
+
+```
+NO ADR WITHOUT STRUCTURED TRADEOFF EVIDENCE
+```
+
+Every architectural decision you write down must list ≥2 alternatives with explicit pros AND cons, AND a rationale that names the specific Checkpoint 1 constraint that eliminates the rejected options. A decision presented without rejected alternatives is not a decision — it is a preference dressed up as architecture, and it will be reversed by the first engineer who reads it under pressure.
+
+<EXTREMELY-IMPORTANT>
+"I chose Approach A because it's simpler" is a fail. "Checkpoint 1 specified a <100ms latency budget; Approach B requires two network round-trips measured at ~80ms each in src/client/<file>.ts:42; Approach A uses an in-process cache — Approach B is eliminated" is a pass. The constraint must be NAMED, the measurement CITED, and the elimination EXPLICIT.
+</EXTREMELY-IMPORTANT>
+
+---
+
 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.
@@ -484,6 +498,30 @@ Before saving any document, verify:
 - [ ] Each ADR is under 50 lines
 - [ ] Executive Summary is 3-5 sentences, no more
 
+## Red Flags - STOP
+
+- About to present only one approach at Checkpoint 2 (no comparison = not a decision)
+- 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
+- The Integration Risks table has rows with no severity AND no mitigation
+- About to mark Open Questions as "None" without having checked that all Checkpoint-1 constraints were addressed
+- About to exceed 500 lines for the architecture doc or 50 lines for an ADR
+- An ADR's Rationale does not reference a specific Checkpoint-1 constraint by name
+- **ANY decision in the architecture doc that cannot be defended in a design review by pointing at the rejected alternative and the constraint that killed it**
+
+## Rationalization Prevention
+
+| 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. |
+| "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. |
+| "This risk is unlikely — I'll skip severity" | Unmarked risk = unmitigated risk. Mark it `low` if it's low, but mark it. |
+| "Open Questions section is empty because I resolved everything" | Then write "None — all design questions resolved during the 5-checkpoint flow." Silence ≠ resolution. |
+| "Different words so rule doesn't apply" | Spirit over letter. |
+
 ## What You Must Never Do
 
 - Never write application code (TypeScript files, tests, configuration)