@mmerterden/multi-agent-pipeline 8.6.2 → 10.2.0

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

@@ -6,33 +6,35 @@
 
 ---
 
-## 1. Command Inventory (29 commands)
+## 1. Command Inventory (34 commands)
 
 ```
-autopilot, channels, dev, dev-autopilot, dev-local, dev-local-autopilot,
-help, issue, jira, kill, local, local-autopilot, log, manual-test, purge,
-refactor, resume, review, scan, search, setup, stack, status, sync, test, update
+analysis, analysis-resolve, autopilot, build-optimize, channels, delete, dev,
+dev-autopilot, dev-local, dev-local-autopilot, diff-explain, garbage-collect,
+help, issue, jira, kill, language, local, local-autopilot, log, manual-test,
+prune-logs, purge, refactor, resume, review, scan, search, setup, stack, status,
+sync, test, update
 ```
 
 Categories:
 
 - **Interactive pickers** (single-purpose, not modes): `jira`, `issue`
 - **Full 8-phase modes**: `autopilot`, `local`, `local-autopilot`
-- **Fast modes** (Init → Dev(Opus) → Commit → Report): `dev`, `dev-autopilot`, `dev-local`, `dev-local-autopilot`
-- **Ops commands** (one-shot, no worktree): `status`, `log`, `kill`, `purge`, `resume`, `review`, `channels`, `scan`, `search`
-- **Meta-ops**: `setup`, `sync`, `update`, `help`, `refactor`, `test`, `stack`, `manual-test`
+- **Fast modes** (Init -> Dev(Opus) -> Commit -> Report): `dev`, `dev-autopilot`, `dev-local`, `dev-local-autopilot`
+- **Ops commands** (one-shot, no worktree): `status`, `log`, `kill`, `purge`, `delete`, `resume`, `review`, `analysis`, `analysis-resolve`, `build-optimize`, `channels`, `scan`, `search`, `diff-explain`, `garbage-collect`, `prune-logs`
+- **Meta-ops**: `setup`, `sync`, `update`, `help`, `refactor`, `test`, `stack`, `manual-test`, `language`
 
-> **Inventory drift is a contract violation.** Adding a slash command under `pipeline/commands/multi-agent/` without updating this list + its counterpart Copilot dir (`pipeline/skills/shared/core/multi-agent-<cmd>/`) is a merge blocker. `smoke-commands-skills-parity.sh` enforces command ↔ skill directory parity; `smoke-cross-cli-behavior.sh` enforces behavior parity. This doc is the authoritative command list — bump the count + table together.
+> **Inventory drift is a contract violation.** Adding a slash command under `pipeline/commands/multi-agent/` without updating this list + its counterpart Copilot dir (`pipeline/skills/shared/core/multi-agent-<cmd>/`) is a merge blocker. `smoke-commands-skills-parity.sh` enforces command ↔ skill directory parity; `smoke-cross-cli-behavior.sh` enforces behavior parity. This doc is the authoritative command list  -  bump the count + table together.
 
 ### 1.1 Figma component subphase skills
 
-In addition to the 26 top-level multi-agent commands, the figma-to-component pipeline ships platform-specific skills that multi-agent dispatches from Phase 3 (see `refs/component-dispatch.md`). The structure is **platform-parallel iOS + Android with a shared common pool**:
+In addition to the 34 top-level multi-agent commands, the figma-to-component pipeline ships platform-specific skills that multi-agent dispatches from Phase 3 (see `refs/component-dispatch.md`). The structure is **platform-parallel iOS + Android with a shared common pool**:
 
 | Location | Skill count | Purpose |
 |---|---|---|
 | `pipeline/skills/figma-ios/` | 5 | iOS-only Phase 3 sub-skills (SwiftUI-specific) |
 | `pipeline/skills/figma-android/` | 5 | Android-only Phase 3 sub-skills (Jetpack Compose-specific) |
-| `pipeline/skills/figma-common/` | 27 | Platform-agnostic helpers (iterate / commit / wiki setup / MCP auth / performance harness / etc.) |
+| `pipeline/skills/figma-common/` | 31 | Platform-agnostic helpers (iterate / commit / wiki setup / MCP auth / performance harness / cross-cutting integration adapters / etc.) |
 
 Both Claude Code and Copilot CLI MUST expose every skill with identical argument shape, identical progress-line emission, and identical state writes. Inventory divergence (skill exists on one side but not the other) is a contract violation and blocks merge.
 
@@ -40,13 +42,13 @@ Both Claude Code and Copilot CLI MUST expose every skill with identical argument
 
 | Skill | Scope | iOS path | Android path |
 |---|---|---|---|
-| `figma-to-component` | Orchestrator (3.0–3.8) | `pipeline/skills/figma-ios/figma-to-component/` | `pipeline/skills/figma-android/figma-to-component/` |
+| `figma-to-component` | Orchestrator (3.0-3.8) | `pipeline/skills/figma-ios/figma-to-component/` | `pipeline/skills/figma-android/figma-to-component/` |
 | `figma-component-implement` | 3.4 code gen | `pipeline/skills/figma-ios/figma-component-implement/` | `pipeline/skills/figma-android/figma-component-implement/` |
 | `figma-component-test` | 3.5 tests | `pipeline/skills/figma-ios/figma-component-test/` | `pipeline/skills/figma-android/figma-component-test/` |
 | `figma-component-code-connect` | 3.6 mapping publish | `pipeline/skills/figma-ios/figma-component-code-connect/` | `pipeline/skills/figma-android/figma-component-code-connect/` |
 | `figma-component-wiki` | 3.7 wiki (4 adapters) | `pipeline/skills/figma-ios/figma-component-wiki/` | `pipeline/skills/figma-android/figma-component-wiki/` |
 
