feat: mistake ledger — never make the same mistake twice

README.md

@@ -312,6 +312,15 @@ bus-wait ticket:PF-1884 --since 12 --timeout-ms 30000
 
 See [docs/message-bus.md](docs/message-bus.md) for channel conventions and cross-model usage.
 
+### Mistake ledger tools (local stdio only)
+
+| Tool | Description |
+|------|-------------|
+| `kb_mistake_record` | Record a mistake a reviewer or test caught, with its fix |
+| `kb_patterns_for` | Get up to 3 approved "known pitfalls" that match a task |
+
+See [docs/mistake-ledger.md](docs/mistake-ledger.md).
+
 ---
 
 ## CLI Commands
@@ -329,6 +338,8 @@ kb classify           Auto-classify unprocessed vault notes
 kb summarize          Generate AI summaries for unsummarized notes
 kb capture-x          Ingest X/Twitter bookmarks from export
 kb safety-check       Review a planned action against KB history
+kb mistakes           Mistake ledger: import-sdd, import-seed, record, record-run, list, stats
+kb patterns           Patterns from repeated mistakes: draft, list, page, set-status
 ```
 
 ---
@@ -580,6 +591,9 @@ These are the actual development patterns used to build this system. Open source
 | `KB_API_KEY_CLAUDE` | No | -- | API key for Claude remote access |
 | `KB_API_KEY_OPENAI` | No | -- | API key for OpenAI/ChatGPT access |
 | `KB_API_KEY_GEMINI` | No | -- | API key for Gemini access |
+| `KB_API_KEY_SWARM` | No | -- | API key for agent-swarm to write to the mistake ledger |
+| `KB_MISTAKES_HOME` | No | ~/.knowledge-base/mistakes | Folder for the mistake ledger files |
+| `KB_PATTERN_MODEL` | No | claude-sonnet-5-5 | Model for `kb patterns draft` |
 | `BETTER_AUTH_SECRET` | No | -- | OAuth token signing secret |
 | `BETTER_AUTH_URL` | No | -- | OAuth issuer URL for remote access |
 | `CLASSIFY_MODEL` | No | claude-haiku-4-5-20251001 | Model for AI classification |

bin/kb.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // bin/kb.js — CLI entry point
-// Commands: start, stop, mcp, register, ingest <path>, search <query>, read <id>, status, setup, bus-send, bus-inbox, bus-wait
+// Commands: start, stop, mcp, register, ingest <path>, search <query>, read <id>, status, setup, bus-send, bus-inbox, bus-wait, mistakes, patterns
 
 import '../src/paths.js'; // loads .env from ~/.knowledge-base/.env
 import { readFileSync } from 'fs';
@@ -103,6 +103,8 @@ const commands = {
   export:   () => import('../src/cli/export-cli.js').then(m => m.exportCmd(args)),
   restore:  () => import('../src/cli/restore-cli.js').then(m => m.restoreCmd(args)),
   auth:     () => import('../src/cli/auth-cli.js').then(m => m.authCmd(args)),
+  mistakes: () => import('../src/cli/mistakes-cli.js').then(m => m.mistakesCmd(args)),
+  patterns: () => import('../src/cli/mistakes-cli.js').then(m => m.patternsCmd(args)),
 };
 
 if (!command || !commands[command]) {
@@ -130,6 +132,8 @@ Commands:
   export             Export vault docs to a portable bundle (--out=dir, --dry-run, --json)
   restore <bundle>   Restore from a bundle (--dry-run, --overwrite, --yes, --strict, --no-embeddings)
   auth add-user <email>  Create an account that can approve OAuth/MCP clients (--password-stdin)
+  mistakes <command>  The mistake ledger: import-sdd, import-seed, record, record-run, list, stats
+  patterns <command>  Patterns from repeated mistakes: draft, list, page, set-status
   setup              Interactive setup wizard (--auto for agent mode)
 `);
   process.exit(command ? 1 : 0);

docs/mistake-ledger.md

