@mmerterden/multi-agent-pipeline 18.0.0 → 19.0.0

package/pipeline/lib/phase-schema.mjs

@@ -0,0 +1,88 @@
+/**
+ * @file phase-schema.mjs  -  read a phase number that may have been written
+ * under either phase vocabulary.
+ *
+ * metrics.jsonl is append-only and v19.0.0 renumbered the phases, so the same
+ * field means two different things depending on when the line was written:
+ * `phase: 3` is Dev in a pre-v19 row and Review in a post-v19 one. Rows from
+ * v19.0.0 on carry `phaseSchema: 2`; rows without the field are generation 1.
+ *
+ * Every aggregator that compares a phase number to a literal, or prints a
+ * phase name, goes through here. Comparing directly is the bug this module
+ * exists to prevent - it does not throw, it silently attributes work to the
+ * wrong phase and the roll-up still looks plausible.
+ *
+ * @module pipeline/lib/phase-schema
+ */
+
+import { readFileSync } from "node:fs";
+
+const CONTRACT = JSON.parse(
+  readFileSync(new URL("../schemas/phases.json", import.meta.url), "utf8"),
+);
+
+export const CURRENT_SCHEMA = CONTRACT.phaseSchema;
+
+/** Generation 1 number -> current number, derived from each phase's `was`. */
+const GEN1_TO_CURRENT = new Map();
+for (const p of CONTRACT.phases) {
+  for (const old of p.was) GEN1_TO_CURRENT.set(Number(old), p.id);
+}
+
+const CURRENT_NAMES = new Map(CONTRACT.phases.map((p) => [p.id, p.name]));
+const GEN1_NAMES = new Map(
+  Object.entries(CONTRACT.legacyPhaseNames)
+    .filter(([k]) => /^\d+$/.test(k))
+    .map(([k, v]) => [Number(k), v]),
+);
+
+/**
+ * Which vocabulary a metrics row was written under.
+ *
+ * @param {object} row  -  a parsed metrics.jsonl line
+ * @returns {number}    -  1 or 2
+ */
+export function schemaOf(row) {
+  const s = Number(row?.phaseSchema);
+  return Number.isInteger(s) && s > 0 ? s : 1;
+}
+
+/**
+ * A row's phase expressed in the CURRENT vocabulary, so rows from both
+ * generations can be counted together.
+ *
+ * @param {string|number} phase
+ * @param {number} schema  -  from schemaOf()
+ * @returns {number|null}  -  null when the value is not a phase number at all
+ */
+export function toCurrentPhase(phase, schema) {
+  const n = Number(phase);
+  if (!Number.isInteger(n)) return null;
+  if (schema >= CURRENT_SCHEMA) return CURRENT_NAMES.has(n) ? n : null;
+  return GEN1_TO_CURRENT.has(n) ? GEN1_TO_CURRENT.get(n) : null;
+}
+
+/**
+ * The name the phase number carried WHEN IT WAS WRITTEN. A historical row is
+ * labelled with its own vocabulary's name; relabelling it with today's name
+ * would make the archive disagree with the log it came from.
+ *
+ * @param {string|number} phase
+ * @param {number} schema
+ * @returns {string}
+ */
+export function phaseNameAsWritten(phase, schema) {
+  const n = Number(phase);
+  const table = schema >= CURRENT_SCHEMA ? CURRENT_NAMES : GEN1_NAMES;
+  return table.get(n) ?? `Phase ${phase}`;
+}
+
+/**
+ * Convenience for the common shape: a row in, its current-vocabulary phase out.
+ *
+ * @param {object} row
+ * @returns {number|null}
+ */
+export function rowPhase(row) {
+  return toCurrentPhase(row?.phase, schemaOf(row));
+}

package/pipeline/lib/plan-todos.sh

@@ -1,14 +1,14 @@
 #!/usr/bin/env bash
 #
-# plan-todos.sh  -  manage the Phase 2 plan as a live Todo list.
+# plan-todos.sh  -  manage the Phase 1 plan as a live Todo list.
 #
-# The Phase 2 plan is broken into a live, reviewable Todo list that updates
+# The Phase 1 plan is broken into a live, reviewable Todo list that updates
 # step-by-step as Phase 3 works through it.
 #
 # State lives in `agent-state.json` under `.plan.todos[]` per
 # pipeline/schemas/plan-todos.schema.json. Phase 2 (Planning) emits the
 # initial plan; Phase 3 (Dev) iterates step-by-step; Phase 4 (Review)
-# inspects completion; Phase 7 (Report) renders the rollup.
+# inspects completion; Phase 5 (Report) renders the rollup.
 #
 # Subcommands:
 #   init      <task-id> [title]            Initialize with empty todos[] (Phase 2 usually pipes the JSON instead)
@@ -19,7 +19,7 @@
 #   skip      <task-id> <todo-id> <reason> Mark skipped (counts as satisfied for dependents)
 #   next      <task-id>                    Print next pending todo (deps-respecting); empty if none
 #   list      <task-id>                    Render Markdown checklist
-#   status    <task-id>                    Print one-line summary: "3/7 done, 1 in progress"
+#   status    <task-id>                    Print one-line summary: "2/5 done, 1 in progress"
 #   show      <task-id>                    Print the full plan JSON
 #
 # Exit codes:
