@mmerterden/multi-agent-pipeline 13.5.1 → 14.0.0

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/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/generate-issue.md

@@ -140,7 +140,7 @@ curl -s -H "Authorization: Bearer $TOKEN" \
 Each source is failure-isolated and never blocks issue creation.
 
 **6a. Figma** (only when `FIGMA_URL` is set):
-Follow the 3-tier chain from `rules/figma-pipeline.md`: Tier 1 MCP (`get_design_context` / `get_screenshot`, one re-auth retry) → Tier 2 REST (`keychainMapping.figma_pat`) → Tier 3 ask the user for a screenshot or proceed link-only.
+Follow the 3-tier chain from `rules/figma-pipeline.md`: Tier 1 MCP (`get_design_context` / `get_screenshot`, one re-auth retry) → Tier 2 REST (`keychainMapping.figma`) → Tier 3 ask the user for a screenshot or proceed link-only.
 
 > This command is standalone (same class as `/multi-agent:analysis`), so Figma MCP use here is allowed  -  it is not a dev-phase violation under the "No MCP outside analysis phase" rule.
 

package/pipeline/multi-agent-refs/multi-repo-integration-build.md

@@ -195,7 +195,7 @@ Memories that reference integration hosts NEVER get auto-pruned  -  even if a co
 
 ## Schema
 
-`prefs.schema.json` adds `global.multiRepoIntegrationHosts`  -  see `pipeline/schemas/prefs.schema.json` for the authoritative definition. Required fields: `repoSet` (array ≥2), one of `(hostPath + platform)` OR `(noHost: true)`. Optional: `hostScheme`, `submodulePaths`, `resolveCommand`, `buildCommand`, `lastUsed`, `count`, `lastResult`.
+`prefs.schema.json` adds `global.multiRepoIntegrationHosts`  -  see `$HOME/.claude/schemas/prefs.schema.json` for the authoritative definition. Required fields: `repoSet` (array ≥2), one of `(hostPath + platform)` OR `(noHost: true)`. Optional: `hostScheme`, `submodulePaths`, `resolveCommand`, `buildCommand`, `lastUsed`, `count`, `lastResult`.
 
 ## Smoke coverage
 

package/pipeline/multi-agent-refs/phases/log-format.md

@@ -62,7 +62,7 @@ Verdict: unverified (2 reviewers)
 
 ## Cost Breakdown
 
-(emit by Phase 7 via `pipeline/scripts/render-agent-log-cost.sh <task-id>`. Renders unconditionally on every run. If the renderer exits 2 (no tracker data + no OTel spans), Phase 7 omits this section without failing the run.)
+(emit by Phase 7 via `$HOME/.claude/scripts/render-agent-log-cost.sh <task-id>`. Renders unconditionally on every run. If the renderer exits 2 (no tracker data + no OTel spans), Phase 7 omits this section without failing the run.)
 
 | Phase | Model | Tokens in | Tokens out | Est. USD |
 | ----- | ----- | --------- | ---------- | -------- |
@@ -89,7 +89,7 @@ Verdict: unverified (2 reviewers)
 Phase 7 MUST attempt to render the Cost Breakdown section as part of the agent-log compose step:
 
 ```bash
-COST_BLOCK=$(bash pipeline/scripts/render-agent-log-cost.sh "$TASK_ID" 2>/dev/null) && \
+COST_BLOCK=$(bash $HOME/.claude/scripts/render-agent-log-cost.sh "$TASK_ID" 2>/dev/null) && \
   printf '%s\n' "$COST_BLOCK" >> "$AGENT_LOG"
 ```
 
