@mmerterden/multi-agent-pipeline 12.3.0 → 12.5.0

package/CHANGELOG.md

@@ -14,6 +14,77 @@ 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
+first-class `/multi-agent` commands.
+
+### Added
+
+- **`/multi-agent:save`** turns a recurring job into a reusable
+  `/multi-agent:<name>` command. It leads with the work actually executed in
+  the current session (distilling repeatable jobs from what was just done),
+  then adds named procedures found in `~/.claude/CLAUDE.md`, and offers them in
+  a multi-select picker: pick one, pick several to combine into one routine
+  (steps concatenated in order), or describe a new one via free text.
+- **`/multi-agent:routines`** lists saved routines with what each does, in
+  `outputLanguage`. **`/multi-agent:forget`** removes one (guarded: never
+  touches a shipped command).
+- Backed by `routine-registry.mjs` (add/list/remove/get; name validation,
+  collision + shipped-command guards, atomic prefs write). Saved routines are
+  `local-only: true` command dirs + a `prefs.global.routines` registry entry:
+  preserved across `/multi-agent:update` by the install snapshot/restore,
+  rejected from the public repo by the sync backstops, and never counted in the
+  command inventory.
+- Registered in `/multi-agent:help` (EN + TR "Routines" section with a dynamic
+  listing of saved routines).
+
+### Changed
+
+- Command inventory 38 -> 41 (`save`, `routines`, `forget`); contract, both sync
+  docs, help EN/TR, and the count smokes updated; 3 Copilot twins added.
+- prefs schema `global.routines` + `schemaVersion` 2.4.0; new
+  `prefs-2.3.0-to-2.4.0.mjs` migration (idempotent, adds `routines: []`).
+
 ## [12.3.0] - 2026-07-23
 
 `/multi-agent:analysis` overhaul: the feature-spec doc is now a development

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "12.3.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/commands/multi-agent/forget/SKILL.md

@@ -0,0 +1,29 @@
+---
+description: "Remove a saved /multi-agent routine (created by /multi-agent:save): deletes its local-only command and its registry entry. Asks which one and confirms."
+description-tr: "Kaydedilmiş bir /multi-agent rutinini (/multi-agent:save ile oluşturulan) siler: local-only komutunu ve registry kaydını kaldırır. Hangisini soracak ve onay alacak."
+argument-hint: "[name]  -  routine to remove; asked if omitted"
+allowed-tools: Bash, Read, AskUserQuestion
+---
+
+# multi-agent forget  -  Remove a Routine
+
+Delete a routine the user saved via `/multi-agent:save`. Backed by `$HOME/.claude/scripts/routine-registry.mjs`.
+
+## Steps
+
+1. **Resolve which routine.** If `$ARGUMENTS` names one, use it. Otherwise run `node "$HOME/.claude/scripts/routine-registry.mjs" list --json`, and `AskUserQuestion` (in `outputLanguage`) with one option per saved routine. No routines -> report there is nothing to forget and stop.
+
+2. **Confirm.** `AskUserQuestion` (in `outputLanguage`): "Remove `/multi-agent:<name>`? This deletes the routine command and its registry entry." Options: `{ label: "Remove", description: "Delete this routine" }`, `{ label: "Cancel", description: "Keep it" }`. Anything but Remove -> stop.
+
+3. **Remove:**
+   ```bash
+   node "$HOME/.claude/scripts/routine-registry.mjs" remove --name "<name>"
+   ```
+   The backend guards against removing a shipped command (it only deletes a dir that is BOTH registered AND `local-only: true`).
+
+4. **Report** (in `outputLanguage`): the routine is removed; note that its `/multi-agent:<name>` entry clears from autocomplete on the next session reload.
+
+## Notes
+
+- Only user-saved routines can be forgotten; shipped `/multi-agent:*` commands are refused by the backend.
+- To see what you can forget, run `/multi-agent:routines`.

