@mmerterden/multi-agent-pipeline 13.0.0 → 13.2.0

package/CHANGELOG.md

@@ -16,6 +16,117 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ## [Unreleased]
 
+## [13.2.0] - 2026-07-28
+
+The iOS coding standard reaches all three hosts, and works outside the pipeline.
+
+The 95-rule registry lived as a pipeline-local routine. Two consequences, both
+measured: only Claude Code could reach it, because `local-only` commands are
+deliberately never synced (verified absent on Copilot CLI and Codex CLI), and it
+applied only when the routine was invoked explicitly  -  nothing pulled the rules in
+while Swift was being written. The plugin's own `reference/code-style` skill is 154
+lines of prose with zero rule IDs, so the registry was not reachable that way either.
+
+### Added
+
+- **`ios-coding-standard` skill**, authored once in `pipeline/skills/shared/external`
+  and routed into the iOS stack plugin's `knowledge/` by the existing generator. That
+  one source now lands as a skill on Claude Code and Copilot CLI (description-matched,
+  so the rules are present while code is being written) and ships inside the plugin for
+  Codex. `references/` carries the registry, the teaching doc, a SwiftLint config for
+  the mechanically-enforceable subset, and a module-scoped lint runner with a baseline
+  mode.
+- **`/multi-agent:ios-coding-standard`** promoted out of `local-only` into the command
+  inventory (43 → 44), with its Copilot twin, so the module-wide audit procedure exists
+  on every host. It reads its rules from the skill rather than carrying a copy.
+
+### Changed
+
+- The registry was generalised before promotion: company hostnames, an internal URL
+  scheme, internal model and endpoint names, and repo-specific module paths were
+  replaced. `smoke-personal-data.sh` is clean across all six promoted files. Rule
+  bodies describe shapes (a mapper doing arithmetic, a logger interpolating a token)
+  rather than named modules, so the registry applies unchanged to any SwiftUI codebase;
+  a project layers its own vocabulary through a `modules/<Module>.yml` overlay.
+- Four over-long skill descriptions trimmed (`ios-simulator` 839→578,
+  `swift-api-design-guidelines` 738→468, `swiftlint` 725→473, and the three new ones).
+  The always-on description surface was at 78,079 of 78,000 bytes before this change;
+  adding a 44th command and a new skill needed 859 bytes it did not have. Each trim
+  removed duplication between a description's "covers" enumeration and its trigger
+  clause, which is where the routing value actually is. Surface is now 77,734.
+
+### Notes
+
+- **Codex lists plugin skills by name only.** Measured: all 76 plugin-provided skills
+  render with an empty description in Codex's skills block, while the 5 system skills
+  render theirs. So on Codex a plugin skill is invoked explicitly rather than matched
+  on description. That is the reason the registry is authored in `shared/external`
+  instead of hand-placed in the plugin: the pipeline install path gives Claude Code and
+  Copilot CLI a description-matched skill, and the plugin copy covers Codex.
+- The iOS plugin now declares 143 skills and Codex surfaces about half. That overflow
+  predates this change and `tools/validate.py` warns on it; routing `knowledge/` behind
+  the plugin's `index` skill is the fix and is separate work.
+
+
+## [13.1.0] - 2026-07-27
+
+Six gates, from one branch that spent half its commits on rework.
+
+A Figma-driven screen task was built through the generic development path. The cause
+chain, measured from the run's own artefacts: Phase 0 reported `completed` having
+written only `tracker-state.json`, so `agent-state.json` and its `taskType` never
+existed, so Phase 3's component dispatch could not fire. The stack plugin already
+ships `create-screen`, `figma-validate` (7 criteria including design-token compliance
+and Code Connect strategy) and `figma-review` (14-item checklist)  -  none of them ran.
+Padding came out 16 where the frame said `Spacing/12`. Three of six commits were fixes,
+the last a full sheet rebuild.
+
+Nothing here is a new capability. Every gate enforces a rule that already existed or
+invokes a skill that was already written but never called.
+
+### Added
+
+- **`phase0-exit-gate.mjs`, blocking.** Phase 0 may not be marked completed until
+  `agent-state.json` exists with a `taskType`, and a Figma reference forces
+  `taskType: "component"` plus a recorded `figmaAccess.tier`. A phase that reports
+  success without its output is worse than one that fails: every later phase then
+  reasons from a field that is not there. The evaluator is pure and exported, so the
+  gate is testable without reproducing a run.
+- **Phase 4 Step 2.8, visual conformance gate.** Runs `figma-review` and
+  `/multi-agent:design-check` for component/screen work, with the coverage gate, and
+  asserts Code Connect was **published** rather than merely written  -  a
+  `*.figma.swift` on disk with "Not published" in Figma is a binding that exists for
+  nobody. `design-check` had been a command with no phase invoking it, so the only
+  thing standing between a build and visual drift was the user opening the app.
+- **Phase 1 Step 1.45, reuse discovery, blocking.** Search for an existing wrapper,
+  entity, mapper or screen before proposing a new one. One run wrote a repository over
+  an endpoint a sibling domain already wrapped **with its country parameter**, called
+  the generated method without it, and re-invented an entity the module already had.
+  "Copy X and rename it" is the reuse answer, not a hint.
+- **`smoke-component-dispatch-gates.sh`** (12 assertions) pins all six.
+
+### Changed
+
+- **Component dispatch halts instead of degrading.** The contract used to send an
+  incomplete-state component task down the generic TDD path while the next sentence
+  said "never silently skip the Figma work"  -  taking the generic path *is* skipping
+  it. That wording authorised the exact failure above.
+- **Dispatch routes on scope, not just platform.** A screen and a component are
+  different jobs and the plugin ships a skill for each; routing a screen to the
+  component skill is why one run produced entities and a mapper but left the screen
+  half-wired. `figma-validate` now runs before the create skill.
+- **Phase 1 captures spacing by token name, per atom.** Phase 3 is forbidden from
+  calling Figma, so a pixel number  -  or a missing entry  -  is unrecoverable later. A
+  UI frame with no spacing entries is a capture failure, not an empty frame.
+- **Phase 3 records that generated trees are not editable.** A mock fixture went into
+  the generated tree; the fix moved it to the custom tree and registered the scenario
+  in the generated index. Same content, wrong side of the generator, and the Debug menu
+  never showed it.
+- **Fast modes warn when handed an analysis document.** `--dev` skips Analysis and
+  Planning by design, so there is no phase that turns a document into a plan. The doc
+  becomes context for one pass and work lands in whatever order it was read.
+
+
 ## [13.0.0] - 2026-07-27
 
 > **Why major and not minor.** The additions here are additive, but two defaults

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "13.0.0",
+  "version": "13.2.0",
   "description": "8-phase AI development pipeline with full orchestration on Claude Code, Copilot CLI and Codex 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",

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