-**Common pool** (all 27 skills under `pipeline/skills/figma-common/` — platform-agnostic, dispatched regardless of iOS/Android):
+**Common pool** (all 31 skills under `pipeline/skills/figma-common/`  -  platform-agnostic, dispatched regardless of iOS/Android):
 
 | Skill | Scope |
 |---|---|
@@ -72,13 +74,17 @@ Both Claude Code and Copilot CLI MUST expose every skill with identical argument
 | `figma-skip` | Skip + update Confluence |
 | `figma-form-integration` | Form protocol adapter |
 | `figma-price-integration` | Price protocol adapter |
+| `figma-navigation` | Navigation pattern adapter (native-first / `ui.navigationSystem`) |
+| `figma-overlays` | Overlay pattern adapter (native-first / `ui.overlaySystem`) |
+| `figma-bottom-sheets` | Bottom-sheet/detent adapter (native-first / `ui.sheetSystem`) |
+| `figma-evolve-component` | Reconcile drift + additive extend (human-gated) |
 | `performance-start` | Perf-tracked component start |
 | `performance-swiftui` | Perf-optimized pipeline |
 | `performance-tour` | Batch produce components |
 | `performance-review-next` | Interactive batch review |
 | `performance-iteration-commit-all` | Batch validate + push all |
 
-Total figma skill count: **37** (5 iOS + 5 Android + 27 Common).
+Total figma skill count: **41** (5 iOS + 5 Android + 31 Common).
 
 ### 1.2 Store-compliance skills
 
@@ -138,7 +144,7 @@ Enforced by `smoke-figma-skill-import.sh` (iOS), `smoke-figma-android-parity.sh`
 
 ### 2.3 Project name placeholders
 
-Use these specific names (from the Copilot set) — **never invent new ones**. They correspond to realistic example project types.
+Use these specific names (from the Copilot set)  -  **never invent new ones**. They correspond to realistic example project types.
 
 | Placeholder | Represents |
 |---|---|
@@ -156,7 +162,7 @@ Use these specific names (from the Copilot set) — **never invent new ones**. T
 
 ### 2.5 Deprecated placeholders (DO NOT USE)
 
-Legacy names found during the v3.7 audit — replaced per this contract.
+Legacy names found during the v3.7 audit  -  replaced per this contract.
 
 | Deprecated | Replace with | Reason |
 |---|---|---|
@@ -168,18 +174,18 @@ Legacy names found during the v3.7 audit — replaced per this contract.
 
 ---
 
-## 2.6 Intentional structural divergence — `multi-agent.md` vs `multi-agent/SKILL.md`
+## 2.6 Intentional structural divergence  -  `multi-agent.md` vs `multi-agent/SKILL.md`
 
-The top-level orchestrator has two deliberately different shapes on the two CLIs. This is **not drift** — it reflects a real capability gap between the host CLIs, and auditors must not flag it as a parity violation.
+The top-level orchestrator has two deliberately different shapes on the two CLIs. This is **not drift**  -  it reflects a real capability gap between the host CLIs, and auditors must not flag it as a parity violation.
 
 | Surface | File | Shape | Why |
 |---|---|---|---|
-| Claude Code (colon-form) | `pipeline/commands/multi-agent.md` | ~300 lines — thin dispatcher that routes to `refs/phases/phase-N-*.md` on demand | Claude Code supports lazy-loaded reference files (`@refs/phases/...`), so only the active phase's docs enter the context window. Saves tokens. |
-| Copilot CLI (dash-form) | `pipeline/skills/shared/core/multi-agent/SKILL.md` | ~830 lines — full inline orchestrator with all 8 phase specs embedded | Copilot CLI loads the whole SKILL.md into context once the skill is dispatched; it doesn't have an equivalent of Claude's ref-file loading pattern. Embedding keeps behavior identical without relying on a feature Copilot lacks. |
+| Claude Code (colon-form) | `pipeline/commands/multi-agent.md` | ~300 lines  -  thin dispatcher that routes to `refs/phases/phase-N-*.md` on demand | Claude Code supports lazy-loaded reference files (`@refs/phases/...`), so only the active phase's docs enter the context window. Saves tokens. |
+| Copilot CLI (dash-form) | `pipeline/skills/shared/core/multi-agent/SKILL.md` | ~830 lines  -  full inline orchestrator with all 8 phase specs embedded | Copilot CLI loads the whole SKILL.md into context once the skill is dispatched; it doesn't have an equivalent of Claude's ref-file loading pattern. Embedding keeps behavior identical without relying on a feature Copilot lacks. |
 
 **What must stay identical** (byte-level) across the two files:
 
-- Phase canonical labels (Phase 0–7)
+- Phase canonical labels (Phase 0-7)
 - Input parsing table (Section 5 of this doc)
 - Routing decisions for each input type
 - Placeholder vocabulary (Section 2 of this doc)
@@ -198,7 +204,7 @@ Future changes that break an item in the "stay identical" list must update **bot
 
 Each file has a different frontmatter schema. The sync flow transforms between them:
 