package/pipeline/commands/multi-agent/help/SKILL.md

@@ -131,6 +131,15 @@ Setup & Maintenance:
 
 ------------------------------------------------------------
 
+Routines (your own reusable jobs):
+
+  /multi-agent:save [name]    Save a recurring job as a reusable /multi-agent:<name> command
+  /multi-agent:routines       List your saved routines and what each does
+  /multi-agent:forget [name]  Remove a saved routine
+<!-- ROUTINES_DYNAMIC: after printing the static lines above, read prefs.global.routines; if non-empty, append one indented line per routine "  /multi-agent:<name>   <description>" under a "Your saved routines:" subheading, in outputLanguage. If empty, print "  (none yet - use /multi-agent:save)". -->
+
+------------------------------------------------------------
+
 Interactive Launchers:
 
   /multi-agent:jira           List MY open Jira issues → pick → branch → mode → go
@@ -345,6 +354,15 @@ Setup & Maintenance:
 
 ------------------------------------------------------------
 
+Rutinler (kendi tekrar eden işlerin):
+
+  /multi-agent:save [ad]          Sık yaptığın bir işi yeniden kullanılabilir /multi-agent:<ad> komutu olarak kaydet
+  /multi-agent:routines           Kayıtlı rutinlerini ve ne yaptıklarını listele
+  /multi-agent:forget [ad]        Kayıtlı bir rutini kaldır
+<!-- ROUTINES_DYNAMIC: yukarıdaki statik satırlardan sonra prefs.global.routines'i oku; boş değilse her rutin için "  /multi-agent:<ad>   <açıklama>" satırını "Kayıtlı rutinlerin:" alt başlığı altında ekle (outputLanguage). Boşsa "  (henüz yok - /multi-agent:save kullan)" yaz. -->
+
+------------------------------------------------------------
+
 İnteraktif Launcher'lar:
 
   /multi-agent:jira           BENİM açık Jira issue'larımı listele → seç → branch → mode → başla

package/pipeline/commands/multi-agent/routines/SKILL.md

@@ -0,0 +1,30 @@
+---
+description: "List your saved /multi-agent routines (from /multi-agent:save) with what each one does, rendered in outputLanguage."
+description-tr: "Kaydettiğin /multi-agent rutinlerini (/multi-agent:save ile) listeler; her birinin ne yaptığını outputLanguage'e göre gösterir."
+argument-hint: ""
+allowed-tools: Bash, Read
+---
+
+# multi-agent routines  -  List Saved Routines
+
+Show every routine the user saved via `/multi-agent:save`. Backed by `$HOME/.claude/scripts/routine-registry.mjs`.
+
+## Steps
+
+1. **Read the registry:**
+   ```bash
+   node "$HOME/.claude/scripts/routine-registry.mjs" list --json
+   ```
+
+2. **Render in `outputLanguage`.** Empty list -> tell the user there are no saved routines yet and that `/multi-agent:save` creates one. Otherwise print a compact table, one row per routine:
+
+   | Komut / Command | Ne yapar / What it does | Oluşturma / Created |
+   |---|---|---|
+   | `/multi-agent:<name>` | `<description>` | `<createdAt date>` |
+
+3. **Integrity note (optional).** If a registry entry has no matching `~/.claude/commands/multi-agent/<name>/` dir (or a local-only routine dir exists with no registry entry), flag it as `needs repair` so the user can re-save or `/multi-agent:forget` it. Never modify anything here - this command is read-only.
+
+## Notes
+
+- Read-only. To add a routine use `/multi-agent:save`; to remove one use `/multi-agent:forget <name>`.
+- Routines are local-only and never synced; this list reflects only the current machine.

package/pipeline/commands/multi-agent/save/SKILL.md

