@mmerterden/multi-agent-pipeline 12.4.0 → 12.5.0

package/CHANGELOG.md

@@ -14,6 +14,45 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ---
 
+## [12.5.0] - 2026-07-24
+
+Repo learning loop: repeated runs on the same repo produce better and cheaper
+output over time. Plus a round of worktree hardening.
+
+### Added
+
+- **Freshness gate** for the triage corpus: `triage-memory` stamps each stored
+  row with the file's git `file_sha`, and queries annotate `stale=true` when
+  the file changed since the lesson was recorded, so dead lessons stop
+  resurfacing in later runs.
+- **Causal diagnosis** on lessons: `learnings-ledger` rows carry an optional
+  `diagnosis` (the verbal root-cause "why", per Reflexion), and Phase 4's
+  lesson-memory loop now records it. `brief` renders it as `(why: ...)` so the
+  reason, not just the outcome, re-enters Phase 1 on the next run.
+- **`learning-curve.mjs`** (+ smoke): a time-bucketed trend over
+  `metrics.jsonl` (first-pass clean rate, review cycles, rework per task,
+  tokens per task, cache ratio) that shows whether a repo's runs are improving.
+- **`prompt-assembly.md`**: stable-prefix prompt-cache guidance, referenced
+  from `phases.md`, so lazy-loaded phase docs stay cache-friendly.
+
+### Changed
+
+- Worktree handling hardened: `.worktrees/` is now a first-class member of the
+  traversal-prune skip set (`node_modules`, `Pods`, `.build`, `DerivedData`,
+  `.next`) across every tree walker (`repo-map`, `repo-cache`,
+  `extract-conventions`, `shadow-git`), so no walker descends into a worktree
+  checkout. Phase 0 gains an explicit residue-guard + traversal-prune contract;
+  Phase 5 heals stale worktree admin state before recreating a worktree.
+- `eval-mine-corpus` now reads the corpus from the per-repo memory dir it is
+  actually written to (was a path that never received data).
+- Phase-doc total token budget recalibrated 50000 -> 51000 for the new
+  contracts (prose compressed first; every per-phase max still passes).
+
+### Fixed
+
+- `gc-worktrees.sh` anchors the repo on the main worktree and resolves paths on
+  both sides, so orphan detection no longer misfires from inside a worktree.
+
 ## [12.4.0] - 2026-07-23
 
 User-defined routines: manage your own recurring, project-specific jobs as

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "12.4.0",
+  "version": "12.5.0",
   "description": "8-phase AI development pipeline with full orchestration on Claude Code and Copilot CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",

package/pipeline/lib/extract-conventions.sh

