@mmerterden/multi-agent-pipeline 16.30.0 → 16.31.1

package/CHANGELOG.md

@@ -14,6 +14,54 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ---
 
+## [16.31.1] - 2026-09-13
+
+### Fixed
+
+- **A literal keychain item name shipped in `refs/rules.md` for two months.** The Vercel section's example read `credential-store.sh get <maintainer's own item>`, which both named whose machine the file came from and taught the wrong mechanism: `keychainMapping` exists precisely so shipped files name the LOGICAL key and the mapping resolves the per-machine item. The example is now the one-line wrapper call, which resolves the token itself. `sync/SKILL.md`'s publish-candidate table and `keychain.py`'s comment carried the same shape and are genericized.
+
+- **`smoke-personal-data.sh` had no pattern for that shape**, which is why it survived every scan. Added, case-sensitively: the owner segment must start lowercase, which is exactly what separates a resolved item name from the `${USER}_...` and `{USER}_...` template spellings the convention calls for - under the main list's `-i` that distinction disappears and the templates match too. It found three live instances on its first run.
+
+- `account-resolver.sh`'s prefix example and `smoke-pref-migration.sh`'s fixtures now use placeholder spellings rather than ones that read like a real account.
+
+## [16.31.0] - 2026-09-13
+
+A pipeline that leaves worktrees, artefacts and exclude lines behind is not generic tooling, it is a guest that rearranges the furniture. This release makes a run leave the repo exactly as it found it, and fixes two credentials-and-integrity gaps found while proving it.
+
+### Added
+
+- **`pipeline/lib/repo-hygiene.sh`** - one owner for everything the pipeline writes into somebody else's repo. `ensure_exclusions` writes a marked block into `.git/info/exclude` covering `.worktrees/`, `.pipeline/`, `.multi-agent/`, `triage-output.json`, `.review-diff.txt`, `.build.log` and `.test.log`; `release_exclusions` removes exactly that block and nothing around it; `prune_empty` removes directories it can `rmdir` and never touches `memory/`. The single-line residue guard that lived inline in Phase 0 moved here, so the write and the removal are now written next to each other rather than one existing and the other not.
+
+  The exclude path resolves through `--git-common-dir`, not `--git-dir`: inside a worktree the latter points at `.git/worktrees/<name>/`, where an exclude file is read by that worktree alone and disappears with it.
+
+  **`safe_root` refuses `/`, `$HOME`, an empty argument and anything that does not resolve.** Every sibling GC script already had that guard; this one wrote into `$HOME/.multi-agent/` without it, which is a real path on a real machine.
+
+- **`doctor`: a `worktree-residue` check** (the 15th). Reports per-repo `.worktrees` count and total size and points at `/multi-agent:garbage-collect` above the threshold. Written because the leak was invisible: one reference repo had accumulated 15 worktrees and 11.4 GB, and nothing reported it.
+
+- **`smoke-repo-residue.sh`** (26 assertions, 10 sections) - simulates a full run's artefacts in a temporary repo and proves `git status --porcelain` is empty afterwards. There was no gate of this shape before, which is why the leak survived.
+
+### Fixed
+
+- **`vercel-deploy.sh` never read the credential store it advertised.** The header has promised "resolved from prefs keychainMapping if unset" since the wrapper was written; the block under that promise sourced the resolver only to name it in an error message. A machine with the token onboarded was still told to set an environment variable. Resolution now lives in one function that both `doctor` and `deploy` call, so the diagnostic can no longer report a token missing that a deploy would have found.
+
+  The key was also **impossible to map**: `keychainMapping` is `additionalProperties: false` and carried no `vercel` slot, so the remediation the error printed could not be followed. The slot now exists in the schema, the preferences template, `credential-inventory.sh`'s capability table and the `keychain.md` key table - the four places `smoke-credential-key-alignment.sh` requires a runtime key to appear, and that gate caught three of them being missing.
+
+- **`.skill-manifest.json` had been stale since 09-09.** Four `SKILL.md` files changed under it and two more were never in it at all, so every install printed drift warnings nobody could act on, and a signed manifest that is allowed to rot is decorative. `smoke-gate-wiring.sh` exempted `sign-skills.sh` as "release-time signing" for a release step that did not exist; the release flow now names it, and the manifest smoke verifies the **shipped tree** rather than only its fixtures.
+
+- **An exclude file with no trailing newline was corrupted.** The block marker was appended directly onto the user's last line, which both mangled that line and made the block unremovable, since the removal matches on the marker being at the start of a line.
+
+- **`gc-tmp.sh` swept four temp prefixes it never knew about** (`complaint-analysis-*`, `generate-issue-*`, `cred-inventory-*`, `pr-body-*`) and `*-wiki` clones. The `.git` requirement that guards wiki clones applies to those alone - applied to the prefix list it would have narrowed an unconditional sweep.
+
+- **`gc-worktrees.sh` failed silently when the hygiene lib was absent**, doing nothing where it was meant to write the guard. It now says so loudly.
+
+- **Two legacy data roots** (`~/.claude/multi-agent-tasks/`, `~/.claude/.multi-agent-state/`, both with zero code references) are recognised by `pruneAbandonedTrees()` through an entry marker, so one content-bearing entry without the marker keeps the whole tree rather than the installer deleting somebody's data.
+
+### Changed
+
+- `worktree-finalize.sh` prunes through the resolved real path rather than `$PROJECT_ROOT`, which differs whenever the repo is reached through a symlink.
+- `purge` is the only path that releases the managed exclude block - a garbage collection run is not a reason to stop ignoring the pipeline's own artefacts.
+- `smoke-offload-ref.sh` and `smoke-gc-worktrees.sh` now assert through `git check-ignore` on the real leak paths instead of matching our own printed strings.
+
 ## [16.30.0] - 2026-09-12
 
 The flow video existed as a contract with no recorder, no UI test ever ran, and the PR carried filenames where a reviewer needed a picture. This release makes the evidence real and asks the user what it is worth paying for.

package/install/_common.mjs

@@ -268,13 +268,30 @@ export function pruneLegacyMultiAgentSkills(skillsDir) {
  *
  * `root: "home"` entries sit beside `~/.claude`, not inside it.
  *
- * @type {ReadonlyArray<{dir: string, root?: "claude"|"home", reason: string}>}
+ * @type {ReadonlyArray<{dir: string, root?: "claude"|"home", reason: string, knownEntries?: string[], entryMarker?: string}>}
  */
 const ABANDONED_TREES = Object.freeze([
   {
     dir: "eval",
     reason: "eval corpora; the harnesses that read them are maintainer-only and no longer ship",
   },
+  {
+    // Two roots the pipeline wrote task state into before the log root settled
+    // on ~/.claude/logs/multi-agent/. Nothing in the tree references either any
+    // more - no script, no doc, no schema - so they are orphaned copies of
+    // state nothing can read. `entryMarker` is the guard: every entry must be a
+    // directory holding an agent-state.json, which is the shape only this
+    // pipeline wrote. A folder someone else put there fails that test and the
+    // tree is kept.
+    dir: "multi-agent-tasks",
+    entryMarker: "agent-state.json",
+    reason: "pre-log-root task state; the current root is ~/.claude/logs/multi-agent/",
+  },
+  {
+    dir: ".multi-agent-state",
+    entryMarker: "agent-state.json",
+    reason: "pre-log-root task state; the current root is ~/.claude/logs/multi-agent/",
+  },
   {
     dir: ".multi-agent",
     root: "home",
@@ -290,9 +307,33 @@ const ABANDONED_TREES = Object.freeze([
 /**
  * @param {string} target
  * @param {ReadonlyArray<string>|undefined} knownEntries
+ * @param {string|undefined} entryMarker file every entry must contain, for trees keyed by task id
  * @returns {boolean} true when every top-level entry is one the abandoned tree is known to contain
  */
-function isKnownLegacyTree(target, knownEntries) {
+function isKnownLegacyTree(target, knownEntries, entryMarker) {
+  if (entryMarker) {
+    // Shape check rather than a name list, for trees whose entries are task ids
+    // and therefore unknowable in advance. An entry qualifies when it carries
+    // the marker, or when it is an empty directory - an abandoned run that was
+    // torn down leaves one of those, and nothing that is empty can belong to
+    // anyone else. A directory with content but no marker is somebody's, and
+    // one such entry keeps the whole tree.
+    try {
+      return readdirSync(target)
+        .filter((name) => name !== ".DS_Store")
+        .every((name) => {
+          const entry = join(target, name);
+          if (existsSync(join(entry, entryMarker))) return true;
+          try {
+            return readdirSync(entry).filter((n) => n !== ".DS_Store").length === 0;
+          } catch {
+            return false;
+          }
+        });
+    } catch {
+      return false;
+    }
+  }
   if (!knownEntries) return true;
   try {
     return readdirSync(target).every((name) => knownEntries.includes(name));
@@ -329,11 +370,11 @@ export const COMMAND_RENAMES = Object.freeze({
  */
 export function pruneAbandonedTrees(claudeDir, home = dirname(claudeDir)) {
   let removed = 0;
-  for (const { dir, root, reason, knownEntries } of ABANDONED_TREES) {
+  for (const { dir, root, reason, knownEntries, entryMarker } of ABANDONED_TREES) {
     const base = root === "home" ? home : claudeDir;
     const target = join(base, dir);
     if (!existsSync(target)) continue;
-    if (!isKnownLegacyTree(target, knownEntries)) {
+    if (!isKnownLegacyTree(target, knownEntries, entryMarker)) {
       console.log(
         `    kept ${target}: holds entries no abandoned install wrote, so it is not ours to remove`,
       );

package/package.json

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

@@ -120,9 +120,8 @@ Step 0 gate rules and why: `features/doctor.md`.
    - `~/.claude/CLAUDE.md`, `~/.claude/rules/`, `~/.claude/knowledge/`
    - `~/.claude/scripts/`  -  EXCEPT `pre-commit-check.sh`, `agent-guard.sh`, `agent-guard.py`, and `build-stack-plugins.mjs` (generic, synced)
    - `~/.claude/settings.json`
-   - **Any `~/.claude/commands/multi-agent/*/SKILL.md` whose frontmatter has `local-only: true`** - these are user/repo-specific alias wrappers that delegate to a private marketplace plugin's skills exposed as `multi-agent:<name>`. Syncing them would leak the private plugin/skill names into the public pipeline. Filter before copy: skip every source file containing `local-only: true`, and after copy assert none reached `pipeline/commands/`.
+   - **Any `~/.claude/commands/multi-agent/*/SKILL.md` whose frontmatter has `local-only: true`** - these are user/repo-specific alias wrappers that delegate to a private marketplace plugin's skills exposed as `multi-agent:<name>`. Syncing them would leak the private plugin/skill names into the public pipeline. Skip them at copy time; the backstop below proves none reached `pipeline/commands/`.
      ```bash