@@ -0,0 +1,46 @@
+---
+description: "Save a recurring job as a reusable /multi-agent:<name> command. Reviews the conversation + your CLAUDE.md for candidate routines, you pick one and name it; it is stored local-only and never synced."
+description-tr: "Sık yaptığın bir işi yeniden kullanılabilir /multi-agent:<ad> komutu olarak kaydeder. Konuşmayı + CLAUDE.md'ni tarayıp aday rutinler önerir, sen seçip ad verirsin; local-only saklanır, asla sync edilmez."
+argument-hint: "[name]  -  optional command name; asked if omitted"
+allowed-tools: Bash, Read, AskUserQuestion
+---
+
+# multi-agent save  -  Save a Routine
+
+**Input**: $ARGUMENTS (optional routine name)
+
+Turn a recurring, project-specific procedure into a first-class `/multi-agent:<name>` command. The saved routine is a **local-only** command (`local-only: true`) plus a registry entry in `prefs.global.routines`; it is never synced to the public repo (the `/multi-agent:sync` backstops enforce this).
+
+Backed by `$HOME/.claude/scripts/routine-registry.mjs`.
+
+## Steps
+
+1. **Distill candidates from what was just done (primary source).** The user usually runs `:save` right after performing a job they want to repeat, so FIRST review the recent session: group the tasks/steps actually executed this conversation into coherent, repeatable jobs. Each distinct job is a candidate - give it a suggested short name, a one-line summary, and the ordered steps it would replay. THEN add, as further candidates, any named end-to-end procedures in `$HOME/.claude/CLAUDE.md` (heading + trigger phrase + numbered steps, e.g. a "... kontrol et" procedure). If nothing repeatable is found in the session and CLAUDE.md has none, say so and offer the free-text path only.
+
+2. **Pick (multi-select) + optionally combine.** `AskUserQuestion` with `multiSelect: true` (in `outputLanguage`): one option per distilled candidate (label = suggested name, description = the one-line summary), PLUS an always-present `Other` free-text path to describe a brand-new routine by hand. Semantics:
+   - one candidate selected -> that becomes the routine;
+   - several selected -> **combine them into ONE routine**, concatenating their steps in the order shown (the routine replays them in sequence); ask for a single name for the combined routine;
+   - `Other` -> the user types the routine themselves.
+   Empty selection is not consent - re-ask.
+
+3. **Name the command.** Use `$ARGUMENTS` if given, else ask. Validate: lowercase `^[a-z0-9][a-z0-9-]*$`, <= 40 chars. `routine-registry.mjs add` rejects a name that collides with a shipped command or an existing routine; on rejection, ask for another name.
+
+4. **Write the routine body** to a temp file: the full procedure the routine should run every time. For a single candidate, embed its steps (when the source is a CLAUDE.md section, reference that section by name AND embed a faithful copy so the routine is self-contained). For a combined (multi-select) routine, concatenate the selected candidates' steps in the shown order under numbered phase headings. Keep the user's own wording; do not invent steps.
+
+5. **Save.** Run:
+   ```bash
+   node "$HOME/.claude/scripts/routine-registry.mjs" add \
+     --name "<name>" \
+     --description "<one-line summary>" \
+     --description-tr "<Turkish one-line summary>" \
+     --source "<CLAUDE.md section name | conversation | user>" \
+     --body-file "/tmp/routine-<name>.md"
+   ```
+
+6. **Report + offer to run.** Tell the user (in `outputLanguage`): the routine is saved and will appear as `/multi-agent:<name>` in autocomplete **after the next session reload** (a freshly written command is not hot-loaded this session). Then offer to run it now (you have the procedure in hand, so you can execute it immediately without waiting for the slash command to register).
+
+## Notes
+
+- Never write under a repo `pipeline/` tree; routines live only under `~/.claude`.
+- The routine file always carries `local-only: true` (the backend asserts this), so `/multi-agent:sync` and the install namespace-wipe both preserve it and keep it out of the public repo.
+- List saved routines with `/multi-agent:routines`; remove one with `/multi-agent:forget <name>`.

package/pipeline/commands/multi-agent/sync/SKILL.md