@@ -63,6 +63,7 @@ budget_exhausted() {
 
 # ---- skip dirs ----------------------------------------------------------------
 SKIP_PRUNE_ARGS=(
+  -path '*/.worktrees' -prune -o
   -path '*/.build' -prune -o
   -path '*/DerivedData' -prune -o
   -path '*/Pods' -prune -o

package/pipeline/lib/repo-cache.sh

@@ -212,6 +212,7 @@ print(json.dumps(out))
       find "$root" -maxdepth "$MAXDEPTH" -type d -name ".git" \
         \( -path "*/node_modules/*" -prune -o -path "*/.build/*" -prune -o \
            -path "*/DerivedData/*" -prune -o -path "*/Pods/*" -prune -o \
+           -path "*/.worktrees/*" -prune -o \
            -path "*/.next/*" -prune -o -print \) 2>/dev/null \
         | while read -r gitdir; do
             [ -n "$gitdir" ] || continue

package/pipeline/lib/shadow-git.sh

@@ -110,6 +110,13 @@ do_init() {
   if [ -f "$project_root/.gitignore" ]; then
     cat "$project_root/.gitignore" >> "$sd/.git/info/exclude"
   fi
+  # `.worktrees/` is forced-excluded too: worktrees live INSIDE the repo at
+  # <repo>/.worktrees/<id>/ and each carries a `.git` gitlink, so a blanket
+  # `add -A` would record every worktree as a "Subproject commit" and churn a
+  # fresh gitlink into every per-tool-call snapshot. The real clone keeps this
+  # out of its own index via .git/info/exclude; the shadow repo has its own
+  # exclude file and must repeat the rule. This mirrors the traversal-prune
+  # contract in phase-0-init.md (never descend into .worktrees on a tree walk).
   cat >> "$sd/.git/info/exclude" <<EOF
 node_modules/
 Pods/
@@ -119,6 +126,7 @@ DerivedData/
 .gradle/
 __pycache__/
 .venv/
+.worktrees/
 *.log
 EOF
   # Initial author setup  -  keep separate from user's global git identity to

package/pipeline/multi-agent-refs/phases/phase-0-init.md

@@ -450,7 +450,7 @@ fi
 
 If the path is still registered and healthy after the heal, enter + pull instead of re-adding (existing behavior). Only when `worktree add` still fails after the heal do the rollback / collision flow in the multi-repo block below.
 
-**Worktree residue guard (required once per repo, idempotent):** every worktree dir contains a `.git` file, so a blanket `git add -A` / `git add .` in the parent tree records `.worktrees/{id}` as a gitlink ("Subproject commit ...") that pollutes the branch and later needs a manual removal commit. Keep `.worktrees/` out of the index via the clone-local exclude file (never committed, so no PR noise in shared repos):
+**Worktree residue guard (required once per repo, idempotent):** every worktree dir holds a `.git` file, so a blanket `git add -A` in the parent tree records `.worktrees/{id}` as a gitlink that pollutes the branch. Keep `.worktrees/` out of the index via the clone-local exclude file (never committed, so no PR noise):
 
 ```bash
 ex="$(git -C "$PROJECT_ROOT" rev-parse --path-format=absolute --git-common-dir)/info/exclude"
@@ -458,6 +458,14 @@ mkdir -p "$(dirname "$ex")"
 grep -qxF '.worktrees/' "$ex" 2>/dev/null || printf '.worktrees/\n' >> "$ex"
 ```
 
+**Traversal-prune contract:** the exclude guard covers only the git INDEX, not
+filesystem scans. Since each worktree is a full checkout, an unpruned tree walk
+double-processes every file and can re-stage gitlinks. So `.worktrees` joins the
+skip set (`node_modules`, `Pods`, `.build`, `DerivedData`, `.next`): every
+`find`, walker, or `git add -A` MUST prune it. Already applied in the Step 2
+scan, `shadow-git.sh` excludes, and the shared walkers (`extract-conventions.sh`,
+`repo-cache.sh`, `repo-map.mjs`); add it to any new tree walk too.
+
 **v2.1.0+ Multi-Repo Worktree Setup**:
 
 When `state.projects[].length > 1`, repeat steps 2-4 **serially per repo** (worktrees are cheap; serial keeps git index sane and surfaces collisions one at a time):

package/pipeline/multi-agent-refs/phases/phase-4-review.md

@@ -414,11 +414,12 @@ At the end of every fix/rework round (each Phase 3 re-entry that resolved accept
 
 ```bash
 node pipeline/scripts/learnings-ledger.mjs add --kind fact \
-  --statement "<one-line root cause: what class of mistake produced the finding and why (<=140 chars)>" \
+  --statement "<one-line rule/what-to-do so this class of finding does not recur (<=140 chars)>" \
+  --diagnosis "<the causal WHY the failure happened, one line>" \
   --scope "<file-or-area glob from the finding>" --task "$TASK_ID"
 ```
 
-Statement shape: root cause, not symptom  -  "force-unwrapped optional in async callback path", not "fixed crash in LoginView". Dedup built in (exit 2 = already stored, skip). Lessons re-enter Phase 1 + triage via `learnings-ledger.mjs brief`.
+Statement shape: the durable rule/root cause, not the symptom  -  "force-unwrapped optional in async callback path", not "fixed crash in LoginView". Always pass `--diagnosis` with the causal why (Reflexion: the verbal reason prevents recurrence; a bare outcome does not). Dedup built in (exit 2 = already stored). Lessons re-enter Phase 1 + triage via `learnings-ledger.mjs brief` (renders diagnosis as "(why: ...)").
 
 Progress line: `    → writing lesson to learnings ledger ({N} entries)`
 

package/pipeline/multi-agent-refs/phases/phase-5-test.md

@@ -103,6 +103,16 @@ Tier 1 / Tier 2 records print `screenshotUrl` from the captured evidence (Tier 2
    The waiting state persists in `tracker-state.json` across the handoff; `/multi-agent:finish` and `/multi-agent:manual-test` CONTINUE this state file and never re-init it (`$HOME/.claude/multi-agent-refs/tracker-contract.md` "Continuation runs").
 6. If fix needed:
    - Branch already has WIP commit (from step 2)  -  changes are safe
+   - **Heal stale admin state first** (same contract as Phase 0  -  step 3's
+     `worktree remove` or an interrupted run can leave a stale entry, so a bare
+     re-add fails with `already exists`/`already registered`):
+     ```bash
+     git -C "$PROJECT_ROOT" worktree prune 2>/dev/null || true
+     if git -C "$PROJECT_ROOT" worktree list --porcelain | grep -qF "{worktree-path}"; then
+       git -C "$PROJECT_ROOT" worktree unlock "{worktree-path}" 2>/dev/null || true
+     fi
+     ```
+     Phase 0's `.worktrees/` residue guard is already in `.git/info/exclude`  -  no re-add.
    - Recreate worktree from branch: `git -C $PROJECT_ROOT worktree add {worktree-path} {branch}`
    - Re-set git identity: `git -C {worktree-path} config user.name/email` (from state)
    - Go back to Phase 3

package/pipeline/multi-agent-refs/phases.md

@@ -149,6 +149,8 @@ Each phase doc is lazy-loaded  -  only the current phase's spec is in context. B
 
 Token estimate: `ceil(chars / 4)`. Budget covers phase-\*.md files only. Guides, rules, and agents are loaded separately on demand.
 
+**Prompt caching (token learning-curve):** assemble each phase prompt as a stable, cacheable prefix (phase instructions + repo learnings brief + conventions + repo evidence) followed by the volatile task suffix, so repeated runs on a known repo pay cache-read price on the prefix. Full contract: `$HOME/.claude/multi-agent-refs/prompt-assembly.md`. The effect (rising cache ratio, falling tokens/task) is what `learning-curve.mjs` trends.
+
 ## SubPhase Convention
 
 When a specialized skill takes over a main pipeline phase, progress is reported as **SubPhases** nested under the parent. Top-level stays 8 phases (0-7); specialized flows get sub-phase detail.

package/pipeline/multi-agent-refs/prompt-assembly.md

@@ -0,0 +1,31 @@
+# Prompt assembly: stable-prefix caching (token learning-curve)
+
+Anthropic prompt caching is **prefix-based**: the longest unchanged leading span of a request is served from cache at a large discount on repeated calls. As the pipeline accumulates durable knowledge about a repo (conventions, learnings brief, repo evidence), that knowledge should become a near-free cached prefix instead of a growing per-run token cost. This is the mechanism that makes "knowing the repo better" literally cheaper each run.
+
+## The rule
+
+Assemble every phase prompt as two spans, in this order:
+
+1. **Stable prefix (cacheable, repo-stable, changes rarely):**
+   - system / role instructions for the phase
+   - the repo learnings brief (`learnings-ledger.mjs brief`)
+   - extracted conventions (Phase 1c) and the design/analysis doc when applicable
+   - repo structural evidence (the reuse-first buckets, Code Connect index)
+2. **Volatile suffix (task-specific, changes every run):**
+   - the specific task / issue / diff
+   - the current file(s) under edit
+   - per-run state and the immediate instruction
+
+Put the stable material FIRST and the volatile material LAST. Reordering volatile content into the middle of the prefix invalidates the cache for everything after it, so keep the boundary clean.
+
+## Why it matters
+
+- Repeated runs on the same repo pay roughly cache-read price (~10% of input) on the stable prefix instead of full price - the dominant per-run token cost once a repo is "known."
+- It turns accumulated learnings from a cost into an asset: more durable knowledge => bigger cached prefix => lower marginal cost, not higher.
+- The effect is visible in `metrics.jsonl` `tokens_cached` / `cache_ratio` and is exactly what `learning-curve.mjs` trends over time (rising cache ratio + falling tokens/task = the learning curve working).
+
+## Anti-patterns
+
+- Interleaving the task text with conventions/learnings (breaks the prefix).
+- Letting the stable prefix bloat past what the phase needs (context rot; cache a lean prefix, not everything - see the corpus merge/drop + progressive-disclosure discipline).
+- Regenerating repo evidence from scratch each run instead of reusing cached/learned artifacts (defeats both the cache and the learning curve).

package/pipeline/schemas/learnings-ledger.schema.json

@@ -34,6 +34,10 @@
       "type": "string",
       "enum": ["low", "medium", "high"],
       "description": "How strongly to weight the entry when replaying it."
+    },
+    "diagnosis": {
+      "type": "string",
+      "description": "Optional causal 'why' behind the lesson (Reflexion): the root-cause reasoning that turns a detected failure into a prevented one. Rendered in the brief as '(why: ...)'. Absent for plain facts/conventions."
     }
   }
 }

package/pipeline/schemas/token-budget.json

@@ -12,6 +12,6 @@
     "phase-6-commit":    { "max_tokens": 6150, "warn_tokens": 5400 },
     "phase-7-report":    { "max_tokens": 5600, "warn_tokens": 4950 }
   },
-  "total_max_tokens": 50000,
-  "note": "Token estimate = ceil(chars / 4). Per-phase budget rule: warn = current+10% (rounded to nearest 50), max = current+25%. Gives ~6 edit cycles of headroom before warn trips  -  intentionally quiet under normal maintenance, loud when a phase grows unusually. Only the active phase is loaded (lazy). Recalibrated at v10.0.0 after the validator/consistency/simplifier/lesson gate contracts landed in phases 1-4. Recalibrated again at v10.9.0 after the verify-by-test (Phase 4 Step 3.7), update-check (Phase 0 Step 0.6), immutable-test (Phase 3 GREEN) and redTests re-entry contracts landed  -  Step 3.7 prose was compressed to a pointer into refs/features/verify-by-test.md before the recalibration."
+  "total_max_tokens": 51000,
+  "note": "Token estimate = ceil(chars / 4). Per-phase budget rule: warn = current+10% (rounded to nearest 50), max = current+25%. Gives ~6 edit cycles of headroom before warn trips  -  intentionally quiet under normal maintenance, loud when a phase grows unusually. Only the active phase is loaded (lazy). Recalibrated at v10.0.0 after the validator/consistency/simplifier/lesson gate contracts landed in phases 1-4. Recalibrated again at v10.9.0 after the verify-by-test (Phase 4 Step 3.7), update-check (Phase 0 Step 0.6), immutable-test (Phase 3 GREEN) and redTests re-entry contracts landed  -  Step 3.7 prose was compressed to a pointer into refs/features/verify-by-test.md before the recalibration. Total bumped 50000 -> 51000 at v12.5.0 after the worktree residue/traversal-prune contract (Phase 0 + Phase 5 heal) and the Reflexion causal-diagnosis contract (Phase 4 lesson memory) landed; the prose was compressed first (161 tokens reclaimed) and every per-phase max still passes  -  only the aggregate needed room."
 }

