@mmerterden/multi-agent-pipeline 12.4.0 → 12.6.0

package/CHANGELOG.md

@@ -14,6 +14,175 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ---
 
+## [Unreleased]
+
+## [12.6.0] - 2026-07-25
+
+Two threads. The design-check command gains a scenario inventory, a coverage
+gate and MCP-currency gating, and the refactor/sync pair learns to research,
+audit and ship the companion dev-toolkit MCP server. Alongside that, a defect
+sweep found eight gates and features that exited 0 while doing nothing -  six
+of them guarded by a smoke test whose fixture had the wrong shape, so the suite
+stayed green the whole time.
+
+Requires `@mmerterden/dev-toolkit-mcp` >= v2.9.0 for the App Store audit path.
+
+### Fixed
+
+- **Eight gates and features that reported success while doing nothing.** Each
+  exited 0 without doing its job, and in six cases the guarding smoke test
+  hand-wrote a fixture with the wrong shape, so the suite stayed green.
+  `npx @mmerterden/multi-agent-pipeline uninstall` was a silent no-op (the
+  `isMainModule` guard compared `import.meta.url` to `argv[1]`, which is
+  `index.js` under the bin dispatcher). `cost-budget-check.mjs` probed
+  `.worktrees/<id>/phase-tracker.json` while `phase-tracker.sh` writes
+  `~/.claude/logs/multi-agent/<id>/tracker-state.json`, so the cost ceiling
+  could never fire; it also now prices `tokens_cached`. `classify-plan-safety.mjs`
+  required `score >= 50` while its heaviest rule is 35, so no single heavy
+  signal could trip the autopilot pause its own contract promises.
+  `triage-memory.mjs` and `learnings-ledger.mjs` derived the repo slug from
+  `--show-toplevel`, which inside a worktree is the task id, sharding the
+  per-repo store one directory per task; they now use `--git-common-dir`.
+  `state-2.0.0-to-2.1.0.mjs` emitted keys `agent-state.schema.json` rejects
+  under `additionalProperties: false`. `memory-load.sh` read `preferences.json`
+  while the installer only writes `multi-agent-preferences.json`, so per-repo
+  memory was dead in production. `smoke-cross-cli-behavior.sh` had unquoted
+  command substitution (SC2046) that made two gates pass while violations were
+  present. The CI leak gate in all three workflows grepped 5 of the 23
+  forbidden patterns and was `release.yml`'s only PII gate; all three now call
+  `smoke-personal-data.sh --root`, keeping one pattern list.
+- **shellcheck moves from `error` to `warning` severity.** `error` returns zero
+  findings across all 175 scripts, so the gate could not catch this repo's
+  actual defect class -  SC2046 is a warning. Noisy codes are excluded with a
+  per-code rationale. Four real findings surfaced and are fixed, including two
+  unguarded `cd` calls in `smoke-shadow-git.sh`, one preceding a relative
+  `rm -rf`.
+- **`credential-store.sh` resolves logical keys through
+  `prefs.global.keychainMapping`.** `get github` searched the backend for a
+  credential literally named "github" and returned empty with exit 1 -
+  indistinguishable from "no such credential" -  because the entry is named by
+  the mapping. Applied in `get`/`set`/`delete`, falling back to the logical key
+  when no mapping exists.
+
+### Changed
+
+- **`ios_app_store_audit` catalog grows to 18 rules**, requiring
+  `@mmerterden/dev-toolkit-mcp` >= v2.9.0. Adds `sdk-floor` (ITMS-90725, the
+  iOS 26 / Xcode 26 build floor in force since 2026-04-28). `embedded-sdk`'s
+  missing framework privacy manifest moves from a `5.1.1` WARNING to
+  `ITMS-91061` ERROR, an enforced rejection since 2025-02-12, so archives that
+  previously passed with a warning now fail. The rule count and the declared
+  minimum are updated across all nine files that asserted them.
+
+### Added
+
+- **`/multi-agent:refactor` band E (Step 0c)**: the companion dev-toolkit MCP
+  server is now in scope. The step researches current MCP practice (protocol
+  revisions and SDK releases, host-client conventions, peer servers, the
+  platform tooling it wraps, field practice) and audits the toolkit repo
+  against it: syntax, stdout hygiene (stdout carries the JSON-RPC frames),
+  advertised tool counts vs reality, `files[]` coverage, dependency freshness.
+  Findings land in the merged Step 4 plan as band-E items, applied in that repo
+  and shipped by sync. New focus filter: `/multi-agent:refactor dev-toolkit`.
+- **`/multi-agent:sync` Step 3d**: ships the dev-toolkit MCP server when it
+  moved (dirty tree, unpushed commits, or an untagged version). Seven ship
+  gates run before anything leaves the machine, including a `tools/list`
+  stdio handshake that must answer with a non-zero tool count, an
+  advertised-count match against README and `package.json`, an
+  `npm pack --dry-run` check that every runtime `tools/*/` directory is inside
+  `files[]`, and a version-contract check against the minimums pipeline skills
+  declare. Publish goes to the registry from that repo's `publishConfig`
+  through a throwaway `--userconfig` built from the `npm` logical Keychain key.
+  Outside autopilot / `release` it asks first; `/multi-agent:sync dev-toolkit`
+  runs only this step.
+- **`global.devToolkit` preference** (schema + template): `enabled`, `label`,
+  `localPath`, `mcpServerName`, `packageName`, `registry`, `repoUrl`. Both
+  commands fall back to auto-detecting the repo from the `mcpServers`
+  registration when `localPath` is absent, and skip silently when nothing
+  resolves. No path is ever hardcoded.
+
+- **`smoke-command-inventory.sh`**: the command count is now DERIVED from
+  `pipeline/commands/multi-agent/*/` and the prose must agree with the tree
+  (contract header, both sync surfaces, every command listed on all three, and a
+  `shared/core` skill counterpart per command). `smoke-generate-issue.sh` and
+  `smoke-review-readiness.sh` stopped asserting the literal `41` and now compare
+  against the derived count too.
+- **`lint-mcp-refs.mjs`**: every `mcp__<server>__<tool>` reference in
+  `commands/`, `skills/` and `multi-agent-refs/` must name a known registered
+  MCP server, and when the companion toolkit resolves locally the referenced
+  `dev-toolkit` tools are checked against its live `tools/list`. Wired into
+  `npm test` and `npm run test:quick`.
+- **`validate-prefs.mjs`**: validates `preferences-template.json` against
+  `prefs.schema.json` (hard failure) and the local preferences file (advisory,
+  `--strict-live` to enforce). Dev-only (ajv), excluded from the published
+  package so the runtime stays zero-dep.
+- `design-check` is registered in the command inventory: contract list +
+  category row, both sync inventories, and the Copilot mirror. Inventory is 42
+  commands.
+
+### Fixed
+
+- **Every `mcp__dev_toolkit__*` reference is now `mcp__dev-toolkit__*`** (55
+  lines across 10 files). A host composes MCP tool names as
+  `mcp__<registered-server-name>__<tool>` and the server registers as
+  `dev-toolkit`, so the snake_case form named tools that do not exist. The worst
+  case was silent: `design-check`'s `allowed-tools` allowlist matched nothing, so
+  the skill was denied the tools it needs, and `smoke-compliance-skills.sh`
+  asserted the wrong spelling and kept the gate green.
+- `prefs.schema.json` accepted neither the template it describes nor a real
+  preferences file. Now declared: `global.modelFallback`, the `_*Template`
+  documentation blocks, nullable `defaultJiraKey`, `keychainMapping.figma_pat` /
+  `figma_user` / `claude_oauth_token` / `claude_oauth_token_fallback` (all four
+  resolved by shipped flows), project-level `componentDevWorkflow`, and a
+  `defaultReviewers` ceiling that fits real reviewer groups (10 -> 40).
+- `global.derivedSkillSources` is now declared in `prefs.schema.json`. It was
+  used by refactor Step 0b and shipped in the preferences template, but the
+  strict (`additionalProperties: false`) global block rejected it.
+- `/multi-agent:sync` Step 3d prefers the toolkit repo's own gate script
+  (`npm run gates`) over the inline gate list, so the definition lives in the
+  repo being shipped and the two cannot drift apart.
+
+---
+
+## [12.5.0] - 2026-07-24
+
+Repo learning loop: repeated runs on the same repo produce better and cheaper
+output over time. Plus a round of worktree hardening.
+
+### Added
+
+- **Freshness gate** for the triage corpus: `triage-memory` stamps each stored
+  row with the file's git `file_sha`, and queries annotate `stale=true` when
+  the file changed since the lesson was recorded, so dead lessons stop
+  resurfacing in later runs.
+- **Causal diagnosis** on lessons: `learnings-ledger` rows carry an optional
+  `diagnosis` (the verbal root-cause "why", per Reflexion), and Phase 4's
+  lesson-memory loop now records it. `brief` renders it as `(why: ...)` so the
+  reason, not just the outcome, re-enters Phase 1 on the next run.
+- **`learning-curve.mjs`** (+ smoke): a time-bucketed trend over
+  `metrics.jsonl` (first-pass clean rate, review cycles, rework per task,
+  tokens per task, cache ratio) that shows whether a repo's runs are improving.
+- **`prompt-assembly.md`**: stable-prefix prompt-cache guidance, referenced
+  from `phases.md`, so lazy-loaded phase docs stay cache-friendly.
+
+### Changed
+
+- Worktree handling hardened: `.worktrees/` is now a first-class member of the
+  traversal-prune skip set (`node_modules`, `Pods`, `.build`, `DerivedData`,
+  `.next`) across every tree walker (`repo-map`, `repo-cache`,
+  `extract-conventions`, `shadow-git`), so no walker descends into a worktree
+  checkout. Phase 0 gains an explicit residue-guard + traversal-prune contract;
+  Phase 5 heals stale worktree admin state before recreating a worktree.
+- `eval-mine-corpus` now reads the corpus from the per-repo memory dir it is
+  actually written to (was a path that never received data).
+- Phase-doc total token budget recalibrated 50000 -> 51000 for the new
+  contracts (prose compressed first; every per-phase max still passes).
+
+### Fixed
+
+- `gc-worktrees.sh` anchors the repo on the main worktree and resolves paths on
+  both sides, so orphan detection no longer misfires from inside a worktree.
+
 ## [12.4.0] - 2026-07-23
 
 User-defined routines: manage your own recurring, project-specific jobs as