@@ -56,7 +56,7 @@ Run every step automatically:
 ```
 Step 1: PLATFORM    Detect macOS / Linux / Windows (Git Bash / WSL); export PLATFORM env
 Step 1.5: DETECT    Compare timestamps, find stale targets
-Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 38 sub-command skills)
+Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 41 sub-command skills)
 Step 3: REPO        Claude Code -> pipeline repo (genericized, personal data scrub, bash -n on all sh)
 Step 3c: PLUGINS    pipeline shared/external -> multi-agent-plugins marketplace (rebuild knowledge/,
                      bump changed plugins' patch version, commit + push the plugins repo)
@@ -257,14 +257,14 @@ This runs on the Claude <-> Copilot axis — the two CLIs the pipeline supports
 |-------------|-------------|
 | `~/.claude/commands/multi-agent/{cmd}/SKILL.md` | `~/.copilot/skills/multi-agent-{cmd}/SKILL.md` |
 
-**38 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
+**41 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
 
 ```
 analysis, analysis-resolve, autopilot, build-optimize, channels, create-jira, dev,
-dev-autopilot, dev-local, dev-local-autopilot, diff-explain, finish, garbage-collect,
+dev-autopilot, dev-local, dev-local-autopilot, diff-explain, finish, forget, garbage-collect,
 help, issue, jira, kill, language, local,
 local-autopilot, log, manual-test, prune-logs, purge, refactor, resume, review, review-issue, review-jira,
-scan, search, setup, stack, status, sync, test, uninstall, update
+routines, save, scan, search, setup, stack, status, sync, test, uninstall, update
 ```
 
 **NOT synced**: `$HOME/.claude/multi-agent-refs/*`  -  lazy-load references, Claude Code specific

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/cross-cli-contract.md

@@ -6,14 +6,14 @@
 
 ---
 
-## 1. Command Inventory (38 commands)
+## 1. Command Inventory (41 commands)
 
 ```
 analysis, analysis-resolve, autopilot, build-optimize, channels, create-jira, dev,
-dev-autopilot, dev-local, dev-local-autopilot, diff-explain, finish, garbage-collect,
+dev-autopilot, dev-local, dev-local-autopilot, diff-explain, finish, forget, garbage-collect,
 help, issue, jira, kill, language, local,
 local-autopilot, log, manual-test, prune-logs, purge, refactor, resume, review, review-issue, review-jira,
-scan, search, setup, stack, status, sync, test, uninstall, update
+routines, save, scan, search, setup, stack, status, sync, test, uninstall, update
 ```
 
 Categories:
@@ -25,6 +25,7 @@ Categories:
 - **Tail modes** (run the pipeline tail over already-done local work): `finish`
 - **Ops commands** (one-shot, no worktree): `status`, `log`, `kill`, `purge`, `uninstall`, `resume`, `review`, `review-jira`, `review-issue`, `analysis`, `analysis-resolve`, `build-optimize`, `channels`, `scan`, `search`, `diff-explain`, `garbage-collect`, `prune-logs`
 - **Meta-ops**: `setup`, `sync`, `update`, `help`, `refactor`, `test`, `stack`, `manual-test`, `language`
+- **Routines** (user-defined routine registry; the routines they create are local-only and never synced): `save`, `routines`, `forget`
 
 > **Inventory drift is a contract violation.** Adding a slash command under `pipeline/commands/multi-agent/` without updating this list + its counterpart Copilot dir (`pipeline/skills/shared/core/multi-agent-<cmd>/`) is a merge blocker. `smoke-commands-skills-parity.sh` enforces command ↔ skill directory parity; `smoke-cross-cli-behavior.sh` enforces behavior parity. This doc is the authoritative command list  -  bump the count + table together.
 

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/migrations/prefs-2.3.0-to-2.4.0.mjs

@@ -0,0 +1,32 @@
+/**
+ * prefs-2.3.0-to-2.4.0.mjs  -  preference schema upgrade 2.3.0 -> 2.4.0
+ *
+ * Adds the user-defined routine registry:
+ *   - global.routines  (v2.4.0)  -  array of {name, description, createdAt,
+ *                                   source, trigger?} indexing local-only
+ *                                   /multi-agent:<name> commands saved via
+ *                                   /multi-agent:save. Never synced (personal).
+ *
+ * Defaults to an empty array. Existing v2.3.0 prefs validate against the
+ * v2.4.0 schema without it, but the migrator initializes it so the routine
+ * commands can read/append without null-guards.
+ *
+ * Idempotent: safe on already-2.4.0 input. Non-destructive: preserves any
+ * user-saved routines.
+ *
+ * @param {object} data  -  parsed JSON content of the preferences file
+ * @returns {object}     -  same data with schemaVersion = "2.4.0"
+ */
+export default function migrate(data) {
+  const out = JSON.parse(JSON.stringify(data));
+
+  out.schemaVersion = "2.4.0";
+
+  if (!out.global) out.global = {};
+
+  if (!Array.isArray(out.global.routines)) {
+    out.global.routines = [];
+  }
+
+  return out;
+}