-     # backstop: no local-only wrapper may exist in the synced target
      grep -rl "^local-only: true" ~/multi-agent-pipeline/pipeline/commands/ 2>/dev/null \
        && { echo "ABORT: local-only wrapper leaked into pipeline/commands"; exit 1; } || true
      # backstop: corporate refs only (generic ai-ios-toolkit is fine)
@@ -140,7 +139,6 @@ Step 0 gate rules and why: `features/doctor.md`.
      # normalize: restore English descriptions, strip description-en sidecars
      node ~/multi-agent-pipeline/pipeline/scripts/localize-commands.mjs restore \
        --dir ~/multi-agent-pipeline/pipeline/commands/multi-agent
-     # backstop: no sidecar may survive into the repo
      grep -rl "^description-en:" ~/multi-agent-pipeline/pipeline/commands/ 2>/dev/null \
        && { echo "ABORT: description-en sidecar leaked into pipeline/commands"; exit 1; } || true
      # backstop: repo description lines must be English (Turkish-diacritics proxy)
@@ -386,8 +384,8 @@ Measured on this machine, which is why the order is what it is:
 | Candidate | login | scopes |
 |---|---|---|
 | `keychainMapping.github` | corporate EMU account | cannot publish to a personal scope under any grant |
-| `mmerterden_Github_Auth_Token` | personal | `admin:public_key, gist, read:org, repo`  -  no `write:packages` |
-| `gh auth token -u mmerterden` | personal | `gist, read:org, repo, workflow, write:packages` ✓ |
+| the personal PAT in the store | personal | `admin:public_key, gist, read:org, repo`  -  no `write:packages` |
+| `gh auth token -u {owner}` | personal | `gist, read:org, repo, workflow, write:packages` ✓ |
 
 **Two 403s mean two different things, and neither says "wrong token" plainly:**
 