@@ -270,3 +270,24 @@ bash $HOME/.claude/scripts/phase-tracker.sh render
 ```
 
 Do NOT call TaskCreate on these CLIs  -  the tool does not exist and the call fails.
+
+## Analysis doc supplied to a fast mode (warn before starting)
+
+The `--dev` family skips Phase 1 (Analysis) and Phase 2 (Planning) by design. So when
+the input references an analysis document  -  a Confluence URL, a local analysis file,
+or the user says "I ran analysis for this"  -  there is **no phase that turns it into a
+plan**. The doc becomes raw context for one Dev pass, and work comes out ordered by
+whatever the model read first: the bottom of the dependency chain lands, the screen
+wiring does not.
+
+Say so before starting, once, and offer the choice:
+
+```
+This mode skips Analysis and Planning, so the analysis document will not be turned
+into a task breakdown. For analysis-driven screen work, /multi-agent or
+/multi-agent:local run both phases.
+  1. Continue with --dev (doc as context only)
+  2. Switch to the full pipeline
+```
+
+Autopilot picks 1 and logs the warning rather than asking.

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

@@ -109,3 +109,24 @@ Routes to the orchestrator with `--dev --local` flags. Apply the `$HOME/.claude/
 /multi-agent:dev-local "PROJ-12345"                            # Jira
 /multi-agent:dev-local "Bug: LoginView dark mode"              # Free-text
 ```
+
+## Analysis doc supplied to a fast mode (warn before starting)
+
+The `--dev` family skips Phase 1 (Analysis) and Phase 2 (Planning) by design. So when
+the input references an analysis document  -  a Confluence URL, a local analysis file,
+or the user says "I ran analysis for this"  -  there is **no phase that turns it into a
+plan**. The doc becomes raw context for one Dev pass, and work comes out ordered by
+whatever the model read first: the bottom of the dependency chain lands, the screen
+wiring does not.
+
+Say so before starting, once, and offer the choice:
+
+```
+This mode skips Analysis and Planning, so the analysis document will not be turned
+into a task breakdown. For analysis-driven screen work, /multi-agent or
+/multi-agent:local run both phases.
+  1. Continue with --dev (doc as context only)
+  2. Switch to the full pipeline
+```
+
+Autopilot picks 1 and logs the warning rather than asking.

package/pipeline/commands/multi-agent/ios-coding-standard/SKILL.md

@@ -0,0 +1,257 @@
+---
+description: "Audit an iOS module against the shared coding-standard registry (95 stable-ID rules), produce a remediation plan, then hand off to dev/dev-local. Use for a standards pass on a module, or when a review needs rule IDs rather than opinions."
+description-tr: "Bir iOS modulunu paylasilan kodlama-standardi registry'sine (95 sabit-ID kural) gore denetler, duzeltme plani cikarir, sonra dev/dev-local'e devreder. Bir modulde standart gecisi icin, ya da bir review'un gorus yerine kural ID'si istedigi durumda kullan."
+argument-hint: "[module name or path]"
+allowed-tools: Skill, Bash, Read, Edit, Write, AskUserQuestion
+---
+
+# multi-agent ios-coding-standard — Module audit → plan → dev handoff
+
+**Input**: $ARGUMENTS — optionally a module name or path. When absent, Phase 1 discovers and asks.
+
+This routine is the **procedure**. The rules live in the `ios-coding-standard` skill, whose registry is
+`references/rules.yml` and whose teaching doc is `references/STANDARD.md`. Load that
+skill first; it is installed on every host and carried by the iOS stack plugin, so
+there is one registry rather than a copy per CLI. Never restate a rule here — cite its ID. A rule that is not in the
+registry is not a rule; if the audit needs one, propose it as `status: proposed` and say so.
+
+Read-only + planning. This routine never edits source — the dev pipeline does.
+
+**Goal.** A developer new to the repo can open any file in the module and understand it without a
+guided tour, and nothing sensitive leaks on the way. Rank every finding by "does fixing this
+shorten the time to first productive PR, or close a real risk?"
+
+Render assistant-facing prose in `outputLanguage`. External payloads (branch names, plan file,
+dev task) stay English.
+
+---
+
+## Phase 1 — Discover and pick the module
+
+1. Repo root via `git rev-parse --show-toplevel`.
+2. **Discover module roots** — any directory with a `Package.swift`, a `Sources/` subtree or an
+   `.xcodeproj`. Sweep the container dirs that exist (`Domains/`, `Packages/`, `Modules/`,
+   `Features/`, `Core/`, `Common/`, top-level module dirs) one level deep, then two if empty.
+3. Record per module: name · path · Swift files · lines · governance docs present · SPM targets.
+   Keep this **module registry** for the whole run — `MOD-*` greps every import against it.
+   Classify each module's role, because the role decides which dependency edges are legal:
+   **feature** · **core/common** · **seam** (cross-module contracts/bridges/navigation) ·
+   **composition root** (legitimately knows every module).
+4. If `$ARGUMENTS` resolves to a module, skip the prompt. Otherwise `AskUserQuestion`
+   (single-select, `outputLanguage`), documented modules first, each option showing file/line
+   counts and `docs: yes/no`. If the list exceeds the question limit, group the smallest into an
+   "other" option and ask again — never truncate silently.
+5. Scope = the whole module's sources across all its targets, unless the user narrows it.
+
+## Phase 2 — Resolve what applies to THIS module
+
+### 2a. The registry is the standard — in-module prose docs are NOT consulted
+
+The skill's `references/rules.yml` (+ a project `modules/<Module>.yml` overlay) is the single source of truth. **Do not read, cite, or
+derive rules from a module's own `*-CLAUDE.md`, `docs/` set or any other in-repo prose.** They are
+being retired precisely so there is one place a rule can live; consulting them re-creates the
+split this command exists to remove. If such a file exists and contradicts the registry, that is a
+finding against the file, not against the code.
+
+The only in-repo inputs are **code and manifests**: sources, tests, `Package.swift`, `Info.plist`,
+the specs the generator reads, and the module registry from Phase 1.
+
+### 2b. Per-module overlay, then inference
+
+1. **`modules/<Module>.yml`** beside the project's own config carries what code cannot state: the vocabulary
+   bindings, the module's role, prohibitions that currently have **zero** instances, deliberate
+   carve-outs, name locks, and the real verification command. Registry-backed, so its findings may
+   be `blocking`.
+   *Why prohibitions need to be written down:* inference reads dominant patterns, and a rule
+   obeyed everywhere has no counter-example to infer from. A ban at 100% compliance is invisible
+   to a scan — it survives only if the overlay states it.
+2. **Repo-level rules** (root `CLAUDE.md`, contributing docs) apply to every module.
+3. **The module's own dominant pattern is its de-facto convention.** Count variants per dimension;
+   the minority instances are the finding. Internal consistency beats conformity to a sibling.
+4. No majority (even split, single instance) → not a finding. Record an Open Question.
+
+Findings from step 3 are tagged `inferred` and capped at **suggestion**. Only registry- or
+overlay-backed rules may be `blocking`.
+
+**When the overlay is missing**, generate a draft from code evidence, print it for confirmation,
+and mark every slot it could not derive — a frozen UI target, a name lock, a carve-out and an
+operational constraint all look like ordinary code from the outside. Do not guess them; list them
+as Open Questions.
+
+### 2c. Vocabulary
+
+Bind each slot to a real symbol by grepping the module, then the reference module. **An unbound
+slot disables its rules** — never invent a name, never import a sibling's.
+
+`HandlerName` · `EventParam` · `CoordinatorType` · `ResultType` / `ErrorType` / `ErrorFactory` ·
+`DIResolver` / `DIConfigurator` · `RequestModelSuffix` / `ResponseModelSuffix` / `TransportSuffix` ·
+`MapperShape` · `SafeEnumProtocol` / `UnknownCase` · `CopySurface` · `AnalyticsSurface` ·
+`A11yIdentifierSource` · `GeneratedServiceRoot` · `SharedComponentsDir` / `SharedEntitiesDir` ·
+`MicroComponentLibrary` · `FrozenUITarget` · `DesignTokenNamespaces` · `CalendarDayHelper` ·
+`LoggerAPI` · `FileHeaderShape` · `ScreenRoot` · `ScreenRoleSuffixes` · `AsyncStyle` ·
+`CompositionRoot` · `SeamLayer` · `ModuleEntrySurface` · `ConcurrencyPosture` · `LintToolchain` ·
+`CredentialStore` (the module's Keychain wrapper, if any).
+
+Print the resolved table before scanning so a wrong binding is caught early.
+
+### 2d. Sensitive-data inventory — required before any SEC rule runs
+
+The `SEC-*` rules are written against the **data classes** in `references/rules.yml →
+sensitive_data_classes`, never against one module's field names. Resolve the module's concrete
+instances of each class: grep entities, request/response models, storage calls and analytics
+events for the values the module actually handles, and map each to its class.
+
+Produce the inventory as a table — **class · concrete symbols · where it enters · required
+lifetime (transient / survives-restart / survives-reinstall) · where it is actually stored ·
+where it is logged · where it leaves (network, analytics, pasteboard, another module)**.
+
+The **lifetime column is the one that decides SEC-01**, and it is filled by walking
+`references/rules.yml → persistence_decision`, not by looking at what the code currently does. Compare it
+against the storage column and report both mismatches:
+- required transient but persisted anywhere (including the Keychain) → **over-persistence**;
+- required to survive a restart but stored outside the Keychain → **under-protection**.
+
+Then generate the SEC lint patterns *from this inventory*, so the checks match this module's real
+vocabulary. A class with no instance here yields no finding; a symbol you cannot classify, or one
+whose required lifetime nobody can state, is an Open Question, not a silent pass.
+
+This table is a deliverable in its own right, independent of whether any violation is found.
+
+## Phase 3 — Scan
+
+Apply the rules in `references/rules.yml` that survived Phase 2 binding, plus the module's own `validation`
+gate. Tag every finding: **rule ID · severity · source (`registry` / `doc` / `inferred`) ·
+onboarding impact (high/medium/low)**.
+
+### Coverage gate — on disk, not in memory
+
+Before scanning, write `.<module>-audit-coverage.tsv` to the scratch dir: one row per target
+(every screen under `ScreenRoot`, every shared component, every entity, every file in every
+target) with columns `path · status · rules-applied`. Mark rows as you go.
+
+- Each target is **audited** or **explicitly skipped with a reason** (generated, fixture,
+  vendored). No third state.
+- **The run is incomplete while any row is unmarked** — and the file, not a claim, is the proof.
+  Chunk the module if it is too large for one pass; the checklist survives a context reset.
+- No sampling. A partial audit reported as complete certifies the unscanned screens as clean.
+
+### Grep hygiene
+
+Registry `mechanism` patterns are line-based and match doc comments. Filter
+`^[[:space:]]*//` — BSD grep does not understand `\s`, so a `\s*//` filter silently lets `/// …`
+through — then open each surviving hit and confirm it is real code. Report pre-filter and
+post-verification counts separately; a table padded with comment matches destroys trust.
+
+### Judgement rules need evidence, not assertion
+
+For any rule marked `enforcement: judgement`, a finding must carry the measurement its `check`
+names — a reference count, a call-site count, a consumer count, a file list. **No count, no
+finding.** This is what keeps a subjective rule from becoming an opinion.
+
+Every judgement rule has a worked ✗/✓ pair in `EXAMPLES.md`, keyed by ID. Cite it in the finding's
+proposed fix rather than re-describing the shape — the developer applying the fix should be
+reading the same picture the audit used.
+
+### Module-specific overrides
+
+The module's own docs win over the registry, including where they contradict a sibling module.
+Never apply one module's dialect to another. List every override honoured, so the reader sees why
+a registry rule was not raised.
+
+## Phase 4 — Produce the plan
+
+No findings → report compliant and stop. Otherwise write
+`<ModulePath>/ios-coding-standard-plan-<module>.md` (or the repo's scratch/docs dir if the module
+tree must stay clean), containing, in order:
+
+1. **Coverage ledger** — total targets · audited · skipped with reasons. Not 100% accounted for
+   means the plan is not deliverable.
+2. **Summary** — counts by severity and source, resolved vocabulary, branch to create.
+3. **Sensitive-data inventory** (Phase 2d) — first, because it is the highest-risk content.
+4. **Screen × role matrix** `[STRUCT-02]` — screens as rows, manifest roles as columns, cells
+   `✓ / missing / misplaced`. The structural map a newcomer reads first.
+5. **Type placement table** `[STRUCT-05]` — type · location · consumer count · correct tier ·
+   move required. Paired with the nested-type list `[STRUCT-01]`: owner · nested type · kind ·
+   reference count · verdict.
+6. **Visibility report** `[VIS-01, VIS-02]` — over-exposed declarations per file, non-final
+   classes with no subclass.
+7. **Boundary report** `[MOD-*]` — import graph (allowed vs forbidden, with coupling depth) ·
+   manifest graph (declared vs legal for the role, plus dead edges) · **removability delta**
+   ("removing X touches N files: …") · inbound test (tests compile with no sibling present).
+8. **Testability seam report** `[TEST-*]` — types reaching for the environment, logic requiring a
+   view to execute, doubles whose signatures have drifted.
+9. **Change-cost probe** `[FLEX-*]` — pick two plausible upcoming changes (a new variant of an
+   existing screen; a new field on a shared entity) and state what each costs in files today.
+10. **Findings table** — rule ID · `file:line` · current state · proposed fix · severity · source ·
+    onboarding impact.
+11. **Per-file work** — grouped per file, blocking → important → suggestion; within a severity,
+    highest onboarding impact first.
+12. **Behaviour-preservation guard** — splitting files, adding MARKs, extracting extensions and
+    moving types must not change behaviour. Anything requiring a behaviour change (a missing
+    analytics event, a wrong result type, a timezone fix, a storage migration) goes in a
+    **separate group**, reviewed and tested on its own, never inside a mechanical split commit.
+13. **Tooling delegation & the ratchet** — the section that decides whether any of this survives.
+    - Classify each applied rule by its registry `enforcement`. For every `lint` / `format` /
+      `scan` rule, state the concrete mechanism and whether that toolchain exists in the repo
+      (`LintToolchain`). **When it does not exist, saying so is a finding**, ranked above most
+      individual violations it would have caught.
+    - Recommend **baseline-and-ratchet, never big-bang**: grandfather existing violations, surface
+      only new ones, drain the backlog behind a green build. Order the plan the same way — stop
+      the bleeding, then clean up.
+    - Custom lint rule identifiers **are** the registry IDs (`sec_01_no_plaintext_persistence`,
+      `mod_01_no_sibling_import`) so a violation points straight at the rule entry.
+    - **Linting is local-only by decision** — the skill's `references/lint-local.sh` with `references/swiftlint.draft.yml`, config
+      and baseline kept outside the repository; no committed config, no build phase, no CI job.
+      State this honestly in the plan rather than describing a gate that does not exist: a
+      pre-PR habit catches less than a wall, so the residual risk is real and belongs in the
+      report. Adopting it project-wide remains an open decision — record it as one so it stays
+      visible instead of quietly lapsing.
+    - Never imply the audit substitutes for the linter, or the linter for a gate. The audit finds
+      the debt once; the linter keeps a developer honest; only a gate stops it returning.
+14. **Numeric exit criteria** — target and today's measured value side by side: lint violations
+    per 1k lines (<1) · public-surface ratio, public declarations ÷ externally consumed symbols
+    (≈1) · forbidden cross-module imports (0) · removability delta · files over threshold and
+    files >120 lines with no sectioning (0) · screens missing a manifest role (0) · escape-hatch
+    count `[CONC-03]` (flat or falling) · exception-marker count (flat or falling) · dead code (0)
+    · screens with logic and no mirrored tests (0) · unclassified sensitive symbols (0).
+15. **Exception ledger** — every `// standard:exception(<ID>)` in the module: rule · reason ·
+    expiry · expired yes/no.
+16. **Open Questions** — Phase 2b dimensions with no majority, and unclassifiable symbols.
+17. **Suggested commit slicing** — one commit per file-group / concern.
+18. **Scope guard** — only this module is touched; definition of done is the module's own
+    verification path.
+
+Then write a **separate one-page onboarding summary** beside the plan, aimed at a developer
+joining next week rather than at whoever does the remediation: the ten always/never lines
+specialised to this module, the screen file manifest, the placement ladder, the sensitive-data
+classes in play, and the verification command. Nobody learns a codebase from a 40-finding audit —
+this page is the actual deliverable, and the audit is how you earn the right to write it
+accurately. Derive it from `references/STANDARD.md § 0`, do not re-invent it.
+
+Show a concise version of the plan to the user too.
+
+## Phase 5 — Hand off
+
+`AskUserQuestion` (single-select, `outputLanguage`):
+
+| Option | What it does |
+|---|---|
+| `/multi-agent:dev-local` | No worktree; branches from the main development branch, fixes on the current checkout |
+| `/multi-agent:dev` | Opens a worktree; Opus fixes on a fresh branch + PR |
+
+Invoke the chosen command with the plan file as the task input, branching off the repo's main
+development branch (e.g. `chore/<module>-coding-standard`). The dev pipeline applies the fixes,
+verifies, and commits only when asked. This routine ends at the handoff.
+
+## Notes
+
+- **Verification reality is per-module — establish it, do not assume it.** Some targets cannot be
+  compiled from the CLI (asset symbol generation, UIKit-dependent packages, a dependency failing
+  earlier in the graph); there, verification is Xcode and a manifest dump validates the manifest
+  only. Never trust a piped build's exit code — a pipe reports the tail's status. Record the
+  module's actual verification command in the plan.
+- One module per run. Several modules means several runs and several plans, never one
+  cross-module churn commit.
+- If the audit wants a rule the registry lacks, add it to the skill's `references/rules.yml` as `status: proposed` with a
+  rationale and surface it in Open Questions. Do not enforce an unregistered rule.
+- No AI attribution anywhere (code, commits, PRs). Author = git identity.

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

