@mmerterden/multi-agent-pipeline 15.10.0 → 15.10.1

package/CHANGELOG.md

@@ -16,6 +16,12 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ## [Unreleased]
 
+## [15.10.1] - 2026-08-21
+
+### Fixed
+- **`uninstall --all-data` now removes the per-repo memory root.** `~/.claude/memory/multi-agent/` holds the learnings ledger and triage corpus: durable knowledge written in prose about the repos it was collected from, which on a corporate checkout is concrete information about the codebase. It survived even the full-cleanup mode, so "removes everything but your tokens" was not true in the one place a user is most likely to mean it. The default run still keeps it, alongside settings and logs, and both halves of that promise are now tested.
+- **Offloaded tool payloads are reclaimable.** v15.10.0 added `offload-ref.sh` without a way to clean up after it. In worktree modes the payloads die with the worktree, but the `--local` modes write into the real checkout, and because `.multi-agent/refs/` is gitignored the files never appear in `git status` and nothing reclaims them. New `gc-refs.sh`, dispatched as a third phase of `/multi-agent:garbage-collect`, sweeps them with the same contract as the /tmp sweeper: dry-run until `--yes`, a root guard that refuses `/` and `$HOME`, a grace window so a sweep cannot pull a ref out from under a running phase, and node-id matching so a file the user put in that directory survives. `--all` sweeps every checkout under `$HOME`.
+
 ## [15.10.0] - 2026-08-21
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "15.10.0",
+  "version": "15.10.1",
   "description": "8-phase AI development pipeline with full orchestration on Claude Code, Copilot CLI and Codex 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/garbage-collect/SKILL.md

@@ -1,6 +1,6 @@
 ---
-description: "Sweep leftover /tmp scratch (picker state, review diffs, channel payloads, analysis drafts) and worktree residue (orphan .worktrees dirs, gitlink index entries) from past runs. Dry-run first; confirms before deleting. Use when scratch files from earlier runs need clearing out."
-description-tr: "Geçmiş çalışmalardan kalan /tmp scratch'ini (picker durumu, review diff'leri, kanal payload'ları, analiz taslakları) ve worktree kalıntılarını (sahipsiz .worktrees klasörleri, gitlink index kayıtları) süpürür. Önce dry-run; silmeden önce onay alır."
+description: "Sweep leftover /tmp scratch (picker state, review diffs, channel payloads, analysis drafts), worktree residue (orphan .worktrees dirs, gitlink index entries) and offloaded tool payloads under .multi-agent/refs/ from past runs. Dry-run first; confirms before deleting. Use when scratch files from earlier runs need clearing out."
+description-tr: "Geçmiş çalışmalardan kalan /tmp scratch'ini (picker durumu, review diff'leri, kanal payload'ları, analiz taslakları), worktree kalıntılarını (sahipsiz .worktrees klasörleri, gitlink index kayıtları) ve .multi-agent/refs/ altındaki offload edilmiş araç çıktılarını süpürür. Önce dry-run; silmeden önce onay alır."
 argument-hint: "[--older-than=<minutes>] [--yes]  -  dry-run unless confirmed"
 ---
 
@@ -72,6 +72,31 @@ deletes nothing until you confirm.
    - On confirm, re-run with `--yes` and echo its summary line. If a gitlink
      was unstaged, remind the user the removal still needs a commit.
 
+7. **Offloaded payload sweep (third phase)**  -  when the current directory is a
+   git repo, also preview the offloaded tool payloads:
+
+   ```bash
+   bash $HOME/.claude/scripts/gc-refs.sh ${ARGUMENTS}
+   ```
+
+   `offload-ref.sh` parks build logs, diffs and test output under
+   `.multi-agent/refs/<node_id>.md`. In worktree modes that directory dies with
+   the worktree; in the `--local` modes it lands in the real checkout, and
+   because it is gitignored it never shows up in `git status`. Only files
+   matching the node-id shape are touched  -  anything else in that directory is
+   left alone, and files inside the grace window are spared so a sweep cannot
+   pull a ref out from under a running phase.
+
+   - Output says `nothing to do` -> skip silently, no question.
+   - Otherwise surface a third `AskUserQuestion` (in `outputLanguage`):
+     `question`: "Delete the listed offloaded payloads?" (include the count and
+     freed size), `header`: "Payloads", options `{ label: "Delete payloads" }` /
+     `{ label: "Cancel", description: "Keep everything, change nothing" }`.
+   - On confirm, re-run with `--yes` and echo its summary line.
+
+   Pass `--all` to sweep every checkout under `$HOME` rather than only the
+   current repo.
+
 ## Notes
 
 - An in-flight analysis keeps its drafts in `/tmp/analysis-<slug>-<timestamp>/`
