@mmerterden/multi-agent-pipeline 12.5.0 → 12.7.0

package/CHANGELOG.md

@@ -14,6 +14,219 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ---
 
+## [Unreleased]
+
+## [12.7.0] - 2026-07-26
+
+A refactor pass whose theme turned out to be one recurring defect: gates that
+reported success without checking anything. Nine of them, plus a data-loss bug found
+while fixing them.
+
+### Fixed
+
+- **The GitHub Actions security audit had never run anywhere.** `smoke-workflow-audit.sh`
+  reported "0 passed, 0 failed, 2 skipped" on the workstation and on the runner, and
+  `ci-lite.yml` justified not installing zizmor and actionlint by saying to run it
+  locally "where the tools exist" - where they were equally absent. Run for the first
+  time it found nine issues: a high-severity cache-poisoning path restoring a
+  lockfile-keyed dependency cache into the job that signs and publishes the tarball,
+  four checkouts persisting their credential, four jobs on the default token scope.
+  All nine fixed across all three repos. The smoke is strict by default now; a
+  missing linter fails, and the local escape hatch is ignored when `CI` is set.
+- **A suite that asserted nothing reported success.** `run-smokes` only read exit
+  codes, and three suites were exiting 0 having checked nothing - including the gate
+  for the no-MCP-outside-analysis rule, which printed "no run to check" on every
+  clean clone and every CI runner. It self-tests against eight fixtures now. The
+  runner counts assertions and fails a suite that made none; the four output shapes
+  it recognises were surveyed across all suites rather than assumed.
+- **`smoke-plugin-validate.sh` ran zero checks here** while appearing as a green CI
+  step. Removed; the real check lives in multi-agent-plugins, which gained its own CI.
+- **The drift check read a mirror and called it the authority.** It resolved the
+  upstream version from the installed plugin cache, only as fresh as the last
+  marketplace update, so it reported "up to date" for a derivation four releases
+  behind. Resolution is local clone, then repo API, then cache; a cache-only answer
+  reports "unverified" rather than passing. `check-derived-drift.mjs` makes the order
+  testable - seven tests, including a clone whose two manifests disagree.
+- **`write-state.mjs` lost a concurrent write.** The lock was created empty with its
+  PID written on the next line, so a writer arriving in that window read an
+  unparseable PID, called the lock stale, and deleted a live one. Both writers then
+  did their own read-modify-write and one update vanished. Reproduced three times in
+  fifteen runs under load, invisible on an idle machine, which is why the smoke read
+  as flaky. The lock is created atomically with its PID via `link()`, an unreadable
+  PID no longer counts as stale, and the smoke went 10 checks to 12 with the race
+  pinned directly.
+- **Coverage was measured against the wrong denominator.** `.c8rc.json` lacked `all`,
+  reporting 83% against a real 33% over its own include set. Floors are 72/68/85.
+- **Two HIGH advisories** pinned by the lockfile, closed.
+- **One skill routed into two stack plugins**: the backend pattern carried a bare
+  `architecture` alternative that also matched `android-architecture` and
+  `swift-architecture`, so a Python/Node plugin shipped Compose and SwiftUI guidance.
+- **`engines.node` claimed `>=20.0.0`** while the code uses `import.meta.dirname`,
+  which arrived in 20.11. A user on 20.0 through 20.10 would have broken.
+- **The orchestrator skill named a log path the code had stopped using**, in one of
+  three sections it had duplicated from loadable references while citing them zero
+  times.
+
+### Added
+
+- **`npm run scorecard`** gates the measurable half of a review score against locked
+  thresholds and names the four categories no script can score instead of giving them
+  a number. Nine measured metrics: coverage floors, zero high or critical advisories,
+  the fixed context budget, the workflow audit, the punctuation rule, a routing clause
+  on every skill description, licence and changelog presence, the zero-assertion check
+  still wired, derived skills current with upstream. Its own first version trusted an
+  exit code that meant two different things and reported an unconfigured machine as
+  passing.
+- **`smoke-context-budget.sh`** pins the bytes every run pays before it starts.
+- **`smoke-own-punctuation.sh`** enforces the locked punctuation rule on our own tree,
+  in both the literal and the escaped encoding - `prefs.schema.json` carried 50
+  escaped em-dashes that the first version of the gate could not see.
+- **`check-derived-drift.mjs`**, with `upstreamVersionSource` and `upstreamLocalClone`
+  in the prefs schema.
+- **`eslint-plugin-n`** and **`publint`**, the latter having sat behind
+  `npx --no-install` and never executed.
+
+### Changed
+
+- **Fixed per-run context: 67150 -> 57831 bytes.** Three duplicated sections moved
+  out of the orchestrator skill to the references it now cites.
+- **A routing clause in all 193 skill descriptions**, 93 of which had none. The
+  linter fails on a missing one instead of warning.
+- **`prettier` is enforced.** It was configured with nothing running it, so 583 files
+  failed the declared style. Scope is code and config; markdown is excluded on
+  purpose and the reason is in the workflow.
+- **The punctuation rule applied to our own files**: 719 em-dashes across 77 files.
+- `--ignore-scripts` on the four CI `npm ci` lines; `pipefail` in 13 lib scripts.
+- eslint 10.8, prettier 3.9.6, c8 12.
+
+## [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

