@mmerterden/multi-agent-pipeline 12.7.0 → 12.8.0

package/CHANGELOG.md

@@ -16,6 +16,132 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ## [Unreleased]
 
+## [12.8.0] - 2026-07-26
+
+12.7.0 fixed nine gates that reported success without checking anything. This
+release is the level above that: gates that check correctly and never run, and a
+shipped surface that could not work where it was shipped to.
+
+### 117 maintainer smokes stopped shipping to users
+
+`pipeline/scripts/` was copied wholesale into `~/.claude/scripts/`, so every
+repository CI gate landed on every user's machine. Measured from a real install:
+of 117 installed smoke scripts, **100 failed** and 17 passed only by accident of
+not needing the repo. They resolve the repo root as `dirname($0)/../..`, which in
+an install layout is `$HOME`, and then read `package.json` / `install.js` /
+`node_modules`. What a user saw:
+
+```
+$ bash ~/.claude/scripts/smoke-install-layout.sh
+FAIL: install.js missing
+```
+
+A green repo gate, run in the wrong place, indistinguishable from a broken
+installation. Worse, `/multi-agent:update` actively instructed users to run
+`smoke-cross-cli-behavior.sh`, which reported "3 failed" for the same reason.
+
+The default for `smoke-*.sh` is now EXCLUDE, in both the install and the tarball.
+A smoke ships only when a command actually invokes it - `CONSUMER_SMOKES` in
+`install/_dev-only-files.mjs`, currently the two that `/multi-agent:update` runs.
+Both now resolve paths through the new `pipeline/scripts/_smoke-root.sh`, which
+handles the repo and install layouts, so `smoke-cross-cli-behavior.sh` reports
+20/20 from an install instead of 17/20.
+
+Also withheld: `run-smokes.mjs`, `eval-*.mjs`, `pipeline/eval/**`, `scorecard.mjs`,
+the linters, `validate-schemas.mjs`, and the fixture corpora - all of them need
+devDependencies or the repo tree. Install drops from 201 files to 73; the tarball
+from 977 to 753.
+
+`smoke-consumer-smoke-surface.sh` holds four invariants: the allowlist equals what
+commands invoke (drift either way fails), every consumer smoke uses the shared
+resolver, no maintainer smoke survives the install filter, and none survives into
+the tarball. `smoke-pack-contents.sh` now evaluates `files[]` the way npm does
+(last matching pattern wins, so a broad negation may be followed by a narrower
+re-inclusion - verified against npm directly) and reports an inert negation that
+guards nothing. `smoke-install-leak-gate.sh` step 4 previously asserted the
+OPPOSITE contract, naming three "essential" smokes that had to install; it now
+derives the expected set from `CONSUMER_SMOKES`.
+
+Fixed along the way: both installers computed the excluded-file count by summing
+`countFiles()` over the exclusion array, which returns 0 for every non-literal
+entry, so the count would have under-reported by 100+ files.
+
+### Four gates that were tested, green, and never ran
+
+Every gate in this repo checks its own behaviour. Nothing checked that a gate is
+*reachable*. Four were not - each with a passing unit test and a passing smoke,
+and no reference from `pipeline/commands/`, `multi-agent-refs/`, `agents/`,
+`skills/` or `install/`:
+
+- **`test-integrity-gate.mjs`** - the anti-reward-hacking control for a suite made
+  green by deleting tests. Now Phase 4 Step 1.76, emitting blocking findings that
+  merge into the reviewer findings at Step 3.0 (before the no-findings
+  short-circuit, which would otherwise skip triage entirely on a diff whose only
+  finding is a deleted test). No opt-out: a run that can switch off its own
+  anti-reward-hacking control cannot be trusted to report a pass.
+- **`review-scope.mjs`** - the reviewer-count cost gate. Now Phase 4 Step 1.77,
+  behind `prefs.global.reviewScopeGate` (default true). Every diff had been paying
+  for the full reviewer set.
+- **`audit-log.sh`** - the PAT-lookup audit trail. `.gitignore` carried defensive
+  globs for it and `/multi-agent:prune-logs` documented managing it, but
+  `credential-store.sh` never called it, so the trail was always empty. Now
+  written on every `get`, on both the success and the miss path, through the
+  Python delegate and the raw-shell path. Since the trail now actually grows,
+  `audit-log.sh` self-rotates past `AUDIT_ROTATE_AT_BYTES` (1 MB) rather than
+  depending on a launchd/cron install nothing ever told a user to set up.
+- **`write-state.mjs`** - the atomic `agent-state.json` writer with an advisory
+  lock, written for exactly the multi-repo race the phase docs create by sharing
+  one state file across worktrees. `operations.md` now documents it as the
+  required mechanism, with the exit codes a caller must handle, and
+  `phase-0-init.md` points at it where the shared file is introduced.
+
+Phase 4 Step 1.75 now scores the diff **once without `--top`**: both new gates
+need every scored file (a shrinking test file ranked 20th; whether any file is
+high-stakes), and the top-5 prompt hint is derived from that report instead of a
+second git walk.
+
+`smoke-gate-wiring.sh` sweeps every runtime script for a reference from the
+instruction surface, with maintainer tooling listed explicitly and by reason
+rather than being the silent default for anything unreferenced. It also pins the
+four wirings individually, and asserts the test-integrity gate is fed the full
+report rather than the truncated hint. It found two more scripts on the first run
+(`review-watch.sh`, `audit-log-rotate.sh`), both correctly user-launched.
+
+### Removed: the v9.1.0 legacy-v2 analysis escape hatch
+
+Triple-dead and still documented in three files. Its own text said "escape hatch
+removed in v9.2.0" - this is 12.8.0. The `prefs.global.legacyV2AnalysisAllowed` it
+depended on was never added to `prefs.schema.json`, and `global` is
+`additionalProperties: false`, so a user who configured it as documented produced
+a preferences file that fails validation. `template_version < v3` now simply
+aborts. The reclaimed budget paid for the two new phase-4 steps, so the fixed
+per-run context ceiling did not move.
+
+### Gate honesty
+
+- **The context ceiling can no longer be bypassed.** It was
+  `${CONTEXT_BUDGET_CEILING:-60000}` - the only env-overridable threshold in the
+  suite, so `CONTEXT_BUDGET_CEILING=999999` passed while measuring nothing. It is
+  a literal now, pinned by `test/context-budget-gate.test.mjs` (the companion to
+  `test/coverage-gate.test.mjs`, which already protects the coverage floors from
+  the same move). Headroom was 3.5% when this was written - precisely when raising
+  the number looks attractive. The test also prints current headroom so it shrinks
+  visibly instead of silently.
+- **The coverage claim names its denominator.** "coverage floors held" reads as a
+  repo-wide figure; c8 instruments JavaScript, and this repo carries ~30k lines of
+  shell and Python that no coverage number covers at all. The metric is now
+  "coverage floors held (JavaScript only)" and states the excluded size, matching
+  what the scorecard's UNMEASURED section already does for whole categories.
+
+### Also
+
+- `smoke-consumer-smoke-surface.sh` and `smoke-gate-wiring.sh` added to `ci-lite`;
+  the consumer-surface gate also runs in `release`, since a publish is the only
+  moment tarball contents become permanent.
+- `test/dev-only-files.test.mjs` (20 tests) covers the exclusion predicate,
+  including that a hypothetical new smoke is withheld by default and that runtime
+  scripts the phases invoke are not.
+
 ## [12.7.0] - 2026-07-26
 
 A refactor pass whose theme turned out to be one recurring defect: gates that

