@mmerterden/multi-agent-pipeline 13.5.1 → 14.1.0

package/pipeline/lib/figma-screenshot.sh

@@ -23,10 +23,10 @@
 #   Tier 2 (Figma REST + PAT)     -> primary path here
 #   Tier 3 (user screenshot)      -> not handled; exit 3 with guidance
 #
-# Token source: credential-store.sh get <logical-key>, where <logical-key>
-# is read from prefs.global.keychainMapping.figma_pat. Falls back to the
-# FIGMA_PAT environment variable. No literal keychain service name is
-# embedded in this script.
+# Token source: figma-token.sh, which resolves the canonical `figma` logical
+# key through credential-store.sh (falling back to the legacy `figma_pat` key,
+# then to the FIGMA_PAT environment variable). No literal keychain service name
+# is embedded in this script.
 #
 # Exit codes:
 #   0  success
@@ -41,7 +41,6 @@ set -euo pipefail
 
 # --- Globals ----------------------------------------------------------------
 
-PREFS="$HOME/.claude/multi-agent-preferences.json"
 # Locate the resolver with an existence check, not a `.`-chain: sourcing a missing file
 # aborts the shell under `set -e`, `||` included, so a chain skips both its later
 # candidates and its trailing `|| true`. A missing store is tolerated here - CRED_STORE
@@ -61,6 +60,26 @@ for _cred_resolver in \
 done
 unset _cred_resolver
 CRED_STORE="${CRED_STORE:-}"
+
+# Tier 2 token lookup lives in one file so it cannot drift per fetcher. Same
+# existence-check discipline as the resolver loop above, and the same tolerance:
+# without it, resolution still works through the FIGMA_PAT env fallback.
+for _figma_token_lib in \
+  "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)/figma-token.sh" \
+  "$HOME/.claude/lib/figma-token.sh" \
+  "$HOME/.copilot/lib/figma-token.sh" \
+  "$HOME/.codex/lib/figma-token.sh"; do
+  [ -f "$_figma_token_lib" ] || continue
+  # shellcheck source=/dev/null
+  . "$_figma_token_lib" 2>/dev/null || true
+  if command -v resolve_figma_token >/dev/null 2>&1; then break; fi
+done
+unset _figma_token_lib
+if ! command -v resolve_figma_token >/dev/null 2>&1; then
+  resolve_figma_token() { [ -n "${FIGMA_PAT:-}" ] && printf '%s' "$FIGMA_PAT"; }
+  figma_token_remediation() { printf 'figma-token.sh not found - reinstall the pipeline, or export FIGMA_PAT.'; }
+fi
+
 FIGMA_API="https://api.figma.com/v1"
 PARALLEL_DL=4
 HTTP_TIMEOUT=60
@@ -105,8 +124,8 @@ Options:
   --help           Show this help text and exit.
 
 Token resolution:
-  Read via credential-store.sh using
-  prefs.global.keychainMapping.figma_pat. Falls back to FIGMA_PAT env.
+  Read via credential-store.sh using prefs.global.keychainMapping.figma
+  (legacy figma_pat still honoured). Falls back to FIGMA_PAT env.
 
 Output:
   PNG files plus manifest.json in the output directory.
@@ -151,35 +170,6 @@ print(f"{file_key}\t{node}")
 PY
 }
 