@@ -467,7 +465,8 @@ When invoked with the `release` argument:
 ```
 1. REPO          Claude Code -> pipeline repo (genericized)
 2. VERIFY        Personal data scan -> 0 results; config-hygiene scan (scan-agent-config.sh) -> 0 HIGH
-3. LINT + TEST   ESLint + smoke tests
+3. LINT + TEST   ESLint + smoke tests (stale .skill-manifest.json fails here; re-sign
+                 it with sign-skills.sh whenever a SKILL.md moved)
 4. VERSION       package.json version bump (patch/minor/major)
 5. Commit + TAG  git commit + git tag v{VERSION}
 6. PUSH          git push --tags; publish is local (release.yml off)

package/pipeline/lib/account-resolver.sh

@@ -8,7 +8,7 @@
 # that precedes the provider segment. Examples:
 #   ${USER}_Github_Access_Token        -> prefix=${USER}
 #   ${USER}_Tktech_Github_Access_Token -> prefix=${USER}_Tktech
-#   personal_Github_Auth_Token        -> prefix=personal
+#   {prefix}_Github_Auth_Token         -> prefix={prefix}
 #
 # Usage:
 #   ./account-resolver.sh             # JSON array

package/pipeline/lib/credential-inventory.sh

@@ -358,6 +358,7 @@ capability_of() {
     figma|figma_mcp)   echo "fetch design context, screenshots and Code Connect mappings" ;;
     jenkins)           echo "read build results" ;;
     npm)               echo "publish to the npm registry" ;;
+    vercel)            echo "deploy the website to Vercel and read its deployment status" ;;
     appstore_connect_key_id|appstore_connect_issuer_id)
                        echo "validate an archive against App Store rules before submission (the .p8 itself is a file at ~/.appstoreconnect/private_keys/, never a mapping)" ;;
     appstore_connect_apple_id|appstore_connect_password_item)

package/pipeline/lib/repo-hygiene.sh

@@ -0,0 +1,164 @@
+#!/usr/bin/env bash
+#
+# repo-hygiene.sh
+# Keeps pipeline artefacts out of the user's repository. Sourceable library.
+#
+# The pipeline writes into a checkout in three ways: the worktree parent
+# (.worktrees/), the per-run artefact dir (.pipeline/), and the offload tree
+# (.multi-agent/). Only the first was ever excluded, and only by a one-line
+# guard duplicated across two phase docs and gc-worktrees.sh. The other two
+# were never excluded anywhere, which is invisible in worktree mode (the
+# worktree is deleted) and permanent in --local mode (nothing deletes it).
+#
+# Functions:
+#   ma_hygiene_ensure_exclusions <repo-root>   Write the managed block into
+#                                              .git/info/exclude. Idempotent;
+#                                              rewrites the block on upgrade so
+#                                              new entries reach old checkouts.
+#   ma_hygiene_release_exclusions <repo-root>  Remove the managed block, and
+#                                              nothing else. Lines a human put
+#                                              there are never touched.
+#   ma_hygiene_local_gitignore <repo-root>     Write .multi-agent/.gitignore.
+#   ma_hygiene_prune_empty <repo-root>         rmdir the artefact parents when
+#                                              their last child is gone.
+#
+# Every function is best-effort: a read-only or non-git directory is not an
+# error, because refusing to run a pipeline over a repo we cannot tidy is worse
+# than leaving it untidy. Callers do not check the return value.
+#
+# bash 3.2 compatible (macOS ships 3.2 and has no flock, no mapfile).
+
+MA_HYGIENE_BEGIN='# >>> multi-agent pipeline (managed) >>>'
+MA_HYGIENE_END='# <<< multi-agent pipeline (managed) <<<'
+
+# Paths the pipeline writes inside a checkout. `.worktrees/` predates this file
+# and may already be present as a bare line; git treats a duplicated pattern as
+# one, so the managed block restates it rather than trying to adopt it.
+ma_hygiene_patterns() {
+  cat <<'PATTERNS'
+.worktrees/
+.pipeline/
+.multi-agent/
+triage-output.json
+.review-diff.txt
+.build.log
+.test.log
+PATTERNS
+}
+
+# Same contract every gc-*.sh in this tree carries: refuse to operate on `/`,
+# on $HOME, or on a path that does not resolve. $HOME matters specifically -
+# `$HOME/.multi-agent/` is a real directory the installer knows about, so a
+# caller that passed the wrong root would have had `prune_empty` delete a file
+# out of it. Callers never check the return value; refusing is silent and safe.
+#
+# One consequence worth knowing: offload-ref.sh and bulk-read.sh fall back to
+# $PWD when they are not inside a repo, so offloading from $HOME itself now
+# skips writing the ignore file. The payload is still written; only the ignore
+# is skipped, and $HOME/.multi-agent/ is a tree the installer prunes anyway.
+ma_hygiene_safe_root() {
+  local root="${1:-}" resolved
+  [ -n "$root" ] || return 1
+  resolved=$(cd "$root" 2>/dev/null && pwd -P) || return 1
+  [ -n "$resolved" ] || return 1
+  [ "$resolved" = "/" ] && return 1
+  [ "$resolved" = "$(cd "$HOME" 2>/dev/null && pwd -P)" ] && return 1
+  printf '%s\n' "$resolved"
+}
+
+# Resolve the exclude file through --git-common-dir, not --git-dir: inside a
+# worktree the latter points at .git/worktrees/<name>, whose info/exclude is
+# per-worktree and dies with it.
+ma_hygiene_exclude_path() {
+  local root="$1" common
+  common=$(git -C "$root" rev-parse --path-format=absolute --git-common-dir 2>/dev/null) || return 1
+  [ -n "$common" ] || return 1
+  printf '%s/info/exclude\n' "$common"
+}
+
+ma_hygiene_ensure_exclusions() {
+  local root ex tmp
+  root=$(ma_hygiene_safe_root "${1:-}") || return 0
+  ex=$(ma_hygiene_exclude_path "$root") || return 0
+  mkdir -p "$(dirname "$ex")" 2>/dev/null || return 0
+  [ -f "$ex" ] || : > "$ex" 2>/dev/null || return 0
+
+  tmp="${ex}.ma-tmp.$$"
+  # Drop any previous managed block, keep everything else verbatim, then append
+  # the current one. sed is the portable way to delete an inclusive range.
+  if grep -qF "$MA_HYGIENE_BEGIN" "$ex" 2>/dev/null; then
+    sed "/^$(printf '%s' "$MA_HYGIENE_BEGIN" | sed 's/[][\.*^$\/]/\\&/g')$/,/^$(printf '%s' "$MA_HYGIENE_END" | sed 's/[][\.*^$\/]/\\&/g')$/d" "$ex" > "$tmp" 2>/dev/null || { rm -f "$tmp"; return 0; }
+  else
+    cat "$ex" > "$tmp" 2>/dev/null || { rm -f "$tmp"; return 0; }
+  fi
+
+  # A file whose last line has no newline would take the BEGIN marker onto the
+  # end of it. That corrupts the user's line AND leaves the marker unanchored,
+  # so `release_exclusions` can never match it again and the block is stuck in
+  # their file for good. Close the line first.
+  if [ -s "$tmp" ] && [ "$(tail -c 1 "$tmp" | wc -l | tr -d ' ')" = "0" ]; then
+    printf '\n' >> "$tmp" 2>/dev/null || { rm -f "$tmp"; return 0; }
+  fi
+
+  {
+    printf '%s\n' "$MA_HYGIENE_BEGIN"
+    ma_hygiene_patterns
+    printf '%s\n' "$MA_HYGIENE_END"
+  } >> "$tmp" 2>/dev/null || { rm -f "$tmp"; return 0; }
+
+  mv "$tmp" "$ex" 2>/dev/null || rm -f "$tmp"
+  return 0
+}
+
+ma_hygiene_release_exclusions() {
+  local root ex tmp
+  root=$(ma_hygiene_safe_root "${1:-}") || return 0
+  ex=$(ma_hygiene_exclude_path "$root") || return 0
+  [ -f "$ex" ] || return 0
+  grep -qF "$MA_HYGIENE_BEGIN" "$ex" 2>/dev/null || return 0
+
+  tmp="${ex}.ma-tmp.$$"
+  sed "/^$(printf '%s' "$MA_HYGIENE_BEGIN" | sed 's/[][\.*^$\/]/\\&/g')$/,/^$(printf '%s' "$MA_HYGIENE_END" | sed 's/[][\.*^$\/]/\\&/g')$/d" "$ex" > "$tmp" 2>/dev/null || { rm -f "$tmp"; return 0; }
+  mv "$tmp" "$ex" 2>/dev/null || rm -f "$tmp"
+  return 0
+}
+
+# `*` and not a list of children: an ignore file that names its siblings does
+# not name itself, so .multi-agent/.gitignore stayed permanently untracked -
+# the one piece of residue the guard existed to prevent. Git reads an ignore
+# file whether or not it is itself ignored, so self-exclusion is safe.
+ma_hygiene_local_gitignore() {
+  local root gi
+  root=$(ma_hygiene_safe_root "${1:-}") || return 0
+  gi="$root/.multi-agent/.gitignore"
+  mkdir -p "$root/.multi-agent" 2>/dev/null || return 0
+  if [ ! -f "$gi" ] || ! grep -q '^\*$' "$gi" 2>/dev/null; then
+    printf '# Local run artefacts  -  never commit. Ignores this file too.\n*\n' > "$gi" 2>/dev/null || return 0
+  fi
+  return 0
+}
+
+# rmdir, never rm -rf: it fails harmlessly when anything is left, which is the
+# behaviour we want. An empty .worktrees/ and .pipeline/evidence/ survive a
+# clean run today and read as leftovers to anyone looking at the checkout.
+ma_hygiene_prune_empty() {
+  local root d
+  root=$(ma_hygiene_safe_root "${1:-}") || return 0
+  for d in "$root/.pipeline/evidence" "$root/.pipeline" "$root/.worktrees/.archive" "$root/.worktrees" "$root/.multi-agent/refs"; do
+    [ -d "$d" ] && rmdir "$d" 2>/dev/null
+  done
+
+  # .multi-agent survives the loop above because it still holds the .gitignore
+  # this library wrote. That file is ours, so a directory holding nothing else
+  # is residue, not user data - but `memory/` there IS user data and is never
+  # touched (see commands/multi-agent/uninstall/SKILL.md).
+  if [ -d "$root/.multi-agent" ]; then
+    local leftover
+    leftover=$(ls -A "$root/.multi-agent" 2>/dev/null)
+    if [ "$leftover" = ".gitignore" ]; then
+      rm -f "$root/.multi-agent/.gitignore" 2>/dev/null
+      rmdir "$root/.multi-agent" 2>/dev/null
+    fi
+  fi
+  return 0
+}

package/pipeline/lib/vercel-deploy.sh

@@ -23,7 +23,8 @@
 #   pipeline/lib/vercel-deploy.sh doctor                       # env + CLI check
 #
 # Environment:
-#   VERCEL_TOKEN           -  required for deploy (resolved from prefs keychainMapping if unset)
+#   VERCEL_TOKEN           -  required for deploy; when unset it is resolved from
+#                             prefs keychainMapping.vercel via credential-store.sh
 #   VERCEL_ORG_ID          -  optional, scopes deploys to a team
 #   VERCEL_PROJECT_ID      -  optional, links to a specific project
 #   VERCEL_DEPLOY_QUIET    -  when set, suppresses progress lines (raw CLI output stays redacted)
@@ -63,8 +64,44 @@ cmd_redact() {
   redact_filter
 }
 
+# Resolve VERCEL_TOKEN from the credential store when the environment has none.
+# The header has promised "resolved from prefs keychainMapping if unset" since
+# this wrapper was written, but nothing ever read the store: the block below
+# sourced the resolver only to name it in an error message. Both `doctor` and
+# `deploy` call this now, so the diagnostic can no longer report "unset" for a
+# token a deploy would have found.
+#
+# credential-store.sh takes the LOGICAL key and maps it through
+# prefs.global.keychainMapping itself, so `get vercel` is the whole mechanism.
+# Command substitution, never argv: the CLI echoes its own arguments on retry.
+ma_vercel_resolve_token() {
+  [ -z "${VERCEL_TOKEN:-}" ] || return 0
+  local _r
+  for _r in \
+    "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)/credential-store-resolver.sh" \
+    "$HOME/.claude/lib/credential-store-resolver.sh" \
+    "$HOME/.copilot/lib/credential-store-resolver.sh" \
+    "$HOME/.codex/lib/credential-store-resolver.sh"; do
+    [ -f "$_r" ] || continue
+    # shellcheck source=/dev/null
+    . "$_r" 2>/dev/null || true
+    if [ -n "${CRED_STORE:-}" ]; then break; fi
+  done
+  [ -n "${CRED_STORE:-}" ] || return 0
+  local _tok
+  _tok=$("$CRED_STORE" get vercel 2>/dev/null || true)
+  # Only export a real value. Exporting an empty VERCEL_TOKEN would hand every
+  # child process a defined-but-blank variable where it previously saw none,
+  # and "set to nothing" reads differently from "unset" to the Vercel CLI.
+  [ -n "$_tok" ] || return 0
+  VERCEL_TOKEN="$_tok"
+  export VERCEL_TOKEN
+  return 0
+}
+
 cmd_doctor() {
   local rc=0
+  ma_vercel_resolve_token
   if command -v vercel >/dev/null 2>&1; then
     echo "vercel: $(vercel --version 2>&1 | redact_filter | head -1)"
   else
@@ -109,28 +146,10 @@ cmd_deploy() {
     exit 1
   fi
 
+  ma_vercel_resolve_token
   if [ -z "${VERCEL_TOKEN:-}" ]; then
-    # Route the credential-helper hint through the resolver instead of a
-    # hardcoded ~/.claude path so Copilot-only installs get a usable command.
-    # The resolver ships alongside this wrapper in lib/; fall back to the
-    # per-CLI install locations when running from a different cwd layout.
-    # shellcheck source=/dev/null
-    # Existence check before sourcing: `. <missing>` aborts the shell under `set -e`,
-    # `||` included, so a `.`-chain reaches neither its later candidates nor its error
-    # branch. The loop also covers all three hosts - the chain it replaced knew only
-    # .claude and .copilot, so a Codex-only install could not resolve at all.
-    for _cred_resolver in \
-      "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)/credential-store-resolver.sh" \
-      "$HOME/.claude/lib/credential-store-resolver.sh" \
-      "$HOME/.copilot/lib/credential-store-resolver.sh" \
-      "$HOME/.codex/lib/credential-store-resolver.sh"; do
-      [ -f "$_cred_resolver" ] || continue
-      # shellcheck source=/dev/null
-      . "$_cred_resolver" 2>/dev/null || true
-      if [ -n "${CRED_STORE:-}" ]; then break; fi
-    done
-    unset _cred_resolver
-    echo "ERROR: VERCEL_TOKEN not set. Resolve via env or keychain ('${CRED_STORE:-credential-store.sh} get <vercel-key>')." >&2
+    echo "ERROR: VERCEL_TOKEN not set and keychainMapping.vercel resolved nothing." >&2
+    echo "Map it once: point prefs.global.keychainMapping.vercel at the keychain item holding the token." >&2
     echo "Hint: vercel CLI accepts the token via env var; do NOT pass --token= on argv (leaks on retry)." >&2
     exit 1
   fi

package/pipeline/multi-agent-refs/features/doctor.md

@@ -195,3 +195,15 @@ read the registration and stopped would have called that healthy.
 Free space on the volume holding `$HOME`. WARN under 2 GB: a worktree plus a
 build is the largest thing a run writes, and ENOSPC mid-run corrupts the state
 file it was writing at the time.
+
+### worktree-residue
+
+Worktrees left under `<repo>/.worktrees/` in the repository the caller is
+standing in. WARN at five or more, or at 2 GB. A finished task removes its own
+worktree at PR time, but a run that stops before Phase 6 never reaches that
+step and nothing else collects it: the finalizer only runs on success, and
+`gc-worktrees` only sweeps entries git has already forgotten. Each survivor is
+a full second checkout, so the total is measured in gigabytes rather than
+megabytes. SKIP outside a git repository - a project name in prefs is a name,
+not a path, and guessing checkout locations to produce a number is how a
+diagnostic starts lying.

package/pipeline/multi-agent-refs/features/model-fallback.md

@@ -121,10 +121,10 @@ evidence, and there is now one fewer of them. Triage also runs on `opus`, which
 makes it the same model as Reviewer 1; the Step 3 anonymisation requirement
 already covers that case and is not optional here.
 
-**Cost accounting.** `prefs.global.costBudget.priceAt` defaults to `fable` to
+**Cost accounting.** `prefs.global.costBudget.pricingModel` defaults to `fable` to
 keep the estimate an upper bound. With the rung off, that default prices every
 call above what it can cost and trips the budget ceiling early, which then
-triggers a downgrade nobody needed. Set `priceAt` to `opus` alongside
+triggers a downgrade nobody needed. Set `pricingModel` to `opus` alongside
 `fableEnabled: false`.
 
 No log line is emitted per dispatch for this: it is a configured absence, not a

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

@@ -158,6 +158,7 @@ The shell driver auto-delegates to `~/.claude/scripts/keychain.py` on macOS / Li
 | `graylog_test`     | Graylog (test)     | `${USER}_Graylog_Test_Access_Token` | API Token, optional  -  unset falls back to `graylog` | Same page on the TEST instance; optional |
 | `firebase`         | Firebase           | `${USER}_Firebase_Access_Json`     | Service-account JSON, as issued. One key per Firebase project; extras are named `..._Json_<projectId>` and listed in `global.firebase.accounts[]` | Firebase Console -> Project settings -> Service accounts -> Generate new private key |
 | `jenkins`          | Jenkins CI         | `${USER}_Jenkins_Access_Token`     | API Token | Jenkins -> User -> Configure -> API Token |
+| `vercel`           | Vercel deploys     | `${USER}_Vercel_Access_Token`      | Access Token | Vercel -> Account Settings -> Tokens. Read by `vercel-deploy.sh`; never passed on argv |
 | `appstore_connect_key_id` | App Store Connect | `${USER}_AppStoreConnect_Key_Id` | Identifier, not a secret | App Store Connect -> Users and Access -> Integrations -> App Store Connect API |
 | `appstore_connect_issuer_id` | App Store Connect | `${USER}_AppStoreConnect_Issuer_Id` | Identifier, not a secret | Same page as the key id; one issuer id per team |
 | `appstore_connect_apple_id` | App Store Connect | `${USER}_AppStoreConnect_Apple_Id` | Email address | The Apple ID itself; no generation step |

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

@@ -63,7 +63,7 @@ Knowledge files grow over time. Maintenance rules:
   and a rebuild is seconds, so age is the wrong question to ask of it.
 - Stale entries are added to the prompt with a "STALE  -  verify before relying" tag
 - `prune-logs` does not touch knowledge  -  only deletes logs and state
-- `purge` does not touch knowledge either  -  separate command: `/multi-agent clear-knowledge {project}`
+- `purge` does not touch knowledge either. Today the only removal path is `/multi-agent:uninstall --all-data`, which drops every project's knowledge at once; there is no per-project clear yet
 
 ---
 

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

@@ -447,14 +447,15 @@ 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 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):
+**Repo residue guard (required once per repo, idempotent):** keep every path the pipeline writes - `.worktrees/`, `.pipeline/`, `.multi-agent/` and the loose logs - out of the index via the clone-local exclude file (never committed, so no PR noise). One call; the rationale is in the lib header:
 
 ```bash