package/README.md

@@ -64,7 +64,7 @@ The discipline behind all of this — bounded loops, evidence gates, token-budge
 | Local | `/multi-agent:local "task"` | Full pipeline, current branch (no worktree) |
 | Finish | `/multi-agent:finish` | Run the review→test→commit→report tail over local work |
 
-Helpers: `setup`, `status`, `resume #N`, `review`, `test`, `channels`, `stack`, `update`, `sync`, `refactor`, `jira`, `issue`, `analysis`, `create-jira`. Full list: `/multi-agent:help`.
+Helpers: `setup`, `status`, `resume #N`, `review`, `test`, `channels`, `stack`, `update`, `sync`, `refactor`, `jira`, `issue`, `analysis`, `create-jira`, `save`, `routines`, `forget`. Full list: `/multi-agent:help`.
 
 ## Stacks
 

package/docs/features.md

@@ -249,6 +249,26 @@ Pipeline learns behavioral signals (feedback corrections, project constraints, e
 
 **What does NOT go in memory**: architecture, code patterns, build gotchas, design decisions — those belong in the knowledge base.
 
+### Lesson Diagnosis (Reflexion)
+
+Phase 4's lesson-memory loop records the causal root cause of each fix (`--diagnosis`), not just the outcome: the verbal "why" that prevents recurrence (Reflexion). `learnings-ledger.mjs brief` renders it as `(why: ...)` back into Phase 1 + triage on the next run, so the reason re-enters the loop, not only the symptom.
+
+### Corpus Freshness Gate
+
+Each triage-corpus row is stamped with the file's git `file_sha`; a query annotates `stale=true` when the file changed since the lesson was recorded, so lessons about code that has since moved on stop resurfacing.
+
+### Learning Curve
+
+`learning-curve.mjs` renders a time-bucketed trend over `metrics.jsonl` (first-pass clean rate, review cycles, rework per task, tokens per task, cache ratio) so a repo's runs can be shown getting better and cheaper over time. Flags: `--bucket=<days>`, `--since`, `--json`, `--markdown`.
+
+## User-Defined Routines
+
+Turn a recurring, project-specific job into a first-class `/multi-agent:<name>` command.
+
+- **`/multi-agent:save`** distills candidate routines from the work just done this session (and named procedures in `~/.claude/CLAUDE.md`), offers them in a multi-select picker (pick one, combine several into one, or free-text a new one), and registers the chosen routine.
+- **`/multi-agent:routines`** lists saved routines (in `outputLanguage`); **`/multi-agent:forget`** removes one (guarded: never touches a shipped command).
+- Backed by `routine-registry.mjs`. Saved routines are `local-only: true` command dirs + a `prefs.global.routines` entry: preserved across `/multi-agent:update` by install snapshot/restore, never synced to the public repo, and never counted in the command inventory.
+
 ## Integrations
 
 ### Figma / Component Generation (dispatched to marketplace plugins)

package/index.js

@@ -36,7 +36,13 @@ if (command === "--version" || command === "-v" || command === "version") {
 } else if (!command || command === "install") {
   await import(pathToFileURL(join(__dirname, "install.js")).href);
 } else if (command === "uninstall" || command === "delete") {
-  await import(pathToFileURL(join(__dirname, "pipeline", "scripts", "uninstall.mjs")).href);
+  const { main } = await import(
+    pathToFileURL(join(__dirname, "pipeline", "scripts", "uninstall.mjs")).href
+  );
+  await main().catch((e) => {
+    console.error("uninstall failed:", e.message);
+    process.exit(1);
+  });
 } else if (command === "help") {
   console.log(`
   multi-agent-pipeline — 8-phase AI development pipeline

package/install/_dev-only-files.mjs

@@ -13,5 +13,6 @@ export const DEV_ONLY_SCRIPTS = Object.freeze([
   "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
 ]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "12.4.0",
+  "version": "12.6.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",
@@ -14,11 +14,11 @@
   },
   "scripts": {
     "start": "node index.js",
-    "test": "node --test test/*.test.mjs && node pipeline/scripts/run-smokes.mjs && node pipeline/scripts/lint-skills.mjs && node pipeline/scripts/eval-triage.mjs && node pipeline/scripts/eval-golden-tasks.mjs && node pipeline/scripts/eval-intent.mjs && node pipeline/scripts/validate-schemas.mjs",
+    "test": "node --test test/*.test.mjs && node pipeline/scripts/run-smokes.mjs && node pipeline/scripts/lint-skills.mjs && node pipeline/scripts/lint-mcp-refs.mjs && node pipeline/scripts/eval-triage.mjs && node pipeline/scripts/eval-golden-tasks.mjs && node pipeline/scripts/eval-intent.mjs && node pipeline/scripts/validate-schemas.mjs && node pipeline/scripts/validate-prefs.mjs",
     "test:unit": "node --test test/*.test.mjs",
     "test:smoke": "node pipeline/scripts/run-smokes.mjs",
     "lint:skills": "node pipeline/scripts/lint-skills.mjs",
-    "test:quick": "node --test test/*.test.mjs && node pipeline/scripts/lint-skills.mjs",
+    "test:quick": "node --test test/*.test.mjs && node pipeline/scripts/lint-skills.mjs && node pipeline/scripts/lint-mcp-refs.mjs",
     "test:coverage": "c8 --check-coverage --reporter=text --reporter=lcov node --test test/*.test.mjs && c8 report",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
@@ -72,6 +72,7 @@
     "LICENSE",
     "!pipeline/scripts/smoke-figma-config-schema.sh",
     "!pipeline/scripts/smoke-personal-data.sh",
+    "!pipeline/scripts/validate-prefs.mjs",
     "!pipeline/scripts/smoke-install-leak-gate.sh",
     "!docs/internal/**"
   ],

package/pipeline/agents/security-auditor.md

@@ -85,7 +85,7 @@ Example: new `MANAGE_EXTERNAL_STORAGE` permission → `(google-play-compliance /
 
 The two SKILL.md files contain tabular rule catalogs:
 
-- **apple-archive-compliance**  -  17 rules (privacy-manifest, required-reason-api, info-plist, code-signing, embedded-sdk, entitlement, asset-validation, binary-size, team-id-consistency, provisioning-profile, swift-abi, extension-signing, ipv6-compliance, debug-tool-leak, production-hygiene, duplicate-resource, dead-reference) with ITMS codes + App Store Review Guideline refs.
+- **apple-archive-compliance**  -  18 rules (privacy-manifest, required-reason-api, info-plist, code-signing, embedded-sdk, entitlement, asset-validation, binary-size, team-id-consistency, provisioning-profile, swift-abi, extension-signing, ipv6-compliance, debug-tool-leak, production-hygiene, duplicate-resource, dead-reference, sdk-floor) with ITMS codes + App Store Review Guideline refs.
 - **google-play-compliance**  -  21 rules across Technical / Security / Privacy / Hygiene categories with Play policy refs.
 
 Cite rule + ref in your Output Format's `Category:` line so the code-reviewer and triage layers inherit the reference text unchanged.

package/pipeline/commands/archive-guard.md

@@ -1,14 +1,14 @@
 ---
-description: Scan an .xcarchive for Apple App Store Review compliance (17-rule deep audit)
+description: Scan an .xcarchive for Apple App Store Review compliance (18-rule deep audit)
 allowed-tools: Bash, Read, Glob
 ---
 
-Run the `ios_app_store_audit` MCP tool (shipped in `@mmerterden/dev-toolkit-mcp` ≥ v2.4)
-on an iOS archive. Backed by the same 17-rule catalog as `/multi-agent:test "store-ready"`
+Run the `ios_app_store_audit` MCP tool (shipped in `@mmerterden/dev-toolkit-mcp` ≥ v2.9.0)
+on an iOS archive. Backed by the same 18-rule catalog as `/multi-agent:test "store-ready"`
  -  this command is the lighter, post-hoc form (no platform-detect, no UI sweep).
 
 > **v8.4.0 migration note:** The standalone `~/ArchiveGuard/.build/release/archive-guard`
-> binary has been retired. The 17 rules live in
+> binary has been retired. The 18 rules live in
 > `dev-toolkit-mcp/tools/ios-app-store-audit/rules/` as a pure-Node port. Output JSON
 > shape is unchanged.
 
@@ -21,7 +21,7 @@ on an iOS archive. Backed by the same 17-rule catalog as `/multi-agent:test "sto
 2. Ask user which archive to scan (or use the argument if provided: $ARGUMENTS).
 3. Run the scan  -  preferred mode is the native MCP tool call:
    ```
-   mcp__dev_toolkit__ios_app_store_audit({
+   mcp__dev-toolkit__ios_app_store_audit({
      archive_path: "<archive_path>",
      rules: "all"          // "all" | "core" | "deep" | csv of ruleIDs
    })

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

@@ -83,6 +83,7 @@ Lib scripts (`~/.claude/lib/`):
 | `create-jira ["desc"] [figma-url] [swagger-url]` | Create a standards-compliant Jira issue: asks the type (**Task** / **Bug** / **Story**), mines the project's recent same-type issues for conventions (summary format, labels, priority, test-scenario style), detects the active sprint, drafts from a standard template with auto-sizing sections (Design Reference / API Contract / Screenshots appear only when their source is given), asks about unknown fields, then full draft preview + explicit approval before create. No worktree, no commits. |
 | `test` or `test [args]` | UI Bug Hunter  -  screenshot + tap + analyze on booted simulator via MCP (read `$HOME/.claude/commands/sim-test.md`). `/multi-agent:test` also resolves here via the `commands/multi-agent/test/SKILL.md` delegate. |
 | `manual-test [#id]` | Phase 5 standalone Manual Test  -  checks out the task branch, prints Xcode / SourceTree hints, waits for user verdict (`ok` / `fix: ...`). |
+| `design-check [scope]` | Mock-mode vs Figma design audit (iOS / Android, local-only). Pick repo + module → mock-support feasibility gate (halts if unsupported) → **scenario inventory** (every launch arg / scenario case / scenario code / fixture / deep link becomes a countable target with file+line evidence) → scope resolve (empty = module, screen, `screen@variant`, target id, Figma URLs, `--resume`) → worktree Debug build + mock launch → drive EACH target by its own driver, capturing tap-reachable sub-states with it → per-variant pixel + px-spacing + typography + color compare → report (side-by-side + annotated overlay + stacked findings + fix prompt) exported to `~/DesignChecks/` as HTML + PDF (+ Confluence if enabled). **Coverage gate**: a target is audited or skipped with a concrete reason, else the run is reported INCOMPLETE with the missing ids. No commits, no CI. |
 | `stack [ios\|android\|backend\|mobile\|all]` | Swap skills for next conversation. No arg = show current stack. |
 | `language [en\|tr]` | Show or set the assistant `outputLanguage` (explanations and chat replies). `promptLanguage` is locked to `en` and is not toggleable. No arg = show current `outputLanguage`. With `en` or `tr` = set and persist `outputLanguage`. External payloads (commits, PR bodies, Jira) stay English. |
 | `setup` | Keychain token + Git Identity onboarding |
@@ -134,6 +135,7 @@ This command uses lazy loading for token efficiency. Read the relevant sub-file
 | Audit tools (Phase 5/6) | `$HOME/.claude/multi-agent-refs/audit-guide.md` |
 | `test` | `$HOME/.claude/commands/sim-test.md` (colon-form `/multi-agent:test` uses the delegate at `commands/multi-agent/test/SKILL.md`) |
 | `manual-test` | `$HOME/.claude/commands/multi-agent/manual-test/SKILL.md` |
+| `design-check` | `$HOME/.claude/commands/multi-agent/design-check/SKILL.md` |
 
 **Modifier flags** (`--dev`, `--local`, `autopilot`) and **ops** (`status`, `log`, `resume`, `kill`, `clear-logs`, `purge`, `review`) are parsed inline by this file  -  no separate spec files, they compose with the pipeline or do one-shot work.