package/install/_common.mjs

@@ -239,6 +239,54 @@ export function pruneLegacyMultiAgentSkills(skillsDir) {
   return removed;
 }
 
+/**
+ * Trees an older installer created and no current one manages.
+ *
+ * A tree that stops being copied does NOT stop existing: the wipe-before-copy
+ * pattern only runs for trees the installer still writes, so dropping one from
+ * the installer leaves whatever it last wrote on every existing machine forever.
+ *
+ * `eval/` is the case that prompted this. An older version copied the eval
+ * corpora into `~/.claude/eval/`; the harnesses that read them are maintainer CI
+ * tooling and no longer ship, so neither installer references `eval` any more and
+ * neither did uninstall - 31 stale files sat there with nothing left that could
+ * ever read or remove them.
+ *
+ * @type {ReadonlyArray<{dir: string, reason: string}>}
+ */
+export const ABANDONED_TREES = Object.freeze([
+  {
+    dir: "eval",
+    reason: "eval corpora; the harnesses that read them are maintainer-only and no longer ship",
+  },
+]);
+
+/**
+ * Remove trees an older install left behind under `root`.
+ *
+ * @param {string} root e.g. `$HOME/.claude`
+ * @returns {number} directories removed
+ */
+export function pruneAbandonedTrees(root) {
+  let removed = 0;
+  for (const { dir, reason } of ABANDONED_TREES) {
+    const target = join(root, dir);
+    if (!existsSync(target)) continue;
+    if (dryRun) {
+      console.log(`    [dry-run] would remove abandoned tree ${target} (${reason})`);
+      removed++;
+      continue;
+    }
+    try {
+      rmSync(target, { recursive: true, force: true });
+      removed++;
+    } catch {
+      /* non-fatal - a leftover tree must never fail an install */
+    }
+  }
+  return removed;
+}
+
 /**
  * Copy a single file, honouring dry-run mode.
  * @param {string} src

package/install/_dev-only-files.mjs

@@ -1,18 +1,138 @@
 /**
- * Dev-only files excluded from end-user installs.
+ * Dev-only files excluded from end-user installs and from the published tarball.
  *
- * These reference the maintainer's private upstream and contain personal data
- * (org names, hostnames, emails) on the `from:` side of substitution rules.
- * End users never run them, so we keep them out of `~/.claude/scripts/` and
- * `~/.copilot/scripts/`.
+ * Two separate reasons live here, and they must not be conflated:
+ *
+ *   1. LEAK: the file references the maintainer's private upstream or carries
+ *      personal data (org names, hostnames, emails) on the `from:` side of a
+ *      substitution rule. Shipping it is a disclosure, not just noise.
+ *
+ *   2. MAINTAINER CI: the file is a repository gate. It resolves the repo root
+ *      as `dirname($0)/../..` and reads `package.json` / `install.js` /
+ *      `node_modules` / the git tree. In an install layout that path is `$HOME`,
+ *      so the script reports things like `FAIL: install.js missing` - a green
+ *      repo check that reads as a broken installation to whoever ran it.
+ *      Measured before this list existed: of 117 installed smoke scripts, 100
+ *      failed that way and 17 passed only by accident of not needing the repo.
+ *
+ * Reason 2 is why the default for `smoke-*.sh` is EXCLUDE. A smoke ships only
+ * when a command actually tells a user to run it - that set is CONSUMER_SMOKES
+ * below, and `smoke-consumer-smoke-surface.sh` fails if the two drift apart.
  *
  * @module install/_dev-only-files
  */
 
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Smoke suites an end user is instructed to run, and which therefore must work
+ * from an installed layout (`~/.claude/scripts/`) as well as from the repo.
+ *
+ * `/multi-agent:update` runs both as its post-update verification. Anything
+ * added here MUST resolve its paths through `_smoke-root.sh`, never through a
+ * bare `dirname($0)/../..`.
+ */
+export const CONSUMER_SMOKES = Object.freeze([
+  "smoke-schema-validation.sh",
+  "smoke-cross-cli-behavior.sh",
+]);
+
+/**
+ * Every `smoke-*.sh` that is NOT in CONSUMER_SMOKES. Expressed as one regex so a
+ * newly added smoke is excluded by default rather than shipping until someone
+ * notices - the safe direction for reason 2 above.
+ */
+export const MAINTAINER_SMOKES = new RegExp(
+  `^smoke-(?!${CONSUMER_SMOKES.map((n) => n.replace(/^smoke-/, "").replace(/\./g, "\\.")).join(
+    "|",
+  )}$)`,
+);
+
+/**
+ * Repository tooling that is not a smoke: the smoke runner itself, the eval
+ * harnesses, the scorecard, and the linters. All of them need devDependencies
+ * (`ajv`, `c8`, `eslint`) or the repo tree, neither of which exists in an
+ * install.
+ */
+const DEV_ONLY_TOOLING = Object.freeze([
+  "run-smokes.mjs",
+  "scorecard.mjs",
+  "lint-skills.mjs",
+  "lint-mcp-refs.mjs",
+  "check-md-links.mjs",
+  "validate-schemas.mjs", // validates the repo's own schema files, needs ajv
+  "sync-parity-check.sh",
+  "benchmark-phase-0.sh",
+  "test-gap-rules", // rule corpus for the repo's own test-gap gate
+]);
+
+/** Eval harnesses (`eval-*.mjs`) read `pipeline/eval/**`, which never ships. */
+const EVAL_HARNESSES = /^eval-.*\.mjs$/;
+
 export const DEV_ONLY_SCRIPTS = Object.freeze([
+  // --- reason 1: leak ---
   "smoke-figma-config-schema.sh",
   "smoke-personal-data.sh", // scanner contains the patterns it detects
   "smoke-install-leak-gate.sh", // same - scanner shadows the install pipeline
   "validate-prefs.mjs", // needs ajv (devDependency); end users have no node_modules here
   "fixtures", // smoke test fixtures live in the repo only, never ship to users
+  // --- reason 2: maintainer CI ---
+  ...DEV_ONLY_TOOLING,
+  EVAL_HARNESSES,
+  MAINTAINER_SMOKES,
 ]);