-### 3.1 Claude Code — `commands/multi-agent/{cmd}.md`
+### 3.1 Claude Code  -  `commands/multi-agent/{cmd}.md`
 
 ```yaml
 ---
@@ -207,7 +213,7 @@ allowed-tools: <comma-separated tool list>
 ---
 ```
 
-### 3.2 Copilot CLI — `skills/multi-agent-{cmd}/SKILL.md`
+### 3.2 Copilot CLI  -  `skills/multi-agent-{cmd}/SKILL.md`
 
 ```yaml
 ---
@@ -264,9 +270,9 @@ Given the same user input, both CLIs must produce identical parsed state:
 | Any other string | `input.type = "free-text"`, `input.summary = <string>` |
 
 Modifier flags are orthogonal and compose:
-- `autopilot` — skip confirmations
-- `--dev` — init → dev → commit → report only
-- `--local` — no worktree
+- `autopilot`  -  skip confirmations
+- `--dev`  -  init → dev → commit → report only
+- `--local`  -  no worktree
 - Combinations: `--dev autopilot`, `--dev --local`, etc.
 
 ---
@@ -287,14 +293,14 @@ Modifier flags are orthogonal and compose:
 
 Commands invoked via Copilot CLI may run on Linux or WSL. Claude Code currently macOS-only. Shell code in `pipeline/skills/figma-common/` command files must be portable.
 
-For Keychain I/O the canonical path is **`~/.claude/lib/credential-store.sh`** (or `~/.copilot/lib/credential-store.sh` on Copilot installs). The shell driver detects platform internally and auto-delegates to `keychain.py` (Python helper, macOS / Linux) or PowerShell `CredentialManager` (Windows). Call sites stay platform-agnostic — no per-OS branching needed.
+For Keychain I/O the canonical path is **`~/.claude/lib/credential-store.sh`** (or `~/.copilot/lib/credential-store.sh` on Copilot installs). The shell driver detects platform internally and auto-delegates to `keychain.py` (Python helper, macOS / Linux) or PowerShell `CredentialManager` (Windows). Call sites stay platform-agnostic  -  no per-OS branching needed.
 
 | Purpose | Canonical (cross-platform) | Underlying backend (for reference / debugging) |
 |---|---|---|
 | Keychain read | `~/.claude/lib/credential-store.sh get <key>` | macOS: `security find-generic-password -a "$USER" -s <key> -w` · Linux: `secret-tool lookup account "$USER" service <key>` · Windows: PowerShell `Get-StoredCredential` |
 | Keychain write | `~/.claude/lib/credential-store.sh set <key> <value>` (or `keychain.py set <key> -` to stream the secret over stdin) | macOS: `security add-generic-password -a "$USER" -s <key> -w "$VAL"` · Linux: `secret-tool store --label=<key> account "$USER" service <key>` · Windows: `New-StoredCredential` |
-| Clipboard read | — (still needs a per-platform branch — there is no helper) | `pbpaste` (macOS) · `wl-paste` (Wayland) · `xclip -selection clipboard -o` (X11) |
-| Clipboard clear | — | `pbcopy < /dev/null` (macOS) · `printf '' \| wl-copy` (Wayland) · `printf '' \| xclip -selection clipboard` (X11) |
+| Clipboard read |  -  (still needs a per-platform branch  -  there is no helper) | `pbpaste` (macOS) · `wl-paste` (Wayland) · `xclip -selection clipboard -o` (X11) |
+| Clipboard clear |  -  | `pbcopy < /dev/null` (macOS) · `printf '' \| wl-copy` (Wayland) · `printf '' \| xclip -selection clipboard` (X11) |
 
 For clipboard ops, callers still gate with `if command -v pbpaste >/dev/null; then ...; elif command -v wl-paste ...; elif command -v xclip ...; fi`. A future `pipeline/lib/clipboard.sh` could absorb that pattern; until it exists, keep the inline guard in figma skill bash blocks.
 
@@ -304,12 +310,12 @@ For clipboard ops, callers still gate with `if command -v pbpaste >/dev/null; th
 
 This contract is validated by:
 
-- `smoke-cross-cli-behavior.sh` — asserts all 29 commands behave identically, pulls from Section 2 (placeholder vocab), Section 5 (argument parsing), Section 6 (output formats); also regression-locks the 6-persona agent deployment
-- `smoke-commands-skills-parity.sh` (50 assertions) — enforces colon-form command ↔ dash-form skill directory parity
-- `smoke-compliance-skills.sh` (45 assertions) — enforces store-compliance skill catalog + 4 consumer wiring
-- `smoke-personal-data.sh` — extended in 0.5.5 to treat deprecated placeholders (`{github-username}`, `{your-website}`, `{website-repo}`) as leaks; adds `mmerterden` to public-handle blocklist for generic docs
-- `pre-push-check.sh` — runs both smoke tests before any push that touches `pipeline/skills/figma-common/` commands
-- `sync.md` (Section 2 REPO step) — genericization lookup table MUST match Section 2 of this contract
+- `smoke-cross-cli-behavior.sh`  -  asserts all 34 commands behave identically, pulls from Section 2 (placeholder vocab), Section 5 (argument parsing), Section 6 (output formats); also regression-locks the 6-persona agent deployment
+- `smoke-commands-skills-parity.sh` (50 assertions)  -  enforces colon-form command ↔ dash-form skill directory parity
+- `smoke-compliance-skills.sh` (45 assertions)  -  enforces store-compliance skill catalog + 4 consumer wiring
+- `smoke-personal-data.sh`  -  extended in 0.5.5 to treat deprecated placeholders (`{github-username}`, `{your-website}`, `{website-repo}`) as leaks; adds `mmerterden` to public-handle blocklist for generic docs
+- `pre-push-check.sh`  -  runs both smoke tests before any push that touches `pipeline/skills/figma-common/` commands
+- `sync.md` (Section 2 REPO step)  -  genericization lookup table MUST match Section 2 of this contract
 
 ---
 