@@ -117,7 +117,7 @@ do_set() {
   fi
   # A planning-output document is accepted directly and converted here.
   #
-  # The conversion used to live as a jq blob inside phase-2-planning.md, which
+  # The conversion used to live as a jq blob inside phase-1-plan.md, which
   # made the mapping from `tasks[]` to `todos[]` a thing two files defined - and
   # the phase doc was the copy nothing tested. Accepting both shapes costs four
   # lines and removes the second definition.

package/pipeline/lib/route-state.sh

@@ -0,0 +1,161 @@
+#!/usr/bin/env bash
+# route-state.sh  -  read and write prefs.global.modelRouting.
+#
+# Backs /multi-agent:route-on, route-off and route-status. Ships disabled and
+# stays that way until someone turns it on; while `enabled` is false nothing in
+# this file changes one dispatch.
+#
+# The `off` contract is borrowed from autopilot-off and for the same reason: it
+# clears the ON STATE, never the rules. Turning routing back on must not re-ask
+# for a configuration the user already gave.
+#
+# Usage:
+#   route-state.sh status                       print the current policy
+#   route-state.sh on  [--strategy=S] [--scope=a,b]
+#   route-state.sh off
+#   route-state.sh set-rules <file.json>        replace rules[] from a JSON array
+#
+# Exit codes:
+#   0  -  done
+#   2  -  bad usage
+#   3  -  preferences missing/unparseable, or a scope value this refuses
+
+set -uo pipefail
+
+PREFS="${MULTI_AGENT_PREFS:-$HOME/.claude/multi-agent-preferences.json}"
+
+# The scope values this accepts, spelled once. `host-session` is NOT here and
+# must never be added: it would mean rewriting the host's base URL, which routes
+# the user's whole session - work that has nothing to do with this pipeline
+# included - through a third layer, breaks the subscription's auth model, and
+# silently changes which model answers. The schema encodes the same list so a
+# hand-edited preferences file is rejected too, rather than only this entry point.
+ALLOWED_SCOPE="subagent bulk-read research"
+
+die() { echo "route-state: $1" >&2; exit "${2:-3}"; }
+
+# A missing `jq` must not look like routing being off. Every read below would
+# come back empty, `route-status` would report disabled, and a user with rules
+# armed would be told there are none.
+command -v jq >/dev/null 2>&1 || die "jq not found  -  cannot read or write preferences (install: brew install jq)"
+[ -f "$PREFS" ] || die "preferences not found at $PREFS  -  run /multi-agent:setup first"
+jq -e . "$PREFS" >/dev/null 2>&1 || die "$PREFS is not valid JSON  -  refusing to write over it"
+
+ACTION="${1:-status}"; shift 2>/dev/null || true
+
+write_prefs() {
+  local filter="$1"; shift
+  local tmp
+  tmp=$(mktemp) || die "mktemp failed"
+  if ! jq "$@" "$filter" "$PREFS" > "$tmp"; then rm -f "$tmp"; die "jq failed  -  preferences left untouched"; fi
+  jq -e . "$tmp" >/dev/null 2>&1 || { rm -f "$tmp"; die "produced invalid JSON  -  preferences left untouched"; }
+  mv "$tmp" "$PREFS"
+}
+
+case "$ACTION" in
+  status)
+    ENABLED=$(jq -r '.global.modelRouting.enabled // false' "$PREFS")
+    STRATEGY=$(jq -r '.global.modelRouting.strategy // "manual"' "$PREFS")
+    SCOPE=$(jq -r '(.global.modelRouting.scope // ["subagent"]) | join(", ")' "$PREFS")
+    NRULES=$(jq -r '(.global.modelRouting.rules // []) | length' "$PREFS")
+    CEIL=$(jq -r '.global.modelRouting.budgetCeilingUsd // "none"' "$PREFS")
+    REC=$(jq -r '.global.modelRouting.recordDecisions // true' "$PREFS")
+
+    echo "routing:   $ENABLED"
+    echo "strategy:  $STRATEGY"
+    echo "scope:     $SCOPE"
+    echo "rules:     $NRULES"
+    echo "ceiling:   $CEIL"
+    echo "decisions: $REC"
+    echo ""
+
+    if [ "$ENABLED" != "true" ]; then
+      echo "Disabled. Rules are stored but read by nothing; dispatch is unchanged."
+      [ "$NRULES" -gt 0 ] && echo "route-on turns these $NRULES rule(s) back on without re-asking."
+      exit 0
+    fi
+
+    if [ "$NRULES" -eq 0 ]; then
+      echo "Armed with no rules. Nothing matches, so nothing is routed  -  this is a"
+      echo "configuration state, not an error."
+    else
+      jq -r '(.global.modelRouting.rules // [])[] |
+        "  when " + ([.when | to_entries[] | "\(.key)=\(.value)"] | join(" ")) +
+        "  ->  " + (.prefer | join(" > "))' "$PREFS"
+    fi
+
+    echo ""
+    # The limit is printed every time rather than documented once, because the
+    # question it answers ("routing is on, why is the reviewer still on Opus")
+    # otherwise arrives days later as a bug report.
+    echo "Honest limit: on Claude Code a subagent cannot be sent to a non-Anthropic"
+    echo "model  -  subagent dispatch belongs to the host. Phase 1/2/3 personas stay"
+    echo "inside the Anthropic ladder whatever the rules say. External providers apply"
+    echo "only where this pipeline makes the call itself (bulk-read, research)."
+    ;;
+
+  on)
+    STRATEGY="manual"; SCOPE_ARG=""
+    for arg in "$@"; do
+      case "$arg" in
+        --strategy=*) STRATEGY="${arg#*=}" ;;
+        --scope=*)    SCOPE_ARG="${arg#*=}" ;;
+        *) die "unknown option: $arg" 2 ;;
+      esac
+    done
+    case "$STRATEGY" in
+      manual|task-fit|cost-ceiling) ;;
+      *) die "strategy must be manual, task-fit or cost-ceiling (got '$STRATEGY')" 2 ;;
+    esac
+
+    if [ -n "$SCOPE_ARG" ]; then
+      SCOPE_JSON="[]"
+      IFS=',' read -r -a parts <<< "$SCOPE_ARG"
+      for one in "${parts[@]}"; do
+        one="${one// /}"
+        # shellcheck disable=SC2076
+        case " $ALLOWED_SCOPE " in
+          *" $one "*) ;;
+          *) die "scope '$one' is not allowed (allowed: $ALLOWED_SCOPE). 'host-session' is refused by design: it would route the whole session, not this pipeline's calls." ;;
+        esac
+        SCOPE_JSON=$(jq -c --arg s "$one" '. + [$s]' <<< "$SCOPE_JSON")
+      done
+      write_prefs '
+          .global.modelRouting //= {}
+        | .global.modelRouting.enabled = true
+        | .global.modelRouting.strategy = $st
+        | .global.modelRouting.scope = ($sc | fromjson)
+      ' --arg st "$STRATEGY" --arg sc "$SCOPE_JSON"
+    else
+      write_prefs '
+          .global.modelRouting //= {}
+        | .global.modelRouting.enabled = true
+        | .global.modelRouting.strategy = $st
+        | .global.modelRouting.scope //= ["subagent"]
+      ' --arg st "$STRATEGY"
+    fi
+    echo "routing enabled (strategy: $STRATEGY)"
+    exec "$0" status
+    ;;
+
+  off)
+    # Rules survive on purpose. Clearing them here would make route-off a
+    # destructive action wearing the name of a toggle.
+    write_prefs '.global.modelRouting //= {} | .global.modelRouting.enabled = false'
+    echo "routing disabled. Rules kept  -  route-on restores this configuration as it is."
+    ;;
+
+  set-rules)
+    FILE="${1:-}"
+    [ -n "$FILE" ] || die "set-rules needs a JSON file containing an array of rules" 2
+    [ -f "$FILE" ] || die "no such file: $FILE" 2
+    jq -e 'type == "array"' "$FILE" >/dev/null 2>&1 || die "$FILE must contain a JSON ARRAY of rules" 2
+    write_prefs '.global.modelRouting //= {} | .global.modelRouting.rules = $r' --slurpfile _ignore /dev/null --argjson r "$(cat "$FILE")"
+    echo "rules replaced: $(jq -r 'length' "$FILE")"
+    ;;
+
+  *)
+    echo "usage: route-state.sh [status|on|off|set-rules <file>]" >&2
+    exit 2
+    ;;
+esac

package/pipeline/lib/run-paths.sh

@@ -40,7 +40,7 @@ ma_logs_root() {
 }
 
 # ma_is_run_dir <dir> -> 0 when the directory holds at least one run marker
-# Phase 6 removes the worktree and salvages the run's files into `artifacts/`
+# Phase 4 removes the worktree and salvages the run's files into `artifacts/`
 # inside the same run directory, so a shipped run keeps its state one level
 # deeper. A reader that only looks at the top level reports it as stateless.
 MA_ARTIFACTS_SUBDIR=artifacts