package/pipeline/schemas/triage-corpus.schema.json

@@ -26,6 +26,10 @@
     "issue": { "type": "string", "minLength": 1 },
     "fix":  { "type": ["string", "null"] },
     "reason": { "type": ["string", "null"] },
-    "reviewer": { "type": ["string", "null"] }
+    "reviewer": { "type": ["string", "null"] },
+    "file_sha": {
+      "type": ["string", "null"],
+      "description": "git blob SHA (git hash-object) of `file` at ingest time. On query, a differing current hash flags the hit stale (freshness gate). Null when not computable (file gone / not a git repo)."
+    }
   }
 }

package/pipeline/scripts/eval-mine-corpus.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 // eval-mine-corpus.mjs  -  grow the triage eval set from real production runs.
 //
-// The pipeline already records every Phase 4 triage decision to
-// `~/.claude/logs/multi-agent/triage-corpus.jsonl` (one line per finding:
+// The pipeline already records every Phase 4 triage decision to the per-repo
+// `~/.claude/memory/multi-agent/<repo-slug>/triage-corpus.jsonl` (one line per finding:
 // severity/file/line/issue/fix/reviewer + the classification the run gave it,
 // plus an optional human `reason`/`reviewer`). Hand-authoring eval fixtures is
 // the bottleneck; this closes the loop by turning those real decisions into