@@ -59,8 +59,8 @@ Run every step automatically:
 ```
 Step 1: PLATFORM    Detect macOS / Linux / Windows (Git Bash / WSL); export PLATFORM env
 Step 1.5: DETECT    Compare timestamps, find stale targets
-Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 43 sub-command skills)
-Step 2b: CODEX      Claude Code -> Codex CLI (1 router skill + 43 specs as refs + 8 agent TOML)
+Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 44 sub-command skills)
+Step 2b: CODEX      Claude Code -> Codex CLI (1 router skill + 44 specs as refs + 8 agent TOML)
 Step 3: REPO        Claude Code -> pipeline repo (genericized, personal data scrub, bash -n on all sh)
 Step 3c: PLUGINS    pipeline shared/external -> multi-agent-plugins marketplace (rebuild knowledge/,
                      bump changed plugins' patch version, commit + push the plugins repo)
@@ -486,12 +486,12 @@ same 43 specs as reference files rather than as peer skills, via Step 2b -  see
 |-------------|-------------|
 | `~/.claude/commands/multi-agent/{cmd}/SKILL.md` | `~/.copilot/skills/multi-agent-{cmd}/SKILL.md` |
 
-**43 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
+**44 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
 
 ```
 analysis, analysis-resolve, autopilot, build-optimize, channels, create-jira, design-check, dev,
 dev-autopilot, dev-local, dev-local-autopilot, diff-explain, finish, forget, garbage-collect,