-ex="$(git -C "$PROJECT_ROOT" rev-parse --path-format=absolute --git-common-dir)/info/exclude"
-mkdir -p "$(dirname "$ex")"
-grep -qxF '.worktrees/' "$ex" 2>/dev/null || printf '.worktrees/\n' >> "$ex"
+. "$HOME/.claude/lib/repo-hygiene.sh"
+ma_hygiene_ensure_exclusions "$PROJECT_ROOT"
 ```
 
+Rewritten on each call, so an older checkout picks up new entries; lines a human added are never touched.
+
 **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
@@ -468,14 +469,13 @@ scan, `shadow-git.sh` excludes, and the shared walkers (`extract-conventions.sh`
 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):
 
 ```bash
+. "$HOME/.claude/lib/repo-hygiene.sh"
 for proj in "${PROJECTS[@]}"; do
   WT_PATH="$proj/.worktrees/$BRANCH_DIR/"
   git -C "$proj" worktree prune 2>/dev/null || true               # heal stale admin state
   git -C "$proj" worktree list --porcelain | grep -qF "$WT_PATH" \
     && git -C "$proj" worktree unlock "$WT_PATH" 2>/dev/null || true
-  ex="$(git -C "$proj" rev-parse --path-format=absolute --git-common-dir)/info/exclude"
-  mkdir -p "$(dirname "$ex")"
-  grep -qxF '.worktrees/' "$ex" 2>/dev/null || printf '.worktrees/\n' >> "$ex"   # residue guard
+  ma_hygiene_ensure_exclusions "$proj"                             # residue guard
   git -C "$proj" worktree add "$WT_PATH" -b "$BRANCH" "origin/$BASE_BRANCH"
   git -C "$WT_PATH" config user.name  "${proj_identity_name}"
   git -C "$WT_PATH" config user.email "${proj_identity_email}"