@@ -38,19 +38,33 @@ const candidatesDir = join(root, "pipeline", "eval", "triage-candidates");
 const validator = join(root, "pipeline", "scripts", "validate-triage.mjs");
 
 const args = process.argv.slice(2);
-const opts = { corpus: null, limit: Infinity, dryRun: false };
+const opts = { corpus: null, limit: Infinity, dryRun: false, repoSlug: null };
 for (let i = 0; i < args.length; i++) {
   if (args[i] === "--corpus") opts.corpus = args[++i];
+  else if (args[i] === "--repo-slug") opts.repoSlug = args[++i];
   else if (args[i] === "--limit") opts.limit = Number(args[++i]) || Infinity;
   else if (args[i] === "--dry-run") opts.dryRun = true;
   else if (args[i] === "-h" || args[i] === "--help") {
-    console.log("Usage: eval-mine-corpus.mjs [--corpus <path>] [--limit N] [--dry-run]");
+    console.log("Usage: eval-mine-corpus.mjs [--corpus <path>] [--repo-slug <slug>] [--limit N] [--dry-run]");
     process.exit(0);
   }
 }
 
+// Resolve the corpus path the SAME way triage-memory.mjs writes it:
+// ~/.claude/memory/multi-agent/<repo-slug>/triage-corpus.jsonl (per repo).
+// (The old default read ~/.claude/logs/.../triage-corpus.jsonl - a flat path
+// nothing writes to - so without --corpus it always found nothing.)
+function resolveRepoSlug() {
+  if (opts.repoSlug) return String(opts.repoSlug);
+  if (process.env.MULTI_AGENT_REPO_SLUG) return process.env.MULTI_AGENT_REPO_SLUG;
+  const r = spawnSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf-8" });
+  if (r.status === 0 && r.stdout.trim()) return r.stdout.trim().split("/").pop();
+  return "default";
+}
+
 const corpusPath =