@@ -0,0 +1,74 @@
+# Mistake ledger
+
+The knowledge base keeps every mistake a reviewer or test catches in an agent's work, together with its fix. Mistakes that repeat become short rules ("patterns"). You approve the rules, and agents are given the matching ones before they start a task.
+
+## Where things live
+
+| What | Where |
+|---|---|
+| Mistake records (append-only) | `~/.knowledge-base/mistakes/ledger.jsonl` |
+| Which patterns were given to which task | `~/.knowledge-base/mistakes/deliveries.jsonl` |
+| First-review numbers per run | `~/.knowledge-base/mistakes/runs.jsonl` |
+| Patterns | vault notes `patterns/<slug>.md` |
+
+Records are never edited. To correct one, record a new one with `supersedes` set to the old id. Every record is also copied into the KB as a document of type `mistake`, so `kb search` finds it.
+
+Set `KB_MISTAKES_HOME` to keep the three files somewhere else.
+
+## Recording mistakes
+
+- **Swarm builds** send their review findings by themselves when a fix passes review (agent-swarm, `KB_API_KEY_SWARM`).
+- **Subagent builds:** `kb mistakes import-sdd <repo>/.superpowers/sdd --project=<name> --client-ok`. Run it as often as you like; nothing is imported twice.
+- **By hand:** the local MCP tool `kb_mistake_record` (stdio only; it is not offered to remote MCP clients), or `kb mistakes record <record.json>`.
+- **The October catalogue:** `kb mistakes import-seed ~/autoresearch/kb-mistakes/catalogue.json`.
+
+`--client-ok` (or `"client_ok": true`) says the owner of the code allows keeping the record. For your own projects that is always true. For a client's code, only with their permission.
+
+A record with a fix commit is **strong** evidence; one without is **weak**.
+
+## From mistakes to patterns
+
+1. `kb patterns draft` asks a model to group the unassigned mistakes. A draft is only written when its mistakes come from at least 2 different tasks, its rule has at most 60 words, and it has a real bad example and a real good example.
+2. `kb patterns page` writes the approval page and remembers its numbering.
+3. Reply with the numbers on the page: `kb patterns set-status "approve 1 and 3, edit 2: <your wording>, reject 4"`.
+   - **approve** — agents may be given the rule;
+   - **edit** — approve it with your wording;
+   - **reject** — never propose it again from the same mistakes;
+   - **retire** — stop using an approved pattern.
+   If any part of the reply is wrong, nothing changes.
+
+Half of the approved patterns go to the `teach` group and are given to agents. The other half go to the `test` group and are held back, so a later experiment can measure whether patterns help on agents that never saw them. Only `teach` patterns are indexed: drafts, rejected and held-back patterns never appear in KB search. (The mistake records behind them stay searchable, so the later experiment runs its agents without KB access.)
+
+An approved pattern that no task has received for 90 days is listed on the next approval page. Nothing is retired automatically.
+
+## Giving patterns to agents
+
+`kb_patterns_for({ task_text, files })` returns at most 3 approved `teach` patterns that match the task, as a ready "Known pitfalls" section. It returns nothing when no pattern matches well enough.
+
+- **Swarm builds:** `swarm init` adds that section to each task.
+- **Subagent builds:** the controller calls `kb_patterns_for` for each task, puts the section in the implementer's brief, and gives the same section to the task's reviewer as extra things to check.
+
+## Seeing whether it works
+
+`kb mistakes stats`, or the **Learning** page of the dashboard, shows how many tasks passed their first review, per model and per run.
+
+A swarm sends its numbers by itself at the final review. After a subagent build, the controller records them with `kb mistakes record-run <run.json>`:
+
+```json
+{ "source": "sdd", "project": "my-project", "run": "2026-10-14-feature", "model": "sonnet", "attempted": 9, "first_pass": 6, "fix_rounds": 4, "patterns_delivered": ["pt_fail-closed"] }
+```
+
+## Settings
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `KB_MISTAKES_HOME` | `~/.knowledge-base/mistakes` | Folder for the ledger files |
+| `KB_API_KEY_SWARM` | none | API key the swarm uses to write records |
+| `KB_PATTERN_MODEL` | `claude-sonnet-5-5` | Model used by `kb patterns draft` |
+
+## Who can write to the ledger
+
+- The HTTP routes (`/api/v1/mistakes`, `/patterns/for`, `/runs`, `/mistakes/metrics`) accept the swarm key only. That key opens nothing else: not search, not documents, not the MCP endpoint.
+- A record sent over HTTP is always stored as a swarm record and cannot supersede another. Corrections are made locally, with `kb mistakes record` or the local MCP tool.
+- Secrets are removed from every kept field before a record is written: keys and tokens by their prefix, bearer headers, `name = value` pairs whose name says secret, passwords inside URLs, and private-key blocks.
+- The approval page gives each pattern a number for good. A number is never reused, and a reply is refused when the pattern changed after the page was made.