@mmerterden/multi-agent-pipeline 12.5.0 → 12.6.0

package/CHANGELOG.md

@@ -14,6 +14,136 @@ 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

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.5.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.
 

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

@@ -0,0 +1,287 @@
+---
+description: "Mock-mode vs Figma design audit (iOS / Android, local-only). Pick repo + module, gate on mock support, enumerate every state driver into a countable target set, build Debug in a worktree, launch in mock mode, fetch Figma variants, compare each pixel + px-spacing + typography + color, and export a side-by-side annotated report (HTML + PDF + Confluence) to ~/DesignChecks. A coverage gate fails the run when a target is neither audited nor skipped with a reason."
+description-tr: "Mock-mod vs Figma tasarım denetimi (iOS / Android, yalnızca lokal). Repo + modül seç, mock desteğini geçitle, her state sürücüsünü sayılabilir bir hedef kümesine çıkar, worktree'de Debug derle, mock modda aç, Figma varyantlarını çek, her varyantı piksel + px-boşluk + tipografi + renk düzeyinde karşılaştır, yan yana annotasyonlu raporu (HTML + PDF + Confluence) ~/DesignChecks altına aktar. Bir hedef ne denetlenmiş ne de gerekçeyle atlanmışsa kapsam geçidi koşuyu başarısız sayar."
+argument-hint: '[scope]  -  empty = whole module; screen name; screen@variant; Figma URL(s); --resume'
+allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep, TaskCreate, TaskUpdate, AskUserQuestion, Skill, mcp__claude_ai_Figma__get_metadata, mcp__claude_ai_Figma__get_design_context, mcp__claude_ai_Figma__get_screenshot, mcp__dev-toolkit__design_mock_detect, mcp__dev-toolkit__design_scenario_inventory, mcp__dev-toolkit__design_mock_launch, mcp__dev-toolkit__design_ui_geometry, mcp__dev-toolkit__design_visual_compare, mcp__dev-toolkit__design_report, mcp__dev-toolkit__ios_list_devices, mcp__dev-toolkit__ios_boot_device, mcp__dev-toolkit__ios_launch_app, mcp__dev-toolkit__ios_terminate_app, mcp__dev-toolkit__ios_screenshot, mcp__dev-toolkit__ios_tap, mcp__dev-toolkit__ios_swipe, mcp__dev-toolkit__ios_type_text, mcp__dev-toolkit__ios_open_url, mcp__dev-toolkit__ios_get_ui_tree, mcp__dev-toolkit__ios_status_bar, mcp__dev-toolkit__ios_set_appearance, mcp__dev-toolkit__ios_set_locale, mcp__dev-toolkit__ios_xcodebuild, mcp__dev-toolkit__ios_xcresult, mcp__dev-toolkit__android_list_devices, mcp__dev-toolkit__android_screenshot, mcp__dev-toolkit__android_tap, mcp__dev-toolkit__android_swipe, mcp__dev-toolkit__android_type_text, mcp__dev-toolkit__android_open_url, mcp__dev-toolkit__android_launch_app, mcp__dev-toolkit__android_stop_app
+---
+
+# /multi-agent:design-check  -  Mock-mode vs Figma design audit
+
+Local, on-device design-conformance auditor. It runs the app in a **mock mode** on a simulator / emulator and compares each screen (and every mock variant the build exposes) against its Figma design at the **pixel + geometry + typography + color** level, then produces a detailed report.
+
+**Local-only**: no CI/CD, no cron, no commits, no PR. It is a read-only audit that writes a report to `~/DesignChecks/`. The worktree exists only to build the Debug app without touching the user's working tree.
+
+> **Language (read FIRST)**: Two independent axes.
+>
+> 1. **`prefs.global.promptLanguage` is always `en`**  -  this spec and every instruction to the LLM stay English.
+> 2. **`prefs.global.outputLanguage` is user-selectable**  -  applies to conversational lines and the human-readable parts of the report. Pass it to `design_report` as `report.lang`; the engine defaults to English and ships an `en` + `tr` label pack, plus per-key `report.labels` overrides.
+>
+> Regardless of `outputLanguage`, these stay English: `AskUserQuestion` labels/headers, branch names, file paths, code identifiers, log lines. Full contract: `$HOME/.claude/multi-agent-refs/rules.md` "Language Application".
+
+## Scope  -  `$ARGUMENTS`
+
+The scope decides which **inventory targets** (Phase 0 step 5) the run must audit. It never changes how thoroughly each target is audited.
+
+| Form | Example | Scope |
+|------|---------|-------|
+| empty / `module` | `/multi-agent:design-check` | Every target in the module's inventory |
+| screen name | `boarding-pass` | Every target whose `screen` matches (case/separator-insensitive) |
+| `screen@variant` | `boarding-pass@expired` | One target |
+| target id | `scenario-case:boardingpassoutcome-expired` | One target, exactly |
+| Figma URL(s) | `https://figma.com/design/…?node-id=1-2` | Only the frames those URLs name |
+| `--resume` | `/multi-agent:design-check --resume` | The unaudited remainder of the most recent run for this repo + module |
+| combinations | `seat-map summary@semi-success` | Union of the above, space- or newline-separated |
+
+Multiple forms may be combined. A scope that matches **no** inventory target is an error, not an empty run: print the closest inventory ids and halt.
+
+**Whole-module is the default, and it is meant to finish.** The inventory prices each target (`cost: relaunch | in-app`) and batches them into a run `plan`, so a 50-target module is typically about a dozen relaunches rather than fifty  -  a full audit is one sitting, not a project. Scope exists for resuming an interrupted run and for re-checking one screen after a fix, **not** for trimming an audit down to what feels affordable. The coverage gate applies to the **scoped** target set, so a deliberate scoped run is never penalised for out-of-scope targets, and `--resume` closes the remainder.
+
+## Pipeline
+
+```
+Phase 0: Init & Gate  → repo + module picker, platform detect, MOCK FEASIBILITY GATE, SCENARIO INVENTORY, scope resolve, report dir, worktree
+Phase 1: Build & Launch → Debug build in worktree, boot device, install, launch in mock mode
+Phase 2: Figma          → fetch module frame tree, enumerate + map variants (ask when ambiguous)
+Phase 3: Drive & Compare → per plan batch: one launch → capture + flip in-app states → match → batch-ask → compare
+Phase 4: Report         → coverage gate + assemble + export HTML + PDF (+ Confluence) to ~/DesignChecks/
+```
+
+## Requirements
+
+- **iOS**: Xcode + an available Simulator. **Android**: Android SDK + a running emulator / device.
+- **MCP**: the `dev-toolkit` MCP server (>= 2.8.0, for `design_scenario_inventory`, the `design_report` coverage gate, and `design_visual_compare` region alignment). The Figma MCP (`mcp__claude_ai_Figma__*`) must be authenticated - the user supplies the Figma URL.
+- The selected module must support a **mock mode** (Phase 0 gate decides this). No mock support → the command halts.
+
+## Phase Tracker Contract (mandatory)
+
+Register one tile per phase in strict order BEFORE any update, on both channels. Full spec: `$HOME/.claude/multi-agent-refs/tracker-contract.md`.
+
+```bash
+bash $HOME/.claude/scripts/phase-tracker.sh init "$TASK_ID"
+for p in "0:Init & Gate" "1:Build & Launch" "2:Figma" "3:Drive & Compare" "4:Report"; do
+  bash $HOME/.claude/scripts/phase-tracker.sh add "${p%%:*}" "${p#*:}"
+done
+```
+
+In Claude Code also drive the native TaskList widget: fire all `TaskCreate` calls in phase order (0→1→2→3→4) first, persist each `taskId` via `phase-tracker.sh meta <N> tasklist_id`, then flip status with `TaskUpdate` + `phase-tracker.sh update` at every boundary. On Copilot / plain shell call `phase-tracker.sh render` instead (no TaskCreate).
+
+## STOP-AND-CONFIRM format
+
+Every Phase 0 / Phase 2 decision uses a native `AskUserQuestion` picker (numbered text menus are forbidden - `feedback_native_picker_ui`). Print a `Step <i>/<n>: <what it decides>` breadcrumb before each picker. Confirmation is required even with a single option; state inheritance from a previous run is FORBIDDEN.
+
+---
+
+## Phase 0 - Init, Feasibility Gate & Inventory
+
+0. **MCP CURRENCY GATE (first, before anything expensive)** - an MCP stdio server publishes its tool list once at `initialize` and never re-reads the code, so a session connected to a server process that started before the last update keeps serving the OLD tool list while still reporting "connected". Discovering that after a Debug build and a device drive wastes the whole run and produces a report missing the very checks this spec relies on.
+
+   Assert both halves before continuing:
+
+   a. **Session** - `mcp__dev-toolkit__design_scenario_inventory` must be present in the tools available to you, and `mcp__dev-toolkit__design_visual_compare` must accept `live_region`. Absent → the session is bound to a stale process.
+
+   b. **Disk** - probe the configured server directly, which reports what a fresh connection WOULD serve:
+   ```bash
+   cd "$(python3 -c "import json,os;print(json.load(open(os.path.expanduser('~/.claude.json')))['mcpServers']['dev-toolkit']['args'][0].rsplit('/',1)[0])")" && \
+   printf '%s\n%s\n' \
+     '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}' \
+     '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
+   | node index.js 2>/dev/null | python3 -c "
+import sys,json
+for l in sys.stdin:
+    try: m=json.loads(l)
+    except: continue
+    if m.get('id')==1: print('version', m['result']['serverInfo']['version'])
+    if m.get('id')==2:
+        n=[t['name'] for t in m['result']['tools']]
+        print('tools', len(n), 'inventory', 'design_scenario_inventory' in n)"
+   ```
+
+   Branch on the two results:
+   - **disk OK, session missing the tool** → **HALT** and tell the user to reconnect: `/mcp` → `dev-toolkit` → Reconnect. Note the tool-count tell (a stale build advertises one fewer `design_*` tool). If a reconnect does not take, stale server processes may be lingering - `pgrep -f dev-toolkit-mcp/index.js` with `ps -o lstart=` shows their start times, and any that predate the code's mtime cannot serve the current tools.
+   - **disk itself stale** (older version, or `inventory False`) → **HALT**: the checkout needs updating before a reconnect can help.
+   - **both current** → continue.
+
+   Never work around a stale server by substituting a local `node` call for the missing tool: the run would silently lose the coverage gate and region alignment, which is exactly the failure this gate exists to prevent.
+
+1. **Repo picker** - reuse `$HOME/.claude/multi-agent-refs/_repo-picker.md`. The account picker is skipped (Figma token is user-supplied, no Jira/GitHub fetch happens) unless Confluence export is enabled, in which case resolve the Confluence token via `account-resolver.sh`.
+2. **Module / dev-context picker** - reuse `$HOME/.claude/multi-agent-refs/_dev-context.md`. Auto-suggest submodules from `.gitmodules` (`submodule-detector.sh`); the user selects the single module to audit (multi-module allowed - each is audited independently).
+3. **Platform detect** - `.xcodeproj` / `Package.swift` → iOS; `build.gradle*` → Android (same markers as `phase-0-init.md`). Persist `state.platform`.
+4. **MOCK FEASIBILITY GATE** - run against the selected module path:
+   ```
+   mcp__dev-toolkit__design_mock_detect({ repo_path: "<module path>", platform: "<ios|android>",
+     extra_keys: <design-check-config mock.keys, if any> })
+   ```
+   Branch on `supported`:
+   - **`false`** → **HALT**. Show `reason` + that no runtime mock switch / launchable app / mock fixtures were found. Tell the user this module cannot be audited by design-check and stop. Do not fabricate a comparison.
+   - **`"debug-only"`** → surface an `AskUserQuestion` warning: mocks are compiled into the Debug build via `#if DEBUG` DI, so **variants cannot be toggled at launch** - only the default Debug state is comparable. Options: `{ label: "Continue", description: "Audit the single default Debug state only" }`, `{ label: "Cancel", description: "Stop" }`.
+   - **`true`** → continue. Persist `state.designCheck.mock = <detect result>` (mechanism, activation, variantsHint, evidence).
+5. **SCENARIO INVENTORY (this is the audit's target set)**:
+   ```
+   mcp__dev-toolkit__design_scenario_inventory({ repo_path: "<module path>", platform,
+     extra_launch_args: <config inventory.extraLaunchArgs>,
+     extra_targets:     <config inventory.extraTargets>,
+     ignore_targets:    <config inventory.ignoreTargets> })
+   ```
+   Returns `targets[]` - each `{ id, kind, label, screen, driver, cost, evidence }` - plus `plan[]`, `relaunchCount`, `groups[]`, `byKind`, `byCost`, `ignored[]`, `truncated`, `scanStrategy`. Kinds: `launch-arg`, `scenario-case`, **`prefix-code`** (a mock repository branching on the prefix of the reference the user types - usually the LARGEST group, and the one a selector-only search misses entirely), `code-scenario`, `fixture`, `deep-link`.
+
+   This list, not the agent's reading of the code and not what the UI happens to expose to tapping, is what the run is measured against. Persist verbatim to `state.designCheck.inventory`.
+   - `targetCount: 0` → warn that no state driver was found and that only the default launch state can be audited; a `debug-only` project legitimately lands here.
+   - `truncated: true` → the inventory hit its cap, so the target set is INCOMPLETE. Say so now, and pass `coverage.truncatedInventory: true` in Phase 4 so the gate fails rather than reporting a clean percentage of a partial denominator. Narrow the scope to a screen and work through the module in `--resume` steps.
+   - `ignored[]` non-empty → list what the config dropped, so a stale `ignoreTargets` cannot quietly shrink the audit.
+6. **Scope resolve** - intersect `$ARGUMENTS` (grammar above) with `inventory.targets`. Persist `state.designCheck.scope = { argument, targetIds[] }`.
+
+   Print the resolved set grouped by screen **with its relaunch cost**: `<n> targets · <relaunchCount> relaunches`. Read the cost from `plan`, not from the target count - one relaunch serves every in-app target on that screen, so a 50-target module is typically a dozen relaunches, not fifty. **Whole-module is the intended default**; only ask for confirmation when `relaunchCount` exceeds `config coverage.confirmAbove` (default 25), and phrase it as a cost estimate, not as an invitation to shrink the audit. Never propose a smaller scope as the easy path - a scoped run is for resuming or for a focused re-check, not for avoiding work.
+7. **`--resume`** - read the most recent `~/DesignChecks/{repo}__{module}/*/run-state.json`; the scope becomes that run's targets minus its `covered` and minus its `skipped` entries. Skips carry a reason and are honoured, so a resume covers the genuinely unaudited remainder. No previous run → tell the user and fall back to whole-module scope after confirmation.
+8. **Report dir** - create `~/DesignChecks/{repo}__{module}/{UTC-timestamp}/` (and `assets/` inside it) now, and persist it as `state.designCheck.reportDir`. Phase 3 writes captures, comparison images, and `run-state.json` into it, so it must exist before driving starts - not at export time. This is report output, not a worktree; $HOME is intended here.
+9. **Worktree** - build the Debug app in an isolated worktree so the user's tree is untouched. Follow `phase-0-init.md` Step 8 convention exactly: `{projectRoot}/{worktreeBasePath}/{taskId}` (default `.worktrees/DC-<shortId>`), **never under $HOME** (`feedback_worktree_path_convention`). Stale-lock heal (`git worktree prune`) + residue guard (`.worktrees/` in `.git/info/exclude`) first. Local mode is not offered - the audit always uses a worktree checkout of the current branch's HEAD (no fetch/push).
+
+Persist `agent-state.json` with `taskId`, `mode: "design-check"`, `platform`, `projectRoot`, `worktreePath`, `module`, `designCheck`.
+
+## Phase 1 - Build & Launch (mock)
+
+1. **Debug build** in the worktree (mock activation requires the Debug configuration):
+   - iOS: `mcp__dev-toolkit__ios_xcodebuild({ workspace|project, scheme, configuration: "Debug", action: "build", destination: "generic/platform=iOS Simulator" })`. Drill failures via `ios_xcresult`.
+   - Android: `./gradlew :<module>:assembleDebug` (or `installDebug`) via Bash.
+2. **Boot device + install**: iOS `ios_list_devices` → `ios_boot_device` → install the built `.app` (`xcrun simctl install`). Android: ensure an emulator is running, `adb install -r <apk>`.
+3. **Deterministic state**: iOS `ios_status_bar({ preset: "clean" })` (09:41 / full battery); set a fixed appearance + locale so captures are stable across runs.
+4. **Launch in mock mode** using the activation from Phase 0:
+   ```
+   mcp__dev-toolkit__design_mock_launch({ platform, bundle_id|package_name,
+     launch_arg: state.designCheck.mock.activation.launchArg,      // iOS, e.g. "-debugMockMode YES"
+     intent_extra: state.designCheck.mock.activation.intentExtra }) // Android
+   ```
+   For `debug-only` there is no switch - just launch the Debug build. The build is installed once and stays installed: Phase 3 relaunches it per target rather than rebuilding.
+
+## Phase 2 - Figma fetch & variant mapping (module-scoped)
+
+Figma **discovery** happens only here: the frame tree is fetched once and no later phase browses Figma looking for candidates. Phase 3 may still fetch a specific node the user hands over in the 3.3 batch-ask - that is a targeted fetch of an already-identified frame, not discovery, and it is the only Figma call allowed after this phase.
+
+1. Resolve the Figma URL (`$ARGUMENTS` or ask via `AskUserQuestion`). Parse `fileKey` + `nodeId` (`figma.com/design/{fileKey}/...?node-id={id}`; convert `-`→`:` in node ids).
+2. `mcp__claude_ai_Figma__get_metadata({ fileKey, nodeId })` → the frame tree. Treat direct child frames as **candidate variants**.
+3. **Map inventory targets → Figma frames**: match each scoped target's `screen` + `label` (and `state.designCheck.mock.variantsHint`) to frame names by similarity.
+   - Confident 1:1 match → accept.
+   - **Ambiguous or unmatched** → deferred to the Phase 3.3 batch-ask, where the live capture can be shown alongside the question. Never guess silently.
+   - `debug-only` projects → a single variant (the default state) mapped to the primary frame.
+4. For each mapped variant: `mcp__claude_ai_Figma__get_screenshot` (the design render PNG, download locally) and `mcp__claude_ai_Figma__get_design_context` (node geometry: `absoluteBoundingBox`, `itemSpacing`, paddings, text `fontSize`/`fontFamily`, `fills` colors, and any `CodeConnectSnippet` component name). Flatten the node subtree with the geometry helper into a `figma_spec` element list. Record the Figma frame size (`figmaFrame`).
+
+Persist the variant list + spec + PNG paths to `state.designCheck.variants[]`.
+
+## Phase 3 - Drive every scoped target → capture → match → batch-ask → compare
+
+**This phase iterates `state.designCheck.scope.targetIds`  -  a finite list decided in Phase 0. It ends when every id is resolved, not when the UI stops offering new taps.** Tap-walking alone cannot reach a state that needs a different launch argument, a different scenario case, or a typed scenario code, which is exactly how a module's error / edge states go missing.
+
+### 3.1 Drive the inventory's plan, batch by batch
+
+**Follow `inventory.plan`, filtered to the scoped ids.** Each batch is one launch: the batch's relaunch target opens a screen, and every in-app target for that same screen is then flipped while the app is already sitting there. Driving the plan is what makes full coverage affordable - target-by-target relaunching is what made earlier runs give up a third of the way in.
+
+For each batch:
+1. Launch once with the batch's `launch` driver (or the plain mock activation for the `(default launch)` batch).
+2. Navigate to the screen (`ios_tap` / `ios_swipe` / `ios_type_text` route through idb).
+3. Capture the batch's relaunch target.
+4. For each in-app target in the batch: flip its selector (scenario case / scenario code), let the screen re-render, capture. **No relaunch between these.**
+
+Per-target activation by `driver.type`:
+
+| `driver.type` | Activation |
+|---|---|
+| `launch-arg` | `design_mock_launch({ launch_arg: "<mock activation> <driver.launchArg>" })` - the mock switch AND the target's flag together |
+| `intent-extra` | `design_mock_launch({ intent_extra: "<mock extra> <driver.intentExtra>" })` |
+| `scenario` | Set `driver.enum` to `driver.case` through the build's debug scenario picker (navigate to it, select, return), then drive the flow that consumes it |
+| `code` (from `prefix-code`) | Type a reference beginning with `driver.code` at the entry field the flow starts from, then walk to `driver.appliesTo`. The prefix decides which fixture the mock repository returns, so this is how most per-screen variants are reached |
+| `code` (from `code-scenario`) | Same entry field, but the code is flow-wide rather than owned by one screen |
+| `fixture` | Activate the launch arg / scenario that reads `driver.file`; when nothing does, the target is a skip with reason "fixture not reachable from any driver" |
+| `deep-link` | `ios_open_url` / `android_open_url` with `driver.url` |
+| `manual` | Config-declared: follow the config's note, or skip with that note as the reason |
+
+While a target's state is on screen, also capture the **sub-states reachable from it by tapping** - overlays, bottom sheets, modals, popups, inline errors, QR / share sheets. These cost no relaunch and belong to the target that exposed them; record them as additional captures under that target id (`<id>#<sub-label>`).
+
+For each capture: `ios_screenshot` (save PNG into the Phase 0 report dir) + `mcp__dev-toolkit__design_ui_geometry` (live boxes + screen size) → append to `state.designCheck.captured[]` with the target id and a human label. **Persist `state` and `run-state.json` after every capture**, so a run that dies mid-way resumes from where it stopped instead of starting over.
+
+If a target cannot be reached, record it immediately as `{ id, reason }` in `state.designCheck.skipped[]` with a concrete reason ("scenario picker not present in this build", "needs a live PNR", "crashes on launch: <symbol>"). "Requires a scenario / prefix / launch-arg" is **not** a reason - that is a description of the work, and the work is this phase's job.
+
+### 3.2 Match each capture → Figma frame (auto)
+
+For each captured screen, resolve its Figma frame: drill the relevant board (`get_metadata` result from Phase 2), match by structure/content; accept only a **confident** match. Add matched → `pairs[]`.
+
+### 3.3 Batch-ask the user for EVERYTHING unmatched (ONE prompt, WITH the visual)
+
+Collect ALL captures with no confident Figma match into a single list and ask the user ONCE - never guess, never show a wrong frame. **For each unmatched screen you MUST SHOW its captured live screenshot** (render/attach the PNG so they see exactly which visual you mean), name the screen, and ask for the Figma node-id / URL (in `outputLanguage`). Optionally list your best-guess candidate frame names. The user supplies the node-id/URL per shown screenshot; each becomes a confirmed pair. A screen the user declines to map is a skip with reason "no Figma frame supplied".
+
+### 3.4 Compare ALL pairs in one pass
+
+For each pair (matched + user-supplied), fetch `get_screenshot` + `get_design_context`, then:
+   ```
+   mcp__dev-toolkit__design_visual_compare({
+     figma_png, live_png, out_dir: "<report dir>/assets", label: "<variant>",
+     figma_spec, live_geometry, figma_frame, live_screen,
+     crop_top_live: <status-bar px>,       // strip device chrome the Figma frame lacks
+     tolerance_px: 2, color_tolerance: 3, max_diff_pct: 1.0 })
+   ```
+   Collect `findings` (spacing / size / position in px, color ΔE with hex, typography), `perceptualPct`, and the written image paths (figma / live / diff / overlay / side-by-side).
+
+**Bottom sheets, modals, and any partial overlay need region alignment.** Their Figma frame covers only the sheet, while the capture is the whole screen. Passing that pair as-is stretches a full screen onto a sheet-shaped frame, which misplaces every element inside the sheet and buries the real defect in noise. So for any capture whose frame is not full-screen:
+
+   ```
+   mcp__dev-toolkit__design_visual_compare({ ...as above,
+     live_region:     <the sheet container's {x,y,w,h} from design_ui_geometry>,
+     expected_region: <where the design puts that sheet, same units> })
+   ```
+   - `live_region` rebases the comparison onto the sheet's own box. Take it from the `design_ui_geometry` element that is the sheet container (the outermost element whose height is well under the screen's and which holds the sheet's content), NOT from a guess.
+   - `expected_region` comes from the Figma frame's own placement inside its parent screen frame. With it, the engine emits an `inset` finding per edge.
+   - `crop_top_live` is ignored when `live_region` is given - the region crop has already excluded device chrome.
+
+**Edge insets are defects, not tolerances.** A design that shows a sheet flush to the screen edges is not satisfied by one floating in from them, and the reverse is equally wrong. Report every `inset` finding as a deviation with its px delta; never absorb a side gap as "close enough", never raise `tolerance_px` to make one disappear. The same applies to the sheet's internal content padding, which the normal element pairing measures once the region alignment is right.
+
+**Component reference (best-effort)**: if a Figma atom carries a Code Connect component name and the repo has a matching `*.figma.swift` / `*.figma.kt`, attach that component's reference render to the variant's `componentRefs`.
+
+**Fix prompt**: from the findings, compose a ready-to-paste developer prompt (target file/screen + each deviation with expected vs actual token/value) so the user can hand it straight to an agent to apply the fix.
+
+### 3.5 Close the ledger
+
+Every scoped target id must end in exactly one bucket:
+
+- **covered** - captured AND compared (or captured and explicitly awaiting a Figma frame the user declined to supply, which is a skip)
+- **skipped** - with a concrete reason recorded in 3.1 / 3.3
+
+Write `run-state.json` into the Phase 0 report dir with `{ targetIds, covered, skipped }` so `--resume` can pick up the remainder. An id in neither bucket is a bug in this phase, and Phase 4's gate will fail the run for it.
+
+Before leaving this phase, compare `covered.length + skipped.length` against `scope.targetIds.length`. If they differ, the difference is a set of targets nobody decided about - go back and drive them, or record why they cannot be driven. Reaching Phase 4 with a mismatch and letting the gate report it is the worst of both worlds: the work is undone AND the run is marked incomplete.
+
+## Phase 4 - Report, coverage gate & export
+
+1. **Output dir**: `state.designCheck.reportDir`, already created in Phase 0 - Phase 3's captures and comparison images are already inside it. Do not mint a second timestamped dir here.
+2. Assemble the report object:
+   ```
+   { project, module, platform, figmaUrl, figmaFileKey, timestamp,
+     lang: <prefs.global.outputLanguage>,
+     coverage: { targets: <scoped inventory targets, as the id array or the target objects>,
+                 covered: <audited id array>,
+                 skipped: [ { id, group, reason } ],
+                 truncatedInventory: <inventory.truncated>,
+                 floor: <config coverage.floor, optional> },
+     variants: [ { name, figmaNodeId, perceptualPct, passed, compareSize, liveSize,
+                   images, findings, fixPrompt, componentRefs } ] }
+   ```
+   Pass **ids**, not counts: the engine then names each unaccounted target in the report instead of printing an anonymous tally. `compareSize` and `liveSize` come straight from the `design_visual_compare` result.
+3. **Render + export**:
+   ```
+   mcp__dev-toolkit__design_report({ report, out_dir: state.designCheck.reportDir,
+     formats: ["html", "pdf"] + (confluence enabled ? ["confluence"] : []) })
+   ```
+   - HTML: self-contained (base64 images, CSS-positioned annotations over the live capture, stacked findings, fix prompt), with the coverage gate banner at the top.
+   - PDF: via Playwright if present; if unavailable the tool returns `pdfError` - report it and note the HTML can be printed manually.
+   - **Confluence**: only if `figmaConfig.confluence.enabled` (or prefs). Reuse the pipeline's Confluence adapter (`/multi-agent:channels` storage-format upload) with the report HTML as the page body + PNGs as attachments. Disabled → graceful skip with a one-line note.
+4. **COVERAGE GATE (blocking, not advisory)** - read `coverage` from the tool result and persist it to `state.designCheck.coverage`:
+   - `gate: "pass"` → report per-variant PASS/FAIL + findings count + report paths.
+   - `gate: "fail"` → the run is **INCOMPLETE**. Print `coverageError`, the `unaccountedIds`, and the exact command that closes the gap: `/multi-agent:design-check --resume`. Do not present an incomplete audit as a finished one, do not bury the miss in a footnote, and never pad the covered list to make the gate pass.
+
+   The gate is a last line of defence, not the plan. If it fires, Phase 3 left work undone - the correct response is to drive the missing targets, and only then to report.
+5. Clean up the worktree (`git worktree remove --force`) unless the user asked to keep the built app. The report dir is never removed.
+
+## Notes
+
+- **Feasibility is real**: many projects legitimately cannot be audited (no launchable app, no runtime switch). Report that honestly and stop - never substitute a fabricated or partial comparison.
+- **The inventory is the contract**: Phase 0 step 5 decides what "done" means. An audit that visits the linear happy path and lists the rest as "not visited" is the failure mode this pipeline exists to prevent; the gate makes it visible instead of polite.
+- **Chunk with scope, not with silence**: a 50-target module is a legitimate multi-run job. Scope it, finish each run's gate cleanly, and let `--resume` carry the remainder.
+- **"Pixel perfect" is perceptual + geometric**: a Figma render never matches device dimensions 1:1, so the engine normalizes scale and crops chrome. Findings are reported with explicit px / pt / hex deltas and a tolerance, not as strict pixel equality.
+- The engine (`design_*` tools) is generic and project-agnostic; all project specifics (mock switch keys, extra launch args / targets, variant→node overrides, status-bar crop, coverage floor, Confluence toggle) come from `design-check-config.json` / prefs, never hardcoded.