-help, issue, jira, kill, language, local,
+help, ios-coding-standard, issue, jira, kill, language, local,
 local-autopilot, log, manual-test, prune-logs, purge, refactor, resume, review, review-issue, review-jira,
 routines, save, scan, search, setup, stack, status, sync, test, testflight-validation, uninstall, update
 ```

package/pipeline/multi-agent-refs/component-dispatch.md

@@ -11,20 +11,53 @@ Phase 3 checks, in order:
 1. `agent-state.json` has `taskType: "component"` (set by Phase 0 Step 7).
 2. `agent-state.json` has a non-null `figmaUrl`.
 
-Either missing → log the anomaly to `agent-log.md` ("component dispatch expected but state incomplete"), fall through to the standard TDD path. Never silently skip the Figma work.
+Either missing → **HALT.** Log the anomaly to `agent-log.md` ("component dispatch
+expected but state incomplete: <which field>") and stop with a user-visible error
+naming the missing field and pointing at `phase0-exit-gate.mjs`.
+
+> Earlier wording sent an incomplete-state component task down the generic TDD path,
+> which contradicted the sentence that followed it: taking the generic path **is**
+> skipping the Figma work.
+> It also authorised the exact degradation that broke a real run  -  Phase 0 never
+> wrote `agent-state.json`, so `taskType` was absent, so a Figma-driven screen was
+> built through the generic path with no token-compliance check, no Code Connect
+> publish and no component review. Spacing came out `16` where the frame said
+> `Spacing/12`, and half the branch's commits were rework.
+>
+> The Phase 0 exit gate now prevents reaching Phase 3 in that state at all; this
+> halt is the second line of defence. A component task that cannot be dispatched as
+> one must fail loudly, because the generic path produces artefacts that look
+> finished and are not.
 
 ## Plugin skill resolution
 
+Scope first, then platform. A screen and a single component are different jobs and
+the plugin ships a skill for each; routing a screen to the component skill is why one
+run produced entities and a mapper but left the screen half-wired.
+
+| `state.componentScope` | Meaning | iOS skill | Android skill |
+|---|---|---|---|
+| `screen` (default when the frame is a full screen, or the task names a screen) | Full clean-architecture vertical: Entity → Repository → Mapper → UseCase → LocalizedText → AnalyticsTracking → CoordinatorEvent → ViewModel → Scene → Preview, then verify | `ai-ios-engineering-toolkit:create-screen` | `ai-android-engineering-toolkit:create-screen` |
+| `component` | One reusable UI component (Configuration / View / +Modifiers / Code Connect) | `ai-ios-engineering-toolkit:create-component` (fallback `create-ui-component`) | `ai-android-engineering-toolkit:create-component` (fallback `create-ui-component`) |
+| `evolve` | Change an existing component | `evolve-component` (fallback `evolve-ui-component`) | same |
+
 ```