-resolve_token() {
-  # 1) Try the keychain via credential-store.sh, keyed by prefs mapping.
-  local token_key=""
-  if [ -f "$PREFS" ] && command -v python3 >/dev/null 2>&1; then
-    token_key=$(python3 -c "
-import json, sys
-try:
-    p = json.load(open('$PREFS'))
-    print(p.get('global', {}).get('keychainMapping', {}).get('figma_pat') or '')
-except Exception:
-    print('')
-" 2>/dev/null || true)
-  fi
-  if [ -n "$token_key" ] && [ -x "$CRED_STORE" ]; then
-    local tok
-    tok=$("$CRED_STORE" get "$token_key" 2>/dev/null || true)
-    if [ -n "$tok" ]; then
-      printf '%s' "$tok"
-      return 0
-    fi
-  fi
-  # 2) Env fallback so CI / one-shot use still works.
-  if [ -n "${FIGMA_PAT:-}" ]; then
-    printf '%s' "$FIGMA_PAT"
-    return 0
-  fi
-  return 1
-}
-
 # curl_figma <output> <url>
 # Honours retries: 429 retries once after a 5s pause; 5xx uses exponential
 # backoff (1s, 2s, 4s). Writes the body to <output>, returns the HTTP code on
@@ -409,11 +399,10 @@ require_cmd python3
 # Tier 1 (Figma MCP) is not reachable from a bash script. Stay on Tier 2 (REST).
 log "INFO: Tier 1 (Figma MCP) not available from shell; using Tier 2 (REST)."
 
-FIGMA_TOKEN=$(resolve_token || true)
+FIGMA_TOKEN=$(resolve_figma_token || true)
 if [ -z "${FIGMA_TOKEN:-}" ]; then
   log "Tier 3 (user-provided screenshot required): no PAT resolved."
-  log "Hint: store the token via credential-store.sh, mapped through"
-  log "      prefs.global.keychainMapping.figma_pat, or export FIGMA_PAT."
+  log "Hint: $(figma_token_remediation)"
   exit 3
 fi
 

package/pipeline/lib/figma-token.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+#
+# figma-token.sh
+# Single resolution point for the Tier 2 Figma Personal Access Token.
+#
+# Sourced by every Tier 2 fetcher (fetch-figma-annotations.sh,
+# figma-screenshot.sh). It exists because those two each carried their own copy
+# of this lookup: when `migrate-prefs.mjs` consolidated
+# `keychainMapping.figma_pat` into `keychainMapping.figma` and deleted the old
+# key, only the migration was updated. Both fetchers kept reading the deleted
+# key, so every migrated install reported `missing-token` while a valid PAT sat
+# under the new name - and the error text told the user to map the key the
+# migration had just removed. One copy of the lookup cannot drift from itself.
+#
+# Tier 2 is only reached when Tier 1 (Figma MCP) is unreachable; see the Figma
+# Access Tier rule in multi-agent-refs/rules.md for the chain and the
+# expired-token decision that gates the move to Tier 3.
+#
+# Resolution order, first non-empty wins:
+#   1. credential-store.sh get figma      - the canonical logical key
+#   2. credential-store.sh get figma_pat  - pre-v13.6 installs that never migrated
+#   3. $FIGMA_PAT                         - env fallback for CI and one-shot runs
+#
+# Logical keys are passed through verbatim. credential-store.sh owns the
+# `prefs.global.keychainMapping` indirection, so resolving the mapping here as
+# well would reintroduce the duplication this file exists to remove. No literal
+# Keychain service name appears here, which keeps the Synced Command Hygiene
+# rule satisfied.
+#
+# Requires `$CRED_STORE` to already be resolved (via credential-store-resolver.sh).
+# An unset or non-executable CRED_STORE is tolerated: resolution falls through to
+# the env fallback so a keychain-less CI box still works.
+
+# The canonical key first, the legacy key second. Space-separated so the loop
+# below stays POSIX-ish and works under bash 3.2 (stock macOS).
+FIGMA_TOKEN_LOGICAL_KEYS="${FIGMA_TOKEN_LOGICAL_KEYS:-figma figma_pat}"
+
+# resolve_figma_token
+# Prints the token on stdout and returns 0, or prints nothing and returns 1.
+resolve_figma_token() {
+  local key tok
+  if [ -n "${CRED_STORE:-}" ] && [ -x "${CRED_STORE:-}" ]; then
+    for key in $FIGMA_TOKEN_LOGICAL_KEYS; do
+      tok=$("$CRED_STORE" get "$key" 2>/dev/null || true)
+      if [ -n "$tok" ]; then
+        printf '%s' "$tok"
+        return 0
+      fi
+    done
+  fi
+  if [ -n "${FIGMA_PAT:-}" ]; then
+    printf '%s' "$FIGMA_PAT"
+    return 0
+  fi
+  return 1
+}
+
+# figma_token_remediation
+# The one place the "how do I fix this" sentence is written, so a fetcher can
+# never name a key the migration deleted.
+figma_token_remediation() {
+  printf 'no Figma PAT for Tier 2. Map prefs.global.keychainMapping.figma (run /multi-agent:setup), or export FIGMA_PAT.'
+}

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

@@ -10,7 +10,7 @@ description: "v3 canonical template for /multi-agent:analysis. 23 main sections
 
 > **Language**: This file is read as a system prompt. Prose stays English. Example tables and headings carry bilingual TR / EN scaffolds; the runtime renderer picks the right column per `outputLanguage`.
 
-> **Locked decisions that govern this template**: the canonical numbered list lives in `pipeline/commands/multi-agent/analysis/SKILL.md` (cite decisions by label, not by a number duplicated here, to avoid drift). The template's structure is shaped chiefly by: one-feature-per-run, section omission rule, citation discipline (incl. annotation-as-copy), forward-looking spec, humanizer punctuation policy, standards binding, per-platform output split, repo-evidence reuse-first, Figma 3-tier access, Gherkin user stories, Goals + Non-Goals paired, SVG default, Files-to-Add tag, API response variants exhaustive, screenshots embedded, all Figma variants drilled, localization mode (ownership-aware), References at bottom, platform-agnostic + Pass B render, convention extraction, Pass B footnote mandatory, Lite mode, SwiftUI Preview block (iOS), variant usage explicit, analysis self-contained (no MCP downstream), and business-rule to acceptance-criterion to test traceability.
+> **Locked decisions that govern this template**: the canonical numbered list lives in `$HOME/.claude/commands/multi-agent/analysis/SKILL.md` (cite decisions by label, not by a number duplicated here, to avoid drift). The template's structure is shaped chiefly by: one-feature-per-run, section omission rule, citation discipline (incl. annotation-as-copy), forward-looking spec, humanizer punctuation policy, standards binding, per-platform output split, repo-evidence reuse-first, Figma 3-tier access, Gherkin user stories, Goals + Non-Goals paired, SVG default, Files-to-Add tag, API response variants exhaustive, screenshots embedded, all Figma variants drilled, localization mode (ownership-aware), References at bottom, platform-agnostic + Pass B render, convention extraction, Pass B footnote mandatory, Lite mode, SwiftUI Preview block (iOS), variant usage explicit, analysis self-contained (no MCP downstream), and business-rule to acceptance-criterion to test traceability.
 
 ## Mode selection - Full vs Lite
 

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

@@ -1,6 +1,6 @@
 ## Android/Kotlin Component Generation Guide
 
-> **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: `pipeline/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-3-dev.md` "MUST: Figma MCP-first (BLOCKING pre-step)".
 
 When the task involves creating an Android UI component (Jetpack Compose), follow this architecture.
 

package/pipeline/multi-agent-refs/channels/issue-comment.md

@@ -112,7 +112,7 @@ Token resolution: `gh auth status` for the active GitHub account selected in Pha
 
 ## Pairing with the Progress flag updater
 
-Every issue comment post is paired with `pipeline/scripts/update-issue-progress.sh "$TASK_ID"` in the same Phase 7 step. Order: comment FIRST (so the timestamp marks the run), flags SECOND (so the body diff is one logical change).
+Every issue comment post is paired with `$HOME/.claude/scripts/update-issue-progress.sh "$TASK_ID"` in the same Phase 7 step. Order: comment FIRST (so the timestamp marks the run), flags SECOND (so the body diff is one logical change).
 
 ```bash
 # Phase 7 Step 5  -  issue channel

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

@@ -111,9 +111,9 @@ On failure (the plugin skill returns an unrecoverable build/test error, or the d
 
 ## `--dev` mode behaviour
 
-When multi-agent is invoked with `--dev` (fast path: Init → Dev → Commit → Report), the dispatch layer passes `mode: "dev"` so the plugin skill can elide unit tests and wiki (structural + snapshot still required; wiki deferred to Phase 7). If the plugin does not honor a `mode` hint, dispatch simply skips the post-build wiki step itself.
+When multi-agent is invoked with `--dev` (fast path: Init → Dev → Review → Commit → Report), the dispatch layer passes `mode: "dev"` so the plugin skill can elide unit tests and wiki (structural + snapshot still required; wiki deferred to Phase 7). If the plugin does not honor a `mode` hint, dispatch simply skips the post-build wiki step itself.
 
-Phase 4 reviewer-skipping is **not** Phase 3's concern  -  Phase 4 decides based on `mode: "dev"` itself.
+Phase 4 runs in `--dev` as it does in the full pipeline, and its reviewer count is **not** Phase 3's concern  -  the Step 1.77 scope gate decides that from diff risk, independently of `mode`. What the dispatch layer owes Phase 4 is the record of which plugin skill it delegated to, appended to `state.telemetry.skillCalls[]`, so the review can check the delivered component against the criteria that skill imposes.
 
 ## Cross-CLI behaviour (intentional divergence)
 

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

@@ -10,10 +10,10 @@
 
 ```
 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,
+dev-autopilot, dev-local, dev-local-autopilot, diff-explain, forget, garbage-collect,
 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
+routines, save, scan, search, setup, ship, stack, status, sync, test, testflight-validation, uninstall, update
 ```
 
 Categories:
@@ -21,8 +21,8 @@ Categories:
 - **Interactive pickers** (single-purpose, not modes): `jira`, `issue`
 - **Issue generator** (one-shot, no worktree, asks type Task/Bug/Story, hard approval gate before create): `create-jira`
 - **Full 8-phase modes**: `autopilot`, `local`, `local-autopilot`
-- **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`
+- **Fast modes** (Init -> Dev(Opus) -> Review -> Commit -> Report): `dev`, `dev-autopilot`, `dev-local`, `dev-local-autopilot`
+- **Tail modes** (run the pipeline tail over already-done local work): `ship`
 - **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`, `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`

package/pipeline/multi-agent-refs/features/dev-critic.md

@@ -7,7 +7,7 @@
 1. Dispatch `dev-critic` sub-agent (Sonnet by default, tools: `Read, Grep, Glob, Bash`).
 2. Critic runs 4 deterministic gates (build / lint / test / secrets)  -  failure of any → `pass: false` with `blocking` finding.
 3. If gates green, critic walks the platform checklist (iOS 13-item / Android Kotlin / Backend generic  -  selected by Phase 1 `detectedStack`).
-4. Returns schema-validated JSON (`pipeline/schemas/dev-critic-output.schema.json`): `{pass, iteration, gates, findings[], escalate}`.
+4. Returns schema-validated JSON (`$HOME/.claude/schemas/dev-critic-output.schema.json`): `{pass, iteration, gates, findings[], escalate}`.
 
 ## Loop cap (STRICT)  -  max 2 iterations
 
@@ -41,4 +41,4 @@ Phase 4 is parallelization-with-voting  -  good for *adversarial* perspectives (
 
 ## Reference
 
-See `pipeline/agents/dev-critic.md` for the full agent specification (gates, checklist enumeration, output schema, severity semantics).
+See `$HOME/.claude/agents/dev-critic.md` for the full agent specification (gates, checklist enumeration, output schema, severity semantics).

package/pipeline/multi-agent-refs/features/model-fallback.md

@@ -10,7 +10,7 @@ without ever editing persona files at runtime.
 > **Fable 5 available again (2026-07).** `claude-fable-5` is the top tier once
 > more. Architect (`ios/android/backend-architect`), Reviewer-1 (`code-reviewer`),
 > and triage personas declare `preferredModel: fable` - the deepest-reasoning
-> roles. **If Fable 5 is unavailable, the first fallback is opus (`claude-opus-4-8`).**
+> roles. **If Fable 5 is unavailable, the first fallback is opus (`claude-opus-5`).**
 > Security and other `preferredModel: opus` personas keep opus as their top tier.
 > The `premiumTierUntil` date gate stays in the contract as a generic mechanism
 > for any plan-window-limited premium tier.
@@ -24,9 +24,42 @@ fable -> opus -> sonnet -> haiku
 The orchestrator walks **one step down per trigger** from whichever tier a
 persona prefers: a `fable` persona degrades `fable -> opus` first, then
 `opus -> sonnet`, then `sonnet -> haiku`; an `opus` persona starts at
-`opus -> sonnet`. So a Fable 5 outage transparently promotes Opus 4.8 into the
+`opus -> sonnet`. So a Fable 5 outage transparently promotes Opus 5 into the
 architect/reviewer roles with no file edits.
 
+### Rung names are the contract; model IDs are not
+
+Personas and dispatch read the **rung** (`fable`, `opus`, `sonnet`, `haiku`). The wire
+model ID each rung resolves to lives in exactly two places: `scripts/cost-table.json`
+(`prices.<rung>.modelId`) and the per-host reviewer table in
+`phases/phase-4-review.md`. A generation move edits those; it never renames a rung and
+never touches a persona file.
+
+Current resolution: `fable` -> `claude-fable-5`, `opus` -> `claude-opus-5`,
+`sonnet` -> `claude-sonnet-5`, `haiku` -> `claude-haiku-4-5`.
+
+**Rate limits do not follow the rung.** Claude Opus 5 draws on a pool separate from
+the combined Opus 4.x pool, so a generation move does not inherit the previous
+generation's headroom. Budget-ceiling downgrades below are unaffected - they read the
+cost ledger, not the provider's quota - but a 429 on the opus rung after a generation
+move is a limits question, not a fallback-contract question.
+
+### Behavioural re-tuning the generation move implies
+
+The pipeline's reviewer and dev prompts were tuned against the previous generation.
+Three shifts on the current opus rung are worth knowing when reading a run that looks
+different rather than broken, and none of them are bugs in this contract:
+
+- **Longer user-facing output.** Effort is not the lever; prompt-level conciseness is.
+  Phase 7 report length and reviewer prose are where this shows.
+- **Self-verification without being asked.** Explicit "double-check your work"
+  scaffolding now causes over-verification rather than preventing under-verification.
+  Phase 4's deterministic gates already carry that load.
+- **Readier subagent delegation.** The previous generation under-reached and needed
+  encouragement; this one does not. Phase 1's parallel scan and Phase 4's reviewer
+  panel are already bounded by explicit counts, which is the right shape - keep them
+  bounded rather than adding "delegate more" guidance.
+
 One step down per trigger, walking the ladder until a tier dispatches or the
 floor (`haiku`) is reached. `haiku` is the last-resort floor: a run that reaches
 it is heavily degraded but still makes progress instead of hard-halting because

package/pipeline/multi-agent-refs/features/plan-todos.md

@@ -1,6 +1,6 @@
 # Feature: Plan Todos Iteration (Phase 3)
 
-**Gated by `prefs.global.planTodos.enabled`** (default: `false`). When enabled and Phase 2 Step 4.5 emitted a `plan.todos[]` (conforming to `pipeline/schemas/plan-todos.schema.json`), Phase 3 iterates with the helper instead of walking `tasks[]` directly:
+**Gated by `prefs.global.planTodos.enabled`** (default: `false`). When enabled and Phase 2 Step 4.5 emitted a `plan.todos[]` (conforming to `$HOME/.claude/schemas/plan-todos.schema.json`), Phase 3 iterates with the helper instead of walking `tasks[]` directly:
 
 ```bash
 while next=$(bash "$HOME/.claude/lib/plan-todos.sh" next "$TASK_ID"); [ -n "$next" ]; do

package/pipeline/multi-agent-refs/features/repo-map.md

@@ -14,7 +14,7 @@ if [ "$(jq -r '.global.repoMap.enabled // false' "$PREFS")" = "true" ]; then
   args=(--root "$WORKTREE" --budget "$BUDGET" --top "$TOP" --format md)
   [ -n "$INCLUDE" ] && args+=(--include "$INCLUDE")
   [ -n "$EXCLUDE" ] && args+=(--exclude "$EXCLUDE")
-  REPO_MAP=$(node pipeline/scripts/repo-map.mjs "${args[@]}" 2>/dev/null || echo "")
+  REPO_MAP=$(node $HOME/.claude/scripts/repo-map.mjs "${args[@]}" 2>/dev/null || echo "")
 fi
 ```
 

package/pipeline/multi-agent-refs/features/review-multi-repo.md

@@ -57,9 +57,9 @@ And log `review.diff_truncated repo=<name> bytes_dropped=<N>`. Triage receives t
 
 **Telemetry**: Per-repo build/test gate timings + a single combined review/triage call set:
 ```bash
-pipeline/scripts/log-metric.sh "$TASK_ID" 4 gate.build repo=common status=pass duration_ms=$D
-pipeline/scripts/log-metric.sh "$TASK_ID" 4 gate.build repo=uicomponents status=pass duration_ms=$D
-pipeline/scripts/log-metric.sh "$TASK_ID" 4 review.combined_diff repos=2 bytes=$BYTES truncated=false
+$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 4 gate.build repo=common status=pass duration_ms=$D
+$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 4 gate.build repo=uicomponents status=pass duration_ms=$D
+$HOME/.claude/scripts/log-metric.sh "$TASK_ID" 4 review.combined_diff repos=2 bytes=$BYTES truncated=false
 ```
 
 ---

package/pipeline/multi-agent-refs/features/shadow-git.md

@@ -1,6 +1,6 @@
 # Feature: Shadow-Git Checkpoints (Phase 3)
 
-**Gated by `prefs.global.shadowGit.enabled`** (default: `false`). The orchestrator snapshots the worktree via `pipeline/lib/shadow-git.sh` so sub-phase rollback is possible without polluting the project's real `.git` history.
+**Gated by `prefs.global.shadowGit.enabled`** (default: `false`). The orchestrator snapshots the worktree via `$HOME/.claude/lib/shadow-git.sh` so sub-phase rollback is possible without polluting the project's real `.git` history.
 
 ```bash
 # Phase 0 (one-time per task): initialize shadow repo + baseline snapshot.

package/pipeline/multi-agent-refs/features/skill-conformance.md

@@ -0,0 +1,116 @@
+# Skill conformance  -  reviewing against the criteria the work was built to
+
+> **TLDR**  -  Phase 4 Step 1.78 resolves, deterministically and before any reviewer runs, WHAT the changed code was supposed to honour: declared rule registries scoped to the diff's languages, in-repo module guides, and the toolchains those registries delegate to. The result is `criteria-manifest.json`: a bounded set of rule IDs that becomes the denominator for "was this applied completely". Reviewers answer per rule ID. An ID that is neither checked nor explicitly waived fails the stage.
+
+## Why this exists
+
+Phase 4 used to select its review criteria from `detectedStack`, a string Phase 1 computed before a line of code existed, and Phase 3 never recorded which skills it actually applied. Two consequences:
+
+- The dev side and the review side could disagree about the standard without either noticing. A component built by a plugin skill was reviewed against `clean-code`.
+- "Did it do this correctly?" had no fixed denominator, so the only available answer was "it looks fine", and a reviewer that opened nothing produced the same output as a reviewer that checked everything.
+
+The `--dev` family made this sharper: those modes have no Phase 1 at all, so the sole input to the old selection logic was absent.
+
+## The four rules that make it work
+
+1. **The denominator is written before the reviewers run.** `criteria-manifest.json` lands on disk in Step 1.78. Reviewers receive the selected rule IDs and must return a verdict per ID. A reviewer cannot narrow the set after seeing the diff, and a no-findings result still has to say what it checked.
+2. **The resolver is primary; self-report only corroborates.** Phase 3 appends to `state.telemetry.skillCalls[]`, but coverage is never computed from it. An unrecorded consultation and no consultation are byte-identical in state, so a percentage derived from self-report reads green over an empty set. `ledger.source` therefore defaults to `derived`, and a declared entry the resolver could not bind to a changed file is FLAGGED rather than believed.
+3. **Absent, empty and zero are three states.** `selfReport: absent` (no key), `empty` (key is `[]`), `declared` (has entries). Collapsing them makes the completeness claim unfalsifiable.
+4. **The pipeline names no stack-specific skill.** Registries opt in; see below.
+
+## Registry discovery is declared, never sniffed
+
+A skill becomes a standards registry by saying so in its own frontmatter:
+
+```yaml
+standards-registry: references/rules.yml
+```
+
+`skill-conformance.mjs` reads frontmatter across the installed skills trees and loads what declared itself. Nothing in the pipeline names `ios-coding-standard`, `apple-archive-compliance` or any other skill, so a future UIKit, Objective-C, Kotlin or backend registry drops in with zero pipeline change  -  and a registry that is absent produces a declared coverage gap rather than a silent pass.
+
+**The skills root differs per host**, so discovery is a bounded walk over candidate roots (`<install>/skills`, `<install>/multi-agent-refs/skills` for Codex, `<repo>/pipeline/skills`), installed layouts first. `install/copilot.mjs` copies `scripts/` byte-for-byte with no path rewrite, so a hardcoded `~/.claude/skills` is inert on two of the three hosts. That bug has already shipped here once: dynamic skill loading exited 1 on every real install while passing a smoke that ran from the repo. `skillsRootsSearched` is recorded in the manifest so an empty result is attributable to a root rather than to an absence of registries.
+
+## Scope is required, and it is what makes this stack-generic
+
+Every registry declares the languages and paths its rules may be applied to:
+
+```yaml
+scope:
+  languages: [swift]
+  paths: ["**/*.swift"]
+  excludePaths: ["**/Generated/**"]
+  notCovered:
+    objective-c: "no ObjC rules exist here; report as a coverage gap"
+```
+
+Per-rule `scope:` narrows this further and never widens it.
+
+Without this the 99 Swift rules of the iOS registry would be applied to an Objective-C or UIKit file, which manufactures findings, buries the real ones, and teaches the reader to distrust the run  -  strictly worse than declaring no coverage. Every dropped rule is counted with its reason in `droppedReasons`, because silently narrowing the rule set is indistinguishable from the code passing it.
+
+A registry that declares no scope loads as `reference-only`: readable context for the reviewers, contributing no rule IDs to the denominator.
+
+## What is deterministic here, and what is deliberately not
+
+**Deterministic (this gate):** which registries apply, which rule IDs are in scope, which changed files no criteria cover, whether the delegated toolchain is wired, and the exception-marker audit.
+
+**Not deterministic, on purpose:** the rules themselves. This gate does NOT execute registry `mechanism` patterns. Across the 99-rule iOS registry the distribution is 47 `judgement` / 41 `lint` / 10 `scan` / 1 `format`, only 43 rules carry `mechanism` at all, and the field is prose with an embedded pattern (`swiftlint file_length, function_body_length`, `custom regex per module`) whose scope is written in English. Perhaps 12-15 have an extractable pattern. Running them unscoped floods a review with doc-comment matches  -  which the registry's own guidance says, requiring each hit be opened and confirmed. The properly engineered version already exists as `references/swiftlint.draft.yml`, 36 regex rules with path scoping.
+
+So instead: **if a registry names a toolchain, check whether the repo wired it, run it when it is there, and report its absence as a finding.** That is stack-generic for free, because swiftlint, ktlint, detekt, eslint and ruff all speak rule IDs. An unwired toolchain ranks above most individual violations it would have caught: those rules are unverified, and a review reporting no violations for them is reporting that nothing was measured.
+
+## The one bespoke scan: exception markers
+
+Cheap, language-agnostic, and it answers "completely" head on  -  an exception is the author's own claim that a rule does not apply here, so an expired or unexplained one is something the reviewers would otherwise take on trust. The marker template is read from the registry's `exception_marker`, never hardcoded, so a registry using a different comment syntax still works.
+
+| Condition | Severity |
+|---|---|
+| Exception expired (`expiry < today`) | blocking |
+| Exception names an ID absent from every registry in scope | blocking |
+| Exception with no rule ID | blocking |
+| Exception with no expiry date | important |
+| Exception with no reason | important |
+
+## Dev-mode substitutes (Phases 1 and 2 never ran)
+
+| Full-pipeline input | Dev-mode substitute |
+|---|---|
+| `detectedStack` (Phase 1) | language census of the diff by file extension. Describes what the diff CONTAINS, not what the repo is nominally built in, so one Objective-C bridging file in a Swift repo is classified correctly |
+| Phase 1 analysis summary (triage scope) | the task description plus the inline task list Phase 3 generated for itself |
+| Phase 2 plan | same inline task list |
+| `state.evidence.figma[]` (Step 1.8) | recorded as `not-applicable (no Phase 1 evidence)` |
+| Step 2.8 visual conformance | recorded as `not-applicable (no Phase 1 evidence)` |
+
+Recording `not-applicable` rather than skipping is the point: "silently skipped" and "out of scope with a reason" must be distinguishable, or the completeness claim cannot be checked.
+
+## Invocation
+
+```bash
+node $HOME/.claude/scripts/skill-conformance.mjs \
+  --diff "$WORKTREE/.review-diff.txt" \
+  --state "$WORKTREE/agent-state.json" \
+  --repo "$WORKTREE" \
+  --out "$WORKTREE/.pipeline/criteria-manifest.json"
+```
+
+Exit codes:
+
+| Code | Meaning |
+|---|---|
+| `0` | manifest written; may still carry findings or declared coverage gaps |
+| `1` | setup error: no diff, unreadable state, or an explicit `--skills-root` that does not exist |
+| `2` | **fail closed**: no skills root resolved at all, a declared registry could not be parsed, or a declared registry path escaped its skill directory |
+
+Any non-zero code halts before the reviewers. Continuing on `2` would drop a whole rule set from the denominator; and because `validate-reviewer.mjs` skips the checklist when zero rules were selected, an empty resolution would otherwise render as a clean review over criteria that were never loaded. An empty registry set inside a root that DOES exist is the different, legitimate case: declared coverage gap, exit 0.
+
+`skillsRootsSearched` lists every candidate root that was probed with an `existed` flag, not only the ones found  -  otherwise the field is empty in exactly the case it exists to explain.
+
+Output validates against `$HOME/.claude/schemas/criteria-manifest.schema.json`.
+
+## Handoff to the reviewers
+
+The manifest's selected rule IDs and registry file paths go into the **shared, cacheable prompt prefix** as one `${CRITERIA}` block, byte-identical for every reviewer (Step 1.9 requires an identical leading block; per-reviewer criteria subsets would invalidate the prefix for the whole panel and pay full input rate on the largest block in the phase). Reviewers read the registry YAML natively  -  the pipeline hands over a path, not a parse.
+
+Deterministic findings merge at Step 3.0 alongside the test-integrity set, so triage adjudicates them rather than never seeing them. A finding citing a registry rule ID carries evidence a reviewer opinion does not, and the triage prompt says so: an ID-citing finding is not dismissible as a matter of taste, though it can still be out of scope for this task.
+
+## Preference
+
+`prefs.global.skillConformance.blockOnCoverageGap` (default **false**). A coverage gap on a stack with no registry would otherwise block every non-iOS run from day one. There is deliberately no opt-out for the stage itself or for the exception-expiry check, on the same grounds as Step 1.76: a run that can switch off its own anti-reward-hacking control cannot be trusted to report a pass.

package/pipeline/multi-agent-refs/features/stack-skill-routing.md

@@ -0,0 +1,72 @@
+# Stack skill routing  -  letting the toolkit plugin choose its own skills
+
+> **TLDR**  -  When a stack toolkit plugin is enabled, Phase 3 asks that plugin's own `index` skill which of its skills apply to this task, loads them before writing code, and records each into `state.telemetry.skillCalls[]`. The routing table lives in the plugin; the pipeline copies none of it.
+
+## Why this exists
+
+Phase 3 dispatched to the toolkit plugin for exactly one case, `taskType === "component"` (see `component-dispatch.md`). Every other task  -  `bugfix`, `feature`, `refactor`, `chore`  -  had no skill dispatch at all: whichever skills the host happened to surface by description match were the ones that got used, and nothing recorded or required any of them.
+
+That is the dev-side half of the gap `features/skill-conformance.md` closes on the review side. Review now asks "was this built to the rules it was supposed to follow"; without this step, the answer for a non-component task was "there were no declared rules, because nobody chose any".
+
+The fix is not a routing table in the pipeline. Each `ai-<platform>-engineering-toolkit` already ships one: an `index` skill whose description says *"Load this first when unsure which skill applies"*, holding a 30-plus row intent-to-skill map maintained alongside the skills it points at. A second copy in this repo would drift the moment the plugin shipped a new skill, and the pipeline's copy would be the stale one.
+
+So the pipeline's job is to **ask**, not to know.
+
+## When it runs
+
+Phase 3 pre-flight, before any code is written, for **every** `taskType`. Component tasks keep their dedicated dispatch in `component-dispatch.md`; this step runs in addition, because the reference skills (architecture, naming, file placement, tokens) apply to a component build too.
+
+## Resolution
+
+Platform comes from the same mapping component dispatch uses, so the two cannot disagree:
+
+| `state.platform` / detected stack | Toolkit |
+|---|---|
+| ios, swift | `ai-ios-engineering-toolkit` |
+| android, kotlin | `ai-android-engineering-toolkit` |
+| anything else | no toolkit  -  step is a recorded no-op |
+
+The toolkit is enabled per repo (`.claude/settings.local.json` / `~/.claude/settings.json` `enabledPlugins`). **Not enabled is not an error here**, unlike component dispatch: a backend or web repo legitimately has no toolkit, and halting would make the pipeline unusable outside mobile. Record the no-op and continue.
+
+Two marketplaces may ship the same toolkit name (a public one and a corporate one). Resolve whichever is enabled and record its **name and version** in the ledger entry, because the routing table and the skill set differ between versions  -  a finding that cites a skill has to be traceable to the version that defined it.
+
+## The call
+
+```text
+Skill(<toolkit>:index, args: "<task title + one-line intent>")
+```
+
+The index returns which `reference/` and `workflow/` skills apply. Load each via the Skill tool before writing code. A typical task pulls one workflow skill plus one or more reference skills.
+
+Emit one progress line per loaded skill per `progress-contract.md`, so the user can see which standards the run bound itself to rather than inferring it afterwards.
+
+## Recording  -  what makes this checkable
+
+Append one `state.telemetry.skillCalls[]` entry per skill actually loaded:
+
+```json
+{"skill": "ai-ios-engineering-toolkit:reference/architecture", "phase": 3,
+ "targetFiles": ["Domains/Checkin/Sources/CheckinScene.swift"],
+ "routedBy": "ai-ios-engineering-toolkit:index@0.13.0", "timestamp": "<ISO-8601>"}
+```
+
+`routedBy` names the index and version that chose it. That is the difference between "the model happened to read a skill" and "the toolkit said this skill governs this task".
+
+What Phase 4 actually does with it, precisely: Step 1.78 lists these entries in the manifest under `ledger.routedByToolkit`, so a reviewer and the Phase 7 report can see which skills the project's own toolkit selected. It does **not** give them extra weight in the coverage maths. The deterministic resolver stays primary because an unrecorded load and no load are indistinguishable in state, and no `routedBy` tag changes that  -  the tag says who chose the skill, not that the code honoured it.
+
+## Failure modes, and why none of them halt
+
+| Situation | Behaviour |
+|---|---|
+| No toolkit for this stack | recorded no-op, continue |
+| Toolkit not enabled in this repo | recorded no-op, continue (component dispatch still halts for its own case) |
+| `index` resolves but routes to a skill that does not exist in this version | record the miss with the version, load the rest, continue. A stale row in a plugin's table must not stop a run |
+| `index` itself does not resolve | record and fall back to the host's own description matching, which is the pre-v14.1.0 behaviour  -  no worse than before |
+
+Nothing here blocks Phase 3. What is downstream is visibility, not enforcement: routed skills appear in the manifest's `ledger.routedByToolkit`, and a task that recorded nothing shows up as `ledgerSource: derived` with its coverage gap stated. Enforcement over rule IDs is the registry's job (`features/skill-conformance.md`), not this step's.
+
+## What this deliberately does NOT do
+
+- It does not decide which skills apply. Copying the plugin's routing into this repo would put the authoritative table in the wrong place and guarantee drift.
+- It does not fail a run for a missing skill. The pipeline's contract is to ask and record, not to require that a third-party plugin be complete.
+- It does not replace `component-dispatch.md`. That path owns the component build itself, including the `figma-validate` pre-check and the halt-on-incomplete-state rule.

package/pipeline/multi-agent-refs/features/verify-by-test.md

@@ -38,4 +38,4 @@ Adds one Sonnet call plus up to `maxFindings` single-test runs (and build-lock c
 
 ## Reference
 
-Wiring: `$HOME/.claude/multi-agent-refs/phases/phase-4-review.md` Step 3.7. Schema: `pipeline/schemas/triage-output.schema.json` v3.2.0 (`$defs.verification`). Evidence gate: `pipeline/scripts/evidence-gate.mjs`. Prefs: `prefs.global.verifyByTest` in `pipeline/schemas/prefs.schema.json`.
+Wiring: `$HOME/.claude/multi-agent-refs/phases/phase-4-review.md` Step 3.7. Schema: `$HOME/.claude/schemas/triage-output.schema.json` v3.2.0 (`$defs.verification`). Evidence gate: `$HOME/.claude/scripts/evidence-gate.mjs`. Prefs: `prefs.global.verifyByTest` in `$HOME/.claude/schemas/prefs.schema.json`.

package/pipeline/multi-agent-refs/features/worktree-finalize.md

@@ -0,0 +1,66 @@
+# Worktree finalize  -  removing a task's worktree once its PR is open
+
+> **TLDR**  -  Phase 6 step 9. Once the PR exists the worktree is dead weight, so it is removed: artefacts are salvaged into the log dir first, the branch is kept and deliberately NOT checked out, and every destructive path is gated. Gated by `prefs.global.settings.worktreeAutoRemoveOnPr` (default **true**). Script: `worktree-finalize.sh`.
+
+## Why it exists
+
+A finished task's worktree is a full second checkout that nobody needs after the PR is open, and removing it is the step people forget. `.worktrees/` then accumulates copies of the repo until `/multi-agent:kill` or `:garbage-collect` is run by hand.
+
+Removing it at PR-open is only safe because of the salvage, so the two are one step and not two.
+
+## What it will not do
+
+**No `git checkout` of the task branch.** `git worktree remove` leaves the branch as an ordinary local branch: the ref, its commits, and the ability to `git checkout <branch>` later all survive untouched. Checking it out here would move the user's HEAD out from under them and can collide with their own uncommitted work on another branch. Phase 5 removes-then-checks-out on purpose, because it is handing the branch over for manual testing; this step is not.
+
+**No `git branch -D`.** The branch is the deliverable.
+
+**No `--force`, ever.** `git worktree remove` refusing is a safety feature. The clean-tree check runs before it, so a refusal at that point means something unexpected (a lock, a submodule, permissions) and forcing past unexpected dirt is how work gets lost.
+
+## Preconditions  -  each one skips with a reason, none is an error
+
+| Condition | Why it blocks |
+|---|---|
+| `worktreePath == projectRoot` (`--local` mode) | there is no worktree; removing it would delete the user's checkout |
+| cwd is inside the worktree | a shell left on a deleted inode is worse than a leftover directory, and Phase 6 legitimately `cd`s into the worktree earlier |
+| not a registered worktree of the project root | a mistyped path must not delete an unrelated directory |
+| real uncommitted changes | never discarded; see the artefact carve-out below |
+| HEAD not on the remote | removing a worktree whose commits exist nowhere else is data loss, not cleanup |
+
+Exit codes: `0` removed, `3` skipped with a reason (report and continue to Phase 7), `1` usage error.
+
+### The artefact carve-out, and why `--untracked-files=no` is wrong
+
+The pipeline's own artefacts live inside the worktree and are untracked, so a raw `git status --porcelain` is never empty at PR-open. Left unhandled the removal would never fire and the feature would look implemented while doing nothing.
+
+So exactly these paths are forgiven, and nothing else:
+
+```
+agent-state.json  phase-tracker.json  triage-output.json
+.review-diff.txt  .build.log  .test.log  .pipeline/
+```
+
+Suppressing all untracked files instead (`--untracked-files=no`) would have been shorter and wrong: a source file the developer created but never `git add`ed is invisible to it, and that file would be destroyed silently.
+
+## Salvage
+
+Copied into `$HOME/.claude/logs/multi-agent/<project>/<task-id>/artifacts/` before removal, each only if present  -  a task that never reached Phase 4 has no triage output and that is not an error.
+
+This is why the removal is safe:
+
+| Consumer | Reads | Without salvage |
+|---|---|---|
+| Phase 7 triage-memory ingest | `triage-output.json` | `[ -f ]`-guarded, so it degrades **silently**: the triage corpus and learnings ledger stop being fed and no error appears |
+| Phase 7 learnings-ledger distill | same file | same silent degradation |
+| `render-work-summary.sh` | `agent-state.json`, `phase-tracker.json` | exits 2, so the Work Summary vanishes from the PR body and the Jira comment |
+| `:resume` | `agent-state.json` | cannot continue a Phase 7 pause |
+| `:status`, `:log` | `agent-state.json` | the task becomes invisible |
+
+`state.worktreeRemovedAt` and `state.artifactsPath` record the outcome. The timestamp is what tells a reader that a worktree-less task was finished-and-tidied rather than killed  -  without it, a missing worktree is indistinguishable from a broken run.
+
+## Multi-repo
+
+Run serially per repo, and only **after** `update_sibling_links`: that function issues an update per PR and the loop `cd`s per repo, so removing repo 1's worktree mid-loop breaks repos 2..N.
+
+## Interaction with the existing removal sites
+
+`gc-worktrees.sh` and `/multi-agent:garbage-collect` never touch a registered, healthy worktree  -  they sweep orphans. Both name this step as the owner of finishing-a-task removal, which is now true rather than aspirational.