@@ -242,7 +242,7 @@ ma_resolve_run_file() {
       printf '%s\n' "$dir/$filename"
       return 0
     fi
-    # The salvaged copy Phase 6 leaves behind.
+    # The salvaged copy Phase 4 leaves behind.
     if [ -f "$dir/$MA_ARTIFACTS_SUBDIR/$filename" ]; then
       printf '%s\n' "$dir/$MA_ARTIFACTS_SUBDIR/$filename"
       return 0

package/pipeline/multi-agent-refs/_account-picker.md

@@ -12,7 +12,7 @@ First step of every `multi-agent` flow **that touches a remote provider**.
 > question, no token lookup. Detection: `freetext` flow first fetches local
 > repos (`repo-cache.sh local "$HOME"`); if the picker resolves to local-only
 > repos, account-picker is bypassed and the state file's `accountId` is left
-> `null` with `tokens={}`. Phases 6/7 read these as "local-only" signals.
+> `null` with `tokens={}`. Phases 4/5 read these as "local-only" signals.
 
 > **Language**: see `picker-contract.md` + `rules.md` Language Application matrix.
 

package/pipeline/multi-agent-refs/_dev-context.md

@@ -70,7 +70,7 @@ Selects extra repos the pipeline may touch beyond the primary repo(s)  -  typica
    is not written here is a candidate the check can never see.
 
    Resolve each entry's `stack` from its local checkout, with the marker table
-   in `phases/phase-1-analysis.md` Step 2 (`.xcodeproj` / `Package.swift` →
+   in `phases/phase-1-plan.md` Step 2 (`.xcodeproj` / `Package.swift` →
    `ios`, `build.gradle(.kts)` → `android`, and so on). No checkout, or no
    marker matched → `stack: "unknown"` and `root: null`. Never infer a stack
    from the repo NAME: `my-app-android` is a naming convention, not a marker,

package/pipeline/multi-agent-refs/_input-parser.md

@@ -35,7 +35,7 @@ The top-level `multi-agent` command classifies user arguments per the rules belo
 
 ¹ Account picker is **skipped** when the resolved primary repo is local-only
   (`provider="local"`). No token lookup, no provider auth  -  the pipeline
-  proceeds with `accountId=null` and Phases 6/7 honor the local-only mode.
+  proceeds with `accountId=null` and Phases 4/5 honor the local-only mode.
 
 ² Free-text flow merges `github`+`bitbucket`+`local` repo caches into a
   single picker list; `(local)` rows come from `repo-cache.sh local "$HOME"`.

package/pipeline/multi-agent-refs/analysis/evidence.md

@@ -225,12 +225,3 @@ The tier boundary is not advisory. A signal row that reaches Section 4 (business
 
 Per source: reachable and answered, reachable and empty, or unreachable. All three are recorded; only the third produces a `fetchErrors[]` entry, and none of them halts.
 
-**Lite mode auto-detection (Locked 25, v9.1.0 scoring)**: at the end of Phase 1c, evaluate three signals and score each:
-
-| Signal | True condition | Score |
-|---|---|---|
-| Confluence spec body lines | < 100 | 1 |
-| Figma frames count | <= 1 | 1 |
-| Repo evidence direct-match count | >= 8 | 1 |
-
-`liteModeAuto = (totalScore >= 2)`. Two of three signals true is enough; the v8.12.0..v9.0.x AND-threshold (all three) forced too many small features into Full mode when one signal was marginal (e.g. a tiny spec with 2 Figma frames). User overrides via `--full` or `--lite` always win over scoring.

package/pipeline/multi-agent-refs/analysis/intake.md

@@ -1,6 +1,6 @@
 # Intake (analysis Phase 0)
 
-> The picker chain that fills `state.analysisSpec.*` before any fetch runs. Loaded by `/multi-agent:analysis`. Pipeline Phase 1 does NOT load this file: in a pipeline run the account, project, repos and task already came from the orchestrator's own Phase 0, and only the source and coverage batches below are asked (see `phase-1-analysis.md` Step 4).
+> The picker chain that fills `state.analysisSpec.*` before any fetch runs. Loaded by `/multi-agent:analysis`. Pipeline Phase 1 does NOT load this file: in a pipeline run the account, project, repos and task already came from the orchestrator's own Phase 0, and only the source and coverage batches below are asked (see `phase-1-plan.md` Step 4).
 
 ### Phase 0 - Intake
 

package/pipeline/multi-agent-refs/analysis/locked.md

@@ -1,25 +1,25 @@
-# Locked decisions (37)
+# Locked decisions (36)
 
-> The 37 Locked decisions of the analysis flow. Loaded by `/multi-agent:analysis`, by `/multi-agent:analysis-resolve` (which inherits them) and by pipeline Phase 1 when it runs the analysis engine. Numbering is canonical: cite as `Locked <n> (<short label>)`.
+> The 36 Locked decisions of the analysis flow. Loaded by `/multi-agent:analysis`, by `/multi-agent:analysis-resolve` (which inherits them) and by pipeline Phase 1 when it runs the analysis engine. Numbering is canonical: cite as `Locked <n> (<short label>)`.
 
 ### Index by category (v9.1.0+)
 
-Browse-friendly grouping of the 37 Locked decisions. Numbering stays canonical (matches the list below); the index is read-only navigation.
+Browse-friendly grouping of the 36 Locked decisions. Numbering stays canonical (matches the list below); the index is read-only navigation.
 
 | Category | Decisions | Concern |
 |---|---|---|
-| **A. Governance** | 1, 5, 6, 7, 10, 26, 27, 32, 36 | Run-level process rules: one feature per run, default output, auto-commit ban, punctuation policy, output picker timing, Pass B preview, evidence digest cache, analysis profile, document reviewed before publish |
-| **B. Citation and Evidence** | 3, 4, 8, 11, 24, 30, 34 | Every fact in the doc traces back to a source: citation discipline, forward-looking spec, standards binding, repo-evidence reuse-first, Pass B footnote mandatory, analysis self-contained (pipeline-wide), references built from the evidence record |
-| **C. Output Format and Structure** | 2, 9, 13, 14, 16, 17, 20, 21, 25, 33, 35, 37 | How the document is laid out: section omission rule, per-platform output split, Gherkin user stories, Goals + Non-Goals paired, Files-to-Add tag, API response variants exhaustive, localization mode (ownership-aware), References at the bottom, Lite mode, corporate backbone always renders, stack-optional render, redesign records v1 before planning v2 |
+| **A. Governance** | 1, 5, 6, 7, 10, 25, 26, 31, 35 | Run-level process rules: one feature per run, default output, auto-commit ban, punctuation policy, output picker timing, Pass B preview, evidence digest cache, analysis profile, document reviewed before publish |
+| **B. Citation and Evidence** | 3, 4, 8, 11, 24, 29, 33 | Every fact in the doc traces back to a source: citation discipline, forward-looking spec, standards binding, repo-evidence reuse-first, Pass B footnote mandatory, analysis self-contained (pipeline-wide), references built from the evidence record |
+| **C. Output Format and Structure** | 2, 9, 13, 14, 16, 17, 20, 21, 32, 34, 36 | How the document is laid out: section omission rule, per-platform output split, Gherkin user stories, Goals + Non-Goals paired, Files-to-Add tag, API response variants exhaustive, localization mode (ownership-aware), References at the bottom, corporate backbone always renders, stack-optional render, redesign records v1 before planning v2 |
 | **D. Design Source and Pipeline Architecture** | 12, 22, 23 | Where design comes from and how the pipeline renders: Figma 3-tier access (BLOCKING), platform-agnostic template + Pass B render, convention extraction (Phase 1c) |
-| **E. UI, Variant, and Test Coverage** | 15, 18, 19, 28, 29, 31 | UI artefact rules: SVG default for new assets, screenshots embedded, all Figma variants drilled, SwiftUI Preview block (iOS), variant usage explicit, business-rule to acceptance-criterion to test traceability |
+| **E. UI, Variant, and Test Coverage** | 15, 18, 19, 27, 28, 30 | UI artefact rules: SVG default for new assets, screenshots embedded, all Figma variants drilled, SwiftUI Preview block (iOS), variant usage explicit, business-rule to acceptance-criterion to test traceability |
 
 When citing a Locked decision in code or docs, prefer `Locked <n> (<short label>)` form so the category is inferable (e.g. `Locked 30 (analysis self-contained, category B)`).
 
 ### Full list
 
 1. **One feature per run.** Every Figma URL, Confluence page, Jira ID, and Standards source the user supplies belongs to the **same feature**. The command never asks "which feature is this for?" or "which URL is primary?". Mixed inputs covering multiple features are treated as user error: surface the conflict, stop, and ask the user to split into separate runs.
-2. **Section omission rule.** Sections with zero evidence are dropped entirely; no `TBD` placeholder section. Numbering remains sequential `1..N` over the rendered set.
+2. **Section omission rule.** Sections with zero evidence are dropped entirely; no `TBD` placeholder section. **A rendered section keeps its canonical template number**, so the set has gaps and that is correct: `1, 2, 4, 9, 13, 14, 21` is a valid rendered document. This clause used to say numbering re-flows sequentially `1..N`, which could not hold alongside Locked 30 - that decision threads ids across sections BY NUMBER (`Section 15.1 scenario`, `Section 4.4`, `Section 3/5 layout cells`), and a re-flowed document sends every one of those cross-references to the wrong section or to nothing. No emitted document ever re-flowed; the rule was the part that was wrong. What IS checked: every rendered number is a real template number, and the numbers ascend without repeating.
 3. **Citation discipline.** Every quoted UI string, endpoint path, error code, or analytics event name in Sections 2-4 must carry an inline citation: `[Figma annotation <nodeId>]` for copy taken from a Dev Mode annotation, `[Figma <nodeId>]` (MCP) or `[figma-export: <project-slug>/<screen-slug>:<nodeId>]` (local source) for design strings; `file:line` for repo evidence; `Confluence:<pageId>:<heading-slug>` for spec text. **Annotation-as-copy precedence:** when the project's `figma-config` has `annotations.enabled` and a node carries a Dev Mode annotation, that annotation is the authoritative copy for the node and the visible text layer is treated as a placeholder; cite the annotation, not the layer text. Never invent copy - blank beats a guess; a node whose annotation has the base language but is missing a target language emits a Section 20 (Risks) row rather than a fabricated value. Uncited quotes are downgraded to `[label TBD - see Open Questions]` and a row is added to Section 7 Risks. Subagent prose and Code Connect snippets are not citations.
 4. **The spec is forward-looking.** Section bodies describe the new feature as drawn / specified. Findings that exist only in legacy code or the existing branch appear as `> Legacy reference: <text> (file:line)` blockquotes inside the relevant section, never as the lead sentence or a primary table row. A legacy-only finding with no forward counterpart goes to Section 7 Risks as a decision item: "current code does X; should the new feature keep, change, or drop this?".
 5. **Output default = Local file.** The Phase 3.5 output picker keeps `Local file` pre-selected. Confluence and Jira outputs are never default-selected (see `analysis-output-confluence-on-request` memory).
@@ -44,17 +44,16 @@ When citing a Locked decision in code or docs, prefer `Locked <n> (<short label>
 22. **Platform-agnostic template + Pass B render.** The template (`$HOME/.claude/multi-agent-refs/analysis-template.md`) describes concepts (state holder, view, navigator, use case, repository, DTO, state model, DI register, localization key, accessibility identifier, test method) without platform-specific class names. Pass B (Phase 2b) projects each concept onto the selected platform using conventions extracted at Phase 1c.
 23. **Convention extraction mandatory (Phase 1c).** After Phase 1b repo evidence, Phase 1c extracts seven pattern groups (folder structure, class naming, UI state model, test method naming, accessibility identifier, localization key, DI registration) per selected repo via `~/.claude/lib/extract-conventions.sh`. Output lands in `state.analysisSpec.evidence.conventions[<repo>]` with confidence levels (high / medium / low / none) and evidence file citations.
 24. **Pass B cell footnote mandatory.** Every cell Pass B fills in Section 13 (Architecture Plan concept table) and any other per-platform projection carries a footnote of the form `^[<convention-key> <confidence>: <evidence-source>]` pointing back to Phase 1c output. Cells with `confidence: low | none` cite `conventions-defaults.md:C<n>-<platform>` and emit a row in Section 20 Risks ("convention fallback applied"). Footnote-less cells fail the dispatch gate.
-25. **Lite mode for small features.** When Phase 1 signals indicate a small feature, Lite mode auto-activates and renders only Sections 1, 2, 4, 9, 13, 14, 21, plus optional 23 Changelog. The user can force Lite with `--lite` or force Full with `--full`. Full mode is the default for new feature analyses. **Scoring (v9.1.0+):** three independent signals - `confluenceSpecLines < 100`, `figmaFramesCount <= 1`, `repoDirectMatchCount >= 8`. Each true signal scores 1 point; Lite auto-activates at `score >= 2`. Previous AND-threshold (`v8.12.0..v9.0.x`) was too strict and forced small features into Full mode when one signal was just over the line. Explicit user flags (`--lite` / `--full`) always win over auto-scoring.
-26. **Pass B preview before render.** Phase 2a presents the resolved convention table to the user before Phase 2b emits any platform file. The user can approve, override individual cells, or cancel. Empty answers do not imply consent (`feedback_no-inferred-defaults-from-empty-answer`); the picker re-asks on empty submit.
-27. **Evidence digest caches Phase 1b and 1c.** `evidence_digest = sha256(featureName || sorted(platforms) || repoEvidence.summary || conventions.summary)`. When the same feature name is invoked again against the same set of repos and the digest matches, Phase 1b and 1c are skipped and the cached `evidence.repoEvidence` / `evidence.conventions` is reused. Cache TTL is 24 hours; manual invalidation via `--no-cache` flag.
-28. **SwiftUI Preview block mandatory (iOS projection, SwiftUI only).** When the iOS file is produced AND the affected view is a SwiftUI view (detected via `import SwiftUI` + `: View` protocol conformance in `evidence.repoEvidence[<repo>].buckets.uiComponents`), Section 13.6 renders a Preview block table covering at minimum: canonical default (LTR Light), Dark, RTL, Dynamic Type accessibilityLarge, and one error variant. Loading state and edge-case variants are added when distinct from canonical. UIKit-only features (no SwiftUI view artefact) drop Section 13.6 with note `(N/A: UIKit-only feature)`. Preview macro convention (`#Preview` for Swift 5.9+ vs legacy `PreviewProvider`) is read from `evidence.conventions[<repo>].previewMacro`. Each Preview variant listed in Section 13.6 must have a matching row in Section 15.2 Snapshot Tests; a Preview without a snapshot row triggers a Section 20 Risk.
-29. **Variant usage explicit and bounded.** Section 6 inventory rows list which variants this feature consumes per component (concrete enum case + bool value). New Section 6.X (Variant Usage Matrix) catalogues the full variant axis vs. used subset with a rationale per excluded variant. Sections 13.6 (Preview) and 15.2 (Snapshot) cover only the used subset; expanding the variant set requires updating Section 6.X first.
-30. **Analysis as self-contained design bridge - no MCP outside analysis phase (BLOCKING, pipeline-wide).** The analysis document is the sole design source for every downstream phase. After Phase 1 of `/multi-agent:analysis` produces `analysis/<feature>-<platform>.md`, Phase 2 Planning, Phase 3 Dev, Phase 4 Review, Phase 5 Test, Phase 6 Commit, and Phase 7 Report consume only the analysis document plus repo Code Connect mappings (`*.figma.swift` / `*.figma.kt`). Calling `mcp__claude_ai_Figma__*`, hitting `api.figma.com`, or fetching a `figma.com/design/...` URL during Phase 2+ is a violation. Applies to every mode that runs Phase 2+: `/multi-agent`, `/multi-agent:autopilot`, `/multi-agent:local`, `/multi-agent:local-autopilot`, at either depth. Hard requirement (v9.0.0): Phase 2 Pre-item and Phase 3 Pre-item (BLOCKING) abort the run when the analysis document is missing. Memory: `[[mcp-only-in-analysis]]`. Generic rule rationale and access matrix: see `$HOME/.claude/rules/figma-pipeline.md` "MUST: No MCP outside analysis phase".
-31. **Business-rule to acceptance-criterion to test traceability (AI + human spine).** The analysis is a development handoff that both an AI implementer and a human reviewer must act on, so it is bound by one shared-ID vocabulary. Every business rule carries a stable id `BR-<slug>-NN` (Section 4.4). Each rule maps to at least one acceptance criterion written Given / When / Then (binary - two readers must not be able to disagree on pass/fail). Each acceptance criterion maps to unit-test scenarios in Section 15.1, one row per case across happy / boundary / error / empty-nil (enumerate at least the failure modes; agents hallucinate error handling when it is omitted). The same ids thread onward: Section 15.6 UI-test flows reference the `BR-` ids and use stable selectors (accessibilityIdentifier / testTag), Section 16 accessibility items reuse those identifiers, Section 11 analytics events cite their triggering rule or story, and Section 5/7 layout cells carry token + Figma node refs. Never invent copy or values (blank beats a guess; a missing source becomes a Section 20 Open Question). **Mode-aware gate:** in Full mode a business rule with no acceptance criterion, or an acceptance criterion with no Section 15.1 scenario, fails the dispatch gate. In **Lite mode Section 15 is not rendered**, so the rule-to-test half does not apply - Section 4.4 still lists each rule with its Given/When/Then acceptance criterion (the acceptance criterion is itself the testable statement), and the 15.1 mapping is deferred to whenever the feature is later analyzed in Full or implemented by a dev run. The rule-to-acceptance-criterion half always holds, in both modes.
-
-32. **Analysis profile selected at intake.** `state.analysisSpec.profile` is `global` (default) or `corporate`, asked once at Phase 0 Step 1b and never re-asked mid-run. `global` renders `$HOME/.claude/multi-agent-refs/analysis-template.md` (23 sections, development handoff). `corporate` renders `$HOME/.claude/multi-agent-refs/analysis-template-corporate.md` (requirements document: `IG -> UC -> FG` spine, three traceability matrices, current-to-target state with impact analysis, then Technical Analysis and Development Analysis). **Both profiles read the same `state.analysisSpec.evidence.*`** - intake, fetching, repo evidence and convention extraction are shared and profile-independent; only the projection differs. This is what keeps the two templates from drifting into two products. One run emits one profile: rendering both from a single run would produce two documents describing the same feature, and the next reader would have to decide which one is current. When only one profile is available (`prefs.global.analysisProfiles` lists one, or the corporate profile has no binding configuration), the step auto-resolves and prints its breadcrumb with the resolution noted, per the picker contract.
-33. **Corporate backbone always renders.** In the `corporate` profile the Locked 2 omission rule is replaced for Part A and the footer: those sections render even with zero evidence, carrying `N/A` when the section is genuinely out of scope for the feature and `EKLENECEK` when evidence is expected but missing. This is the point of a requirements document - a reader has to be able to tell "we considered hardware needs and there are none" from "nobody looked". Every `EKLENECEK` emits a matching Section 20 Risks and Open Questions row naming what is missing and who can answer it; an `EKLENECEK` with no such row fails the dispatch gate, because an unanswered question nobody owns is how a placeholder reaches production. **Missing inputs never block the run**: the corporate source practice of halting until every input arrives is deliberately not adopted - the document is produced with `EKLENECEK` in the gaps and the gaps are raised in Section 20. Part B follows the global omission table unchanged. In the `global` profile Locked 2 applies as written, with no placeholder of any kind.
-34. **References are built from the evidence record, not written.** Section 21 is emitted by `$HOME/.claude/scripts/build-references.mjs` from `state.analysisSpec.evidence.*` in both profiles. Each row carries a precision anchor in its `Sürüm / Ref` column - Figma node id, Confluence `pageId` plus page version, the commit SHA a repo was read at, the Swagger spec version - because a reference with no anchor points at a moving target. Each row carries an `Erişim / Access` cell: a declared source that could not be fetched still gets a row reading `erişilemedi (<reason>)`, since a silently dropped source reads to the next person as a source that never existed. User statements from the conversation that no fetched source contains are recorded as `Serbest metin` rows, quoted verbatim, with the decision they settled. **Coverage gate**: every entry in `evidence.figma[]`, `confluence[]`, `jira[]`, `swagger[]`, `repo[]`, `standards[]`, `firebase[]`, `documents[]`, `outside[]`, `freeText[]` and every entry in `evidence.fetchErrors[]` must appear as a row, and every row must map to an evidence entry. A source that shaped the document but is missing from References fails the dispatch gate; so does an invented row with no evidence behind it.
-35. **Stack-optional render.** Platform and repo selection are optional. When `state.analysisSpec.platforms[]` is empty, the run still completes: the analysis layers that do not need a target repository render in full - Part A and Part B in the corporate profile, Sections 1-12 and 16-17 in the global profile - and only the development layer is dropped (corporate Part C; global Sections 13, 14, 15) along with the Pass B projection, since there are no conventions to project onto. A Section 20 row records that the development analysis awaits a repo selection. **The channel split survives the missing repo.** Channels are derived from the evidence instead of repo stack tags (`intake.md` Step 3 carries the signal table) and one document is emitted per derived channel - `mobile`, `web`, or both. A phone screen and a browser screen carry different requirements before anyone has picked a repository; the split (Locked 9) exists to carry that difference and only its *projection* half needs conventions. `mobile` stays one channel rather than iOS plus Android, since without conventions nothing tells the two apart. Evidence with no interface at all yields a single channel-agnostic `<feature>.md`. Files land under `~/Desktop/multiAgentAnalysis/<feature-name>/`, named `<feature>-<channel>.md` (or `<feature>.md` for the channel-agnostic case): the repo-relative `analysis/` path has nothing to be relative to without a repo, and the current working directory is never used, since for a repo-less run it is arbitrary. Desktop rather than a hidden directory because the document is a deliverable somebody is meant to open and hand over, and `multiAgentAnalysis` rather than a bare `Analysis` because a generic word collides with whatever else is on a desktop while the producer name groups every run this command ever writes. The Phase 3.5 picker shows the resolved path and takes an override through its Other input. A requirements document is useful before anyone has decided which repository will hold the code, and refusing to produce one until that decision exists inverts the order the work actually happens in.
-36. **The document is reviewed before it is published.** An analysis run used to go from draft straight to dispatch behind a deterministic validator, so nothing read what it was about to publish: one run put a channel it never searched for, an open question about a frame it never opened, and twenty-three unowned `EKLENECEK` markers onto a live page. Every one is what a reader catches on the first pass. Phase 3.2 runs `phases/phase-4-review.md` Step 0 (strict validator, the host's three-reviewer set, triage) on the draft before the destination is chosen: a finding is cheap while nothing is written. Reviewers are subagents holding `analysis/review.md`, never the context that wrote the document, which cannot notice a search it never thought to run. A blocking finding returns to Phase 2b with dispatch closed and never becomes an open question, since "the document is wrong" is not something to ask the reader; capped at two returns. Phase 3.3 sorts every remaining gap into searched-and-closed, asked-and-answered, or `AS-NN`; an unstamped gap fails the dispatch gate. Autopilot runs both; only the asking degrades, into rows stamped `autopilot: could not ask`.
-37. **A redesign records v1 before it plans v2.** `options.redesign` is an opt-in on the `options.uiTests` axis, never a third `mode` value: `mode` says how many sections, `redesign` says which content, and a `mode: redesign` would switch off the Full-mode traceability, Test Plan and rule-to-test gates in exactly the documents that need them. It adds three sub-sections and no top-level section: current behaviour with `CB-<slug>-NN` ids and `repo/file:line` citations, the v1 to v2 endpoint mapping, and a difference list over a closed status vocabulary. Every `Missing` and `Partial` owes a Section 20 row by `AS-NN`, and a `CB-` id in one table but not the other fails in both directions - a behaviour that is in the code and on nobody's difference list is what a redesign loses and production finds. Evidence and certainty are derived from `repoEvidence`, never graded by the writer (Locked 24, same reason), and `options.redesign` is an `evidence_digest` input. Contract and the eight checks: `analysis/redesign.md`, loaded only on a redesign run.
+25. **Pass B preview before render.** Phase 2a presents the resolved convention table to the user before Phase 2b emits any platform file. The user can approve, override individual cells, or cancel. Empty answers do not imply consent (`feedback_no-inferred-defaults-from-empty-answer`); the picker re-asks on empty submit.
+26. **Evidence digest caches Phase 1b and 1c.** `evidence_digest = sha256(featureName || sorted(platforms) || repoEvidence.summary || conventions.summary)`. When the same feature name is invoked again against the same set of repos and the digest matches, Phase 1b and 1c are skipped and the cached `evidence.repoEvidence` / `evidence.conventions` is reused. Cache TTL is 24 hours; manual invalidation via `--no-cache` flag.
+27. **SwiftUI Preview block mandatory (iOS projection, SwiftUI only).** When the iOS file is produced AND the affected view is a SwiftUI view (detected via `import SwiftUI` + `: View` protocol conformance in `evidence.repoEvidence[<repo>].buckets.uiComponents`), Section 13.6 renders a Preview block table covering at minimum: canonical default (LTR Light), Dark, RTL, Dynamic Type accessibilityLarge, and one error variant. Loading state and edge-case variants are added when distinct from canonical. UIKit-only features (no SwiftUI view artefact) drop Section 13.6 with note `(N/A: UIKit-only feature)`. Preview macro convention (`#Preview` for Swift 5.9+ vs legacy `PreviewProvider`) is read from `evidence.conventions[<repo>].previewMacro`. Each Preview variant listed in Section 13.6 must have a matching row in Section 15.2 Snapshot Tests; a Preview without a snapshot row triggers a Section 20 Risk.
+28. **Variant usage explicit and bounded.** Section 6 inventory rows list which variants this feature consumes per component (concrete enum case + bool value). New Section 6.X (Variant Usage Matrix) catalogues the full variant axis vs. used subset with a rationale per excluded variant. Sections 13.6 (Preview) and 15.2 (Snapshot) cover only the used subset; expanding the variant set requires updating Section 6.X first.
+29. **Analysis as self-contained design bridge - no MCP outside analysis phase (BLOCKING, pipeline-wide).** The analysis document is the sole design source for every downstream phase. After Phase 1 of `/multi-agent:analysis` produces `analysis/<feature>-<platform>.md`, Phase 1 Plan, Phase 2 Dev, Phase 3 Review, Phase 3 Review, Phase 4 Commit, and Phase 5 Report consume only the analysis document plus repo Code Connect mappings (`*.figma.swift` / `*.figma.kt`). Calling `mcp__claude_ai_Figma__*`, hitting `api.figma.com`, or fetching a `figma.com/design/...` URL during Phase 2+ is a violation. Applies to every mode that runs Phase 2+: `/multi-agent`, `/multi-agent:autopilot`, `/multi-agent:local`, `/multi-agent:local-autopilot`, at either depth. Hard requirement (v9.0.0): Phase 2 Pre-item and Phase 3 Pre-item (BLOCKING) abort the run when the analysis document is missing. Memory: `[[mcp-only-in-analysis]]`. Generic rule rationale and access matrix: see `$HOME/.claude/rules/figma-pipeline.md` "MUST: No MCP outside analysis phase".
+30. **Business-rule to acceptance-criterion to test traceability (AI + human spine).** The analysis is a development handoff that both an AI implementer and a human reviewer must act on, so it is bound by one shared-ID vocabulary. Every business rule carries a stable id `BR-<slug>-NN` (Section 4.4). Each rule maps to at least one acceptance criterion written Given / When / Then (binary - two readers must not be able to disagree on pass/fail). Each acceptance criterion maps to unit-test scenarios in Section 15.1, one row per case across happy / boundary / error / empty-nil (enumerate at least the failure modes; agents hallucinate error handling when it is omitted). The same ids thread onward: Section 15.6 UI-test flows reference the `BR-` ids and use stable selectors (accessibilityIdentifier / testTag), Section 16 accessibility items reuse those identifiers, Section 11 analytics events cite their triggering rule or story, and Section 3/5 layout cells carry token + Figma node refs. Never invent copy or values (blank beats a guess; a missing source becomes a Section 20 Open Question). **Gate:** a business rule with no acceptance criterion, or an acceptance criterion with no Section 15.1 scenario, fails the dispatch gate. There is no mode clause: the rule used to be suspended in Lite mode, which deferred the rule-to-test half to "whenever the feature is later analyzed in Full" - a debt nothing tracked and nothing ever paid. Section 15 renders when there is evidence for it and is dropped when there is not, like every other section, and the gate applies to whatever was rendered.
+
+31. **Analysis profile selected at intake.** `state.analysisSpec.profile` is `global` (default) or `corporate`, asked once at Phase 0 Step 1b and never re-asked mid-run. `global` renders `$HOME/.claude/multi-agent-refs/analysis-template.md` (23 sections, development handoff). `corporate` renders `$HOME/.claude/multi-agent-refs/analysis-template-corporate.md` (requirements document: `IG -> UC -> FG` spine, three traceability matrices, current-to-target state with impact analysis, then Technical Analysis and Development Analysis). **Both profiles read the same `state.analysisSpec.evidence.*`** - intake, fetching, repo evidence and convention extraction are shared and profile-independent; only the projection differs. This is what keeps the two templates from drifting into two products. One run emits one profile: rendering both from a single run would produce two documents describing the same feature, and the next reader would have to decide which one is current. When only one profile is available (`prefs.global.analysisProfiles` lists one, or the corporate profile has no binding configuration), the step auto-resolves and prints its breadcrumb with the resolution noted, per the picker contract.
+32. **Corporate backbone always renders.** In the `corporate` profile the Locked 2 omission rule is replaced for Part A and the footer: those sections render even with zero evidence, carrying `N/A` when the section is genuinely out of scope for the feature and `EKLENECEK` when evidence is expected but missing. This is the point of a requirements document - a reader has to be able to tell "we considered hardware needs and there are none" from "nobody looked". Every `EKLENECEK` emits a matching Section 20 Risks and Open Questions row naming what is missing and who can answer it; an `EKLENECEK` with no such row fails the dispatch gate, because an unanswered question nobody owns is how a placeholder reaches production. **Missing inputs never block the run**: the corporate source practice of halting until every input arrives is deliberately not adopted - the document is produced with `EKLENECEK` in the gaps and the gaps are raised in Section 20. Part B follows the global omission table unchanged. In the `global` profile Locked 2 applies as written, with no placeholder of any kind.
+33. **References are built from the evidence record, not written.** Section 21 is emitted by `$HOME/.claude/scripts/build-references.mjs` from `state.analysisSpec.evidence.*` in both profiles. Each row carries a precision anchor in its `Sürüm / Ref` column - Figma node id, Confluence `pageId` plus page version, the commit SHA a repo was read at, the Swagger spec version - because a reference with no anchor points at a moving target. Each row carries an `Erişim / Access` cell: a declared source that could not be fetched still gets a row reading `erişilemedi (<reason>)`, since a silently dropped source reads to the next person as a source that never existed. User statements from the conversation that no fetched source contains are recorded as `Serbest metin` rows, quoted verbatim, with the decision they settled. **Coverage gate**: every entry in `evidence.figma[]`, `confluence[]`, `jira[]`, `swagger[]`, `repo[]`, `standards[]`, `firebase[]`, `documents[]`, `outside[]`, `freeText[]` and every entry in `evidence.fetchErrors[]` must appear as a row, and every row must map to an evidence entry. A source that shaped the document but is missing from References fails the dispatch gate; so does an invented row with no evidence behind it.
+34. **Stack-optional render.** Platform and repo selection are optional. When `state.analysisSpec.platforms[]` is empty, the run still completes: the analysis layers that do not need a target repository render in full - Part A and Part B in the corporate profile, Sections 1-12 and 16-17 in the global profile - and only the development layer is dropped (corporate Part C; global Sections 13, 14, 15) along with the Pass B projection, since there are no conventions to project onto. A Section 20 row records that the development analysis awaits a repo selection. **The channel split survives the missing repo.** Channels are derived from the evidence instead of repo stack tags (`intake.md` Step 3 carries the signal table) and one document is emitted per derived channel - `mobile`, `web`, or both. A phone screen and a browser screen carry different requirements before anyone has picked a repository; the split (Locked 9) exists to carry that difference and only its *projection* half needs conventions. `mobile` stays one channel rather than iOS plus Android, since without conventions nothing tells the two apart. Evidence with no interface at all yields a single channel-agnostic `<feature>.md`. Files land under `~/Desktop/multiAgentAnalysis/<feature-name>/`, named `<feature>-<channel>.md` (or `<feature>.md` for the channel-agnostic case): the repo-relative `analysis/` path has nothing to be relative to without a repo, and the current working directory is never used, since for a repo-less run it is arbitrary. Desktop rather than a hidden directory because the document is a deliverable somebody is meant to open and hand over, and `multiAgentAnalysis` rather than a bare `Analysis` because a generic word collides with whatever else is on a desktop while the producer name groups every run this command ever writes. The Phase 3.5 picker shows the resolved path and takes an override through its Other input. A requirements document is useful before anyone has decided which repository will hold the code, and refusing to produce one until that decision exists inverts the order the work actually happens in.
+35. **The document is reviewed before it is published.** An analysis run used to go from draft straight to dispatch behind a deterministic validator, so nothing read what it was about to publish: one run put a channel it never searched for, an open question about a frame it never opened, and twenty-three unowned `EKLENECEK` markers onto a live page. Every one is what a reader catches on the first pass. Phase 3.2 runs `phases/phase-3-review.md` Step 0 (strict validator, the host's three-reviewer set, triage) on the draft before the destination is chosen: a finding is cheap while nothing is written. Reviewers are subagents holding `analysis/review.md`, never the context that wrote the document, which cannot notice a search it never thought to run. A blocking finding returns to Phase 2b with dispatch closed and never becomes an open question, since "the document is wrong" is not something to ask the reader; capped at two returns. Phase 3.3 sorts every remaining gap into searched-and-closed, asked-and-answered, or `AS-NN`; an unstamped gap fails the dispatch gate. Autopilot runs both; only the asking degrades, into rows stamped `autopilot: could not ask`.
+36. **A redesign records v1 before it plans v2.** `options.redesign` is an opt-in on the `options.uiTests` axis, never a third `mode` value: `mode` says how many sections, `redesign` says which content, and a `mode: redesign` would switch off the Full-mode traceability, Test Plan and rule-to-test gates in exactly the documents that need them. It adds three sub-sections and no top-level section: current behaviour with `CB-<slug>-NN` ids and `repo/file:line` citations, the v1 to v2 endpoint mapping, and a difference list over a closed status vocabulary. Every `Missing` and `Partial` owes a Section 20 row by `AS-NN`, and a `CB-` id in one table but not the other fails in both directions - a behaviour that is in the code and on nobody's difference list is what a redesign loses and production finds. Evidence and certainty are derived from `repoEvidence`, never graded by the writer (Locked 24, same reason), and `options.redesign` is an `evidence_digest` input. Contract and the eight checks: `analysis/redesign.md`, loaded only on a redesign run.

package/pipeline/multi-agent-refs/analysis/render.md

@@ -46,7 +46,7 @@
 
 Locked 36 carries the rule. Operationally:
 
-1. Run `phases/phase-4-review.md` Step 0, the analysis-mode branch. It already defines
+1. Run `phases/phase-3-review.md` Step 0, the analysis-mode branch. It already defines
    the strict validator, the host's three-reviewer set with its model routing, and the
    triage. Do not restate it here; a second definition is the one that rots.
 2. Dispatch reviewers as subagents, each given the draft path, the state JSON and

package/pipeline/multi-agent-refs/analysis/synthesis.md

@@ -52,8 +52,8 @@ Convention preview - Pass B will render with:
 | DI | UserProfileDependencyConfigurator ^[C7 high] | UserProfileModule (Hilt) ^[C7 fallback: defaults] |
 
 Confidence summary:
-  iOS:     7/7 high, 0 medium, 0 low, 0 fallback
-  Android: 5/7 high, 1 medium, 0 low, 1 fallback
+  iOS:     5/5 high, 0 medium, 0 low, 0 fallback
+  Android: 3/5 high, 1 medium, 0 low, 1 fallback
 ```
 
 AskUserQuestion shape:
@@ -86,11 +86,17 @@ For each `platform` in `state.analysisSpec.platforms[]`:
    - `android` → `~/.claude/rules/kotlin-android.md` first → `evidence.standards[]` entries whose path contains `android` or `kotlin`
    - `backend` → `evidence.standards[]` entries matching language hints (`python`, `go`, `node`, `fastapi`) → fall back to `~/.claude/rules/security.md` + `code-style.md`
    - `web` → `evidence.standards[]` entries matching `react`, `vue`, `next`, `sveltekit` → `~/.claude/rules/code-style.md`
-2. **Apply per-platform omission rules.** Backend-only file drops Sections 5, 6, 7, 8, 16. Web with no UI inventory still keeps 5 (UI exists in code). Sections 1, 2, 4, 9, 13, 14, 20, 21 always present per Locked decision 2 + 13.
-3. **Resolve mode.** If user passed `--lite` → Lite. If user passed `--full` → Full. Otherwise use `state.analysisSpec.liteModeAuto`. Lite mode renders only Sections 1, 2, 4, 9, 13, 14, 21 plus optional 23.
-4. **Produce YAML front-matter header** (see `$HOME/.claude/multi-agent-refs/analysis-template.md`). Include `profile: <state.analysisSpec.profile | global>` and `platform: <platform | none>` so the validator applies the right contract per profile (Locked 32) and recognises the stack-optional render (Locked 35), `mode: full | lite`, plus `ui_tests: <state.analysisSpec.options.uiTests | false>`, `a11y_depth: <state.analysisSpec.options.a11yDepth | basic>` and `redesign: <state.analysisSpec.options.redesign | false>` so the pre-dispatch validator can enforce the opt-in coverage (15.6 present when ui_tests, 16.2 walkthrough present when a11y_depth is full, 4.5 / 4.6 / 9.5 present when redesign). `status` is written only by `/multi-agent:analysis-resolve`; a rendered document is a draft.
+2. **Apply per-platform omission rules.** Backend-only file drops Sections 5, 6, 7, 8, 16. Web with no UI inventory still keeps 5 (UI exists in code). Sections 1, 2, 4, 9, 13, 14, 20, 21 always present per Locked decision 2 + 13; their numbers are canonical and never re-flowed.
+3. **Resolve the section set from evidence, not from a mode.** There is one
+   pipeline. A section renders when it has evidence and is dropped when it does
+   not, per Locked 2. Lite mode used to answer this question with a fixed list
+   (1, 2, 4, 9, 13, 14, 21 plus optional 23) chosen by a three-signal score, and
+   that list fought Locked 2 in both directions: a small feature with rich
+   business rules lost Section 15 because it was not on the list, and a feature
+   with no API contract kept Section 9 because it was. Evidence decides now.
+4. **Produce YAML front-matter header** (see `$HOME/.claude/multi-agent-refs/analysis-template.md`). Include `profile: <state.analysisSpec.profile | global>` and `platform: <platform | none>` so the validator applies the right contract per profile (Locked 32) and recognises the stack-optional render (Locked 35), plus `ui_tests: <state.analysisSpec.options.uiTests | false>`, `a11y_depth: <state.analysisSpec.options.a11yDepth | basic>` and `redesign: <state.analysisSpec.options.redesign | false>` so the pre-dispatch validator can enforce the opt-in coverage (15.6 present when ui_tests, 16.2 walkthrough present when a11y_depth is full, 4.5 / 4.6 / 9.5 present when redesign). `status` is written only by `/multi-agent:analysis-resolve`; a rendered document is a draft.
 5. **Read conventions for this platform's repo.** For each cell Pass B fills in Section 13 and in any per-platform projection (Sections 5, 6, 7, 8, 10, 11, 13, 14, 15, 16, 17), read `state.analysisSpec.evidence.conventions[<repo>].<field>` and emit the value with a footnote (Locked 24). If `conventionOverrides` has an entry for that field, use the override and footnote with `^[user-override: <reason>]` instead of evidence path.
-6. **Concatenate non-null sections in canonical order.** Numbering stays sequential `1..N` over the rendered set (omitted sections do not create gaps).
+6. **Concatenate non-null sections in canonical order.** Each rendered section keeps its canonical template number, so omitted sections DO leave gaps - `1, 2, 4, 9, 13, 14, 21` is a correct rendered document. Locked 30 cites sections by number across the whole document; re-flowing them would break every one of those references.
 7. **Schema validation** on the per-platform spec object:
    ```bash
    python3 -c "import json,jsonschema; jsonschema.validate(json.load(open('state/<feature>-<platform>.json')), json.load(open('$HOME/.claude/schemas/analysis-spec.schema.json')))"

package/pipeline/multi-agent-refs/android-guide.md

@@ -14,7 +14,7 @@
 - [Compliance Rules (maps to multi-agent-toolkit MCP audit tools)](#compliance-rules-maps-to-multi-agent-toolkit-mcp-audit-tools)
 <!-- /toc -->
 
-> **MUST: Figma MCP-first (BLOCKING).** If the task references any Figma frame (URL, node ID, or "from the design"), the Dev phase MUST call `mcp__claude_ai_Figma__get_design_context` for every frame BEFORE writing a single Composable line. Use the `CodeConnectSnippet` component name verbatim - no sound-alike substitutions. Authentication failure is not a skip path. Full rule, trigger conditions, and gate failure modes: `$HOME/.claude/rules/figma-pipeline.md` "MUST: Figma MCP-first (BLOCKING)". Phase wiring: `$HOME/.claude/multi-agent-refs/phases/phase-3-dev.md` "MUST: Figma MCP-first (BLOCKING pre-step)".
+> **MUST: Figma MCP-first (BLOCKING).** If the task references any Figma frame (URL, node ID, or "from the design"), the Dev phase MUST call `mcp__claude_ai_Figma__get_design_context` for every frame BEFORE writing a single Composable line. Use the `CodeConnectSnippet` component name verbatim - no sound-alike substitutions. Authentication failure is not a skip path. Full rule, trigger conditions, and gate failure modes: `$HOME/.claude/rules/figma-pipeline.md` "MUST: Figma MCP-first (BLOCKING)". Phase wiring: `$HOME/.claude/multi-agent-refs/phases/phase-2-dev.md` "MUST: Figma MCP-first (BLOCKING pre-step)".
 
 When the task involves creating an Android UI component (Jetpack Compose), follow this architecture.