Extract lessons candidates from trace artifacts

.github/workflows/release.yml

@@ -39,7 +39,10 @@ jobs:
         run: |
           set -eu
           out="rs/target/${{ matrix.target }}/release"
-          "$out/bean-check" --help >/dev/null
+          # all five runtime binaries must be present and runnable
+          for b in bean-check bean-verify bean-run bean-hook bean-lessons; do
+            "$out/$b" --help >/dev/null
+          done
           "$out/bean-check" --dir test/fixtures/converged --no-state >/dev/null   # exit 0 ready
           if "$out/bean-check" --dir test/fixtures/open-risk --no-state; then
             echo "expected blocked exit"; exit 1
@@ -51,7 +54,7 @@ jobs:
           dir="bean-${GITHUB_REF_NAME}-${{ matrix.target }}"
           out="rs/target/${{ matrix.target }}/release"
           mkdir -p "$dir"
-          cp "$out"/bean-check "$out"/bean-verify "$out"/bean-run "$out"/bean-hook "$dir"/
+          cp "$out"/bean-check "$out"/bean-verify "$out"/bean-run "$out"/bean-hook "$out"/bean-lessons "$dir"/
           cp README.md LICENSE "$dir"/ 2>/dev/null || true
           tar -czf "$dir.tar.gz" "$dir"
           shasum -a 256 "$dir.tar.gz" > "$dir.tar.gz.sha256"

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+- **`bean-lessons` — trace analyzer (read-only, deterministic).** Reads the `.bean/runs/*.json`
+  trace corpus and writes a ranked lessons-candidates report to `.bean/lessons.json` (+ optional
+  `--markdown`). Five candidate kinds: `recurring_residual`, `high_pivot`, `budget_exceeded`,
+  `blocker_code_frequency`, `verifier_failure`. No LLM, no network. Read-only with respect to
+  claims, prompts, skills, and memory — it **proposes, never applies** (this is NOT cross-task
+  learning). Exit codes: `0` candidates found, `2` none/empty corpus (report still written), `3`
+  invalid corpus or write failure (fail closed). Schema: `schemas/lessons.schema.json`; docs:
+  `skills/bean/references/lessons.md`; fixtures: `test/fixtures/traces/`; built + shipped by
+  `install.sh` and the release tarballs.
+
 - **Trace artifact v0 (emit-only).** Every `bean-run` now writes a stable post-run record to
   `.bean/runs/<run_id>.json`: `schema_version`, `run_id`, `goal`, `started_at`/`ended_at`,
   `status`, `certificate`, `rounds`, `pivot_count`, `blockers_opened`/`blockers_closed`,

README.md

@@ -52,7 +52,7 @@ git clone https://github.com/grainulation/bean.git
 cd bean && ./install.sh
 ```
 
-This builds the runtime (`bean-check`, `bean-verify`, `bean-run`, `bean-hook`), installs the `/bean` skill, and registers the native Stop hook for Claude Code and Codex.
+This builds the runtime (`bean-check`, `bean-verify`, `bean-run`, `bean-hook`, `bean-lessons`), installs the `/bean` skill, and registers the native Stop hook for Claude Code and Codex.
 
 **Prebuilt binaries** (no Rust): download the tarball for your platform from the [latest release](https://github.com/grainulation/bean/releases) and put the binaries on your `PATH`.
 
@@ -79,14 +79,15 @@ bean also triggers on "do this thoroughly", "be systematic", or when a task obje
 | **5. Revise beliefs** | Supersede claims that new evidence overturns; resolve conflicts.                     |
 | **6. Converged?**     | No unresolved conflicts + evidence bar (or oracle) met + a dry round → deliver.      |
 
-## The runtime (four binaries)
+## The runtime (five binaries)
 
 A single self-contained binary per tool — no install dependency. (The JS `bean-check` is kept as the conformance reference; the Rust runtime must match it byte-for-byte, including certificates.)
 
 - **`bean-check`** — the compiler/gate. Reads `.bean/claims.json` (+ optional `run.json`) and exits nonzero until the loop converges: conflicts, undischarged risks, below-bar load-bearing claims, dry-round, budget — plus the 2.0 oracle gate. Emits a deterministic certificate.
 - **`bean-verify`** — the only path that runs an oracle: a declared command (argv, no shell, claim JSON on stdin); records a scrubbed verdict `bean-check` adjudicates.
-- **`bean-run`** — the driver: injects the compiler signal into the agent's prompt each round, records what it emits, enforces forward progress. Model-agnostic (`--agent "claude -p"` / `"codex exec -"`).
+- **`bean-run`** — the driver: injects the compiler signal into the agent's prompt each round, records what it emits, enforces forward progress, and writes a per-run trace artifact (`.bean/runs/<run_id>.json`). Model-agnostic (`--agent "claude -p"` / `"codex exec -"`).
 - **`bean-hook`** — the native Stop hook for Claude Code and Codex: blocks the agent from finishing until the loop converges; inert when a project has no `.bean/` ledger.
+- **`bean-lessons`** — read-only trace analyzer: reads `.bean/runs/*.json` and writes a ranked lessons-candidates report (`.bean/lessons.json`). Deterministic; proposes, never applies.
 
 The 2.0 oracle gate is opt-in via `run.json` → `verification.mode`: `compat` (default, == 1.x), `advisory` (warn), `strict` (require a passing oracle or a named residual). See [`skills/bean/references/oracle-gate.md`](skills/bean/references/oracle-gate.md).
 

install.sh

@@ -3,7 +3,7 @@
 # bean installer — builds the Rust runtime and wires it into Claude Code (and Codex).
 #
 # What you get after this:
-#   - the bean runtime binaries (bean-check, bean-verify, bean-run, bean-hook) built into ./bin
+#   - the bean runtime binaries (bean-check, bean-verify, bean-run, bean-hook, bean-lessons) built into ./bin
 #   - the /bean skill installed
 #   - a native Stop hook registered so bean COUPLES to execution: an agent can't finish a
 #     bean-tracked task (one with a .bean/ ledger) until the loop converges. Inert otherwise.
@@ -28,10 +28,10 @@ build_runtime() {
 	echo "  building the Rust runtime (release)..."
 	cargo build --release --quiet --manifest-path "$REPO_DIR/rs/Cargo.toml"
 	mkdir -p "$REPO_DIR/bin"
-	for b in bean-check bean-verify bean-run bean-hook; do
+	for b in bean-check bean-verify bean-run bean-hook bean-lessons; do
 		cp "$REPO_DIR/rs/target/release/$b" "$REPO_DIR/bin/$b"
 	done
-	echo "  binaries -> $REPO_DIR/bin (bean-check, bean-verify, bean-run, bean-hook)"
+	echo "  binaries -> $REPO_DIR/bin (bean-check, bean-verify, bean-run, bean-hook, bean-lessons)"
 }
 
 install_claude() {