+
+/**
+ * True when `name` (a path relative to `pipeline/scripts/`) must not be
+ * installed. Shared by both installers' excluded-file counters and by
+ * `smoke-consumer-smoke-surface.sh`, so the count and the gate can never
+ * disagree with what `copyDir` actually filtered.
+ *
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function isDevOnlyScript(name) {
+  const rel = String(name).split("\\").join("/").replace(/^\//, "");
+  return DEV_ONLY_SCRIPTS.some((pat) =>
+    typeof pat === "string" ? rel === pat || rel.startsWith(pat + "/") : pat.test(rel),
+  );
+}
+
+/**
+ * How many files under `scriptsDir` `copyDir` will filter out.
+ *
+ * Walks the tree and applies `isDevOnlyScript` to the same relative paths
+ * `copyDir`'s filter sees, so the number printed by an install is the number
+ * actually withheld. The previous form summed `countFiles()` over the exclusion
+ * array, which silently returned 0 for every non-literal (regex) entry.
+ *
+ * @param {string} scriptsDir absolute path to `pipeline/scripts`
+ * @returns {number}
+ */
+export function countDevOnlyFiles(scriptsDir) {
+  let excluded = 0;
+  const walk = (abs, rel) => {
+    for (const entry of readdirSync(abs, { withFileTypes: true })) {
+      const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+      const childAbs = join(abs, entry.name);
+      if (entry.isDirectory()) {
+        // An excluded directory takes its whole subtree with it, exactly as
+        // cpSync's filter does when it returns false for the directory itself.
+        if (isDevOnlyScript(childRel)) excluded += countTree(childAbs);
+        else walk(childAbs, childRel);
+      } else if (isDevOnlyScript(childRel)) {
+        excluded++;
+      }
+    }
+  };
+  const countTree = (abs) => {
+    let n = 0;
+    for (const entry of readdirSync(abs, { withFileTypes: true })) {
+      n += entry.isDirectory() ? countTree(join(abs, entry.name)) : 1;
+    }
+    return n;
+  };
+  walk(scriptsDir, "");
+  return excluded;
+}