package/pipeline/schemas/prefs.schema.json

@@ -17,7 +17,8 @@
         "2.0.0",
         "2.1.0",
         "2.2.0",
-        "2.3.0"
+        "2.3.0",
+        "2.4.0"
       ],
       "description": "v2.0.0: pre-v3.7. v2.1.0: v3.7+ adds identities[].servicePatMap, platformIdentityRouting, recentGroups, recentBranches, serviceStatus, settings, expanded keychainMapping. v2.2.0: v6.0.0 formalizes v5.7 / v5.8 additions (reportChannels, reportContent with technicalAnalysis, wikiScope, autopilotReportTimeoutSeconds) that had been running as 2.1.0 sub-migrations without a proper version bump."
     },
@@ -273,6 +274,40 @@
             "maxItems": 10
           }
         },
+        "routines": {
+          "type": "array",
+          "description": "v2.4.0+. User-defined routines saved via /multi-agent:save. Each entry indexes a local-only /multi-agent:<name> command dir under ~/.claude/commands/multi-agent/. Never synced (personal). Managed by routine-registry.mjs.",
+          "maxItems": 100,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name", "description"],
+            "properties": {
+              "name": {
+                "type": "string",
+                "pattern": "^[a-z0-9][a-z0-9-]*$",
+                "maxLength": 40,
+                "description": "Routine command name; invocable as /multi-agent:<name>."
+              },
+              "description": {
+                "type": "string",
+                "description": "One-line summary shown by /multi-agent:routines and :help."
+              },
+              "createdAt": {
+                "type": "string",
+                "format": "date-time"
+              },
+              "source": {
+                "type": "string",
+                "description": "Where the routine came from, e.g. a CLAUDE.md section name or 'user'."
+              },
+              "trigger": {
+                "type": ["string", "null"],
+                "description": "Optional natural-language trigger phrase the routine captures."
+              }
+            }
+          }
+        },
         "recentGroups": {
           "type": "array",
           "description": "v2.1.0+. LRU of multi-repo selection groups. Each group is a set of repo paths chosen together for multi-repo tasks. Max 10.",

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

@@ -1,19 +1,19 @@
 .claude/.pipeline-version	1
 .claude/CLAUDE.md	1
 .claude/agents	8
-.claude/commands	44
+.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	23
-.claude/scripts	195
+.claude/schemas	24
+.claude/scripts	199
 .claude/settings.json	1
 .claude/skills	428
 .copilot/.pipeline-version	1
 .copilot/agents	8
 .copilot/copilot-instructions.md	1
 .copilot/lib	27
-.copilot/schemas	23
-.copilot/scripts	195
-.copilot/skills	467
+.copilot/schemas	24
+.copilot/scripts	199
+.copilot/skills	470