@@ -79,6 +104,10 @@ deletes nothing until you confirm.
   `awaiting_output_decision`, pass `--older-than=<minutes>` so fresh drafts are
   spared, or finish the run first.
 - The /tmp phase only touches `/tmp` scratch; the worktree phase only touches
-  the current repo's `.worktrees/` residue and index. Persistent per-task logs
+  the current repo's `.worktrees/` residue and index; the payload phase only
+  touches node-id files under `.multi-agent/refs/`. Persistent per-task logs
   live under `~/.claude/logs/multi-agent/` and are cleaned by
-  `/multi-agent:prune-logs`.
+  `/multi-agent:prune-logs`. The per-repo memory stores under
+  `~/.claude/memory/multi-agent/` are durable knowledge, not scratch: they are
+  removed only by `/multi-agent:uninstall --all-data`, or one entry at a time
+  with `learnings-ledger.mjs forget`.

package/pipeline/scripts/gc-refs.sh

@@ -0,0 +1,187 @@
+#!/usr/bin/env bash
+# gc-refs.sh  -  remove offloaded tool payloads left behind in a repo checkout.
+#
+# `offload-ref.sh` parks build logs, diffs and test output under
+# <root>/.multi-agent/refs/<node_id>.md so a phase prompt can carry a pointer
+# instead of the whole log. In worktree modes that directory dies with the
+# worktree. In the --local modes there is no worktree: the refs land in the
+# real checkout and nothing ever removes them. They are gitignored, so they are
+# invisible to `git status` and grow without bound.
+#
+# This sweeps them, with the same safety contract as gc-tmp.sh:
+#   - dry-run by default: lists what WOULD be removed and the space it frees,
+#     and deletes nothing until --yes
+#   - root guard: refuses a root that is not a directory, and refuses $HOME
+#     and / outright, so a stray GC_REFS_ROOT cannot sweep a home directory
+#   - fresh-payload grace: files touched in the last GC_REFS_GRACE_MIN minutes
+#     (default 10) are spared, so a sweep during an in-flight run cannot pull a
+#     ref out from under the agent that is about to read it
+#
+# Only files matching the node-id shape are touched; anything else a user put
+# in that directory is left alone.
+#
+# Usage:
+#   gc-refs.sh                     # dry-run over the current repo
+#   gc-refs.sh --yes               # actually delete
+#   gc-refs.sh --older-than=1440   # only payloads older than a day
+#   gc-refs.sh --all               # every repo under GC_REFS_SEARCH (default $HOME)
+#
+# Env:
+#   GC_REFS_ROOT       override the repo root (default: git toplevel, else $PWD)
+#   GC_REFS_SEARCH     where --all looks for checkouts (default $HOME)
+#   GC_REFS_GRACE_MIN  grace window in minutes (default 10, 0 = off)
+#
+# Exit: 0 on success or nothing to do, 2 on usage error or a refused root.
+
+set -uo pipefail
+
+GRACE_MIN="${GC_REFS_GRACE_MIN:-10}"
+SEARCH_ROOT="${GC_REFS_SEARCH:-$HOME}"
+DELETE=0
+OLDER_MIN=0
+ALL=0
+
+usage() {
+  grep -E '^#( |$)' "$0" | sed -E 's/^# ?//'
+}
+
+for arg in "$@"; do
+  case "$arg" in
+    --yes | --force) DELETE=1 ;;
+    --all) ALL=1 ;;
+    --older-than=*)
+      OLDER_MIN="${arg#*=}"
+      if ! printf '%s' "$OLDER_MIN" | grep -qE '^[0-9]+$'; then
+        echo "gc-refs: --older-than needs a whole number of minutes, got: $OLDER_MIN" >&2
+        exit 2
+      fi
+      ;;
+    -h | --help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "gc-refs: unknown argument: $arg" >&2
+      exit 2
+      ;;
+  esac
+done
+
+if ! printf '%s' "$GRACE_MIN" | grep -qE '^[0-9]+$'; then
+  echo "gc-refs: GC_REFS_GRACE_MIN needs a whole number of minutes, got: $GRACE_MIN" >&2
+  exit 2
+fi
+
+# Collect the refs directories to consider.
+REFS_DIRS=""
+if [ "$ALL" -eq 1 ]; then
+  if [ ! -d "$SEARCH_ROOT" ]; then
+    echo "gc-refs: no search root at $SEARCH_ROOT  -  nothing to do"
+    exit 0
+  fi
+  # Prune the trees that are large and never hold a pipeline checkout, so a
+  # home-wide sweep stays seconds rather than minutes.
+  REFS_DIRS=$(find "$SEARCH_ROOT" \
+    \( -name node_modules -o -name Pods -o -name .build -o -name DerivedData -o -name .next \) -prune \
+    -o -type d -path "*/.multi-agent/refs" -print 2>/dev/null)
+else
+  ROOT="${GC_REFS_ROOT:-}"
+  if [ -z "$ROOT" ]; then
+    ROOT=$(git rev-parse --show-toplevel 2>/dev/null || true)
+    [ -n "$ROOT" ] || ROOT="$PWD"
+  fi
+  # Root guard: never accept a root that resolves to / or $HOME. A sweep is
+  # recursive and a mistyped override should not be able to reach a home dir.
+  case "$ROOT" in
+    / | "$HOME")
+      echo "gc-refs: refusing to sweep '$ROOT'  -  point GC_REFS_ROOT at a repo checkout" >&2
+      exit 2
+      ;;
+  esac
+  [ -d "$ROOT" ] || {
+    echo "gc-refs: no directory at $ROOT  -  nothing to do"
+    exit 0
+  }
+  [ -d "$ROOT/.multi-agent/refs" ] && REFS_DIRS="$ROOT/.multi-agent/refs"
+fi
+
+if [ -z "$REFS_DIRS" ]; then
+  echo "gc-refs: no offloaded payloads found  -  nothing to do"
+  exit 0
+fi
+
+# Match the node-id shape offload-ref.sh writes (p<phase>-<slug>-<8 hex>.md).
+# Anything else in that directory belongs to someone else.
+NODE_GLOB='p*-*-*.md'
+
+MATCHES=""
+while IFS= read -r dir; do
+  [ -n "$dir" ] || continue
+  # `-mmin +0` is not a no-op: it means "older than a minute" and would drop a
+  # file written seconds ago. The age filter is applied only when one was asked
+  # for; the grace window below is what protects an in-flight payload.
+  if [ "$OLDER_MIN" -gt 0 ]; then
+    found=$(find "$dir" -maxdepth 1 -type f -name "$NODE_GLOB" -mmin +"$OLDER_MIN" 2>/dev/null)
+  else
+    found=$(find "$dir" -maxdepth 1 -type f -name "$NODE_GLOB" 2>/dev/null)
+  fi
+  [ -n "$found" ] || continue
+  while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    # Grace: skip anything touched inside the window.
+    if [ "$GRACE_MIN" -gt 0 ] && [ -n "$(find "$f" -mmin -"$GRACE_MIN" 2>/dev/null)" ]; then
+      continue
+    fi
+    MATCHES="$MATCHES$f
+"
+  done <<EOF
+$found
+EOF
+done <<EOF
+$REFS_DIRS
+EOF
+
+MATCHES=$(printf '%s' "$MATCHES" | grep -v '^$' || true)
+if [ -z "$MATCHES" ]; then
+  echo "gc-refs: no offloaded payloads outside the grace window  -  nothing to do"
+  exit 0
+fi
+
+COUNT=$(printf '%s\n' "$MATCHES" | grep -c .)
+BYTES=0
+while IFS= read -r f; do
+  [ -n "$f" ] || continue
+  sz=$(wc -c < "$f" 2>/dev/null | tr -d ' ')
+  BYTES=$((BYTES + ${sz:-0}))
+done <<EOF
+$MATCHES
+EOF
+KB=$(((BYTES + 1023) / 1024))
+
+if [ "$DELETE" -eq 0 ]; then
+  echo "gc-refs: would remove $COUNT offloaded payload(s), freeing ${KB} KB"
+  printf '%s\n' "$MATCHES" | sed 's/^/  /'
+  echo ""
+  echo "Nothing deleted. Re-run with --yes to remove them."
+  exit 0
+fi
+
+removed=0
+while IFS= read -r f; do
+  [ -n "$f" ] || continue
+  rm -f "$f" && removed=$((removed + 1))
+done <<EOF
+$MATCHES
+EOF
+
+# Drop a refs directory that is now empty; leave one that still holds
+# something we did not put there.
+while IFS= read -r dir; do
+  [ -n "$dir" ] || continue
+  rmdir "$dir" 2>/dev/null || true
+done <<EOF
+$REFS_DIRS
+EOF
+
+echo "gc-refs: removed $removed offloaded payload(s), freed ${KB} KB"
+exit 0