-  opts.corpus || join(homedir(), ".claude", "logs", "multi-agent", "triage-corpus.jsonl");
+  opts.corpus ||
+  join(homedir(), ".claude", "memory", "multi-agent", resolveRepoSlug(), "triage-corpus.jsonl");
 
 if (!existsSync(corpusPath)) {
   console.log(`eval-mine-corpus: no corpus at ${corpusPath} - nothing to mine.`);

package/pipeline/scripts/fixtures/install-layout.tsv

@@ -4,10 +4,10 @@
 .claude/commands	47
 .claude/lib	27
 .claude/multi-agent-preferences.json	1
-.claude/multi-agent-refs	51
+.claude/multi-agent-refs	52
 .claude/rules	12
 .claude/schemas	24
-.claude/scripts	197
+.claude/scripts	199
 .claude/settings.json	1
 .claude/skills	428
 .copilot/.pipeline-version	1
@@ -15,5 +15,5 @@
 .copilot/copilot-instructions.md	1
 .copilot/lib	27
 .copilot/schemas	24
-.copilot/scripts	197
+.copilot/scripts	199
 .copilot/skills	470

package/pipeline/scripts/gc-worktrees.sh

@@ -64,6 +64,13 @@ if ! git -C "$REPO" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
   exit 0
 fi
 REPO="$(cd "$REPO" && pwd -P)"
+# Anchor on the MAIN worktree (first porcelain entry) so a run started from a
+# subdirectory OR from inside a linked worktree still targets
+# <main-repo>/.worktrees/ rather than a bogus <subdir>/.worktrees/ (which
+# silently found nothing and left residue behind).
+MAIN_WT="$(git -C "$REPO" worktree list --porcelain 2>/dev/null | sed -n 's/^worktree //p' | head -1)"
+MAIN_WT="$(cd "$MAIN_WT" 2>/dev/null && pwd -P)" || MAIN_WT=""
+[ -n "$MAIN_WT" ] && REPO="$MAIN_WT"
 WT_ROOT="$REPO/.worktrees"
 
 changed=0
@@ -76,9 +83,24 @@ pruned=$(git -C "$REPO" worktree prune -v 2>&1 | grep -c . || true)
 # 2. Orphan dirs: present under .worktrees/ but not registered as worktrees.
 orphans=()
 if [ -d "$WT_ROOT" ]; then
-  registered=$(git -C "$REPO" worktree list --porcelain 2>/dev/null | sed -n 's/^worktree //p')
+  # Resolve every registered worktree path to its physical form so the
+  # orphan test below compares like-for-like against `pwd -P`-resolved dirs.
+  # A raw (unresolved) registered path with a symlinked component would fail
+  # the match and get a HEALTHY worktree misclassified as an orphan and
+  # deleted under --yes; resolving both sides removes that risk (this mirrors
+  # purge.sh, which resolves both sides).
+  registered=""
+  while IFS= read -r regpath; do
+    [ -n "$regpath" ] || continue
+    regphys="$(cd "$regpath" 2>/dev/null && pwd -P)" || regphys=""
+    [ -n "$regphys" ] && registered="$registered$regphys
+"
+  done <<EOF
+$(git -C "$REPO" worktree list --porcelain 2>/dev/null | sed -n 's/^worktree //p')
+EOF
   for d in "$WT_ROOT"/*/; do
     [ -d "$d" ] || continue
+    [ -L "${d%/}" ] && continue  # never follow a symlinked entry out of the tree
     dir="$(cd "$d" && pwd -P)"
     # Path guard: only ever consider dirs strictly inside <repo>/.worktrees/.
     case "$dir" in "$WT_ROOT"/*) ;; *) continue ;; esac

package/pipeline/scripts/learning-curve.mjs

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+// learning-curve.mjs  -  time-bucketed TREND over metrics.jsonl.
+//
+// aggregate-metrics.mjs reports lifetime totals; this reports the CURVE: how
+// the pipeline's per-task quality/cost move over time as it accumulates
+// learnings on a repo. Without a trend you cannot tell whether "it gets better
+// over time" is real - this is the measurement layer for the learning loop.
+//
+// Buckets tasks by the timestamp of their first event, then per bucket reports:
+//   tasks, first-pass-clean rate, avg review cycles, rework/task,
+//   tokens/task, cache-reuse ratio. Prints a first->last trend for the
+//   headline KPIs. Read-only, zero deps, no API/model calls.
+//
+// Usage:
+//   learning-curve.mjs [--bucket=<days>] [--since=ISO] [--json|--markdown]
+// Env: METRICS_FILE overrides the default ~/.claude/logs/multi-agent/metrics.jsonl
+//
+// Exit: 0 always (advisory; empty/missing metrics -> friendly note).
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const args = process.argv.slice(2);
+const opts = { json: false, markdown: false, since: null, bucketDays: 7 };
+for (const a of args) {
+  if (a === "--json") opts.json = true;
+  else if (a === "--markdown" || a === "--md") opts.markdown = true;
+  else if (a.startsWith("--since=")) opts.since = a.slice(8);
+  else if (a.startsWith("--bucket=")) opts.bucketDays = Math.max(1, parseInt(a.slice(9), 10) || 7);
+  else if (a === "--help" || a === "-h") {
+    console.log("Usage: learning-curve.mjs [--bucket=<days>] [--since=ISO] [--json|--markdown]");
+    process.exit(0);
+  }
+}
+
+const METRICS_FILE =
+  process.env.METRICS_FILE || join(homedir(), ".claude", "logs", "multi-agent", "metrics.jsonl");
+
+function emitEmpty(reason) {
+  if (opts.json) console.log(JSON.stringify({ ok: false, reason, buckets: [] }));
+  else console.error(`learning-curve: ${reason}`);
+  process.exit(0);
+}
+
+if (!existsSync(METRICS_FILE)) emitEmpty(`no metrics file at ${METRICS_FILE}`);
+
+const events = [];
+for (const line of readFileSync(METRICS_FILE, "utf-8").split("\n")) {
+  if (!line.trim()) continue;
+  try {
+    const e = JSON.parse(line);
+    if (opts.since && e.ts && e.ts < opts.since) continue;
+    events.push(e);
+  } catch {
+    /* skip corrupted line */
+  }
+}
+if (events.length === 0) emitEmpty("no metrics events in range");
+
+// Fold events into per-task aggregates.
+const num = (v) => (typeof v === "number" ? v : Number(v)) || 0;
+const tasks = new Map();
+for (const e of events) {
+  const id = e.task_id;
+  if (!id) continue;
+  let t = tasks.get(id);
+  if (!t) {
+    t = { firstTs: e.ts, reviewCycles: null, rework: 0, tokensIn: 0, tokensOut: 0, tokensCached: 0 };
+    tasks.set(id, t);
+  }
+  if (e.ts && (!t.firstTs || e.ts < t.firstTs)) t.firstTs = e.ts;
+  const d = e.details || {};
+  if (e.event === "review.completed" && d.review_cycles != null) t.reviewCycles = num(d.review_cycles);
+  if (e.event === "rework.started") t.rework += 1;
+  t.tokensIn += num(d.tokens_in);
+  t.tokensOut += num(d.tokens_out);
+  t.tokensCached += num(d.tokens_cached);
+}
+
+// Bucket tasks by first-seen day / bucketDays window (UTC).
+const DAY = 86400000;
+const bucketOf = (ts) => {
+  const ms = Date.parse(ts);
+  if (Number.isNaN(ms)) return null;
+  const dayIndex = Math.floor(ms / DAY);
+  const b = Math.floor(dayIndex / opts.bucketDays) * opts.bucketDays;
+  return new Date(b * DAY).toISOString().slice(0, 10);
+};
+
+const byBucket = new Map();
+for (const t of tasks.values()) {
+  const key = bucketOf(t.firstTs);
+  if (!key) continue;
+  if (!byBucket.has(key)) byBucket.set(key, []);
+  byBucket.get(key).push(t);
+}
+
+const round = (n, p = 2) => Math.round(n * 10 ** p) / 10 ** p;
+const buckets = [...byBucket.keys()].sort().map((start) => {
+  const list = byBucket.get(start);
+  const n = list.length;
+  const withReview = list.filter((t) => t.reviewCycles != null);
+  const firstPassClean = withReview.filter((t) => t.reviewCycles <= 1).length;
+  const totIn = list.reduce((s, t) => s + t.tokensIn, 0);
+  const totOut = list.reduce((s, t) => s + t.tokensOut, 0);
+  const totCached = list.reduce((s, t) => s + t.tokensCached, 0);
+  return {
+    bucketStart: start,
+    tasks: n,
+    firstPassCleanRate: withReview.length ? round(firstPassClean / withReview.length) : null,
+    avgReviewCycles: withReview.length
+      ? round(withReview.reduce((s, t) => s + t.reviewCycles, 0) / withReview.length)
+      : null,
+    reworkPerTask: round(list.reduce((s, t) => s + t.rework, 0) / n),
+    tokensPerTask: Math.round((totIn + totOut) / n),
+    cacheRatio: totIn ? round(totCached / totIn) : null,
+  };
+});
+
+// first->last trend for the headline KPIs (only when >=2 buckets).
+let trend = null;
+if (buckets.length >= 2) {
+  const a = buckets[0];
+  const z = buckets[buckets.length - 1];
+  const delta = (x, y) => (x == null || y == null ? null : round(y - x));
+  trend = {
+    from: a.bucketStart,
+    to: z.bucketStart,
+    firstPassCleanRate: delta(a.firstPassCleanRate, z.firstPassCleanRate),
+    avgReviewCycles: delta(a.avgReviewCycles, z.avgReviewCycles),
+    tokensPerTask: a.tokensPerTask && z.tokensPerTask ? z.tokensPerTask - a.tokensPerTask : null,
+    cacheRatio: delta(a.cacheRatio, z.cacheRatio),
+  };
+}
+
+const out = { ok: true, bucketDays: opts.bucketDays, buckets, trend };
+
+if (opts.json) {
+  console.log(JSON.stringify(out, null, 2));
+  process.exit(0);
+}
+
+// Markdown / text (default)
+const arrow = (v, goodIsUp) => {
+  if (v == null || v === 0) return "-";
+  const up = v > 0;
+  const good = up === goodIsUp;
+  return `${up ? "+" : ""}${v} ${good ? "(better)" : "(worse)"}`;
+};
+console.log(`# Learning curve (${opts.bucketDays}-day buckets)\n`);
+console.log("| Bucket | Tasks | First-pass clean | Avg review cycles | Rework/task | Tokens/task | Cache ratio |");
+console.log("|---|---|---|---|---|---|---|");
+for (const b of buckets) {
+  console.log(
+    `| ${b.bucketStart} | ${b.tasks} | ${b.firstPassCleanRate ?? "-"} | ${b.avgReviewCycles ?? "-"} | ${b.reworkPerTask} | ${b.tokensPerTask} | ${b.cacheRatio ?? "-"} |`,
+  );
+}
+if (trend) {
+  console.log(`\n**Trend ${trend.from} -> ${trend.to}:**`);
+  console.log(`- First-pass clean: ${arrow(trend.firstPassCleanRate, true)}`);
+  console.log(`- Avg review cycles: ${arrow(trend.avgReviewCycles, false)}`);
+  console.log(`- Tokens/task: ${arrow(trend.tokensPerTask, false)}`);
+  console.log(`- Cache ratio: ${arrow(trend.cacheRatio, true)}`);
+} else {
+  console.log("\n(need >= 2 buckets for a trend; keep running the pipeline)");
+}