-project.platform  → component skill (enabled marketplace plugin, Claude Code)
-──────────────────────────────────────────────────────────────────────────────
-ios               → Skill: ai-ios-engineering-toolkit:create-component
-                            (fallback: ai-ios-engineering-toolkit:create-ui-component)
-android           → Skill: ai-android-engineering-toolkit:create-component
-                            (fallback: ai-android-engineering-toolkit:create-ui-component)
 web, multi-*      → HALT with clear error (no web target)
 ```
 
+Phase 0 Step 7 sets `state.componentScope` alongside `taskType`: a Figma frame that
+is a full screen, or a task whose title names a screen, is `screen`; a frame that is
+a single atom is `component`. When it cannot be decided, ask  -  do not default to
+`component`, because the screen path is a superset and the component path silently
+omits the wiring.
+
+**Pre-implementation validation is not optional on iOS.** Before the create skill
+runs, dispatch `ai-ios-engineering-toolkit:figma-validate` for the frame. It checks
+registry presence, Code Connect strategy, **design token compliance**, dependency
+readiness, atomic scope and already-implemented status in about ten seconds. Those
+are precisely the checks whose absence produced guessed spacing and an unpublished
+Code Connect binding. A `figma-validate` failure halts the dispatch.
+
 **Dual-name resolution.** The public (`multi-agent-plugins`) and a corporate/private marketplace named the same skill differently  -  `create-component` vs `create-ui-component`. Dispatch tries `create-component` first; if it is not available in the current repo, tries `create-ui-component`. (Same dual-name rule applies when `taskType` maps to evolve → `evolve-component`/`evolve-ui-component`, or fix → `fix-bug`.)
 
 If **neither** resolves, the platform's `ai-<platform>-engineering-toolkit` plugin is not enabled in this repo. **Halt with a user-visible error**: "component task requires the ai-<platform>-engineering-toolkit plugin enabled in this repo (`.claude/settings.local.json`)." Do not silently fall back to TDD  -  a component task ran through the bugfix path would produce wrong artefacts.

package/pipeline/multi-agent-refs/cross-cli-contract.md

@@ -6,12 +6,12 @@
 
 ---
 
-## 1. Command Inventory (43 commands)
+## 1. Command Inventory (44 commands)
 
 ```
 analysis, analysis-resolve, autopilot, build-optimize, channels, create-jira, design-check, dev,
 dev-autopilot, dev-local, dev-local-autopilot, diff-explain, finish, forget, garbage-collect,