package/README.md

@@ -6,7 +6,7 @@
 [![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://github.com/mmerterden/multi-agent-pipeline/blob/main/package.json)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/mmerterden/multi-agent-pipeline/badge)](https://scorecard.dev/viewer/?uri=github.com/mmerterden/multi-agent-pipeline)
 
-An 8-phase AI development pipeline for **Claude Code** and **Copilot CLI**. Drives a Jira issue or GitHub URL to a merged PR in one command — analysis → plan → TDD → review → test → commit → PR — with multi-repo orchestration, a plan-approval gate, CLI-aware parallel review, and store-compliance checks. Component and Figma-to-code work is dispatched to the per-stack marketplace plugins (iOS/SwiftUI, Android/Compose) rather than bundled, so component skills live in one place.
+An 8-phase AI development pipeline for **Claude Code** and **Copilot CLI**. Drives a Jira issue or GitHub URL to a merged PR in one command - analysis → plan → TDD → review → test → commit → PR - with multi-repo orchestration, a plan-approval gate, CLI-aware parallel review, and store-compliance checks. Component and Figma-to-code work is dispatched to the per-stack marketplace plugins (iOS/SwiftUI, Android/Compose) rather than bundled, so component skills live in one place.
 
 Runs natively on Claude Code and Copilot CLI. macOS / Linux / Windows. Zero runtime dependencies.
 
@@ -20,7 +20,7 @@ npx @mmerterden/multi-agent-pipeline install --all   # Claude Code + Copilot CLI
 /multi-agent:setup          # keychain token scan + git identity + default stack
 ```
 
-Run a task — the input type is auto-detected:
+Run a task - the input type is auto-detected:
 
 ```bash
 /multi-agent "PROJ-1234"                              # Jira id → fetch, plan, build
@@ -31,7 +31,7 @@ Run a task — the input type is auto-detected:
 /multi-agent:issue                                    # browse unassigned GitHub issues → pick
 ```
 
-Every input runs the same short intake — **account → (repo) → maturity check → dev-context** — then enters Phase 0. A Jira id or GitHub URL is fetched and maturity-checked *before* any code is written; free-text skips the fetch and goes straight to planning. Multi-repo tasks add extra repos at the dev-context step.
+Every input runs the same short intake - **account → (repo) → maturity check → dev-context** - then enters Phase 0. A Jira id or GitHub URL is fetched and maturity-checked *before* any code is written; free-text skips the fetch and goes straight to planning. Multi-repo tasks add extra repos at the dev-context step.
 
 Add `autopilot` to skip confirmations, `--dev` for the fast dev-only path, or `--local` to work on the current branch without a worktree (e.g. `/multi-agent:autopilot "PROJ-1234"`).
 
@@ -41,18 +41,18 @@ Update later with `/multi-agent:update`. Uninstall (tokens preserved) with `npx
 
 One command runs 8 phases, with a gate between the risky ones:
 
-- **0 · Init** — parse the input (Jira id / GitHub URL / free text), pick account + repo(s), fetch the issue, run a maturity check.
-- **1 · Analysis** — detect the stack, scan the codebase, map impact (Opus).
-- **2 · Plan** — write a task breakdown and **stop for your approval** before touching code.
-- **3 · Dev** — TDD: failing test → code → green, following the repo's style + the active stack skills.
-- **4 · Review** — deterministic gates (build / lint / test / secret-scan) must pass first, then a **CLI-aware parallel review** — Claude Code runs 2 models (Fable + Sonnet), Copilot CLI runs 3 (GPT-5.4 + Opus + Sonnet) — and a **Fable triage** keeps only actionable findings; blockers loop back to Phase 3.
-- **5 · Test** — build + run the suite; success is required (no faked passes).
-- **6 · Commit/PR** — conventional commit, push (must succeed), open a PR (`Ref: #N`, never auto-close).
-- **7 · Report** — technical summary + a Jira comment with test scenarios, posted through the channels layer.
+- **0 · Init** - parse the input (Jira id / GitHub URL / free text), pick account + repo(s), fetch the issue, run a maturity check.
+- **1 · Analysis** - detect the stack, scan the codebase, map impact (Opus).
+- **2 · Plan** - write a task breakdown and **stop for your approval** before touching code.
+- **3 · Dev** - TDD: failing test → code → green, following the repo's style + the active stack skills.
+- **4 · Review** - deterministic gates (build / lint / test / secret-scan) must pass first, then a **CLI-aware parallel review** - Claude Code runs 2 models (Fable + Sonnet), Copilot CLI runs 3 (GPT-5.4 + Opus + Sonnet) - and a **Fable triage** keeps only actionable findings; blockers loop back to Phase 3.
+- **5 · Test** - build + run the suite; success is required (no faked passes).
+- **6 · Commit/PR** - conventional commit, push (must succeed), open a PR (`Ref: #N`, never auto-close).
+- **7 · Report** - technical summary + a Jira comment with test scenarios, posted through the channels layer.
 
-Under the hood: each task runs in its own **git worktree** (or the current branch with `:local`), commits use the **git identity routed from the repo's origin URL**, and **multi-repo** tasks get per-repo worktrees plus an integration build. Tokens stay in the OS keychain; nothing is committed or logged. `/multi-agent:review` can also review an existing GitHub/Bitbucket PR — per-finding inline comments anchored to `file:line` + an explicit Approve / Needs-Work state.
+Under the hood: each task runs in its own **git worktree** (or the current branch with `:local`), commits use the **git identity routed from the repo's origin URL**, and **multi-repo** tasks get per-repo worktrees plus an integration build. Tokens stay in the OS keychain; nothing is committed or logged. `/multi-agent:review` can also review an existing GitHub/Bitbucket PR - per-finding inline comments anchored to `file:line` + an explicit Approve / Needs-Work state.
 
-The discipline behind all of this — bounded loops, evidence gates, token-budgeted phase docs, immutable tests, fresh-context handoffs — is catalogued in [docs/engineering.md](./docs/engineering.md). The full feature list lives in [docs/features.md](./docs/features.md).
+The discipline behind all of this - bounded loops, evidence gates, token-budgeted phase docs, immutable tests, fresh-context handoffs - is catalogued in [docs/engineering.md](./docs/engineering.md). The full feature list lives in [docs/features.md](./docs/features.md).
 
 ## Modes
 
@@ -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
 
@@ -78,7 +78,7 @@ This enables the matching plugin (+ the shared `ai-common` plugin) in the repo's
 
 ## Tool support
 
-The pipeline runs natively on **Claude Code** and **Copilot CLI** — both install from the same `pipeline/skills/` source and get identical coverage.
+The pipeline runs natively on **Claude Code** and **Copilot CLI** - both install from the same `pipeline/skills/` source and get identical coverage.
 
 | Tool | Flag | Notes |
 |---|---|---|
@@ -89,7 +89,7 @@ Filter skills by stack with `--platform=ios\|android\|all`.
 
 ## Tokens & integrations
 
-`setup` scans your OS keychain and maps each token by a **logical name** (e.g. `jira`) to its real keychain entry — the pipeline resolves tokens through that mapping (`credential-store.sh`), so literal keychain names never appear in synced files. Tokens stay in the keychain (macOS Keychain / Windows Credential Manager / Linux libsecret), are **never committed or logged**, and are all **optional** — the pipeline asks for any it needs at Phase 0.
+`setup` scans your OS keychain and maps each token by a **logical name** (e.g. `jira`) to its real keychain entry - the pipeline resolves tokens through that mapping (`credential-store.sh`), so literal keychain names never appear in synced files. Tokens stay in the keychain (macOS Keychain / Windows Credential Manager / Linux libsecret), are **never committed or logged**, and are all **optional** - the pipeline asks for any it needs at Phase 0.
 
 | Token | Used for | Phase |
 |---|---|---|
@@ -107,15 +107,15 @@ The **secret scan** runs as a `PreToolUse` hook on Claude Code (hard-blocks a co
 
 ## Platform support
 
-Runs on **macOS**, **Linux**, and **Windows** (Git Bash / WSL). Shell and credential access go through a platform-agnostic layer — the keychain resolves automatically to **macOS Keychain**, **Linux libsecret** (`secret-tool`), or **Windows Credential Manager**, and scripts fall back between BSD and GNU tool variants. Node.js 18 / 20 / 22.
+Runs on **macOS**, **Linux**, and **Windows** (Git Bash / WSL). Shell and credential access go through a platform-agnostic layer - the keychain resolves automatically to **macOS Keychain**, **Linux libsecret** (`secret-tool`), or **Windows Credential Manager**, and scripts fall back between BSD and GNU tool variants. Node.js 18 / 20 / 22.
 
 ## Companion repos
 
 | Repo | What it is |
 |---|---|
 | [`mmerterden/multi-agent-plugins`](https://github.com/mmerterden/multi-agent-plugins) | Marketplace of per-stack skill toolkits (iOS / Android / Frontend / Backend + common). `/multi-agent:stack` enables the matching plugin. |
-| [`mmerterden/dev-toolkit-mcp`](https://github.com/mmerterden/dev-toolkit-mcp) | MCP server for UI testing / simulator capture / xcodebuild — powers the Phase 5 UI Bug Hunter. `npx @mmerterden/dev-toolkit-mcp` |
+| [`mmerterden/dev-toolkit-mcp`](https://github.com/mmerterden/dev-toolkit-mcp) | MCP server for UI testing / simulator capture / xcodebuild - powers the Phase 5 UI Bug Hunter. `npx @mmerterden/dev-toolkit-mcp` |
 
 ## License
 
-MIT — see [LICENSE](./LICENSE). Security issues: see [SECURITY.md](./SECURITY.md) (do not open public issues for vulnerabilities).
+MIT - see [LICENSE](./LICENSE). Security issues: see [SECURITY.md](./SECURITY.md) (do not open public issues for vulnerabilities).

package/docs/FIGMA_PIPELINE.md

@@ -6,38 +6,38 @@ End-to-end guide for generating production-ready UI components from Figma design
 
 ## What you get
 
-- **One command** — `/multi-agent <figma-url-or-issue>` — produces a complete component: Configuration + View + Modifiers + Preview + README + three layers of tests + Code Connect + wiki doc.
-- **Platform-agnostic orchestration** — classification happens once in Phase 0; the orchestrator picks the right code generator for iOS or Android based on `figmaConfig.project.platform`.
-- **Multi-repo aware** — components span multiple repos (tokens in `common`, view in `components`, docs in `wiki`). The orchestrator sequences writes correctly.
-- **Non-blocking side effects** — wiki generation + Jira sync run as augmentations; failures log and Phase 7 continues.
-- **Cross-cutting integration skills** — Phase 3D detects content patterns (`figma-form-integration`, `figma-price-integration`, `figma-ui-patterns`) and interaction patterns (`figma-navigation`, `figma-overlays`, `figma-bottom-sheets`) and dispatches the matching skill. All are **native-SwiftUI-first**; a project's own navigation/overlay/sheet system is used only when `figmaConfig.ui.{navigationSystem,overlaySystem,sheetSystem}` declares one (absent → stock SwiftUI: `NavigationStack`, `.alert`/`.sheet(item:)`, `.presentationDetents`). Generic across SwiftUI codebases.
-- **Evolve an existing component** — `figma-evolve-component` reconciles a shipped component against current Figma (drift-heal) and additively extends it for a new need, behind a mandatory human gate — distinct from a fresh build, `figma-mend` (rebuild), and `figma-fix` (review bug).
+- **One command** - `/multi-agent <figma-url-or-issue>` - produces a complete component: Configuration + View + Modifiers + Preview + README + three layers of tests + Code Connect + wiki doc.
+- **Platform-agnostic orchestration** - classification happens once in Phase 0; the orchestrator picks the right code generator for iOS or Android based on `figmaConfig.project.platform`.
+- **Multi-repo aware** - components span multiple repos (tokens in `common`, view in `components`, docs in `wiki`). The orchestrator sequences writes correctly.
+- **Non-blocking side effects** - wiki generation + Jira sync run as augmentations; failures log and Phase 7 continues.
+- **Cross-cutting integration skills** - Phase 3D detects content patterns (`figma-form-integration`, `figma-price-integration`, `figma-ui-patterns`) and interaction patterns (`figma-navigation`, `figma-overlays`, `figma-bottom-sheets`) and dispatches the matching skill. All are **native-SwiftUI-first**; a project's own navigation/overlay/sheet system is used only when `figmaConfig.ui.{navigationSystem,overlaySystem,sheetSystem}` declares one (absent → stock SwiftUI: `NavigationStack`, `.alert`/`.sheet(item:)`, `.presentationDetents`). Generic across SwiftUI codebases.
+- **Evolve an existing component** - `figma-evolve-component` reconciles a shipped component against current Figma (drift-heal) and additively extends it for a new need, behind a mandatory human gate - distinct from a fresh build, `figma-mend` (rebuild), and `figma-fix` (review bug).
 
 ## How it runs
 
-When multi-agent Phase 0 classifies a task as `component` (Figma URL in description, or figma-driven instruction path), Phase 3 delegates the entire phase to the enabled `ai-<platform>-engineering-toolkit` marketplace plugin's component skill (`create-component`, fallback `create-ui-component`) via the Skill tool. Component skills live in the plugin marketplace, not the pipeline. The dispatch layer records a coarse component-build row in `state.phases["3"].subphases[]` — multi-agent's phase-tracker reads that array with no special case. The subphase list below describes the flow the plugin skill runs internally.
+When multi-agent Phase 0 classifies a task as `component` (Figma URL in description, or figma-driven instruction path), Phase 3 delegates the entire phase to the enabled `ai-<platform>-engineering-toolkit` marketplace plugin's component skill (`create-component`, fallback `create-ui-component`) via the Skill tool. Component skills live in the plugin marketplace, not the pipeline. The dispatch layer records a coarse component-build row in `state.phases["3"].subphases[]` - multi-agent's phase-tracker reads that array with no special case. The subphase list below describes the flow the plugin skill runs internally.
 
 ### Internal phase order
 
 ```
-3.0  init               — node-id parse, registry lookup, worktree confirm
-3.1  gather             — Figma API / MCP fetch, variant properties, token extraction
-3.2a testing identifiers — semantic tags (platform-agnostic)
-3.2b localisation        — string keys → common repo
-3.2c accessibility       — a11y metadata; platform-aware output
-3.2d analytics           — event keys
-3.3  token mapping       — Figma values → design token symbols
-3.4a Configuration       — pure value type (SwiftUI struct / Compose @Immutable data class)
-3.4b View                — SwiftUI body / @Composable fun
-3.4c Docs                — FIGMA.md (iOS) / README.md (Android)
-3.4d Preview             — variant grid
-3.4e Modifiers           — fluent API
-3.5a structural tests    — ViewInspector / Compose Testing
-3.5b snapshot tests      — SnapshotTesting / Paparazzi
-3.5c unit tests          — configuration semantics + behavioural
-3.6  Code Connect        — .figma.swift / .figma.kt registration
-3.7  wiki                — 4-adapter dispatch (submodule / in-repo / github-wiki / separate-repo)
-3.8  cleanup             — artifact pruning, state finalize
+3.0  init               - node-id parse, registry lookup, worktree confirm
+3.1  gather             - Figma API / MCP fetch, variant properties, token extraction
+3.2a testing identifiers - semantic tags (platform-agnostic)
+3.2b localisation        - string keys → common repo
+3.2c accessibility       - a11y metadata; platform-aware output
+3.2d analytics           - event keys
+3.3  token mapping       - Figma values → design token symbols
+3.4a Configuration       - pure value type (SwiftUI struct / Compose @Immutable data class)
+3.4b View                - SwiftUI body / @Composable fun
+3.4c Docs                - FIGMA.md (iOS) / README.md (Android)
+3.4d Preview             - variant grid
+3.4e Modifiers           - fluent API
+3.5a structural tests    - ViewInspector / Compose Testing
+3.5b snapshot tests      - SnapshotTesting / Paparazzi
+3.5c unit tests          - configuration semantics + behavioural
+3.6  Code Connect        - .figma.swift / .figma.kt registration
+3.7  wiki                - 4-adapter dispatch (submodule / in-repo / github-wiki / separate-repo)
+3.8  cleanup             - artifact pruning, state finalize
 ```
 
 Each subphase emits a `→ <verb> <object>` progress line per `refs/progress-contract.md`; multi-agent's phase-tracker renders them inline under the Phase 3 row.
@@ -71,7 +71,7 @@ Minimum viable config:
 
 Android projects swap the `build` section to `{ "gradleModule": ":components:button", "variant": "debug" }` and set `project.platform` to `"android"`.
 
-**Optional `ui` block — UI interaction systems.** Consumed by the `figma-navigation` / `figma-overlays` / `figma-bottom-sheets` skills and Phase 4 review. Omit it (or set `mode: "native"`) and the pipeline generates stock SwiftUI (`NavigationStack`, `.alert`/`.sheet(item:)`, `.sheet`+`presentationDetents`). Set `mode: "custom"` to route to a project-supplied system by type name:
+**Optional `ui` block - UI interaction systems.** Consumed by the `figma-navigation` / `figma-overlays` / `figma-bottom-sheets` skills and Phase 4 review. Omit it (or set `mode: "native"`) and the pipeline generates stock SwiftUI (`NavigationStack`, `.alert`/`.sheet(item:)`, `.sheet`+`presentationDetents`). Set `mode: "custom"` to route to a project-supplied system by type name:
 
 ```json
 "ui": {
@@ -97,7 +97,7 @@ Full contract: [`pipeline/multi-agent-refs/issue-jira-triad.md`](../pipeline/mul
 | Mode | Path layout | Push semantics |
 |---|---|---|
 | `submodule` | `{repos.wiki.path}/FigmaComponents/{Category}/{Name}/{Name}.md` | Commit into submodule's branch, push, update parent repo's pointer |
-| `in-repo` | `{repos.components.path}/.wiki/components/{Category}/{Name}.md` | No push — ships with the component commit in Phase 6 |
+| `in-repo` | `{repos.components.path}/.wiki/components/{Category}/{Name}.md` | No push - ships with the component commit in Phase 6 |
 | `github-wiki` | `{owner}/{repo}.wiki.git/{Category}/{Name}.md` | Clone the `.wiki.git`, commit, push |
 | `separate-repo` | Remote repo's configured branch | Clone to cache, commit, push |
 
@@ -124,14 +124,14 @@ Global settings that affect the figma pipeline:
 |---|---|---|
 | Phase 3 halts with "plugin not enabled" | The `ai-<platform>-engineering-toolkit` plugin is not enabled in this repo | Enable it in the repo's `.claude/settings.local.json` (`"ai-ios-engineering-toolkit@<marketplace>": true`) and reload the session |
 | `multi-agent:create-component` not found | Marketplace not installed / plugin disabled | Install the marketplace and enable the platform toolkit; dispatch tries `create-component` then `create-ui-component` |
-| Wiki adapter failure | Remote unreachable (separate-repo mode) | Adapter caches pending output; next run retries. Non-blocking — Phase 7 continues. |
-| Jira auto-create hits 5xx | Transient Jira outage | Non-blocking — pipeline continues without link. User can run `/multi-agent:channels` post-hoc to add it. |
+| Wiki adapter failure | Remote unreachable (separate-repo mode) | Adapter caches pending output; next run retries. Non-blocking - Phase 7 continues. |
+| Jira auto-create hits 5xx | Transient Jira outage | Non-blocking - pipeline continues without link. User can run `/multi-agent:channels` post-hoc to add it. |
 | Android gradle unresolved | `figmaConfig.build.gradleModule` not set | Populate the config; halt is intentional (no guessing) |
 
 ## Further reading
 
-- [`pipeline/multi-agent-refs/component-dispatch.md`](../pipeline/multi-agent-refs/component-dispatch.md) — Phase 3 delegation contract.
-- [`pipeline/multi-agent-refs/wiki-capture.md`](../pipeline/multi-agent-refs/wiki-capture.md) — Phase 7 wiki contract.
-- [`pipeline/multi-agent-refs/issue-jira-triad.md`](../pipeline/multi-agent-refs/issue-jira-triad.md) — issue → jira → wiki triad contract.
-- [`pipeline/multi-agent-refs/progress-contract.md`](../pipeline/multi-agent-refs/progress-contract.md) — live progress-line emission contract.
-- [`pipeline/multi-agent-refs/cross-cli-contract.md`](../pipeline/multi-agent-refs/cross-cli-contract.md) — Claude ↔ Copilot CLI parity.
+- [`pipeline/multi-agent-refs/component-dispatch.md`](../pipeline/multi-agent-refs/component-dispatch.md) - Phase 3 delegation contract.
+- [`pipeline/multi-agent-refs/wiki-capture.md`](../pipeline/multi-agent-refs/wiki-capture.md) - Phase 7 wiki contract.
+- [`pipeline/multi-agent-refs/issue-jira-triad.md`](../pipeline/multi-agent-refs/issue-jira-triad.md) - issue → jira → wiki triad contract.
+- [`pipeline/multi-agent-refs/progress-contract.md`](../pipeline/multi-agent-refs/progress-contract.md) - live progress-line emission contract.
+- [`pipeline/multi-agent-refs/cross-cli-contract.md`](../pipeline/multi-agent-refs/cross-cli-contract.md) - Claude ↔ Copilot CLI parity.

package/docs/adr/0001-three-model-triage.md

@@ -1,11 +1,11 @@
 # 1. CLI-aware parallel review with top-tier triage
 
-**Status:** Accepted · 2025 · Amended 2026-04 (CLI-aware reviewer set) · Amended 2026-07 (v10.6.0: Fable 5 restored — Reviewer 1 and triage run on Fable on Claude Code; Copilot CLI pins Opus. "Opus" below reads as "the top tier of the day")
+**Status:** Accepted · 2025 · Amended 2026-04 (CLI-aware reviewer set) · Amended 2026-07 (v10.6.0: Fable 5 restored - Reviewer 1 and triage run on Fable on Claude Code; Copilot CLI pins Opus. "Opus" below reads as "the top tier of the day")
 
 ## Context
 
 Code review is the phase where the pipeline most commonly ships wrong work. A
-single reviewer model — whether Opus, Sonnet, or GPT — systematically misses
+single reviewer model - whether Opus, Sonnet, or GPT - systematically misses
 certain failure classes and hallucinates others. Worse, reviewer output tends
 to be noisy: style nitpicks, out-of-scope findings, and repeated observations
 across diffs.
@@ -20,26 +20,26 @@ We need a review stage that:
 
 Phase 4 runs **reviewers in parallel** on the same diff. The reviewer set is
 determined by the host CLI, because GPT-5.4 is only natively reachable from
-Copilot CLI — Claude Code has no first-class GPT bridge, and round-tripping
+Copilot CLI - Claude Code has no first-class GPT bridge, and round-tripping
 would add latency without improving signal.
 
 **Claude Code (2 parallel reviewers):**
 
-- **Opus** — deep security and architecture focus
-- **Sonnet** — quality, correctness, naming
+- **Opus** - deep security and architecture focus
+- **Sonnet** - quality, correctness, naming
 
 **Copilot CLI (3 parallel reviewers):**
 
-- **Opus** — deep security and architecture focus
-- **GPT-5.4** — edge cases and cross-provider diversity
-- **Sonnet** — quality, correctness, naming
+- **Opus** - deep security and architecture focus
+- **GPT-5.4** - edge cases and cross-provider diversity
+- **Sonnet** - quality, correctness, naming
 
 Their raw findings are then passed to a **separate Opus triage agent** that
 classifies each finding as `accepted`, `deferred`, or `rejected`. Only
 `accepted` blocking items loop back to Phase 3 for rework.
 
 Deterministic gates (build, lint, test, secret scan) run before any AI
-reviewer is invoked — no point paying for review on code that doesn't build.
+reviewer is invoked - no point paying for review on code that doesn't build.
 
 ## Consequences
 
@@ -47,7 +47,7 @@ Positive:
 
 - Three different model lineages each catch a different slice of issues.
 - The triage pass filters the noise that individual reviewers can't filter
-  about themselves — it has scope context from Phase 1/2 that single reviewers
+  about themselves - it has scope context from Phase 1/2 that single reviewers
   don't carry.
 - Hallucinated findings get rejected instead of looping the pipeline forever.
 - `validate-triage.mjs` enforces the triage output contract at runtime; a
@@ -61,7 +61,7 @@ Negative / costs:
   more expensive.
 - Triage agent introduces a single point of failure; validator + fallback
   (treat all findings as accepted after double-failure) bounds the damage.
-- Cross-provider (GPT) dependency on Copilot CLI — if the provider is down,
+- Cross-provider (GPT) dependency on Copilot CLI - if the provider is down,
   the pipeline continues with 2 reviewers (Opus + Sonnet) and a warning.
 - Cross-CLI asymmetry: Copilot CLI catches a slice of failures (edge cases
   via GPT diversity) that Claude Code's 2-model set misses. Accepted as a
@@ -70,7 +70,7 @@ Negative / costs:
 ## Alternatives Considered
 
 **Single reviewer (Opus only):** simpler, cheaper, but misses edge cases
-the other model lineages catch. Trialed in early v2 — noticeable false
+the other model lineages catch. Trialed in early v2 - noticeable false
 negatives on concurrency bugs.
 
 **Two reviewers + no triage:** cheaper still. Rejected because the raw

package/docs/adr/0002-instruction-driven-flag.md

@@ -7,12 +7,12 @@
 The main 9-phase pipeline is TDD-centric. The Figma-to-SwiftUI workflow is
 config-driven (design tokens, Code Connect, Wiki generation) and does not
 map onto the red-green-refactor cycle. Earlier versions handled this with
-implicit branching in Phase 3 — "if the task has a Figma URL, fork here".
+implicit branching in Phase 3 - "if the task has a Figma URL, fork here".
 
 Implicit branches had three problems:
 
-1. Hard to debug — no single place where the fork was decided.
-2. Silent failure when instruction files were missing or misnamed — Phase 6
+1. Hard to debug - no single place where the fork was decided.
+2. Silent failure when instruction files were missing or misnamed - Phase 6
    would fall through to standard commit flow, losing Figma-specific steps.
 3. Phase 7 audit couldn't tell which branch was actually taken.
 
@@ -30,7 +30,7 @@ Phase 6 uses a **deterministic truth table** (documented at
 | ------------------- | -------------------------------- | ------ |
 | true  | yes | Instruction-driven path |
 | true  | no  | Log error, set `instructionDrivenFallback=true`, use standard path |
-| false | —   | Standard path |
+| false | -   | Standard path |
 
 ## Consequences
 
@@ -40,7 +40,7 @@ Positive:
 - Missing instruction files fail loud (`instructionDrivenFallback` surfaced in
   Phase 7 report) instead of silent.
 - The Figma pipeline could be extracted to its own package without changing
-  main pipeline code — it just writes the flag + files, and the main pipeline
+  main pipeline code - it just writes the flag + files, and the main pipeline
   reads them.
 
 Negative:

package/docs/adr/0003-unified-shared-skills.md

@@ -1,6 +1,6 @@
 # 3. Unified `skills/shared/` for Claude Code + Copilot CLI
 
-**Status:** Accepted · 2026-04 (v3.5.0) · Amended 2026-04 (v5.3.3 — internal `core/external/` split, install destination unchanged)
+**Status:** Accepted · 2026-04 (v3.5.0) · Amended 2026-04 (v5.3.3 - internal `core/external/` split, install destination unchanged)
 
 ## Context
 
@@ -11,7 +11,7 @@ Consequences:
 - Claude users could not invoke `multi-agent-*` pipeline skills (they were
   Copilot-only).
 - Copilot users couldn't access iOS/SwiftUI guidance.
-- Two directories meant two places to add or update a skill — drift was
+- Two directories meant two places to add or update a skill - drift was
   inevitable, and unnoticed.
 - README claim "145 skills" was not accurate for either CLI.
 
@@ -33,7 +33,7 @@ Positive:
 - Adding a skill is now a single write.
 - Skill index (`pipeline/skills/shared/README.md`) auto-generates from a
   single source.
-- Unblocks the 4.0 single-source-for-commands-and-skills plan — same
+- Unblocks the 4.0 single-source-for-commands-and-skills plan - same
   directory structure, just needs content unification.
 
 Negative:
@@ -41,7 +41,7 @@ Negative:
 - Disk footprint per install is ~1.5× larger than before for users who
   only wanted iOS or only wanted web.
 - Some iOS skills are noise for backend-only users and vice versa.
-  Mitigated by the categorized index — easy to browse and ignore.
+  Mitigated by the categorized index - easy to browse and ignore.
 
 ## Alternatives Considered
 
@@ -49,7 +49,7 @@ Negative:
 the drift-risk but not the "which CLI gets what" asymmetry in the source.
 Hidden complexity.
 
-**Per-stack skill packs (`skills/ios/`, `skills/android/`, …) with
+**Per-stack skill packs (`skills/ios/`, `skills/android/`, ...) with
 install-time filter:** tempting. Rejected for 3.5.0 because the install-time
 filter would need a stack detector exact enough to not exclude relevant
 cross-cutting skills. Revisit for 4.0.

package/docs/adr/0004-zero-dependency-philosophy.md

@@ -10,8 +10,8 @@ compatibility puzzle. For a CLI tool that installs itself into user shells
 and runs with write access to `~/.claude/` and `~/.copilot/`, the blast
 radius of a compromised dependency is large.
 
-At the same time, some conveniences — JSON Schema validators (`ajv`), YAML
-parsers (`yaml`), templating engines — would be trivial to pull in and would
+At the same time, some conveniences - JSON Schema validators (`ajv`), YAML
+parsers (`yaml`), templating engines - would be trivial to pull in and would
 shorten a few scripts.
 
 ## Decision
@@ -26,7 +26,7 @@ Consequences:
 - `validate-triage.mjs`, `validate-{reviewer,analysis,planning}.mjs`,
   `write-state.mjs`, `migrate-state.mjs` all hand-roll their JSON Schema
   validation. Slower to write, but zero attack surface.
-- `validate-schemas.mjs` is a shallow checker — catches "the schema file is
+- `validate-schemas.mjs` is a shallow checker - catches "the schema file is
   itself malformed", doesn't deep-validate every instance. That's what the
   runtime validators are for.
 - Install is fast: `npm install` against the published package is a single
@@ -37,7 +37,7 @@ Consequences:
 Positive:
 
 - No supply-chain surface in the published package.
-- No Node version interop headaches — Node 18+ core APIs are stable enough.
+- No Node version interop headaches - Node 18+ core APIs are stable enough.
 - `npx @mmerterden/multi-agent-pipeline install` runs instantly from cold.
 
 Negative:
@@ -53,7 +53,7 @@ Negative:
 **Pull in `ajv` for real schema validation:** clean and standard. Rejected
 because of supply-chain surface + bundle bloat (adds ~200 kB gzipped).
 
-**Optional deps — use `ajv` if installed, fall back otherwise:** too clever.
+**Optional deps - use `ajv` if installed, fall back otherwise:** too clever.
 "Sometimes validated, sometimes not" is worse than either extreme.
 
 **Bundle dependencies into the published tarball:** would remove the install-