@@ -100,9 +100,9 @@ Emission is best-effort  -  exit 2 (no data) is silently skipped. Never fail the
 Every phase that dispatches a billable LLM agent MUST forward its token totals to the tracker. The minimal contract (already enforced via `smoke-tracker-contract.sh` for Phase 4):
 
 ```bash
-pipeline/scripts/log-metric.sh "$TASK_ID" <phase-id> <event> \
+$HOME/.claude/scripts/log-metric.sh "$TASK_ID" <phase-id> <event> \
   model=<fable|opus|sonnet|haiku|gpt-5.4|gpt-5.6|gpt-5.6-terra> tokens_in=$IN tokens_out=$OUT tokens_cached=$CACHED duration_ms=$DUR
-LOG_METRIC_FORWARD_TO_TRACKER=1 pipeline/scripts/log-metric.sh "$TASK_ID" <phase-id> tokens \
+LOG_METRIC_FORWARD_TO_TRACKER=1 $HOME/.claude/scripts/log-metric.sh "$TASK_ID" <phase-id> tokens \
   model=<...> tokens_in=$IN tokens_out=$OUT tokens_cached=$CACHED
 ```
 

package/pipeline/multi-agent-refs/phases/modes.md

@@ -1,7 +1,7 @@
 > **TLDR**  -  Three orthogonal modifier flags that can combine freely:
 >
 > - `autopilot` → skips confirmations (Plan, Test, Commit, PR prompts), still fails safe on review blockers and build retries.
-> - `--dev` → strips to Init → Dev(Opus self-contained) → Test → Commit → Report. No Phase 1/2/4. Phase 5 Test is an interactive prompt (suppressed only by `autopilot`).
+> - `--dev` → strips to Init → Dev(Opus self-contained) → Review → Test → Commit → Report. No Phase 1/2. Phase 4 Review runs in every `--dev` combination; Phase 5 Test is an interactive prompt (suppressed only by `autopilot`).
 > - `--local` → no worktree, works directly in `$PROJECT_ROOT` on a local branch.
 >
 > Combined: `--dev --local autopilot` = fastest, least-friction path.