package/pipeline/scripts/uninstall.mjs

@@ -31,6 +31,7 @@
  * Preserved by default, removed with --all-data:
  *   - $HOME/.claude/multi-agent-preferences.json (pipeline settings)
  *   - $HOME/.claude/logs/multi-agent/ (task logs, state, metrics, audit trail)
+ *   - $HOME/.claude/memory/multi-agent/ (per-repo learnings ledger + triage corpus)
  *
  * @module pipeline/scripts/runtime/uninstall
  */
@@ -635,6 +636,7 @@ export async function main() {
     console.log("  FULL CLEANUP (--all-data) also removes:");
     console.log("    - ~/.claude/multi-agent-preferences.json (pipeline settings)");
     console.log("    - ~/.claude/logs/multi-agent/ (task logs, state, metrics, audit trail)");
+    console.log("    - ~/.claude/memory/multi-agent/ (per-repo learnings ledger + triage corpus)");
     console.log("");
   }
   console.log("  PRESERVED (never touched):");
@@ -733,14 +735,22 @@ export async function main() {
     stripManagedBlock(join(COP, "copilot-instructions.md"));
   }
 
-  // Full cleanup: pipeline settings + the multi-agent log root. Both are
-  // pipeline-generated data (not user-authored like CLAUDE.md / rules), so
-  // --all-data removes them; the default run leaves them in place.
+  // Full cleanup: pipeline settings, the log root, and the per-repo memory
+  // stores. All three are pipeline-generated data (not user-authored like
+  // CLAUDE.md / rules), so --all-data removes them; the default run leaves them
+  // in place.
+  //
+  // The memory root was missing here, and it is the one a user is most likely
+  // to mean by "remove everything": the learnings ledger and triage corpus hold
+  // architectural facts and past review findings written in prose about the
+  // repos they were collected from. On a corporate checkout that is concrete
+  // information about the codebase, and it survived even --all-data.
   if (allData && HOME) {
     console.log("");
-    console.log("  [Full cleanup] Removing pipeline settings + logs...");
+    console.log("  [Full cleanup] Removing pipeline settings, logs + memory...");
     rmIfExists(join(HOME, ".claude", "multi-agent-preferences.json"));
     rmIfExists(join(HOME, ".claude", "logs", "multi-agent"));
+    rmIfExists(join(HOME, ".claude", "memory", "multi-agent"));
   }
 
   // Legacy adapter-file cleanup (adapters removed in v10.7.0). These blocks
@@ -818,7 +828,7 @@ export async function main() {
   if (!allData) {
     console.log("");
     console.log(
-      "  Kept your pipeline settings + logs. To remove those too, re-run with --all-data.",
+      "  Kept your pipeline settings, logs + per-repo memory. To remove those too, re-run with --all-data.",
     );
   } else {
     console.log("");