-help, issue, jira, kill, language, local,
+help, ios-coding-standard, issue, jira, kill, language, local,
 local-autopilot, log, manual-test, prune-logs, purge, refactor, resume, review, review-issue, review-jira,
 routines, save, scan, search, setup, stack, status, sync, test, testflight-validation, uninstall, update
 ```
@@ -24,7 +24,7 @@ Categories:
 - **Fast modes** (Init -> Dev(Opus) -> Commit -> Report): `dev`, `dev-autopilot`, `dev-local`, `dev-local-autopilot`
 - **Tail modes** (run the pipeline tail over already-done local work): `finish`
 - **Ops commands** (one-shot, no worktree): `status`, `log`, `kill`, `purge`, `uninstall`, `resume`, `review`, `review-jira`, `review-issue`, `analysis`, `analysis-resolve`, `build-optimize`, `channels`, `scan`, `search`, `diff-explain`, `garbage-collect`, `prune-logs`
-- **Local audits** (worktree only to build; no commit, push, PR or channels): `design-check`, `testflight-validation`. `testflight-validation` additionally never invokes `altool --upload-app`  -  a validation run must not be able to ship a build by accident.
+- **Local audits** (worktree only to build; no commit, push, PR or channels): `design-check`, `testflight-validation`, `ios-coding-standard`. `testflight-validation` additionally never invokes `altool --upload-app`  -  a validation run must not be able to ship a build by accident.
 - **Meta-ops**: `setup`, `sync`, `update`, `help`, `refactor`, `test`, `stack`, `manual-test`, `language`
 - **Routines** (user-defined routine registry; the routines they create are local-only and never synced): `save`, `routines`, `forget`
 

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

@@ -531,3 +531,32 @@ Phase 7 cost rollup carries this as a `phase 0` line item so the user sees ambig
 **Progress (per `$HOME/.claude/multi-agent-refs/progress-contract.md`):** emit one `→ <verb> <object>` line for each of: `→ parsing input`, `→ checking token <service>`, `→ scanning project <root>`, `→ creating worktree <repo>`, `→ binding identity <name>`, `→ writing state`. When `clarifyAmbiguous.enabled`, also emit `→ scoring task ambiguity` before Step 8 and `→ asking clarifying questions <N>` when `stopAndAsk` fires.
 
 **Save preferences**: Write updated prefs to `$HOME/.claude/multi-agent-preferences.json` with all Phase 0 selections.
+
+---
+
+#### Phase 0 exit gate (BLOCKING  -  run before marking the phase completed)
+
+Phase 0 owns `agent-state.json`. Do not call
+`phase-tracker.sh update 0 completed` until this gate passes:
+
+```bash
+node "$HOME/.claude/scripts/phase0-exit-gate.mjs" "$TASK_ID" --input "$ORIGINAL_INPUT"
+```
+
+It asserts three things, each of which has failed silently in a real run:
+
+1. **`agent-state.json` exists.** A run once reported Phase 0 `completed` with only
+   `tracker-state.json` on disk. Every later phase then reasons from fields that are
+   not there.
+2. **`taskType` is set.** Phase 3 branches on it (Step 7). Absent, a Figma-driven
+   screen is dispatched as generic development, skipping the stack plugin's
+   token-compliance check, Code Connect publish and component review. That run
+   guessed `16` where the frame said `Spacing/12`, and half its commits were rework.
+3. **A Figma reference forces `taskType: "component"`, and `figmaAccess.tier` is
+   recorded.** Without the tier, a later phase cannot tell "the design was confirmed"
+   from "the design was never fetched"  -  which is exactly when spacing gets guessed.
+
+A failure is a halt, not a warning. Fix the state and re-run the gate; the phase
+stays `in_progress` until it passes. **Never** mark Phase 0 completed on the grounds
+that its steps ran  -  the gate checks the output, and the output is what Phase 3
+consumes.

package/pipeline/multi-agent-refs/phases/phase-1-analysis.md

@@ -63,7 +63,14 @@ When `state.contextLinks[]` or the task description contains a Figma reference,
 | 2 (REST) | `GET /v1/files/{fileKey}/nodes?ids={nodeId}` + `GET /v1/images/{fileKey}?ids={nodeId}&format=png&scale=2`, PAT via `~/.claude/lib/credential-store.sh get <logical-key>` (logical key = `prefs.global.keychainMapping.figma_pat`); canonical component resolved from repo `*.figma.swift` / `*.figma.kt` mapping keyed by `fileKey` + `nodeId` | same shape, but `codeConnectSnippets[]` is empty when repo mapping is absent (record an Open Question), `tier: 2` |
 | 3 (screenshot) | User-attached screenshot stored alongside task evidence | degraded record: `codeConnectSnippets: []`, forced Open Question, `tier: 3` |
 
-Persist results under `state.evidence.figma[]`. Halt the run if all three tiers fail; never substitute primitives or invent layout from prose. Canonical chain reference: `pipeline/rules/figma-pipeline.md` "MUST: Figma access - 3-tier fallback chain".
+Persist results under `state.evidence.figma[]`. Halt the run if all three tiers fail; never substitute primitives or invent layout from prose.
+
+**Spacing goes in by token NAME, per atom  -  never a pixel number.** `tokens[]` must
+carry each frame's spacing/padding as Figma names them (`Spacing/12`, edge `4`), keyed
+to the atom. Phase 3 cannot call Figma, so what is missed here is gone: one run guessed
+`16` where the frame said `Spacing/12` and the sheet was rebuilt. A pixel number also
+cannot map back to a token. No spacing entries on a UI frame is a **capture failure**,
+not an empty frame  -  Open Question and halt. Canonical chain reference: `pipeline/rules/figma-pipeline.md` "MUST: Figma access - 3-tier fallback chain".
 
 **Telemetry (required for the no-MCP gate):** Tier 1 uses `mcp__claude_ai_Figma__*` tools. Every such MCP invocation MUST append an entry to `state.telemetry.mcpCalls[]` as `{ "tool": "<full mcp tool name>", "phase": 1, "timestamp": "<ISO-8601>" }`. This is the only phase permitted to record `phase: 1` (or `0`) entries; `smoke-no-mcp-in-dev-phases.sh` fails the run if any entry carries `phase >= 2`. Recording is what makes that BLOCKING contract enforceable  -  an MCP call left unrecorded defeats the gate, so record every one.
 
@@ -73,6 +80,22 @@ Progress lines:
 → figma evidence: <N> frames captured (tier=<n>, code-connect=<M>, open-questions=<K>)
 ```
 
