@mmerterden/multi-agent-pipeline 13.0.0 → 13.1.0

package/CHANGELOG.md

@@ -16,6 +16,65 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ## [Unreleased]
 
+## [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.1.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/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/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`.

package/pipeline/multi-agent-refs/phases/phase-3-dev.md

@@ -367,3 +367,35 @@ bash $HOME/.claude/scripts/phase-tracker.sh tokens 3 <input_count> <output_count
 The tracker accumulates the totals additively, so multiple calls in the same phase compound. The render output then shows live cost on the active phase tile (e.g. `Phase 3  Dev   2m 14s · 12.4k tok`). This satisfies the contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` and the `smoke-tracker-tokens-invocation.sh` enforcement gate. Skipping this call is the #1 cause of "I can't see how much it cost" complaints.
 
 If you do not have access to the model's reported token counts, pass best-effort estimates derived from input length / output length  -  partial cost data is better than none.
+
+
+#### Generated trees are not yours to edit
+
+Many repos generate part of their source: a service client from an OpenAPI spec, mock
+scenario indexes, localization keys, testing identifiers, design tokens. A generated
+file is regenerated on the next build, so an edit there is lost silently, and the
+matching hand-authored tree is the one that takes the change.
+
+Before writing into any path, check whether it is generated:
+
+```bash
+# a Generated/ segment, or a header saying so, is the signal
+find . -type d -name Generated -not -path './.*' | head
+grep -rl "DO NOT EDIT\|auto-generated\|Generated by" --include="*.swift" --include="*.kt" . | head
+```
+
+The pairing is usually `Generated/<x>` for output and `Custom<X>/` or
+`CustomSources/` for input. Two concrete shapes seen in the wild:
+
+| Want to | Wrong place | Right place |
+|---|---|---|
+| add a mock fixture / named scenario | a `Fixtures/` file under a generated tree | the repo's custom fixture tree, plus registering the scenario in the generated index the build reads |
+| add or change a service endpoint | the generated client method | the OpenAPI source the generator consumes, then regenerate |
+
+One run wrote a mock fixture into the generated fixtures tree; the fix commit 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.
+
+When the analysis doc has not recorded which trees are generated, that is a Phase 1
+gap  -  say so rather than guessing, since guessing wrong is invisible until the next
+regeneration.

package/pipeline/multi-agent-refs/phases/phase-4-review.md

@@ -272,6 +272,32 @@ Each reviewer inherits the `code-reviewer` agent's focus areas (Security, Archit
 
 Skills are injected into reviewer prompt context  -  the reviewer uses them as reference, not as commands.
 
+#### Step 2.8  -  Visual conformance gate (component / screen work only)
+
+Runs when `state.taskType == "component"` **or** the diff touches SwiftUI UI files
+AND the task carried a Figma reference. Two checks, in order:
+
+1. **`ai-ios-engineering-toolkit:figma-review`** over the implemented frames  -  the
+   plugin's own component review, including the 14-item checklist that covers design
+   tokens, accessibility identifiers, previews and Code Connect.
+2. **`/multi-agent:design-check`** for pixel + spacing + typography + colour
+   conformance against the Figma variants, with its coverage gate: a variant that is
+   neither audited nor skipped-with-a-reason fails the run.
+
+**Code Connect must be published, not merely written.** A `*.figma.swift` file on
+disk with `Code Connect: Not published` in Figma means the binding does not exist for
+anyone but the author. Assert the publish step ran; an unpublished binding is a
+blocking finding.
+
+Why this is a gate and not advice: `design-check` existed as a command for a while
+with **no phase invoking it**, so the only thing standing between a build and visual
+drift was the user opening the app and looking. On one run that produced 16pt padding
+where the frame said `Spacing/12`, and a full sheet rebuild afterwards. A reviewer
+reading a diff cannot see spacing; something has to compare against the design.
+
+Skip only when the diff has no UI change. Record the outcome in
+`consensus.visualConformance` so Phase 7 reports whether it ran.
+
 **iOS/Swift  -  interaction & convention checks (conditional).** When the diff touches SwiftUI UI files (`*View.swift`, `*Screen.swift`, `*Configuration.swift`, `*+Modifiers.swift`), the iOS reviewers additionally apply the component/interaction conventions documented in the analysis doc (Section 14 Code Connect mapping) and, where the repo has the marketplace component toolkit enabled (`ai-ios-engineering-toolkit`), that plugin's navigation / overlay / bottom-sheet conventions (interaction: emit-intent vs self-route/self-present; native-SwiftUI-first vs the project's `ui.*` custom system) plus the component accessibility rules (minimalism). These back the Step 1.5 iOS convention checks. Generic across SwiftUI projects  -  not tied to any one app. Omit when the diff has no SwiftUI UI changes (keeps the reviewer prompt lean).
 
 **Module review guides (conditional, all stacks).** A module in the repo may carry its own CLAUDE guide  -  a convention/checklist file living somewhere in the module's directory tree that the host CLI never auto-loads. When a changed file's module has such a guide, the review must consult it. Discovery is deterministic, from the diff's changed paths: for each changed file, walk its directory chain up to the repo root and collect `CLAUDE.md`, `*-CLAUDE.md`, and `AGENTS.md` files (root-level ones excluded  -  the host CLI already loads those). Dedupe, cap at 5 (log any dropped). Inject into every reviewer prompt with the directive: read each guide before reviewing and apply its rules/checklist to the changed files under its directory  -  a guide governs only its own subtree, and guide violations are findings triaged by severity like any other. No guides found → no-op, prompt stays lean. Same contract as `/multi-agent:review` Step 2b.

package/pipeline/scripts/phase0-exit-gate.mjs

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+/**
+ * phase0-exit-gate.mjs  -  Phase 0 may not be marked completed until it has
+ * actually produced its own output.
+ *
+ * Why this exists. Phase 0 Step 7 says to classify the task and "persist to
+ * `agent-state.json.taskType`", and Phase 3 branches on that field to route a
+ * Figma-driven task to the component skills (`create-screen` / `create-component`
+ * in the stack plugin) instead of generic development. On a real run the tracker
+ * showed Phase 0 `completed` while the task directory held only
+ * `tracker-state.json`  -  no `agent-state.json` at all. With no `taskType`, the
+ * dispatch could not fire, so a Figma-driven screen was built as generic work: no
+ * token-compliance check, no Code Connect publish, no 14-item component review,
+ * and spacing guessed at 16 where the frame said `Spacing/12`. Half the commits on
+ * that branch were rework.
+ *
+ * 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. So this is a
+ * gate, not a lint  -  the spec already said what to write, and prose alone did
+ * not make it happen.
+ *
+ * Usage:
+ *   node phase0-exit-gate.mjs <task_id> [--input "<original user input>"] [--json]
+ *
+ * Exit codes: 0 = pass, 1 = gate failure (Phase 0 must not be closed), 2 = usage
+ *
+ * @module pipeline/scripts/phase0-exit-gate
+ */
+
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+const FIGMA_URL = /figma\.com\/(design|make|file)\//i;
+
+/** Fields that can carry the user's original request text. */
+const INPUT_TEXT_FIELDS = [
+  ["input", "summary"],
+  ["input", "raw"],
+  ["issue", "body"],
+  ["issue", "title"],
+  ["jira", "summary"],
+  ["jira", "description"],
+  ["task", "description"],
+];
+
+/**
+ * Pull a nested value without throwing on a missing branch.
+ * @param {object} obj
+ * @param {string[]} path
+ * @returns {unknown}
+ */
+function at(obj, path) {
+  return path.reduce((acc, k) => (acc && typeof acc === "object" ? acc[k] : undefined), obj);
+}
+
+/**
+ * Collect every string in the state that could hold the original request, so a
+ * Figma reference is found wherever the input parser happened to store it.
+ *
+ * @param {object} state
+ * @returns {string}
+ */
+export function inputTextOf(state) {
+  const parts = [];
+  for (const path of INPUT_TEXT_FIELDS) {
+    const v = at(state, path);
+    if (typeof v === "string") parts.push(v);
+  }
+  // evidence[].url / figmaFrames[] are where the analysis phase parks references.
+  for (const key of ["figmaFrames", "designRefs"]) {
+    const v = state[key];
+    if (Array.isArray(v)) parts.push(v.map((x) => (typeof x === "string" ? x : JSON.stringify(x))).join(" "));
+  }
+  return parts.join("\n");
+}
+
+/**
+ * Evaluate the gate against a parsed state object.
+ *
+ * Kept pure and exported so the smoke can drive it without laying down a task
+ * directory: a gate that can only be tested by reproducing a full run does not
+ * get tested.
+ *
+ * @param {object|null} state - parsed agent-state.json, or null when absent
+ * @param {string} extraInput - input text supplied on the command line
+ * @returns {{ok: boolean, failures: string[], taskType: string|undefined, figmaSeen: boolean}}
+ */
+export function evaluate(state, extraInput = "") {
+  const failures = [];
+
+  if (state === null) {
+    return {
+      ok: false,
+      failures: [
+        "agent-state.json is missing. Phase 0 owns this file; without it taskType, " +
+          "maturity, account and repo resolution are all unreadable by later phases.",
+      ],
+      taskType: undefined,
+      figmaSeen: FIGMA_URL.test(extraInput),
+    };
+  }
+
+  const taskType = typeof state.taskType === "string" ? state.taskType.trim() : "";
+  if (!taskType) {
+    failures.push(
+      "agent-state.json has no taskType. Phase 3 branches on it: without the field " +
+        "a component task is dispatched as generic development (Step 7 of phase-0-init).",
+    );
+  }
+
+  const haystack = `${inputTextOf(state)}\n${extraInput}`;
+  const figmaSeen = FIGMA_URL.test(haystack);
+
+  if (figmaSeen && taskType && taskType !== "component") {
+    failures.push(
+      `the input carries a Figma URL but taskType is "${taskType}". Step 7 rule 1 makes ` +
+        `"component" mandatory here  -  otherwise the run skips the stack plugin's ` +
+        `token-compliance check, Code Connect publish and component review.`,
+    );
+  }
+
+  // The Figma access chain records which tier answered. A component task with no
+  // recorded tier means nothing verified that the design was actually reachable,
+  // which is how a run ends up guessing spacing.
+  if (figmaSeen) {
+    const tier = at(state, ["figmaAccess", "tier"]);
+    if (tier === undefined || tier === null || tier === "") {
+      failures.push(
+        "the input carries a Figma URL but state.figmaAccess.tier is unset. The 3-tier " +
+          "access chain must record which tier answered, so a later phase can tell " +
+          "'design confirmed' from 'design never fetched'.",
+      );
+    }
+  }
+
+  return { ok: failures.length === 0, failures, taskType: taskType || undefined, figmaSeen };
+}
+
+/** @param {string} taskId */
+function statePathFor(taskId) {
+  return join(homedir(), ".claude", "logs", "multi-agent", taskId, "agent-state.json");
+}
+
+function main(argv) {
+  const args = argv.slice(2);
+  const taskId = args.find((a) => !a.startsWith("--"));
+  if (!taskId) {
+    console.error("usage: phase0-exit-gate.mjs <task_id> [--input \"<text>\"] [--json]");
+    return 2;
+  }
+  const inputIdx = args.indexOf("--input");
+  const extraInput = inputIdx >= 0 ? (args[inputIdx + 1] ?? "") : "";
+  const asJson = args.includes("--json");
+
+  const path = statePathFor(taskId);
+  let state = null;
+  if (existsSync(path)) {
+    try {
+      state = JSON.parse(readFileSync(path, "utf-8"));
+    } catch (e) {
+      console.error(`phase0-exit-gate: ${path} is not valid JSON: ${e.message}`);
+      return 1;
+    }
+  }
+
+  const result = evaluate(state, extraInput);
+
+  if (asJson) {
+    console.log(JSON.stringify({ taskId, statePath: path, ...result }, null, 2));
+  } else if (result.ok) {
+    console.log(
+      `phase0-exit-gate: PASS (taskType=${result.taskType}${result.figmaSeen ? ", figma reference present" : ""})`,
+    );
+  } else {
+    console.error("phase0-exit-gate: FAIL  -  Phase 0 must not be marked completed");
+    for (const f of result.failures) console.error(`  - ${f}`);
+    console.error(`  state: ${path}`);
+  }
+  return result.ok ? 0 : 1;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  process.exit(main(process.argv));
+}

package/pipeline/skills/shared/core/multi-agent-dev/SKILL.md

@@ -62,3 +62,24 @@ Phase 7: Report     → Channels (Jira / Confluence / PR / Wiki)
 | Phase 5 User Test | ✅ | ✅ (same) |
 | Phase 7 channels (Jira / Confluence / PR / Wiki) | ✅ | ✅ (same) |
 | Duration | ~10-15 min | ~5-7 min |
+
+## 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/skills/shared/core/multi-agent-dev-local/SKILL.md

@@ -34,3 +34,24 @@ Routes to the orchestrator with the `--dev --local` flags. The pipeline contract
 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.