package/pipeline/multi-agent-refs/phases/phase-2-planning.md

@@ -120,7 +120,7 @@ Based on Phase 1 `detectedStack`, assign relevant skills:
 
 #### Output contract
 
-Phase 2 produces an object conforming to `$HOME/.claude/schemas/planning-output.schema.json`  -  `tasks[]` with `id`, `subject`, `targetFiles`, `complexity`, `blockedBy`, plus optional `architectureNotes` and `mode`. Phase 3 reads `tasks[]` in dependency order; the schema's `blockedBy` field drives the ready-task picker.
+Phase 2 produces an object conforming to `$HOME/.claude/schemas/planning-output.schema.json`  -  `tasks[]` with `id`, `title`, `type`, `files`, plus optional `dependsOn` and `acceptanceCriteria`. Phase 3 reads `tasks[]` in dependency order; the schema's `dependsOn` field drives the ready-task picker.
 
 **Required: validator gate (deterministic)  -  run on the persisted file before the approval gate renders the plan; the validator's exit code decides, not the LLM turn:**
 

package/pipeline/multi-agent-refs/phases/phase-3-dev.md

@@ -49,7 +49,7 @@ The analysis document is the SOLE design source in Phase 3. Variant choices, pad
 
 #### Input contract
 
-Phase 3 consumes the Phase 2 output object conforming to `$HOME/.claude/schemas/planning-output.schema.json`  -  the task graph (`tasks[]` with `id`, `subject`, `targetFiles`, `complexity`, `blockedBy`) plus the architecture review notes. Tasks execute in dependency order; the schema's `blockedBy` field drives the ready-task picker. In a Short run (no Phase 2), Opus generates the equivalent task list inline before entering the loop below.
+Phase 3 consumes the Phase 2 output object conforming to `$HOME/.claude/schemas/planning-output.schema.json`  -  the task graph (`tasks[]` with `id`, `title`, `type`, `files`, and optional `dependsOn` / `acceptanceCriteria`) plus the architecture review notes. Tasks execute in dependency order; the schema's `dependsOn` field drives the ready-task picker. In a Short run (no Phase 2), Opus generates the equivalent task list inline before entering the loop below.
 
 **Plan Todo iteration (opt-in)**: gated by `prefs.global.planTodos.enabled` (default: `false`). When enabled and Phase 2 Step 4.5 emitted a `plan.todos[]`, Phase 3 iterates via `$HOME/.claude/lib/plan-todos.sh next/start/complete/fail` instead of walking `tasks[]` directly. When disabled, the loop walks `tasks[]` from `planning-output`  -  TDD contract is unchanged. Full helper loop + state semantics: `$HOME/.claude/multi-agent-refs/features/plan-todos.md`. A todo with `sourceTag: Reuse` binds the file analysis already found; `Modify` edits in place. Writing a new file over a `Reuse` step is a Locked 11 violation and Phase 4 flags it.
 

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