package/install/claude.mjs

@@ -27,13 +27,14 @@ import {
   ensureDir,
   ensureRealDir,
   isDryRun,
+  pruneAbandonedTrees,
   pruneLegacyMultiAgentSkills,
   removePipelineAgentFiles,
   wipeDir,
   writeFile,
 } from "./_common.mjs";
 import { copyExternalSkillsFiltered } from "./_platform-filter.mjs";
-import { DEV_ONLY_SCRIPTS } from "./_dev-only-files.mjs";
+import { DEV_ONLY_SCRIPTS, countDevOnlyFiles } from "./_dev-only-files.mjs";
 
 /**
  * Dead matcher written by pre-v11.4.1 installs. Hook matchers only ever see
@@ -64,6 +65,14 @@ export function installClaude(ctx) {
   const CLAUDE_LIB = join(home, ".claude", "lib");
   const CLAUDE_MA_REFS = join(home, ".claude", "multi-agent-refs");
 
+  // Before laying anything down: drop trees an older install created that no
+  // current installer manages. Wipe-before-copy only protects trees still being
+  // written, so an abandoned one persists on every existing machine forever.
+  const prunedTrees = pruneAbandonedTrees(join(home, ".claude"));
+  if (prunedTrees > 0) {
+    console.log(`  [Claude Code] Removed ${prunedTrees} abandoned tree(s) from an older install`);
+  }
+
   installCommands(pipelineSrc, CLAUDE_COMMANDS, useSymlinks);
   installMultiAgentRefs(pipelineSrc, CLAUDE_MA_REFS, useSymlinks);
   installScripts(pipelineSrc, CLAUDE_SCRIPTS, useSymlinks);
@@ -201,13 +210,10 @@ function installScripts(pipelineSrc, dest, useSymlinks) {
   if (!useSymlinks) ensureRealDir(dest);
   wipeDir(dest);
   copyDir(scriptsSrc, dest, { exclude: DEV_ONLY_SCRIPTS, useSymlinks });
-  // Count files actually excluded, not the array length: DEV_ONLY_SCRIPTS mixes
-  // individual .sh files with the `fixtures` directory (many files), so the
-  // array length under-counts the real exclusion.
-  const excludedCount = DEV_ONLY_SCRIPTS.reduce(
-    (n, name) => n + countFiles(join(scriptsSrc, name)),
-    0,
-  );
+  // Count files actually excluded by walking the tree: DEV_ONLY_SCRIPTS mixes
+  // literal names, whole directories, and regexes (the maintainer-smoke rule),
+  // so summing countFiles() over the array reported 0 for every regex entry.
+  const excludedCount = countDevOnlyFiles(scriptsSrc);
   const scriptCount = countFiles(scriptsSrc) - excludedCount;
   console.log(`    -> ${scriptCount} files copied to ${dest} (${excludedCount} dev-only excluded)`);
 }

package/install/copilot.mjs

@@ -23,7 +23,7 @@ import {
   writeFile,
 } from "./_common.mjs";
 import { copyExternalSkillsFiltered } from "./_platform-filter.mjs";
-import { DEV_ONLY_SCRIPTS } from "./_dev-only-files.mjs";
+import { DEV_ONLY_SCRIPTS, countDevOnlyFiles } from "./_dev-only-files.mjs";
 import { generateCopilotInstructions } from "./_copilot-instructions.mjs";
 
 /**
@@ -166,13 +166,10 @@ function installScripts(pipelineSrc, dest, useSymlinks) {
   if (!useSymlinks) ensureRealDir(dest);
   wipeDir(dest);
   copyDir(scriptsSrc, dest, { exclude: DEV_ONLY_SCRIPTS, useSymlinks });
-  // Count files actually excluded, not the array length: DEV_ONLY_SCRIPTS mixes
-  // individual .sh files with the `fixtures` directory (many files), so the
-  // array length under-counts the real exclusion.
-  const excludedCount = DEV_ONLY_SCRIPTS.reduce(
-    (n, name) => n + countFiles(join(scriptsSrc, name)),
-    0,
-  );
+  // Count files actually excluded by walking the tree: DEV_ONLY_SCRIPTS mixes
+  // literal names, whole directories, and regexes (the maintainer-smoke rule),
+  // so summing countFiles() over the array reported 0 for every regex entry.
+  const excludedCount = countDevOnlyFiles(scriptsSrc);
   const scriptCount = countFiles(scriptsSrc) - excludedCount;
   console.log(`    -> ${scriptCount} files copied to ${dest} (${excludedCount} dev-only excluded)`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "12.7.0",
+  "version": "12.8.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",
@@ -75,7 +75,22 @@
     "!pipeline/scripts/smoke-personal-data.sh",
     "!pipeline/scripts/validate-prefs.mjs",
     "!pipeline/scripts/smoke-install-leak-gate.sh",
-    "!docs/internal/**"
+    "!docs/internal/**",
+    "!pipeline/scripts/smoke-*.sh",
+    "!pipeline/scripts/run-smokes.mjs",
+    "!pipeline/scripts/eval-*.mjs",
+    "!pipeline/scripts/scorecard.mjs",
+    "!pipeline/scripts/lint-skills.mjs",
+    "!pipeline/scripts/lint-mcp-refs.mjs",
+    "!pipeline/scripts/check-md-links.mjs",
+    "!pipeline/scripts/validate-schemas.mjs",
+    "!pipeline/scripts/sync-parity-check.sh",
+    "!pipeline/scripts/benchmark-phase-0.sh",
+    "!pipeline/scripts/fixtures/**",
+    "!pipeline/scripts/test-gap-rules/**",
+    "!pipeline/eval/**",
+    "pipeline/scripts/smoke-schema-validation.sh",
+    "pipeline/scripts/smoke-cross-cli-behavior.sh"
   ],
   "devDependencies": {
     "@eslint/js": "^10.0.1",

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

@@ -65,7 +65,7 @@ When citing a Locked decision in code or docs, prefer `Locked <n> (<short label>
 27. **Evidence digest caches Phase 1b and 1c.** `evidence_digest = sha256(featureName || sorted(platforms) || repoEvidence.summary || conventions.summary)`. When the same feature name is invoked again against the same set of repos and the digest matches, Phase 1b and 1c are skipped and the cached `evidence.repoEvidence` / `evidence.conventions` is reused. Cache TTL is 24 hours; manual invalidation via `--no-cache` flag.
 28. **SwiftUI Preview block mandatory (iOS projection, SwiftUI only).** When the iOS file is produced AND the affected view is a SwiftUI view (detected via `import SwiftUI` + `: View` protocol conformance in `evidence.repoEvidence[<repo>].buckets.uiComponents`), Section 13.6 renders a Preview block table covering at minimum: canonical default (LTR Light), Dark, RTL, Dynamic Type accessibilityLarge, and one error variant. Loading state and edge-case variants are added when distinct from canonical. UIKit-only features (no SwiftUI view artefact) drop Section 13.6 with note `(N/A: UIKit-only feature)`. Preview macro convention (`#Preview` for Swift 5.9+ vs legacy `PreviewProvider`) is read from `evidence.conventions[<repo>].previewMacro`. Each Preview variant listed in Section 13.6 must have a matching row in Section 15.2 Snapshot Tests; a Preview without a snapshot row triggers a Section 20 Risk.
 29. **Variant usage explicit and bounded.** Section 6 inventory rows list which variants this feature consumes per component (concrete enum case + bool value). New Section 6.X (Variant Usage Matrix) catalogues the full variant axis vs. used subset with a rationale per excluded variant. Sections 13.6 (Preview) and 15.2 (Snapshot) cover only the used subset; expanding the variant set requires updating Section 6.X first.
-30. **Analysis as self-contained design bridge - no MCP outside analysis phase (BLOCKING, pipeline-wide, v9.0.0; legacy soft-skip v9.1.0).** The analysis document is the sole design source for every downstream phase. After Phase 1 of `/multi-agent:analysis` produces `analysis/<feature>-<platform>.md`, Phase 2 Planning, Phase 3 Dev, Phase 4 Review, Phase 5 Test, Phase 6 Commit, and Phase 7 Report consume only the analysis document plus repo Code Connect mappings (`*.figma.swift` / `*.figma.kt`). Calling `mcp__claude_ai_Figma__*`, hitting `api.figma.com`, or fetching a `figma.com/design/...` URL during Phase 2+ is a violation. Applies to every mode that runs Phase 2+: `/multi-agent`, `/multi-agent:autopilot`, `/multi-agent:local`, `/multi-agent:local-autopilot`, `/multi-agent:dev`, `/multi-agent:dev-autopilot`, `/multi-agent:dev-local`, `/multi-agent:dev-local-autopilot`. Hard requirement (v9.0.0): Phase 2 Pre-item and Phase 3 Pre-item (BLOCKING) abort the run when the analysis document is missing. **Legacy soft-skip (v9.1.0+):** existing v2 analyses (`template_version: v2`) emit `WARN: legacy v2 analysis doc detected; v3 expected. Re-run /multi-agent:analysis to regenerate. Continuing with reduced binding strength.` and the run continues when `prefs.global.legacyV2AnalysisAllowed == true` OR env `MULTI_AGENT_LEGACY_V2_ANALYSIS=allow` is set. The soft-skip degrades Pass B footnote enforcement to warning level and skips Phase 1c convention extraction (no `conventions[]` data in v2 docs). The escape hatch is removed in v9.2.0; users must regenerate v3 docs by then. Smoke gate `pipeline/scripts/smoke-no-mcp-in-dev-phases.sh` reads `state.telemetry.mcpCalls[]` and fails on any entry with `phase >= 2`. Halt condition: if a downstream phase needs design information not present in the analysis document, the run halts and the user re-runs `/multi-agent:analysis` to regenerate. Memory: `[[mcp-only-in-analysis]]`. Generic rule rationale and access matrix: see `pipeline/rules/figma-pipeline.md` "MUST: No MCP outside analysis phase".
+30. **Analysis as self-contained design bridge - no MCP outside analysis phase (BLOCKING, pipeline-wide).** The analysis document is the sole design source for every downstream phase. After Phase 1 of `/multi-agent:analysis` produces `analysis/<feature>-<platform>.md`, Phase 2 Planning, Phase 3 Dev, Phase 4 Review, Phase 5 Test, Phase 6 Commit, and Phase 7 Report consume only the analysis document plus repo Code Connect mappings (`*.figma.swift` / `*.figma.kt`). Calling `mcp__claude_ai_Figma__*`, hitting `api.figma.com`, or fetching a `figma.com/design/...` URL during Phase 2+ is a violation. Applies to every mode that runs Phase 2+: `/multi-agent`, `/multi-agent:autopilot`, `/multi-agent:local`, `/multi-agent:local-autopilot`, `/multi-agent:dev`, `/multi-agent:dev-autopilot`, `/multi-agent:dev-local`, `/multi-agent:dev-local-autopilot`. Hard requirement (v9.0.0): Phase 2 Pre-item and Phase 3 Pre-item (BLOCKING) abort the run when the analysis document is missing. Memory: `[[mcp-only-in-analysis]]`. Generic rule rationale and access matrix: see `pipeline/rules/figma-pipeline.md` "MUST: No MCP outside analysis phase".
 31. **Business-rule to acceptance-criterion to test traceability (AI + human spine).** The analysis is a development handoff that both an AI implementer and a human reviewer must act on, so it is bound by one shared-ID vocabulary. Every business rule carries a stable id `BR-<slug>-NN` (Section 4.4). Each rule maps to at least one acceptance criterion written Given / When / Then (binary - two readers must not be able to disagree on pass/fail). Each acceptance criterion maps to unit-test scenarios in Section 15.1, one row per case across happy / boundary / error / empty-nil (enumerate at least the failure modes; agents hallucinate error handling when it is omitted). The same ids thread onward: Section 15.6 UI-test flows reference the `BR-` ids and use stable selectors (accessibilityIdentifier / testTag), Section 16 accessibility items reuse those identifiers, Section 11 analytics events cite their triggering rule or story, and Section 5/7 layout cells carry token + Figma node refs. Never invent copy or values (blank beats a guess; a missing source becomes a Section 20 Open Question). **Mode-aware gate:** in Full mode a business rule with no acceptance criterion, or an acceptance criterion with no Section 15.1 scenario, fails the dispatch gate. In **Lite mode Section 15 is not rendered**, so the rule-to-test half does not apply - Section 4.4 still lists each rule with its Given/When/Then acceptance criterion (the acceptance criterion is itself the testable statement), and the 15.1 mapping is deferred to whenever the feature is later analyzed in Full or implemented via `/multi-agent:dev`. The rule-to-acceptance-criterion half always holds, in both modes.
 
 ## Input

package/pipeline/lib/credential-store.sh

@@ -113,18 +113,36 @@ if isinstance(name, str) and name.strip():
 }
 
 # --- Subcommands ------------------------------------------------------------
+# Append one PAT-lookup audit event. Every `get` goes through here, which is the
+# point of the control: the audit trail described in the .gitignore hardening and
+# managed by `/multi-agent:prune-logs` was written by audit-log.sh, but nothing
+# ever called it, so the trail was always empty and the control was inert.
+#
+# Never fails the caller and never echoes a secret: audit-log.sh hashes the repo
+# URL, logs the logical key (not the value), and is silent on error by design.
+audit_lookup() {
+  local logical="$1" success="$2"
+  local audit="$SCRIPT_DIR/../scripts/audit-log.sh"
+  [ -f "$audit" ] || return 0
+  bash "$audit" pat_lookup "$logical" "${USER:-unknown}" "${MULTI_AGENT_REPO_URL:-}" "$success" \
+    >/dev/null 2>&1 || true
+}
+
 do_get() {
   local key="${1:-}"
   [ -z "$key" ] && { echo "usage: $0 get <key>" >&2; exit 3; }
+  local logical="$key"
   key=$(resolve_key "$key")
   if delegate_to_python; then
     local val rc
     val=$(python3 "$KEYCHAIN_PY" get "$key" 2>/dev/null) || rc=$?
     rc=${rc:-0}
     if [ "$rc" -eq 0 ] && [ -n "$val" ]; then
+      audit_lookup "$logical" true
       printf '%s' "$val"
       return 0
     fi
+    audit_lookup "$logical" false
     return 1
   fi
   local val=""
@@ -149,8 +167,10 @@ if (\$c) { \$c.GetNetworkCredential().Password }
       echo "ERR: unsupported platform" >&2; exit 2 ;;
   esac
   if [ -z "$val" ]; then
+    audit_lookup "$logical" false
     return 1
   fi
+  audit_lookup "$logical" true
   printf '%s' "$val"
 }
 

package/pipeline/multi-agent-refs/_account-picker.md

@@ -14,7 +14,7 @@ First step of every `multi-agent` flow **that touches a remote provider**.
 > repos, account-picker is bypassed and the state file's `accountId` is left
 > `null` with `tokens={}`. Phases 6/7 read these as "local-only" signals.
 
-> **Language**: Per `$HOME/.claude/multi-agent-refs/rules.md` Language Application matrix  -  `AskUserQuestion.label` and `header` stay English (UI button + chip contract); `question` and `description` follow `outputLanguage`. Commit/PR/Jira payloads: subject + branch names + code identifiers stay English; body text follows `outputLanguage`.
+> **Language**: see `picker-contract.md` + `rules.md` Language Application matrix.
 
 ## Steps
 

package/pipeline/multi-agent-refs/_dev-context.md

@@ -6,7 +6,7 @@ description: "Internal  -  dev context (extra repos) picker for multi-agent."
 
 Selects extra repos the pipeline may touch beyond the primary repo(s)  -  typically submodules (e.g. SDKs vendored inside an app repo) or sibling libraries. Each candidate is enriched with a `canPush` flag so the picker can pre-select repos that the active account is allowed to edit, and surface read-only ones as advisory context the pipeline will not modify.
 
-> **Language**: Per `$HOME/.claude/multi-agent-refs/rules.md` Language Application matrix  -  `AskUserQuestion.label` and `header` stay English (UI button + chip contract); `question` and `description` follow `outputLanguage`. Commit/PR/Jira/Wiki payloads: subject + branch names + code identifiers stay English; body text follows `outputLanguage`.
+> **Language**: see `picker-contract.md` + `rules.md` Language Application matrix.
 
 ## Steps
 

package/pipeline/multi-agent-refs/_repo-picker.md

@@ -6,7 +6,7 @@ description: "Internal  -  multi-select repo picker for multi-agent."
 
 Used by `picker-issue`, `picker-jira`, `gh-num`, and `freetext` flows.
 
-> **Language**: Per `$HOME/.claude/multi-agent-refs/rules.md` Language Application matrix  -  `AskUserQuestion.label` and `header` stay English (UI button + chip contract); `question` and `description` follow `outputLanguage`. Commit/PR/Jira/Wiki payloads: subject + branch names + code identifiers stay English; body text follows `outputLanguage`.
+> **Language**: see `picker-contract.md` + `rules.md` Language Application matrix.
 
 ## Steps
 

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

@@ -67,6 +67,34 @@ Run phases sequentially. Log every step to `agent-log.md`.
 If any phase fails, mark task as `paused` and stop  -  user can `resume` later.
 Update `agent-state.json` at EVERY phase transition.
 
+### Writing `agent-state.json` (required mechanism)
+
+Every state update goes through `write-state.mjs`. Never write the file with a
+plain read-modify-write (`jq ... > tmp && mv`, an editor tool, `cat >`):
+
+```bash
+# Merge a patch into the current state (the normal case).
+echo '{"currentPhase":4,"phases":{"4":{"status":"running"}}}' \
+  | node $HOME/.claude/scripts/write-state.mjs "$STATE_FILE"
+
+# Full replacement, only when rewriting the document wholesale.
+printf '%s' "$NEW_STATE" | node $HOME/.claude/scripts/write-state.mjs --replace "$STATE_FILE"
+```
+
+Why the indirection is required: multi-repo mode and concurrent worktrees share
+one `agent-state.json` per task id, so two writers using read-then-write lose one
+of the two updates  -  the second write is computed from a snapshot taken before
+the first landed. `write-state.mjs` does tmpfile + rename (atomic on POSIX) under
+an advisory `.lock`, reclaims a lock whose holder PID is dead, and releases the
+lock on every error path.
+
+Exit codes the caller must handle: `0` written, `1` invalid JSON on stdin, `2`
+lock timeout (another writer held it past the acquire window  -  retry once, then
+halt per the halt-visibility rule), `3` I/O error.
+
+Reads need no wrapper; the rename makes any read see either the old or the new
+document, never a truncated one.
+
 **Halt visibility (required, autopilot included).** A halt is never silent. Whenever a phase halts on a hard error (validator failed twice, no subagent returned, dispatch error past fallback, lock irrecoverable), in addition to the `agent-log.md` line: (a) write `state.status = "paused"` and `state.haltReason = "<phase>:<cause>"`; (b) record the cause on the tracker via `phase-tracker.sh meta <phase> halt "<cause>"` and `phase-tracker.sh update <phase> failed`; (c) emit one `>&2` alert line `HALT phase <N>: <cause>  -  resume with /multi-agent:resume #<id>`. Autopilot suppresses *confirmations*, not *halts*  -  the user must always be able to see why an unattended run stopped without reading the log.
 
 ### Pipeline Best Practices

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

@@ -487,6 +487,7 @@ done
 
 State file in multi-repo mode:
 - Single shared `agent-state.json` lives at `$HOME/.claude/logs/multi-agent/{first-project}/{task-id}/agent-state.json` (anchored on the first repo for back-compat with `multi-agent log`/`status` commands)
+- **One shared file + per-repo writers is exactly the race `write-state.mjs` exists for.** Every update to it (here and in every later phase) goes through `node $HOME/.claude/scripts/write-state.mjs` per the required mechanism in `operations.md` "Writing `agent-state.json`". A read-modify-write from two repos in the same loop drops one repo's `projects[]` entry.
 - `state.projects[]` holds per-repo `{name, root, worktreePath, branch, baseBranch, identity, platform, baseFetchStatus, commit, pr, pushAttempts, buildStatus}`  -  see `agent-state.schema.json`
 - Scalar fields (`project`, `projectRoot`, `worktreePath`, `branch`, `baseBranch`, `identity`) mirror `projects[0]` so legacy phases that read scalars keep working
 - Atomicity: if any repo's worktree creation fails (collision aborted, fetch aborted, disk full), roll back already-created worktrees: `git -C $proj worktree remove --force $WT_PATH; git -C $proj branch -D $BRANCH`. Never leave a partial multi-repo state.

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

@@ -13,7 +13,7 @@ Phase 2 Planning consumes the analysis document. MCP forbidden.
    - Abort with `ERR: analysis doc missing. Run /multi-agent:analysis "<feature>" first.`
 
 2. **Parse YAML front-matter**: `feature`, `platform`, `language`, `mode`, `evidence_digest`, `template_version`. Persist into `state.analysis.frontMatter`.
-   - **Soft-skip (v9.1.0+, Locked 30)**: when `template_version == v2` AND (`prefs.global.legacyV2AnalysisAllowed == true` OR env `MULTI_AGENT_LEGACY_V2_ANALYSIS=allow`), emit `WARN: legacy v2 analysis doc detected; v3 expected. Continuing in degraded mode.` Step 3 section coverage check skips v3-specific sections (10 Localization, 11 Analytics, 12 Deeplink/Push, 13.6 SwiftUI Preview, 21 References). Phase 4 reviewer flags missing v3 sections rather than blocking. Escape hatch removed in v9.2.0; users must regenerate v3 docs by then.
+   - **`template_version` < `v3` aborts**: `ERR: analysis doc is template v<n>; v3 required. Re-run /multi-agent:analysis to regenerate.` No degraded mode.
 
 3. **Section coverage check**: verify these sections are non-empty (template v3 required sections per Locked 2):
    - Section 1 Summary, Section 2 Goals + Non-Goals, Section 4 User Stories, Section 9 API Contracts, Section 13 Architecture Plan, Section 14 Files to Add, Section 20 Risks, Section 21 References

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

@@ -16,8 +16,7 @@ Pre-flight steps (run in order, abort on failure):
 2. **Parse YAML front-matter** (the doc has a `template_version: v3` header):
    - `feature`, `platform`, `language`, `mode (full | lite)`, `evidence_digest`
    - Persist into `state.analysis.frontMatter`
-   - **Abort condition (v9.0.x strict)**: `template_version` < `v3` -> exit with `ERR: analysis doc is template v<n>; v9 requires v3. Re-run analysis to regenerate.`
-   - **Soft-skip (v9.1.0+, Locked 30)**: when `prefs.global.legacyV2AnalysisAllowed == true` OR env `MULTI_AGENT_LEGACY_V2_ANALYSIS=allow` is set AND `template_version == v2`, emit `WARN: legacy v2 analysis doc detected; v3 expected. Continuing with reduced binding strength.` and persist `state.dev.legacyAnalysisMode = true`. Step 4 (Code Connect lookup) and Step 6 (conventions handoff) still run, but Step 5 (standards binding) and Pass B footnote enforcement degrade to warning level (Phase 4 reviewer flags missing citations rather than blocking). Escape hatch removed in v9.2.0.
+   - **Abort condition**: `template_version` < `v3` -> exit with `ERR: analysis doc is template v<n>; v3 required. Re-run /multi-agent:analysis to regenerate.` No degraded mode.
 
 3. **Evidence digest match (cache validation)**: if `state.run.lastAnalysisDigest` is present AND matches `frontMatter.evidence_digest`, mark as fresh; otherwise WARN that analysis is stale (continue but flag).