@mmerterden/multi-agent-pipeline 12.6.0 → 12.7.0

package/CHANGELOG.md

@@ -16,6 +16,89 @@ 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

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
 
@@ -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-

package/docs/adr/0005-lazy-phase-docs.md

@@ -11,7 +11,7 @@ instructions for phases not yet relevant, leaving less room for the actual
 code being worked on.
 
 Additionally, phase docs are the easiest part of the pipeline to inflate
-accidentally — examples, prose, caveats pile up. Without a budget, phase
+accidentally - examples, prose, caveats pile up. Without a budget, phase
 docs silently grow until they push useful content out of context.
 
 ## Decision
@@ -43,7 +43,7 @@ Positive:
 - Context window stays available for the code under review.
 - Budgets surface "this phase is getting bloated" early (warn) before they
   become blocking (max).
-- A PR that inflates a phase doc past `max` fails CI — hard forcing function
+- A PR that inflates a phase doc past `max` fails CI - hard forcing function
   against doc rot.
 
 Negative:

package/docs/adr/0006-skills-core-external-split.md

@@ -9,7 +9,7 @@ ADR-0003 (v3.5.0) collapsed the split `skills/claude/` + `skills/copilot/` into
 By v5.3.x the maintenance burden of the flat tree became visible in everyday work:
 
 - **Source navigation.** Browsing `pipeline/skills/shared/` on GitHub shows 148 sibling directories with no hint which ones are load-bearing for the pipeline vs. which ones are third-party imports.
-- **Code review cost.** Changes under `shared/` have very different risk profiles depending on which kind of skill changed. `multi-agent-sync/SKILL.md` is pipeline-critical — any drift breaks cross-CLI parity. `ios-developer/SKILL.md` is a reference guide imported from upstream — edits almost never affect pipeline behavior.
+- **Code review cost.** Changes under `shared/` have very different risk profiles depending on which kind of skill changed. `multi-agent-sync/SKILL.md` is pipeline-critical - any drift breaks cross-CLI parity. `ios-developer/SKILL.md` is a reference guide imported from upstream - edits almost never affect pipeline behavior.
 - **Grep noise.** `grep -r skills/shared/` produces 148× the noise it should when searching for pipeline code.
 - **Audit findings.** The v5.3.0 audit flagged this as technical debt worth addressing once the pipeline stabilized.
 
@@ -19,14 +19,14 @@ Keep the single-write benefit of ADR-0003. Split the source layout into two subd
 
 ```
 pipeline/skills/shared/
-├── core/         — 21 multi-agent* orchestration skills (pipeline-critical)
-├── external/     — 127 iOS / Android / generic skills imported from upstream
-└── README.md     — skill index
+├── core/         - 21 multi-agent* orchestration skills (pipeline-critical)
+├── external/     - 127 iOS / Android / generic skills imported from upstream
+└── README.md     - skill index
 ```
 
 **Install destination is unchanged.** Both trees flatten into `~/.claude/skills/` and `~/.copilot/skills/`; skill discovery at runtime sees the same flat list of 148 skills regardless of where they live in source. ADR-0003's core decision ("same coverage on both CLIs") is preserved.
 
-`install.js` was updated to `copyDir(sharedCoreSrc, CLAUDE_SKILLS)` + `copyDir(sharedExternalSrc, CLAUDE_SKILLS)` — two reads, same flat write.
+`install.js` was updated to `copyDir(sharedCoreSrc, CLAUDE_SKILLS)` + `copyDir(sharedExternalSrc, CLAUDE_SKILLS)` - two reads, same flat write.
 
 ## Consequences
 
@@ -41,7 +41,7 @@ Negative:
 
 - `install.js` walks two source trees instead of one. Implementation cost: 6 lines.
 - Every smoke test and doc reference that hard-coded `pipeline/skills/shared/multi-agent-*/` as a path had to update to `pipeline/skills/shared/core/multi-agent-*/`. One-time sweep.
-- ADR-0003's "single source of truth" wording becomes "single install target from two logical sources" — slightly more nuance to explain.
+- ADR-0003's "single source of truth" wording becomes "single install target from two logical sources" - slightly more nuance to explain.
 
 ## Alternatives Considered