@@ -126,7 +126,7 @@ Tier 1 / Tier 2 records print `screenshotUrl` from the captured evidence (Tier 2
        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.
+     Phase 0's repo 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/rules.md

@@ -161,11 +161,10 @@ This is the single source of truth. When a contributor or model is unsure where
 Provider tools that print failed argv on retry leak credentials into the conversation transcript. Every Vercel call from the pipeline (Phase 6 deploy hooks, Phase 7 site updates, manual `vercel deploy` shells) MUST go through the wrapper:
 
 ```bash
-# CORRECT  -  token via env var, output redacted automatically. Token resolution
-# goes through the cross-platform credential helper so the same snippet works
-# on macOS / Linux / Windows installs:
-VERCEL_TOKEN="$(~/.claude/lib/credential-store.sh get mmerterden_Vercel_Access_Token)" \
-  bash $HOME/.claude/lib/vercel-deploy.sh deploy --prod
+# CORRECT  -  the wrapper resolves the token itself, via the logical key `vercel`
+# that keychainMapping maps to this machine's item. Never name the item here.
+# An explicit VERCEL_TOKEN in the environment still wins.
+bash $HOME/.claude/lib/vercel-deploy.sh deploy --prod
 
 # Health check before deploy:
 bash $HOME/.claude/lib/vercel-deploy.sh doctor

package/pipeline/preferences-template.json

@@ -15,7 +15,8 @@
       "graylog_test": null,
       "usage_ingest": null,
       "firebase": null,
-      "jenkins": null
+      "jenkins": null,
+      "vercel": null
     },
     "tokenScripts": {},
     "platformIdentityRouting": {},

package/pipeline/schemas/prefs.schema.json

@@ -198,6 +198,10 @@
               "type": ["string", "null"],
               "description": "NPM registry token (npm.pkg.github.com or npmjs.com). Used by package publish flow."
             },
+            "vercel": {
+              "type": ["string", "null"],
+              "description": "Keychain item holding the Vercel access token. vercel-deploy.sh resolves it through credential-store.sh so the value never reaches argv, where the CLI would leak it on a retry. Absent = deploys need VERCEL_TOKEN in the environment."
+            },
             "appstore_connect_key_id": {
               "type": ["string", "null"],
               "description": "App Store Connect API key ID. Tier 1 of the App Store Connect access chain, used by /multi-agent:store-ready Gate 2 (and its iOS alias /multi-agent:testflight-validation). An identifier rather than a secret; mapped anyway so every credential is read through the same layer. Creating an API key needs an Admin or App Manager role, which is why Tier 2 exists."

package/pipeline/scripts/bulk-read.sh

@@ -124,11 +124,19 @@ ROOT=$(git rev-parse --show-toplevel 2>/dev/null || true)
 REFS_DIR="$ROOT/.multi-agent/refs"
 NODE_ID=""
 if mkdir -p "$REFS_DIR" 2>/dev/null; then
-  GITIGNORE="$ROOT/.multi-agent/.gitignore"
-  if [ ! -f "$GITIGNORE" ]; then
-    printf '# Local run artefacts  -  never commit.\nmemory/\nrefs/\n' > "$GITIGNORE"
-  elif ! grep -q '^refs/$' "$GITIGNORE" 2>/dev/null; then
-    printf 'refs/\n' >> "$GITIGNORE"
+  # Shared with offload-ref.sh via pipeline/lib/repo-hygiene.sh. `../lib` resolves in
+  # both layouts: pipeline/scripts -> pipeline/lib in the repo, ~/.claude/scripts ->
+  # ~/.claude/lib installed. Fall back to writing it inline if the lib is absent,
+  # so this script stays usable standalone.
+  _MA_HYG="$(dirname "${BASH_SOURCE[0]}")/../lib/repo-hygiene.sh"
+  if [ -f "$_MA_HYG" ]; then
+    . "$_MA_HYG"
+    ma_hygiene_local_gitignore "$ROOT"
+  else
+    GITIGNORE="$ROOT/.multi-agent/.gitignore"
+    if [ ! -f "$GITIGNORE" ] || ! grep -q '^\*$' "$GITIGNORE" 2>/dev/null; then
+      printf '# Local run artefacts  -  never commit. Ignores this file too.\n*\n' > "$GITIGNORE"
+    fi
   fi
   if command -v shasum >/dev/null 2>&1; then
     DIGEST=$(shasum -a 256 "$FILE" | awk '{print substr($1,1,8)}')

package/pipeline/scripts/doctor.mjs

@@ -84,6 +84,7 @@ const CHECK_IDS = [
   "task-tools",
   "mcp-registration",
   "disk-space",
+  "worktree-residue",
 ];
 
 // Only these five may return BLOCK. Enforced below, not merely documented: a
@@ -641,6 +642,59 @@ function checkDiskSpace() {
   ok("disk-space");
 }
 
+// A finished task removes its own worktree at PR time, but a run that dies
+// before Phase 6 never reaches that step and nothing else collects it: the
+// finalizer only runs on success and gc-worktrees only sweeps entries git no
+// longer knows about. So worktrees accumulate silently, and each one is a full
+// second checkout. Measured on one real iOS repo: 15 left behind, 11 GB.
+//
+// Only the repo the caller is standing in is examined. A project name in prefs
+// is a name, not a path, and guessing checkout locations to report a number is
+// how a diagnostic starts lying.
+function checkWorktreeResidue() {
+  let repo;
+  try {
+    repo = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    skip("worktree-residue", "not inside a git repository, so there is no checkout to measure");
+    return;
+  }
+  const wt = join(repo, ".worktrees");
+  let entries;
+  try {
+    entries = readdirSync(wt).filter((n) => n !== ".DS_Store" && n !== ".archive");
+  } catch {
+    ok("worktree-residue");
+    return;
+  }
+  if (entries.length === 0) {
+    ok("worktree-residue");
+    return;
+  }
+  let gb = null;
+  try {
+    const out = execFileSync("du", ["-sk", wt], { encoding: "utf8" });
+    const kb = Number(out.trim().split(/\s+/)[0]);
+    if (Number.isFinite(kb)) gb = kb / 1024 / 1024;
+  } catch {
+    /* du is not everywhere; the count alone is still worth reporting */
+  }
+  const size = gb === null ? "" : `, ${gb.toFixed(1)} GB`;
+  if (entries.length >= 5 || (gb !== null && gb >= 2)) {
+    report(
+      "worktree-residue",
+      "WARN",
+      `${entries.length} worktree(s) left under ${wt}${size}; runs that stopped before Phase 6 are never collected`,
+      "run /multi-agent:garbage-collect, or /multi-agent:kill for a task you know is dead",
+    );
+    return;
+  }
+  ok("worktree-residue");
+}
+
 /* ------------------------------------------------------------------ main -- */
 
 function main() {
@@ -675,7 +729,7 @@ function main() {
     } else {
       process.stdout.write(`${line.severity} ${line.id}  -  ${line.problem}  -  ${line.step}\n`);
       process.stdout.write(
-        "\n-> indeterminate: the layout did not resolve, so 13 checks did not run\n",
+        `\n-> indeterminate: the layout did not resolve, so ${CHECK_IDS.length - 1} checks did not run\n`,
       );
     }
     process.exitCode = 4;
@@ -694,6 +748,7 @@ function main() {
   checkTaskTools();
   checkMcpRegistration();
   checkDiskSpace();
+  checkWorktreeResidue();
 
   const blocked = results.filter((r) => r.severity === "BLOCK");
   const warned = results.filter((r) => r.severity === "WARN");

package/pipeline/scripts/gc-tmp.sh

@@ -97,8 +97,24 @@ NAME_ARGS=(
   -o -name 'context-links-*'
   -o -name 'context-by-type-*'
   -o -name 'analysis-*'
+  -o -name 'complaint-analysis-*'
+  -o -name 'generate-issue-*'
+  -o -name 'cred-inventory-*'
+  -o -name 'pr-body-*'
+  -o \( -name '*-wiki' -type d \)
 )
 
+# `complaint-analysis-*` needs its own entry: find matches the basename against
+# the whole glob, so `analysis-*` never matched it. Same for the other three,
+# which were writing into $ROOT with nothing sweeping them (phase-0-init.md,
+# phase-6-commit.md, generate-issue.md).
+#
+# `*-wiki` is the one loose pattern here, and a suffix glob over $ROOT could
+# name something a person created. It is narrowed twice: `-type d` above, and
+# the `.git` check in the loop below - the pipeline's only `*-wiki` artefact is
+# a shallow clone (analysis/evidence.md), so a directory without a `.git` is
+# somebody else's and is left alone.
+
 MTIME_ARGS=()
 if [ "$OLDER_MIN" -gt 0 ]; then
   MTIME_ARGS=(-mmin "+$OLDER_MIN")
@@ -114,6 +130,20 @@ while IFS= read -r -d '' p; do
     skipped_active=$((skipped_active + 1))
     continue
   fi
+  # The `.git` requirement belongs to the `*-wiki` pattern alone. Checking the
+  # suffix first would re-narrow entries an unambiguous prefix already claimed:
+  # `multi-agent-foo-wiki` ends in `-wiki`, and demanding a `.git` there would
+  # spare scratch that `multi-agent-*` has always swept unconditionally.
+  case "${p##*/}" in
+    multi-agent-* | issue-progress-* | channels-* | context-links-* | context-by-type-* | \
+      analysis-* | complaint-analysis-* | generate-issue-* | cred-inventory-* | pr-body-*) ;;
+    *-wiki)
+      # See the NAME_ARGS note: only our shallow clones, never a user's folder.
+      if [ ! -e "$p/.git" ]; then
+        continue
+      fi
+      ;;
+  esac
   matches+=("$p")
 done < <(find "$ROOT" -mindepth 1 -maxdepth 1 \( "${NAME_ARGS[@]}" \) ${MTIME_ARGS[@]+"${MTIME_ARGS[@]}"} -print0 2>/dev/null)
 

package/pipeline/scripts/gc-worktrees.sh

@@ -12,8 +12,13 @@
 #      "Subproject commit" entry by a blanket `git add -A` before the
 #      residue guard existed. --yes runs `git rm --cached` (the commit
 #      itself stays yours to make).
-#   4. missing residue guard          -> ensures `.worktrees/` is in
-#      .git/info/exclude so the gitlink class cannot re-occur.
+#   4. missing residue guard          -> writes the managed block in
+#      .git/info/exclude (`.worktrees/`, `.pipeline/`, `.multi-agent/` and
+#      the loose run logs) so none of them can reach the index. The block is
+#      rewritten on each call, so a repo guarded by the old one-line form is
+#      upgraded in place.
+#   5. empty artefact parents         -> rmdir only, so a `.worktrees/` or
+#      `.pipeline/` left behind by a finished run stops reading as residue.
 #
 # Registered, healthy worktrees are NEVER touched. Finishing a task removes its
 # own worktree in Phase 6 (worktree-finalize, v14.1.0+); killing one is
@@ -143,22 +148,39 @@ $gitlinks
 EOF
 fi
 
-# 4. Residue guard: keep .worktrees/ out of the index from now on.
+# 4. Residue guard: keep every pipeline artefact out of the index from now on.
+# `.worktrees/` was the only entry for a long time, which left `.pipeline/` and
+# `.multi-agent/` writable into the branch; the managed block in repo-hygiene.sh
+# covers all of them and is rewritten on each call, so an old checkout upgrades.
 ex="$(git -C "$REPO" rev-parse --path-format=absolute --git-common-dir 2>/dev/null)/info/exclude"
-if [ -n "${ex%/info/exclude}" ] && ! grep -qxF '.worktrees/' "$ex" 2>/dev/null; then
-  if [ "$DELETE" -eq 1 ]; then
-    mkdir -p "$(dirname "$ex")" \
-      && printf '.worktrees/\n' >> "$ex" \
-      && { echo "→ added .worktrees/ to .git/info/exclude (residue guard)"; changed=$((changed + 1)); }
+_MA_HYG="$(dirname "${BASH_SOURCE[0]}")/../lib/repo-hygiene.sh"
+[ -f "$_MA_HYG" ] && . "$_MA_HYG"
+if [ -n "${ex%/info/exclude}" ] && ! grep -qF "${MA_HYGIENE_BEGIN:-# >>> multi-agent pipeline (managed) >>>}" "$ex" 2>/dev/null; then
+  if ! command -v ma_hygiene_ensure_exclusions >/dev/null 2>&1; then
+    # The guard is the whole point of step 4. Going quiet when the library is
+    # missing would leave the repo unguarded and say nothing, which is the one
+    # outcome worse than failing.
+    echo "gc-worktrees: WARN  -  $_MA_HYG not found; the residue guard was NOT written" >&2
+  elif [ "$DELETE" -eq 1 ]; then
+    ma_hygiene_ensure_exclusions "$REPO"
+    echo "→ wrote the managed residue block to .git/info/exclude"
+    changed=$((changed + 1))
   else
-    echo "would add .worktrees/ to .git/info/exclude (residue guard)"
+    echo "would write the managed residue block to .git/info/exclude"
   fi
 fi
 
+# 5. Artefact parents left empty by a finished run read as leftovers to anyone
+# looking at the checkout. rmdir, never rm -rf: it fails harmlessly if anything
+# is still there.
+if [ "$DELETE" -eq 1 ] && command -v ma_hygiene_prune_empty >/dev/null 2>&1; then
+  ma_hygiene_prune_empty "$REPO"
+fi
+
 total=$(( ${#orphans[@]} + $(printf '%s' "$gitlinks" | grep -c . || true) ))
 if [ "$DELETE" -eq 1 ]; then
   echo "══ gc-worktrees: applied $changed change(s) in $REPO ══"
-elif [ "$total" -eq 0 ] && [ "$pruned" -eq 0 ] && { [ -z "${ex%/info/exclude}" ] || grep -qxF '.worktrees/' "$ex" 2>/dev/null; }; then
+elif [ "$total" -eq 0 ] && [ "$pruned" -eq 0 ] && { [ -z "${ex%/info/exclude}" ] || grep -qF "${MA_HYGIENE_BEGIN:-# >>> multi-agent pipeline (managed) >>>}" "$ex" 2>/dev/null; }; then
   echo "gc-worktrees: no worktree residue in $REPO  -  nothing to do"
 else
   echo "══ gc-worktrees: dry-run  -  re-run with --yes to apply ══"

package/pipeline/scripts/keychain.py

@@ -189,7 +189,7 @@ def _macos_find(args: list[str]) -> Optional[str]:
 
 def get(label: str, account: Optional[str] = None) -> Optional[str]:
     """Lookup by label first, then by service name. Two coexisting conventions:
-    - User's manually-added tokens (e.g. mmerterden_Vercel_Access_Token) use -l (label).
+    - User's manually-added tokens (e.g. ${USER}_Vercel_Access_Token) use -l (label).
     - credential-store.sh-managed items use -s (service).
     The helper finds either."""
     pf = _ensure_backend()

package/pipeline/scripts/offload-ref.sh

@@ -158,11 +158,19 @@ mkdir -p "$REFS_DIR" 2>/dev/null || { cat "$BUF"; exit 0; }
 
 # Never commit an offloaded payload: it is a build log, and the worktree it
 # belongs to is deleted at the end of the task.
-GITIGNORE="$ROOT/.multi-agent/.gitignore"
-if [ ! -f "$GITIGNORE" ]; then
-  printf '# Local run artefacts  -  never commit.\nmemory/\nrefs/\n' > "$GITIGNORE"
-elif ! grep -q '^refs/$' "$GITIGNORE"; then
-  printf 'refs/\n' >> "$GITIGNORE"
+# Shared with bulk-read.sh via pipeline/lib/repo-hygiene.sh. `../lib` resolves in
+# both layouts: pipeline/scripts -> pipeline/lib in the repo, ~/.claude/scripts ->
+# ~/.claude/lib installed. Fall back to writing it inline if the lib is absent,
+# so this script stays usable standalone.
+_MA_HYG="$(dirname "${BASH_SOURCE[0]}")/../lib/repo-hygiene.sh"
+if [ -f "$_MA_HYG" ]; then
+  . "$_MA_HYG"
+  ma_hygiene_local_gitignore "$ROOT"
+else
+  GITIGNORE="$ROOT/.multi-agent/.gitignore"
+  if [ ! -f "$GITIGNORE" ] || ! grep -q '^\*$' "$GITIGNORE" 2>/dev/null; then
+    printf '# Local run artefacts  -  never commit. Ignores this file too.\n*\n' > "$GITIGNORE"
+  fi
 fi
 
 SLUG=$(printf '%s' "$LABEL" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9' '-' | sed 's/-\{1,\}/-/g; s/^-//; s/-$//')

package/pipeline/scripts/purge.sh

@@ -231,5 +231,16 @@ fi
 # Drop the now-empty .worktrees/ shell (only when truly empty).
 [ -d "$WT_ROOT" ] && rmdir "$WT_ROOT" 2>/dev/null
 
+# purge is the whole-repo teardown, so it is the one place the managed exclude
+# block should come back out - a per-task finalize must not, because other tasks
+# in the same repo still need the guard. Empty artefact parents go with it.
+# Only the marker-delimited block is removed; lines a human added stay.
+_MA_HYG="$(dirname "${BASH_SOURCE[0]}")/../lib/repo-hygiene.sh"
+if [ -f "$_MA_HYG" ]; then
+  . "$_MA_HYG"
+  ma_hygiene_prune_empty "$MAIN_WT"
+  ma_hygiene_release_exclusions "$MAIN_WT"
+fi
+
 echo "══ purge: removed $removed_wt worktree(s) and $removed_br local branch(es) in $MAIN_WT ══"
 exit 0

package/pipeline/scripts/worktree-finalize.sh

@@ -318,6 +318,15 @@ if git -C "$rp_pr" worktree remove "$rp_wt" 2>/dev/null; then
     ' 2>/dev/null || true
   fi
 
+  # The worktree is gone, but its parent `.worktrees/` stays behind as an empty
+  # directory and reads as leftover to anyone looking at the checkout. rmdir,
+  # never rm -rf: it fails harmlessly while any other task still has one.
+  _MA_HYG="$(dirname "${BASH_SOURCE[0]}")/../lib/repo-hygiene.sh"
+  if [ -f "$_MA_HYG" ]; then
+    . "$_MA_HYG"
+    ma_hygiene_prune_empty "$rp_pr"
+  fi
+
   emit
   exit 0
 fi

package/pipeline/skills/.skill-manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-09-09T18:15:55Z",
-  "skillCount": 207,
+  "generatedAt": "2026-09-13T12:09:01Z",
+  "skillCount": 209,
   "entries": [
     {
       "path": "shared/core/apple-archive-compliance/SKILL.md",
@@ -11,6 +11,10 @@
       "path": "shared/core/google-play-compliance/SKILL.md",
       "sha256": "356ff2b30f414e582bb215c4728696af8e249dfe924e16a550294e48fd9bdcf9"
     },
+    {
+      "path": "shared/core/multi-agent-analysis-jira/SKILL.md",
+      "sha256": "405e3afb02ad00cbcd1eace0ab3659d8d405dc78ec68c46f0836c23a83a43950"
+    },
     {
       "path": "shared/core/multi-agent-analysis-resolve/SKILL.md",
       "sha256": "ad59c484a3a251799101aaebfe1cf50ceb10a2e2a389d89c6d56e67ba331ef79"
@@ -47,6 +51,10 @@
       "path": "shared/core/multi-agent-diff-explain/SKILL.md",
       "sha256": "7cb37a224e61d66e350202ecfc5fbc6c33da3fe0718504a093602f5cde5b648f"
     },
+    {
+      "path": "shared/core/multi-agent-doctor/SKILL.md",
+      "sha256": "a9e6b8a764df223b9d6867cc9f2a89d93f989605891c829a81fc3e5ca139a1b2"
+    },
     {
       "path": "shared/core/multi-agent-feedback/SKILL.md",
       "sha256": "9ec0c33fdaef52691fac48ac582e665bb8eb87d59009feabf156f71728d977a4"
@@ -73,7 +81,7 @@
     },
     {
       "path": "shared/core/multi-agent-issue/SKILL.md",
-      "sha256": "a491d26b94a7c909f98be96f881010666fafedf6e323a6b75515cc26912dfc02"
+      "sha256": "aec8737af368b01c7e3133521c711861456c18b07e3829425e5c0485a0181051"
     },
     {
       "path": "shared/core/multi-agent-jira/SKILL.md",
@@ -101,7 +109,7 @@
     },
     {
       "path": "shared/core/multi-agent-manual-test/SKILL.md",
-      "sha256": "8d4501e9e1321146f7a1759fd5c8b4397cbd77d7a31fb265fabf7816386fba4b"
+      "sha256": "e7f7f8004d286c5b5b596f8659bcf57b2350eb9c67a55470bb2e9b714513a3a4"
     },
     {
       "path": "shared/core/multi-agent-prune-logs/SKILL.md",
@@ -117,7 +125,7 @@
     },
     {
       "path": "shared/core/multi-agent-refactor/SKILL.md",
-      "sha256": "83cc0567ede79eabc42045b4e39d6d3ec820e73a3e14e5f01ebff898cfdec117"
+      "sha256": "56b49a8216086961bc407a60b559942252a1aae3005b73811b1d40668758cc84"
     },
     {
       "path": "shared/core/multi-agent-resume-local/SKILL.md",
@@ -133,7 +141,7 @@
     },
     {
       "path": "shared/core/multi-agent-review-issue/SKILL.md",
-      "sha256": "f5579a33ea0e0ec6e601d539e22acd6c0bf65b3c95464c974f3fbddf286749e7"
+      "sha256": "d9c0a256d37febab7be7d00252710ca065bd4e8a186ef47e00c5898e48f53cf5"
     },
     {
       "path": "shared/core/multi-agent-review-jira/SKILL.md",
@@ -157,11 +165,11 @@
     },
     {
       "path": "shared/core/multi-agent-search/SKILL.md",
-      "sha256": "2a3a8c4a53b65b828c7093076a0ec05dc6b146825f7407f91b3852347717d94e"
+      "sha256": "32541ceca20c489814f9d948763d5237d4a71473a05683d9da262b8f6dea815b"
     },
     {
       "path": "shared/core/multi-agent-setup/SKILL.md",
-      "sha256": "dc5840da1022b6930fa28dab01ac15ad66fd720743fb7ecfcdf6c6d85b4410e6"
+      "sha256": "40dc72793cd6bd1054d6203275fbc9f4ecdd6d8dc5de8f2437e7f670f4c5c646"
     },
     {
       "path": "shared/core/multi-agent-stack/SKILL.md",
@@ -169,7 +177,7 @@
     },
     {
       "path": "shared/core/multi-agent-status/SKILL.md",
-      "sha256": "1137106f9af881834a970ca3dc748001e937666601d3fcb18b6913bb2cd1ac11"
+      "sha256": "436d1716ce5fc4977dadfce8a85b09877f93c626953739a7ad70eefbbcd25869"
     },
     {
       "path": "shared/core/multi-agent-steer/SKILL.md",
@@ -181,7 +189,7 @@
     },
     {
       "path": "shared/core/multi-agent-sync/SKILL.md",
-      "sha256": "c0e2c22d0f6da9a60f5552d6f47db0490a355ea4ce08722716470e03535e5418"
+      "sha256": "8f033b904e90926b15f6e5a8f8703b47a17373e5450921514633ea0a9edaf327"
     },
     {
       "path": "shared/core/multi-agent-test-accessibility/SKILL.md",
@@ -213,7 +221,7 @@
     },
     {
       "path": "shared/core/multi-agent-update/SKILL.md",
-      "sha256": "66d960a9c360ba0353b6496fde641c1a99834274bc0ac68932ed107b15411ccb"
+      "sha256": "e93e913473cb5d3a5810b30f26011a0d18754bed983890f4261b87972526d94a"
     },
     {
       "path": "shared/core/multi-agent/SKILL.md",

package/pipeline/skills/shared/core/multi-agent-sync/SKILL.md

@@ -207,7 +207,8 @@ When invoked with the `release` argument:
 ```
 1. REPO          Claude Code -> pipeline repo (genericized)
 2. VERIFY        Personal data scan -> 0 results
-3. LINT + TEST   ESLint + smoke tests
+3. LINT + TEST   ESLint + smoke tests (stale .skill-manifest.json fails here; re-sign
+                 it with sign-skills.sh whenever a SKILL.md moved)
 4. VERSION       package.json version bump (patch/minor/major)
 5. Commit + TAG  git commit + git tag v{VERSION}
 6. PUSH          git push --tags; publish is local (release.yml off)