@@ -320,7 +326,7 @@ To change anything in this contract:
 1. Amend this file with rationale
 2. Update `sync.md` genericization table (if Section 2 changes)
 3. Update `smoke-cross-cli-behavior.sh` fixtures (if Section 5/6 changes)
-4. Run `smoke-cross-cli-behavior.sh` and `smoke-personal-data.sh` locally — both must pass
+4. Run `smoke-cross-cli-behavior.sh` and `smoke-personal-data.sh` locally  -  both must pass
 5. Announce in pipeline repo `CHANGELOG.md` under `## [Unreleased]` → `### Contract`
 
 No silent changes. No exceptions.

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

@@ -5,15 +5,15 @@
 **Gated by `prefs.global.devCritic.enabled`** (default: `false`). When enabled, after the generator's last edit and BEFORE Phase 4:
 
 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`).
+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}`.
 
-## Loop cap (STRICT) — max 2 iterations
+## Loop cap (STRICT)  -  max 2 iterations
 
 | Round | Behavior |
 |---|---|
-| 1 | Full critic pass — all gates + full checklist |
+| 1 | Full critic pass  -  all gates + full checklist |
 | 2 | Re-check only round-1 failures. No new findings allowed (scope creep prevention) |
 | 3+ | NOT ALLOWED. Critic returns `escalate: true`; orchestrator pauses (interactive) or proceeds to Phase 4 with logged failure (autopilot) |
 
@@ -37,7 +37,7 @@ Introduces ~1× Sonnet call per Dev iteration. On simple bug fixes the cost outw
 
 ## Why this fits orchestrator-workers + evaluator-optimizer hybrid
 
-Phase 4 is parallelization-with-voting — good for *adversarial* perspectives (security, architecture). Phase 3.5 is evaluator-optimizer — good for *deterministic* criteria (build, tests, checklists). Sending failing builds into Phase 4 wastes 2–3 reviewer calls + Opus triage; Phase 3.5 absorbs that cost at one Sonnet call.
+Phase 4 is parallelization-with-voting  -  good for *adversarial* perspectives (security, architecture). Phase 3.5 is evaluator-optimizer  -  good for *deterministic* criteria (build, tests, checklists). Sending failing builds into Phase 4 wastes 2-3 reviewer calls + Opus triage; Phase 3.5 absorbs that cost at one Sonnet call.
 
 ## Reference
 

package/pipeline/commands/multi-agent/refs/features/external-context-injection.md

@@ -24,8 +24,8 @@ One fetcher per type. Each fetcher emits a normalized JSON view that the analysi
 | `fortify` | `~/.claude/lib/fetch-fortify.sh <url>` (already invoked in Phase 0 Step 1b.2 for the legacy `state.fortifyFinding` field; Phase 1 reads that field, Phase 4 reads the full payload for the security gate) | `state.fortifyFinding` |
 | `swagger` | `~/.claude/lib/fetch-swagger.sh <url>` → endpoints[], request/response examples | `state.fetchedContext.swagger[]` |
 | `confluence` | `~/.claude/lib/fetch-confluence.sh <url>` → page body, code blocks, extracted API contracts | `state.fetchedContext.confluence[]` |
-| `figma` | `~/.claude/lib/fetch-figma.sh <url>` (via existing MCP / REST fallback path) when the task is a component; otherwise advisory only | `state.fetchedContext.figma[]` |
-| `generic-doc` | no automatic fetcher — surfaced as advisory; the agent uses WebFetch on demand when the URL turns out to be load-bearing | n/a |
+| `figma` | no standalone fetcher - resolve via the Figma 3-tier chain (Tier 1 MCP tools, Tier 2 `~/.claude/lib/figma-screenshot.sh` + REST) when the task is a component; otherwise advisory only | `state.fetchedContext.figma[]` |
+| `generic-doc` | no automatic fetcher  -  surfaced as advisory; the agent uses WebFetch on demand when the URL turns out to be load-bearing | n/a |
 
 ## Exit code handling
 
@@ -34,7 +34,7 @@ One fetcher per type. Each fetcher emits a normalized JSON view that the analysi
 - `3` (network/auth) → mark as `{status: "failed", reason: "<exit-msg>"}`, continue.
 - `4`/`5`/`6` (config errors) → mark as `{status: "failed", reason: "<exit-msg>"}`, continue and log a setup hint.
 
-Failures are never fatal at Phase 1 — the agent still runs analysis, just without the referenced source.
+Failures are never fatal at Phase 1  -  the agent still runs analysis, just without the referenced source.
 
 ## Prompt injection shape
 
@@ -44,15 +44,15 @@ Added immediately after the knowledge-injection block, before codebase explorati
 ## Referenced External Sources
 
 (when fetchers populated `state.fetchedContext.<type>`)
-### <type> — <url>
+### <type>  -  <url>
 <fetched content, scoped to relevance>
 
 (when fetcher pending)
 ### Pending references