package/pipeline/scripts/learnings-ledger.mjs

@@ -120,7 +120,7 @@ function writeRow(slug, row) {
 
 /** Append one entry unless an entry with the same kind + normalized statement
  *  already exists (idempotent). Returns true when written. */
-function addEntry(slug, { kind, statement, scope, task, confidence }, existing) {
+function addEntry(slug, { kind, statement, scope, task, confidence, diagnosis }, existing) {
   const stmt = String(statement || "").trim();
   if (!stmt) return false;
   const seenKey = `${kind}::${normStatement(stmt)}`;
@@ -135,6 +135,11 @@ function addEntry(slug, { kind, statement, scope, task, confidence }, existing)
     source_task: task || null,
     confidence: CONFIDENCES.has(confidence) ? confidence : "medium",
   };
+  // Optional causal diagnosis (Reflexion P5): the "why it failed" behind a
+  // lesson. Verbal diagnosis is what turns a detected error into a prevented
+  // one; a bare outcome does not. Stored only when supplied.
+  const diag = String(diagnosis || "").trim();
+  if (diag) row.diagnosis = diag;
   writeRow(slug, row);
   existing.add(seenKey);
   return true;
@@ -152,6 +157,7 @@ function cmdAdd() {
     scope: flags.scope && flags.scope !== true ? String(flags.scope) : "global",
     task: flags.task && flags.task !== true ? String(flags.task) : null,
     confidence: flags.confidence && flags.confidence !== true ? String(flags.confidence) : "medium",
+    diagnosis: flags.diagnosis && flags.diagnosis !== true ? String(flags.diagnosis) : null,
   }, existing);
   process.stdout.write(JSON.stringify({ ok: true, slug, added: wrote ? 1 : 0, deduped: wrote ? 0 : 1 }) + "\n");
   process.exit(wrote ? 0 : 2);
@@ -247,7 +253,8 @@ function cmdBrief() {
     lines.push("", `## ${labels[kind]}`);
     for (const r of items) {
       const scope = r.scope && r.scope !== "global" ? ` [${r.scope}]` : "";
-      lines.push(`- ${r.statement}${scope}`);
+      const why = r.diagnosis ? ` (why: ${r.diagnosis})` : "";
+      lines.push(`- ${r.statement}${scope}${why}`);
     }
   }
   lines.push("</repo-learnings>");

package/pipeline/scripts/repo-map.mjs

@@ -82,7 +82,7 @@ function parseArgs(argv) {
 // ---- File walking ----------------------------------------------------------
 
 const DEFAULT_IGNORE = new Set([
-  '.git', 'node_modules', 'Pods', '.build', 'DerivedData', '.next',
+  '.git', '.worktrees', 'node_modules', 'Pods', '.build', 'DerivedData', '.next',
   'dist', 'build', '__pycache__', '.venv', 'venv', '.cache',
   '.gradle', '.idea', '.vscode', 'target',
 ]);

package/pipeline/scripts/smoke-learning-curve.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# smoke-learning-curve.sh  -  contract for learning-curve.mjs (time-bucketed
+# trend over metrics.jsonl).
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+LC="$SCRIPT_DIR/learning-curve.mjs"
+
+PASS=0
+FAIL=0
+record_pass() { PASS=$((PASS + 1)); printf '  \342\234\223 %s\n' "$1"; }
+record_fail() { FAIL=$((FAIL + 1)); printf '  \342\234\227 %s\n' "$1"; }
+
+printf '\342\206\222 smoke-learning-curve: metrics trend contract\n'
+
+tmp=$(mktemp -d "${TMPDIR:-/tmp}/lc.XXXXXX")
+trap 'rm -rf "$tmp"' EXIT
+M="$tmp/metrics.jsonl"
+
+# Two early tasks (noisy: 3/2 review cycles, low cache) + two later tasks
+# (clean: 1 cycle, high cache) -> the curve should improve.
+cat > "$M" <<'EOF'
+{"ts":"2026-06-02T10:00:00Z","task_id":"t1","phase":"4","event":"review.completed","details":{"review_cycles":3,"tokens_in":100000,"tokens_out":8000,"tokens_cached":10000}}
+{"ts":"2026-06-02T10:05:00Z","task_id":"t1","phase":"3","event":"rework.started","details":{}}
+{"ts":"2026-06-03T09:00:00Z","task_id":"t2","phase":"4","event":"review.completed","details":{"review_cycles":2,"tokens_in":90000,"tokens_out":7000,"tokens_cached":20000}}
+{"ts":"2026-06-24T09:00:00Z","task_id":"t3","phase":"4","event":"review.completed","details":{"review_cycles":1,"tokens_in":40000,"tokens_out":4000,"tokens_cached":30000}}
+{"ts":"2026-06-25T09:00:00Z","task_id":"t4","phase":"4","event":"review.completed","details":{"review_cycles":1,"tokens_in":38000,"tokens_out":3500,"tokens_cached":32000}}
+EOF
+
+# 1. parses
+bash -n "$SCRIPT_DIR/smoke-learning-curve.sh" >/dev/null 2>&1 || true
+if node --check "$LC" 2>/dev/null; then record_pass "learning-curve.mjs parses"; else record_fail "syntax error"; fi
+
+# 2. JSON: buckets + improving trend
+out=$(METRICS_FILE="$M" node "$LC" --json 2>/dev/null)
+nbuckets=$(printf '%s' "$out" | python3 -c "import json,sys;print(len(json.load(sys.stdin)['buckets']))")
+[ "$nbuckets" -ge 2 ] && record_pass "produces >=2 time buckets" || record_fail "expected >=2 buckets, got $nbuckets"
+
+tokens_delta=$(printf '%s' "$out" | python3 -c "import json,sys;print(json.load(sys.stdin)['trend']['tokensPerTask'])")
+case "$tokens_delta" in
+  -*) record_pass "tokens/task trend is negative (improving)" ;;
+  *) record_fail "tokens/task trend should drop, got $tokens_delta" ;;
+esac
+cache_delta=$(printf '%s' "$out" | python3 -c "import json,sys;print(json.load(sys.stdin)['trend']['cacheRatio'])")
+case "$cache_delta" in
+  -*|0|0.0) record_fail "cache ratio should rise, got $cache_delta" ;;
+  *) record_pass "cache ratio trend rises (improving)" ;;
+esac
+
+# 3. markdown renders a table + trend
+md=$(METRICS_FILE="$M" node "$LC" 2>/dev/null)
+printf '%s' "$md" | grep -q "Learning curve" && record_pass "markdown has a header" || record_fail "no markdown header"
+printf '%s' "$md" | grep -q "Trend" && record_pass "markdown shows a trend block" || record_fail "no trend block"
+
+# 4. missing metrics -> graceful, exit 0
+METRICS_FILE="/nope/none.jsonl" node "$LC" --json >/dev/null 2>&1
+[ "$?" -eq 0 ] && record_pass "missing metrics is a graceful no-op (exit 0)" || record_fail "missing metrics should exit 0"
+
+printf '\n\342\225\220\342\225\220 smoke-learning-curve: %d passed, %d failed \342\225\220\342\225\220\n' "$PASS" "$FAIL"
+[ "$FAIL" -eq 0 ]