+#### Step 1.45  -  Reuse discovery (BLOCKING for new services, entities, mappers)
+
+Before proposing any new service call, entity or mapper, search for what already
+covers it. Record hits under `state.reuse[]` and cite them in the doc; proposing new
+code over a hit needs a one-line reason.
+
+Search for: a **wrapper** over the same endpoint (especially one supplying parameters
+the generated call leaves optional); an **entity** for the same concept (module's
+shared entities first, then siblings); a **mapper** over the same response; a **screen**
+doing the same interaction.
+
+Why blocking: one run proposed a new repository over an endpoint a sibling already
+wrapped **with its country parameter**, called the generated method without it, and
+re-invented an entity the module had. Half that branch's commits went to converging
+back. "Copy X and rename it" is the reuse answer, not a hint  -  name X's files.
+
 #### Step 1.5  -  External Context Injection (`state.contextLinks[]`)
 
 Phase 0 Step 1b catalogued every typed external link from the task description into `state.contextLinks[]`. Phase 1 dispatches each entry to its matching fetcher (crashlytics, fortify, graylog, swagger, confluence, figma, generic-doc) and prepends results under a **Referenced External Sources** section in the analysis prompt  -  so the agent doesn't re-discover what the ticket already pointed at. `state.graylogContext` is injected there too, as diagnostic context (advisory only). Failures never fatal (a non-zero fetcher exit is marked skipped and the analysis still runs, exactly as for crashlytics); pending refs are advisories. Full dispatch table, exit-code handling, prompt injection shape, log line shape: `$HOME/.claude/multi-agent-refs/features/external-context-injection.md`.