-- <type>: <url> — <one-line metadata>
+- <type>: <url>  -  <one-line metadata>
 ```
 
-The agent treats fetched content as **ground truth** for the referenced source (no re-discovery, no contradiction). Pending references are advisories — the agent decides whether to fetch via WebFetch on demand when the task hinges on that source.
+The agent treats fetched content as **ground truth** for the referenced source (no re-discovery, no contradiction). Pending references are advisories  -  the agent decides whether to fetch via WebFetch on demand when the task hinges on that source.
 
 ## Log line shape
 

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

@@ -0,0 +1,91 @@
+# Model Fallback Contract (v10.1.0)
+
+Personas that declare `preferredModel: opus` route to the top available
+intelligence tier (`claude-opus-4-8`). Opus access can be quota-limited or
+temporarily unavailable. This contract defines when and how the orchestrator
+falls back, deterministically, without ever editing persona files at runtime.
+
+> **Fable retired (2026-06).** Earlier versions routed architect / Reviewer-1 /
+> triage personas to `claude-fable-5` as the top tier. Fable 5 is no longer
+> available, so opus is now the top tier and the persona frontmatter declares
+> `preferredModel: opus`. The `premiumTierUntil` date gate stays in the contract
+> as a generic mechanism for any future plan-window-limited premium tier.
+
+## Tier ladder
+
+```
+opus -> sonnet -> haiku
+```
+
+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
+two tiers happened to be unavailable at once. A dispatch error at the floor is a
+genuine outage  -  it falls through to the normal phase-error path (pause ->
+resume), since there is nothing left to step down to. The mechanism is the existing per-dispatch override:
+set `PHASE_MODEL_OVERRIDE=<fallback>` before dispatch (the orchestrator exports
+`CLAUDE_CODE_SUBAGENT_MODEL` on Claude Code, or passes `--model` on Copilot
+CLI). Persona frontmatter stays the source of truth for the *preferred* model;
+the override is per-dispatch and leaves files untouched.
+
+## Prefs knob
+
+`prefs.global.modelFallback` (template default below; absent knob = `enabled: true`
+with no date gate; an absent `floorModel` defaults to `haiku`, so installs that
+predate this field still get the second downgrade step):
+
+```json
+"modelFallback": {
+  "enabled": true,
+  "premiumTierUntil": null,
+  "fallbackModel": "sonnet",
+  "floorModel": "haiku",
+  "onDispatchError": true
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `enabled` | Master switch. `false` = always dispatch the persona's `preferredModel`, fail loudly on error. |
+| `premiumTierUntil` | ISO date (`YYYY-MM-DD`) or `null`. When set and today is **after** this date, every `preferredModel` dispatch is downgraded to `fallbackModel` unless the user re-confirms (see Date gate). Use when the top tier is included in a plan only until a known date. |
+| `fallbackModel` | Target of the first downgrade step. Default `sonnet` (the next tier below opus). |
+| `floorModel` | Last-resort tier when `fallbackModel` also fails to dispatch. Default `haiku`. Set to the same value as `fallbackModel` (or `null`) to disable the second step and halt after one downgrade. |
+| `onDispatchError` | When `true`, a failed top-tier dispatch (model unavailable / quota / 4xx on model id) retries once on `fallbackModel`, and a failed `fallbackModel` dispatch retries once on `floorModel`, instead of aborting the phase. |
+
+## Triggers (checked in this order)
+
+1. **Date gate (Phase 0 Step 0, once per run).** If `premiumTierUntil` is set and
+   in the past, print one line:
+   `WARN: premium tier plan window ended <date>; preferredModel personas will dispatch on <fallbackModel>. Set prefs.global.modelFallback.premiumTierUntil to null to keep the top tier on usage credits.`
+   Then export the override for every `preferredModel` persona this run. Interactive modes
+   may instead ask once (`Keep top tier (usage credits) / Fall back to <model>`);
+   autopilot never asks - it falls back and logs.
+2. **Dispatch error (per dispatch).** On a model-unavailable / quota error from a
+   top-tier dispatch and `onDispatchError: true`: retry the same persona once with
+   `PHASE_MODEL_OVERRIDE=<fallbackModel>`. If that retry also fails with a dispatch
+   error and `floorModel` is set and differs from `fallbackModel`, retry once more
+   with `PHASE_MODEL_OVERRIDE=<floorModel>`. A failure at the floor (or when no
+   floor is configured) falls through to the normal phase-error path (pause ->
+   resume). Never silent-skip the persona. Each downgrade emits its own
+   `model_fallback` metric line so a two-step degrade is visible in Phase 7.
+3. **Cost budget ceiling (existing gate).** When `cost-budget-check.mjs` exits 11
+   (exceeded) mid-run, the run already pauses per the cost-budget contract; on
+   user-approved continue, `preferredModel` personas downgrade to `fallbackModel` for the
+   remainder of the run.
+
+## Logging
+
+Every fallback emits one `log-metric.sh` line (`metric: model_fallback`,
+attributes: `persona`, `from`, `to`, `trigger: date-gate|dispatch-error|budget`)
+and one agent-log line so Phase 7 reports show which phases ran degraded.
+The cost ledger prices the dispatch at the model actually used (the tracker's
+per-phase `model` field already carries the override).
+
+## Non-goals
+
+- No automatic re-upgrade mid-run (a run that fell back stays fallen back -
+  deterministic over clever).
+- No edits to `pipeline/agents/*.md` at runtime; frontmatter is install-time
+  configuration only.
+- Copilot CLI reviewer set and adapter-platform model pins are out of scope
+  (they pin their own models and do not use this persona ladder).

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

@@ -17,4 +17,4 @@ while next=$(bash "$HOME/.claude/lib/plan-todos.sh" next "$TASK_ID"); [ -n "$nex
 done
 ```
 
-When disabled, the loop still walks `tasks[]` from `planning-output` — `plan-todos.sh` adds visibility (status, notes, deps-respecting `next`) but the underlying TDD contract is unchanged.
+When disabled, the loop still walks `tasks[]` from `planning-output`  -  `plan-todos.sh` adds visibility (status, notes, deps-respecting `next`) but the underlying TDD contract is unchanged.

package/pipeline/commands/multi-agent/refs/features/prior-fix-detection.md

@@ -4,19 +4,19 @@ Before any analysis, check if this issue was already fixed by someone else.
 
 ## Check order
 
-1. **Git commit search** — look for commits referencing this issue ID across all branches:
+1. **Git commit search**  -  look for commits referencing this issue ID across all branches:
 
    ```bash
    git -C $PROJECT_ROOT log --all --oneline --grep="{jiraId}" --since="8 weeks ago"
    ```
 
-2. **Affected file history** — after identifying key files (from issue description keywords), check recent changes:
+2. **Affected file history**  -  after identifying key files (from issue description keywords), check recent changes:
 
    ```bash
    git -C $PROJECT_ROOT log --oneline --since="4 weeks ago" -- {affected_file_paths}
    ```
 
-3. **Jira comments/status** — fetch latest comments to see if someone reported a fix:
+3. **Jira comments/status**  -  fetch latest comments to see if someone reported a fix:
 
    ```bash
    curl -s -H "Authorization: Bearer $JIRA_TOKEN" \
@@ -28,7 +28,7 @@ Before any analysis, check if this issue was already fixed by someone else.
 
 ```
 This issue appears to already have been addressed:
-  {hash} — {message} (by {author}, {date})
+  {hash}  -  {message} (by {author}, {date})
 
 Options:
   1. Verify fix (check if cherry-pick/merge to base branch is needed)

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

@@ -2,7 +2,7 @@
 
 **Gated by `prefs.global.repoMap.enabled`** (default: `false`). Pattern source: <https://aider.chat/docs/repomap.html>.
 
-Before launching Explore agents, run the deterministic repo map renderer and inject the result into each Explore prompt as `${REPO_MAP}`. This gives every explorer a token-budgeted overview of the most-referenced files in the repo — ranked via cross-file declaration references with TF-IDF-style credit splitting so universally-shared helper names (`pass`, `fail`, `init`) don't dominate.
+Before launching Explore agents, run the deterministic repo map renderer and inject the result into each Explore prompt as `${REPO_MAP}`. This gives every explorer a token-budgeted overview of the most-referenced files in the repo  -  ranked via cross-file declaration references with TF-IDF-style credit splitting so universally-shared helper names (`pass`, `fail`, `init`) don't dominate.
 
 ```bash
 REPO_MAP=""
@@ -20,11 +20,11 @@ fi
 
 ## Properties
 
-- **Deterministic** — same worktree state → same map. No embeddings, no network. Sub-second on monorepos.
-- **Advisory** — Explore agents may ignore the map if they have stronger signals (Phase 0 knowledge cache, explicit user context). Never gates the pipeline.
-- **Truncation-safe** — output is capped at `tokenBudget`; the script falls back to "no files extracted within budget" rather than over-spending.
-- **Cost ledger** — emit `phase-1.repo_map_emitted bytes=$(wc -c <<<"$REPO_MAP") budget=$BUDGET` so Phase 7 cost summary can show the size injected.
+- **Deterministic**  -  same worktree state → same map. No embeddings, no network. Sub-second on monorepos.
+- **Advisory**  -  Explore agents may ignore the map if they have stronger signals (Phase 0 knowledge cache, explicit user context). Never gates the pipeline.
+- **Truncation-safe**  -  output is capped at `tokenBudget`; the script falls back to "no files extracted within budget" rather than over-spending.
+- **Cost ledger**  -  emit `phase-1.repo_map_emitted bytes=$(wc -c <<<"$REPO_MAP") budget=$BUDGET` so Phase 7 cost summary can show the size injected.
 
 ## When to enable
 
-Large repos (>200 source files) where Explore otherwise spends multiple rounds finding the right starting files. Skip on small repos — the overhead exceeds the gain.
+Large repos (>200 source files) where Explore otherwise spends multiple rounds finding the right starting files. Skip on small repos  -  the overhead exceeds the gain.

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

@@ -6,14 +6,14 @@
 # Phase 0 (one-time per task): initialize shadow repo + baseline snapshot.
 bash "$HOME/.claude/lib/shadow-git.sh" init "$TASK_ID" "$WORKTREE"
 
-# Per-step (mode: per-todo-step — default): snapshot AFTER each plan-todos
+# Per-step (mode: per-todo-step  -  default): snapshot AFTER each plan-todos
 # step completes successfully, so restore lands on a known-good state.
 bash "$HOME/.claude/lib/plan-todos.sh" complete "$TASK_ID" "$id" "$notes"
 bash "$HOME/.claude/lib/shadow-git.sh" snapshot "$TASK_ID" "$WORKTREE" "step $id: $task"
 
 # Per-mutation (mode: per-tool-call): the orchestrator hooks into every Edit/
 # Write/MultiEdit/Bash-mutation tool call. Higher fidelity, ~50ms × tool-call
-# overhead — recommended only for security-critical paths or experimental
+# overhead  -  recommended only for security-critical paths or experimental
 # refactors where the user values fine-grained rollback over speed.
 
 # Rollback on demand (interactive helper):

package/pipeline/commands/multi-agent/refs/frontend-guide.md

@@ -15,7 +15,7 @@ When the task involves frontend development (React, Next.js, Vue), follow these
 ### React Component Pattern
 
 ```tsx
-// Props interface — explicit, documented
+// Props interface  -  explicit, documented
 interface ButtonProps {
   label: string;
   variant?: "primary" | "secondary" | "ghost";
@@ -25,7 +25,7 @@ interface ButtonProps {
   onClick: () => void;
 }
 
-// Component — single responsibility
+// Component  -  single responsibility
 export function Button({
   label,
   variant = "primary",
@@ -50,10 +50,10 @@ export function Button({
 ### State Management
 
 ```tsx
-// Simple state — useState/useReducer
+// Simple state  -  useState/useReducer
 const [count, setCount] = useState(0);
 
-// Complex state — custom hook
+// Complex state  -  custom hook
 function useAuth() {
   const [user, setUser] = useState<User | null>(null);
   const [loading, setLoading] = useState(true);
@@ -68,7 +68,7 @@ function useAuth() {
   return { user, loading, isAuthenticated: !!user };
 }
 
-// Server state — React Query / SWR
+// Server state  -  React Query / SWR
 const { data, isLoading, error } = useQuery({
   queryKey: ["users", userId],
   queryFn: () => fetchUser(userId),
@@ -103,7 +103,7 @@ Every interactive element MUST have:
 ### Testing
 
 ```tsx
-// Component test — React Testing Library
+// Component test  -  React Testing Library
 test("renders button with label", () => {
   render(<Button label="Submit" onClick={vi.fn()} />);
   expect(screen.getByRole("button", { name: "Submit" })).toBeInTheDocument();
@@ -124,13 +124,13 @@ test("shows loading state", () => {
 
 ### Quality Checklist
 
-1. No magic numbers — design tokens or CSS variables
-2. Semantic HTML — correct elements, not div-soup
-3. Accessibility — ARIA labels, keyboard nav, contrast
-4. Responsive — works on mobile, tablet, desktop
-5. i18n — all strings via translation keys
-6. Error boundaries — graceful error handling
-7. Loading states — skeleton/spinner for async operations
-8. Tests — component + hook tests, no implementation details
-9. Performance — memoization where needed (React.memo, useMemo, useCallback)
-10. Build passes — zero warnings, TypeScript strict mode
+1. No magic numbers  -  design tokens or CSS variables
+2. Semantic HTML  -  correct elements, not div-soup
+3. Accessibility  -  ARIA labels, keyboard nav, contrast
+4. Responsive  -  works on mobile, tablet, desktop
+5. i18n  -  all strings via translation keys
+6. Error boundaries  -  graceful error handling
+7. Loading states  -  skeleton/spinner for async operations
+8. Tests  -  component + hook tests, no implementation details
+9. Performance  -  memoization where needed (React.memo, useMemo, useCallback)
+10. Build passes  -  zero warnings, TypeScript strict mode

package/pipeline/commands/multi-agent/refs/issue-jira-triad.md

@@ -1,6 +1,6 @@
 # Issue → Jira → Wiki Triad
 
-> **TLDR** — When a GitHub issue triggers the pipeline and has no Jira ID, the `autoJiraFromGithubIssue` policy decides whether to auto-create a Jira task (and patch the GitHub issue body with the new Jira link). Phase 7 then posts a humanizer'd wiki-content summary back as a Jira comment, closing the loop. Autopilot treats `ask` as `always`.
+> **TLDR**  -  When a GitHub issue triggers the pipeline and has no Jira ID, the `autoJiraFromGithubIssue` policy decides whether to auto-create a Jira task (and patch the GitHub issue body with the new Jira link). Phase 7 then posts a humanizer'd wiki-content summary back as a Jira comment, closing the loop. Autopilot treats `ask` as `always`.
 
 This doc is referenced from `refs/phases/phase-0-init.md` Step 1 (GitHub issue input) and `refs/phases/phase-7-report.md` Step 2 (component wiki). Keeps the phase docs tight and gives the triad contract a stable home.
 
@@ -9,13 +9,13 @@ This doc is referenced from `refs/phases/phase-0-init.md` Step 1 (GitHub issue i
 ```
 GitHub issue (no Jira link)
      │
-     ▼  Phase 0 Step 1  — auto-create policy
+     ▼  Phase 0 Step 1   -  auto-create policy
 Jira issue (new, linked both ways)
      │
-     ▼  Phase 3 — component implementation
-wiki markdown in pipeline/skills/…
+     ▼  Phase 3  -  component implementation
+wiki markdown in pipeline/skills/...
      │
-     ▼  Phase 7 Report Step 2 — wiki capture + Jira comment post
+     ▼  Phase 7 Report Step 2  -  wiki capture + Jira comment post
 Jira comment (humanizer'd component summary)
 ```
 
@@ -23,16 +23,16 @@ Jira comment (humanizer'd component summary)
 
 Inputs:
 
-- `state.inputType === "github-issue-url"` or `"github-issue-number"` — not `jira-*`, not `free-text`.
+- `state.inputType === "github-issue-url"` or `"github-issue-number"`  -  not `jira-*`, not `free-text`.
 - `state.jiraId` is null (no `{JIRA_KEY}-XXXXX` found in the issue body).
-- `prefs.global.autoJiraFromGithubIssue` — enum `ask` | `always` | `never`.
-- `state.mode` — `autopilot` overrides `ask` to `always` (no interactive fallback when user isn't watching).
+- `prefs.global.autoJiraFromGithubIssue`  -  enum `ask` | `always` | `never`.
+- `state.mode`  -  `autopilot` overrides `ask` to `always` (no interactive fallback when user isn't watching).
 
 Decision table:
 
 | preference | interactive | autopilot |
 |---|---|---|
-| `ask`    | prompt `Create Jira issue for this? (y/n)` | treat as `always` |
+| `ask`    | native `AskUserQuestion` picker (`question` "Create a Jira issue for this?" in `outputLanguage`, `header` "Jira", `options` `{ label: "Create", description: "Create + link a Jira issue for this GitHub issue" }`, `{ label: "Skip", description: "Continue without a Jira issue" }`); **Create** → Create path, **Skip** → skip + log | treat as `always` |
 | `always` | silently create + log | silently create + log |
 | `never`  | skip + log | skip + log |
 
@@ -43,9 +43,9 @@ Decision table:
 3. Derive Jira fields from the GitHub issue:
    - `summary` ← GitHub issue title (truncate to 255 chars).
    - `description` ← GitHub issue body, prefixed with `h3. From GitHub\n[GH{issueNo}|{url}]\n\n`.
-   - `issueType` — infer from labels: `bug` → Bug, `enhancement` → Story, default Task.
-   - `project` — `figmaConfig.jira.projectKey`, or `prefs.global.defaultJiraKey`, or prompt (cached after first use).
-   - `priority` — derive from labels if present (`priority:high` → High, etc.); else leave unset (Jira default).
+   - `issueType`  -  infer from labels: `bug` → Bug, `enhancement` → Story, default Task.
+   - `project`  -  `figmaConfig.jira.projectKey`, or `prefs.global.defaultJiraKey`, or prompt (cached after first use).
+   - `priority`  -  derive from labels if present (`priority:high` → High, etc.); else leave unset (Jira default).
 4. `POST {jira.baseUrl}/rest/api/2/issue` with the derived payload.
 5. On success: store new Jira key in `state.jiraId`. Emit `→ created Jira {newKey}`.
 6. Patch the GitHub issue body: append a line `Jira: [{newKey}]({jira.baseUrl}/browse/{newKey})` so the bidirectional link is visible on GitHub without refetching the pipeline state.
@@ -65,9 +65,9 @@ Runs after Phase 7 Report Step 2 (wiki capture) has produced markdown and only w
 Flow:
 
 1. Emit `→ posting wiki summary to Jira {jiraId}`.
-2. Read the first N lines of the primary wiki markdown file (the component's overview page — one of `writtenPaths[0]`).
-3. Render as Jira comment: title line (`h3. Component docs — {componentName}`) + an overview paragraph + a link to the full page (wiki URL, if the adapter returned `pushedRemote`).
-4. **Run through the humanizer skill** — same policy as Step 4 Confluence: user-facing content must read naturally.
+2. Read the first N lines of the primary wiki markdown file (the component's overview page  -  one of `writtenPaths[0]`).
+3. Render as Jira comment: title line (`h3. Component docs  -  {componentName}`) + an overview paragraph + a link to the full page (wiki URL, if the adapter returned `pushedRemote`).
+4. **Run through the humanizer skill**  -  same policy as Step 4 Confluence: user-facing content must read naturally.
 5. `POST {jira.baseUrl}/rest/api/2/issue/{jiraId}/comment`.
 6. Log: `Phase 7: wiki summary posted to Jira {jiraId}`.
 
@@ -78,7 +78,7 @@ On failure: log + continue. Wiki is already written; the Jira comment is an augm
 Autopilot forces:
 
 - `autoJiraFromGithubIssue: ask` → `always` (no user to prompt).
-- `wikiToJiraComment` obeys its preference (default `true`) — no prompting either way.
+- `wikiToJiraComment` obeys its preference (default `true`)  -  no prompting either way.
 
 Rationale: autopilot is explicit consent for side-effect creation; muting Jira activity would defeat the purpose.
 
@@ -88,8 +88,8 @@ Rationale: autopilot is explicit consent for side-effect creation; muting Jira a
 |---|---|---|---|
 | `prefs.global.autoJiraFromGithubIssue` | enum ask/always/never | `ask` | Phase 0 auto-create decision |
 | `prefs.global.wikiToJiraComment` | bool | `true` | Phase 7 wiki → Jira comment post |
-| `figmaConfig.jira.projectKey` | string | — | Target project for new issues (falls back to `prefs.global.defaultJiraKey`) |
-| `prefs.global.keychainMapping.jira` | string | — | Jira token keychain lookup |
+| `figmaConfig.jira.projectKey` | string |  -  | Target project for new issues (falls back to `prefs.global.defaultJiraKey`) |
+| `prefs.global.keychainMapping.jira` | string |  -  | Jira token keychain lookup |
 
 ## Cross-CLI parity