package/pipeline/scripts/triage-memory.mjs

@@ -84,6 +84,33 @@ function ensureDir(p) {
   mkdirSync(dirname(p), { recursive: true });
 }
 
+// Freshness gate (P1): stamp each finding with the git blob SHA of its file at
+// ingest time; on query, if the file's current content hash differs, the hit is
+// flagged stale so a reused finding is verified, not trusted blindly.
+function repoTop() {
+  try {
+    return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function fileSha(file, top) {
+  if (!file || !top) return null;
+  try {
+    return execFileSync("git", ["hash-object", "--", file], {
+      cwd: top,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
 const STOP = new Set([
   "the","a","an","and","or","but","of","in","on","at","to","for","with","by","is","are",
   "be","been","being","this","that","these","those","it","its","as","not","no","do","does",
@@ -157,6 +184,7 @@ function ingest() {
   catch (e) { die(`cannot parse triage JSON: ${e.message}`, 1); }
 
   const ts = new Date().toISOString();
+  const top = repoTop();
   const corpus = readCorpus(slug);
   const seen = new Set(corpus.map((r) => `${r.task_id}::${r.classification}::${r.file}::${r.issue}`));
 
@@ -188,6 +216,7 @@ function ingest() {
         fix: f.fix || null,
         reason: f._reason || null,
         reviewer: f.reviewer || null,
+        file_sha: fileSha(file, top),
       };
       writeRow(slug, row);
       seen.add(key);
@@ -212,21 +241,30 @@ function query() {
   const qTokens = tokenize(issueText);
   const fileRe = fileGlob ? globToRegExp(fileGlob) : null;
   const filtered = fileRe ? corpus.filter((r) => fileRe.test(r.file || "")) : corpus.slice();
+  const top = repoTop();
   const ranked = filtered
     .map((r) => ({ row: r, score: score(qTokens, r) }))
     .filter((x) => x.score > 0 || qTokens.size === 0)
     .sort((a, b) => b.score - a.score)
     .slice(0, topN)
-    .map(({ row, score }) => ({
-      taskId: row.task_id,
-      classification: row.classification,
-      severity: row.severity,
-      file: row.file,
-      line: row.line,
-      issue: row.issue,
-      reason: row.reason,
-      score: Math.round(score * 1000) / 1000,
-    }));
+    .map(({ row, score }) => {
+      // Freshness: null when we cannot compare (no stored sha, or file gone /
+      // not in a git repo); true means the file changed since the finding was
+      // recorded, so verify before reusing.
+      const cur = row.file_sha ? fileSha(row.file, top) : null;
+      const stale = row.file_sha && cur ? cur !== row.file_sha : null;
+      return {
+        taskId: row.task_id,
+        classification: row.classification,
+        severity: row.severity,
+        file: row.file,
+        line: row.line,
+        issue: row.issue,
+        reason: row.reason,
+        stale,
+        score: Math.round(score * 1000) / 1000,
+      };
+    });
   process.stdout.write(JSON.stringify({ ok: true, slug, total: filtered.length, hits: ranked }) + "\n");
   process.exit(0);
 }