@@ -59,7 +59,7 @@ Full contract: `$HOME/.claude/multi-agent-refs/phases/phase-7-report.md` (Autopi
 
 ## Dev-Only Mode (`--dev`)
 
-Dev-only mode strips the pipeline to minimum: no deep analysis, no planning phase, no multi-model review, no user test. The **Opus** dev agent directly analyzes the task scope and implements.
+Dev-only mode strips the pipeline to what a scoped task needs: no deep analysis, no planning phase. The **Opus** dev agent directly analyzes the task scope and implements, and Phase 4 then reviews what it produced. Review is deliberately NOT part of the strip: analysis and planning shape work that has not happened yet, so a task the user has already scoped can skip them, while review judges work that now exists and has no substitute.
 
 **Activation**: Append `--dev` to any pipeline command:
 
@@ -75,7 +75,7 @@ Dev-only mode strips the pipeline to minimum: no deep analysis, no planning phas
 **Pipeline in dev-only mode:**
 
 ```
-Phase 0: Init -> Phase 3: Dev (self-contained) -> Phase 5: Test -> Phase 6: Commit -> Phase 7: Report
+Phase 0: Init -> Phase 3: Dev (self-contained) -> Phase 4: Review -> Phase 5: Test -> Phase 6: Commit -> Phase 7: Report
 ```
 
 **What changes in dev-only (Tablo 2  -  Dev-Only modes):**
@@ -86,10 +86,10 @@ Phase 0: Init -> Phase 3: Dev (self-contained) -> Phase 5: Test -> Phase 6: Comm
 | Phase 1 (Analysis)  | Parallel Explore agents                         | **SKIP**                                                                           | **SKIP**                                     | **SKIP**                                      | **SKIP**                                      |
 | Phase 2 (Planning)  | TaskCreate + architecture review + **Plan Approval Gate** (clarification max 2 rounds + approval loop) | **SKIP** (plan gate not applicable  -  fast path) | **SKIP** | **SKIP** | **SKIP** |
 | Phase 3 (Dev)       | Follows Phase 2 plan, TDD cycle (Sonnet)        | **Self-contained** (Opus): agent scans relevant files, implements with TDD, builds | Same as `--dev`                              | Same as `--dev`                               | Same as `--dev`                               |
-| Phase 4 (Review)    | Parallel review + Fable triage (Claude: 2-model / Copilot: 3-model) | **SKIP**                                                       | **SKIP**                                     | **SKIP**                                      | **SKIP**                                      |
+| Phase 4 (Review)    | Parallel review + Fable triage (Claude: 2-model / Copilot: 3-model) | **Same**  -  gates, parallel review, triage; blocking findings return to Phase 3 (cap 3) | **Same**, blocking findings auto-fixed; circuit breaker halts at 3 cycles | **Same as `--dev`**, on the local branch diff | **Same as `--dev autopilot`** |
 | Phase 5 (User Test) | Interactive prompt (ask user to test)           | **Interactive prompt** (ask user to test)                                          | **Skip** (autopilot suppresses interactive prompts) | **Interactive prompt** (same as `--dev`)      | **Skip** (same as `--dev autopilot`)          |
 | Phase 6 (Commit)    | Commit + PR                                     | Same  -  still asks (unless autopilot)                                               | Auto commit + push + PR                      | Same as `--dev`                               | Auto commit + push + PR                       |
-| Phase 7 (Report)    | Full report + channels multi-select             | Simplified  -  no review/analysis sections, BUT **channels menu still pauses** | Channels menu **STILL PAUSES** | Same as `--dev` | Channels menu **STILL PAUSES** |
+| Phase 7 (Report)    | Full report + channels multi-select             | Simplified  -  no analysis section, review section IS present, BUT **channels menu still pauses** | Channels menu **STILL PAUSES** | Same as `--dev` | Channels menu **STILL PAUSES** |
 
 **Phase 3 in dev-only mode (self-contained):**
 
@@ -101,9 +101,9 @@ The **Opus** agent receives the task description (from Jira, GitHub issue, or fr
 
 No separate task breakdown  -  the agent handles scope autonomously.
 
-**State tracking**: `agent-state.json` gets `"onlyDevelop": true`. Phases 1, 2, 4 are marked `"skipped"` instead of `"pending"`. Phase 5 stays `"pending"` and runs interactively unless `autopilot` is also set, in which case it is marked `"skipped"`.
+**State tracking**: `agent-state.json` gets `"onlyDevelop": true`. Phases 1 and 2 are marked `"skipped"` instead of `"pending"`. Phase 4 stays `"pending"` and runs. Phase 5 stays `"pending"` and runs interactively unless `autopilot` is also set, in which case it is marked `"skipped"`.
 
-**Combinable with autopilot**: `--dev autopilot` = fastest path. Init -> Dev -> auto-commit -> auto-PR -> Report (Phase 5 skipped). Zero user interaction (except build failures after 3 retries).
+**Combinable with autopilot**: `--dev autopilot` = fastest path. Init -> Dev -> Review (auto-fix) -> auto-commit -> auto-PR -> Report (Phase 5 skipped). Zero user interaction (except build failures after 3 retries, and review findings that survive 3 rework cycles).
 
 ---
 

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

@@ -8,11 +8,11 @@ Before anything else  -  initialize the visual tracker so the user sees the pipe
 
 ```bash
 TASK_ID="${INPUT_TASK_ID:-pipeline-$(date +%Y%m%d-%H%M%S)}"
-pipeline/scripts/phase-tracker.sh init "$TASK_ID"
+$HOME/.claude/scripts/phase-tracker.sh init "$TASK_ID"
 for p in 0:Init 1:Analysis 2:Planning 3:Dev 4:Review 5:Test 6:Commit 7:Report; do
-  pipeline/scripts/phase-tracker.sh add "${p%%:*}" "${p#*:}"
+  $HOME/.claude/scripts/phase-tracker.sh add "${p%%:*}" "${p#*:}"
 done
-pipeline/scripts/phase-tracker.sh update 0 in_progress
+$HOME/.claude/scripts/phase-tracker.sh update 0 in_progress
 ```
 
 If `INPUT_TASK_ID` isn't known yet (free-text, project not selected), use a placeholder; rename later via `mv` once parsed in Step 1.
@@ -85,22 +85,24 @@ When Step 1 input parsing surfaces a Figma reference (URL, node ID, or "from the
 
 Probe order:
 
-1. **Tier 1 (Figma MCP)**: dispatch a lightweight probe `mcp__claude_ai_Figma__get_metadata(fileKey, nodeId)` for the first referenced frame. Auth failure runs `mcp__claude_ai_Figma__authenticate` + `mcp__claude_ai_Figma__complete_authentication` then retries once. Success → `state.figmaAccess.tier = 1`.
-2. **Tier 2 (Figma REST)**: when Tier 1 fails, resolve the PAT via `~/.claude/lib/credential-store.sh get <logical-key>` where `<logical-key>` = `prefs.global.keychainMapping.figma_pat`. Probe `GET https://api.figma.com/v1/files/{fileKey}/nodes?ids={nodeId}` with header `X-Figma-Token: $TOKEN`. HTTP 200 → `state.figmaAccess.tier = 2`. Token missing / 401 / 403 → fall through.
+1. **Tier 1 (Figma MCP)**: check the host serves `mcp__claude_ai_Figma__*` before probing. Absent → set `state.figmaAccess.tier1Unavailable = "host"` and fall through to Tier 2 with no probe, no re-auth retry, no MCP-token question. Present → probe `get_metadata(fileKey, nodeId)` on the first frame; on auth failure run `authenticate` + `complete_authentication` and retry once, and only a *second* failure raises the recreate-or-continue question. Success → `state.figmaAccess.tier = 1`.
+2. **Tier 2 (Figma REST)**: when Tier 1 fails, resolve the PAT via `~/.claude/lib/credential-store.sh get <logical-key>` where `<logical-key>` = `prefs.global.keychainMapping.figma`. Probe `GET https://api.figma.com/v1/files/{fileKey}/nodes?ids={nodeId}` with header `X-Figma-Token: $TOKEN`. HTTP 200 → `state.figmaAccess.tier = 2`. Token missing / 401 / 403 → fall through.
 3. **Tier 3 (User-attached screenshot)**: when Tiers 1 + 2 both fail, scan the task payload for inline screenshots or attachments. Present → `state.figmaAccess.tier = 3` and `state.figmaAccess.reviewBlocking = true` (Phase 4 enforces this).
 4. **Halt**: all three tiers fail → emit a single AskUserQuestion asking the user how to proceed (provide PAT, paste a screenshot, abort). Never proceed with text-derived guesses.
 
+Record the cause, not just the downshift. `tier1Unavailable = "host"` means the tier never existed here - routine on Copilot and Codex, where the installer registers only `dev-toolkit`. `"auth"` means it existed and the credential failed, which on Claude Code points at a dead `figma_mcp` token worth surfacing in Phase 7. Conflating them costs two wasted MCP round trips and a question the user cannot act on. On those two hosts a mapped `figma` PAT is the primary path, not a fallback.
+
 Log the resolved tier in the agent log:
 
 ```
 → figma access tier: <1|2|3>
 ```
 
-Full chain definition, REST endpoints, URL parsing, canonical-component contract: `pipeline/rules/figma-pipeline.md` "MUST: Figma access - 3-tier fallback chain (BLOCKING, pipeline-wide)". Do not duplicate it here.
+Full chain definition, REST endpoints, URL parsing, canonical-component contract: `$HOME/.claude/rules/figma-pipeline.md` "MUST: Figma access - 3-tier fallback chain (BLOCKING, pipeline-wide)". Do not duplicate it here.
 
 #### Step 0.6 - Update check (advisory, opt-out via `prefs.global.updateCheck.enabled`)
 
-Run `bash pipeline/scripts/update-check.sh` (cached per `updateCheck.ttlHours`, default 24h; 3s-bounded; every failure path silent). Empty output → continue. Output `<local>|<latest>` means a newer version exists:
+Run `bash $HOME/.claude/scripts/update-check.sh` (cached per `updateCheck.ttlHours`, default 24h; 3s-bounded; every failure path silent). Empty output → continue. Output `<local>|<latest>` means a newer version exists:
 
 - **Interactive**: log `→ update available: v<local> -> v<latest>`, ask ONE AskUserQuestion  -  **Update now** (recommended) / **Continue without updating**. On *Update now* (or `updateCheck.autoUpdate: true`, which skips the question): run the `/multi-agent:update` flow, log `→ updated to v<latest>`, continue the run (note in the log: already-loaded phase docs finish this run on the old version; full effect next session). On *Continue*: no re-ask until the TTL expires.
 - **Autopilot**: never ask (zero-interaction contract). Log `→ update available: ... (log-only; run /multi-agent:update)` and continue  -  unless `autoUpdate: true`, then update silently first.
@@ -189,7 +191,7 @@ Classify and fetch external data:
 
 0. **Intent guard (conceptual-vs-edit)**  -  gated by `prefs.global.intentGuard.enabled` (default `true`). Before any project selection, worktree, or Jira prompt, classify the input:
    ```bash
-   INTENT=$(bash pipeline/lib/classify-intent.sh "$DESCRIPTION")
+   INTENT=$(bash $HOME/.claude/lib/classify-intent.sh "$DESCRIPTION")
    ```
    - `question` -> the user asked something conceptual, not a task to implement. Do NOT create a branch/worktree/Jira. Surface a picker (picker-contract): **Answer here** (default) / **Treat as a task**. On "Answer here" (autopilot default for `question`), answer the question directly in chat and end the run cleanly  -  no dev chain, no commits. On "Treat as a task", fall through to step 1 below.
    - `ambiguous` or `task` -> proceed to step 1 (normal task flow). Ambiguous input is treated as a task; the guard never blocks an actionable request.
@@ -526,7 +528,7 @@ Log: `Phase 0 Step 7: taskType = {component|bugfix|feature|refactor|chore}`
 **Gated by `prefs.global.clarifyAmbiguous.enabled`** (default: `false`). When enabled and `state.maturity.status != "blocker"`:
 
 1. Dispatch `agents/task-clarifier.md` (Haiku by default) with the task title + body + acceptance + maturity warnings already on `agent-state`.
-2. The agent returns JSON conforming to `pipeline/schemas/clarify-output.schema.json`  -  `clarityScore` (0-10), `questions[]`, `stopAndAsk`.
+2. The agent returns JSON conforming to `$HOME/.claude/schemas/clarify-output.schema.json`  -  `clarityScore` (0-10), `questions[]`, `stopAndAsk`.
 3. If `clarityScore >= prefs.clarifyAmbiguous.minScoreToProceed` (default 6) or `stopAndAsk == false` → write `state.clarification` (score + rationale, no questions), proceed to Phase 1 silently.
 4. If `stopAndAsk == true`:
 
@@ -543,7 +545,7 @@ Log: `Phase 0 Step 7: taskType = {component|bugfix|feature|refactor|chore}`
 
 **Cost:** ~$0.0025 per Haiku call. The pipeline's other expensive phases (Phase 4 reviewers, Phase 3 Sonnet codegen) far outweigh this  -  the value is avoiding the ~30 min wasted when Phase 3 builds the wrong thing because Phase 0 didn't ask.
 
-**Reference:** see `pipeline/agents/task-clarifier.md` for the full scoring rubric and question-quality rules.
+**Reference:** see `$HOME/.claude/agents/task-clarifier.md` for the full scoring rubric and question-quality rules.
 
 **Why this fits Phase 0 (not a new phase):** clarification doesn't change what code gets written  -  it changes what gets understood before code is written. Phase 0 already collects identity / project / branch / maturity; ambiguity scoring fits naturally as the last contextual gate.
 
@@ -552,7 +554,7 @@ Log: `Phase 0 Step 7: taskType = {component|bugfix|feature|refactor|chore}`
 After each clarifier call:
 
 ```bash
-LOG_METRIC_FORWARD_TO_TRACKER=1 pipeline/scripts/log-metric.sh "$TASK_ID" 0 clarify.call \
+LOG_METRIC_FORWARD_TO_TRACKER=1 $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 0 clarify.call \
   model=haiku score=$SCORE questions=$Q stop_and_ask=$STOP autopilot_mode=$AP \
   duration_ms=$D tokens_in=$TI tokens_out=$TO
 ```