@mmerterden/multi-agent-pipeline 10.0.6 → 10.2.0

package/CHANGELOG.md

@@ -14,6 +14,123 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ---
 
+## [10.2.0] - 2026-07-02
+
+Generic SwiftUI interaction coverage for the figma-to-swiftui pipeline. Three
+new cross-cutting integration skills (navigation, overlays, bottom sheets) plus
+a reconcile-and-extend workflow, all native-SwiftUI-first with an optional
+per-project `ui.*` config hook so the same capabilities work on any SwiftUI
+codebase  -  no app-specific coupling. Phase 3D dev detection and Phase 4 review
+both consume them.
+
+### Added
+
+- **`figma-navigation` / `figma-overlays` / `figma-bottom-sheets` skills**
+  (`pipeline/skills/figma-common/`). Cross-cutting integration adapters, same
+  shape as `figma-form-integration` / `figma-price-integration`: a component
+  emits a typed intent / takes a caller-owned binding and never routes, presents
+  an app-level overlay, or owns the sheet surface. Native SwiftUI by default
+  (`NavigationStack`/`navigationDestination`, `.alert`/`.confirmationDialog`/
+  `.sheet(item:)` + ref-counted loading, `.sheet`+`presentationDetents`); a
+  project's own system is used only when `figma-config` declares
+  `ui.navigationSystem` / `ui.overlaySystem` / `ui.sheetSystem`.
+- **`figma-evolve-component` workflow.** Reconcile an already-implemented
+  component against current Figma (drift-heal) + additively extend it for a
+  need, behind a mandatory human gate; distinct from `figma-to-swiftui`
+  (build new), `figma-mend` (rebuild), and `figma-fix` (review bug).
+- **`animated-gradient-border` UI pattern** (`figma-ui-patterns/patterns/`)  -
+  self-contained native-SwiftUI recipe (angular-gradient stroke + Reduce-Motion
+  gate), no external dependency.
+- **`ui` block in `figma-project-config.schema.json`**  -  optional
+  `navigationSystem` / `overlaySystem` / `sheetSystem` (`mode: native | custom`
+  + type names). Absent → native SwiftUI.
+
+### Changed
+
+- **Phase 3D pattern detection (§1.5.4).** Detects navigation / overlay /
+  bottom-sheet affordances and dispatches the matching integration skill
+  (gate-driven, per `orchestrator-discipline` Rule 4).
+- **Phase 4B view (§4.7.4)** references the new skills; **`figma-to-swiftui`
+  accessibility reference** enriched with the VoiceOver-minimalism decision tree
+  (annotate only what a vision-impaired user needs; state-necessity tree;
+  anti-patterns).
+- **Phase 4 review** (`phase-4-review.md`): Step 1.5 gains iOS interaction +
+  accessibility-minimalism checks (self-routing/self-presenting components,
+  `AnyView` through an overlay center, un-ref-counted loading, magic-number
+  detents, a11y over-annotation), and the new skills are injected as reviewer
+  reference context for SwiftUI UI diffs. Generic across SwiftUI projects.
+- **`figma-to-component` SKILL.md** documents the complementary integration
+  skills; **`orchestrator-discipline` Rule 4** and **`cross-cli-contract`**
+  updated (figma-common 27 → 31, total figma skills 37 → 41).
+
+## [10.1.0] - 2026-06-25
+
+Fable 5 retired (no longer available): the pipeline's top intelligence tier is
+now Opus. Plus per-task cost visibility on by default, four Phase 1/4 token
+economy measures, and a stability pass that bounds dispatch timeouts, heals
+stale worktrees, and validates state before resume.
+
+### Changed
+
+- **Fable 5 -> Opus across all routing.** The five heavy agent personas
+  (`code-reviewer`, `security-auditor`, `ios/android/backend-architect`) now
+  declare `preferredModel: opus` instead of `fable`; Phase 1 Analysis, Phase 2
+  Planning, Phase 4 Reviewer 1 + triage, and the `--dev` dev model all run on
+  Opus. This also resolves the prior CLAUDE.md-vs-phase-doc inconsistency
+  (CLAUDE.md already documented Opus for these stages).
+- **Model fallback ladder is now `opus -> sonnet`** (was `fable -> opus ->
+  sonnet`). `modelFallback.fallbackModel` default is `sonnet`. The
+  `premiumTierUntil` date gate is kept as a generic mechanism for any future
+  plan-window-limited premium tier. `model-fallback.md` bumped to v10.1.0 and
+  `smoke-model-fallback.sh` updated to assert the new ladder + Opus personas.
+- **`costBudget` defaults on in warn mode.** The proactive per-task cost ceiling
+  (`cost-budget-check.mjs`) now ships enabled (`onExceed: "warn"`, `maxUsd: 5`,
+  priced at the conservative opus rate) so runaway spend is visible live. Warn
+  never halts; set `onExceed: "halt"` to make the ceiling blocking, or
+  `enabled: false` to opt out.
+
+### Added
+
+- **Phase 4 context economy (Step 1.9).** Reviewer and triage prompts now build
+  a byte-identical shared prefix (full diff + analysis summary + plan) so, when
+  the host supports prompt caching, reviewer 2/3 and triage read it at the
+  discounted cache-read rate instead of re-billing the diff as fresh input.
+- **Single-repo diff cap.** Diffs exceeding the Phase 4 token allowance are
+  truncated with a `file://...review-diff.txt` pointer and a
+  `review.diff_truncated` metric - the single-repo equivalent of the existing
+  multi-repo 80% cap.
+- **Phase 1 light Explore tier.** Small `bugfix`/`chore` tasks (single named
+  file or a referenced crash/stack frame) scan only the named area + direct
+  callers instead of a full-repo "very thorough" pass.
+- **Triage prior-art injection cap.** Merged prior-art is capped at the 8
+  highest-similarity hits so a many-finding review does not inflate the triage
+  prompt.
+
+### Fixed
+
+- **Parallel dispatch timeouts.** Phase 1 Explore and Phase 4 reviewer dispatches
+  are now bounded by a wall-clock budget (`EXPLORE_TIMEOUT_SECONDS` /
+  `REVIEWER_TIMEOUT_SECONDS`, default 180). A stalled or dead agent is dropped and
+  the phase proceeds with the dispatches that returned, instead of hanging
+  indefinitely waiting on the slowest one.
+- **Worktree stale-lock heal.** Phase 0 runs `worktree prune` + `unlock` before
+  every `worktree add`, ending the `already exists` wedge a run killed mid-add
+  left behind.
+- **Resume safety validation.** New `validate-state.mjs` checks `agent-state.json`
+  is safe to re-enter (parseable + `currentPhase` in range + well-formed
+  `phases`, tolerant of legacy shapes) before resume picks a phase, instead of
+  silently re-entering on stale state.
+- **Model fallback floor.** The ladder now walks `opus -> sonnet -> haiku`
+  (`floorModel`, absent defaults to `haiku`) so two simultaneously-unavailable
+  tiers degrade instead of hard-halting the phase.
+- **Visible halts + lock tuning.** Hard halts surface to stderr + tracker even in
+  autopilot (no more silent stops); `write-state` lock acquire window is
+  env-tunable (default 15s) with the stale window cut 60s -> 30s; external curls
+  gain `--connect-timeout 5`; `phase-tracker` gains a concurrent-safe
+  `MULTI_AGENT_STRICT_TASK_ID` mode; the retired `fable` price entry is removed.
+
+---
+
 ## [10.0.6] - 2026-06-23
 
 Release-plumbing patch so the stable line reaches npmjs. No behavior change to

package/README.md

@@ -154,6 +154,7 @@ slows down the install.
 
 ## What's new
 
+- **v10.1.0** (2026-06-20) - Fable 5 retired (no longer available): the five heavy agent personas plus Phase 1 / Phase 2 / Phase 4 reviewer-1 + triage and `--dev` fast mode now route to Opus (top available tier); fallback ladder is `opus -> sonnet`. Per-task cost guard (`costBudget`) now defaults on in warn mode. Token economy: Phase 4 shared cache prefix + single-repo diff cap, Phase 1 light Explore tier for small bugfixes, triage prior-art injection capped.
 - **v10.0.0** (2026-06-12) - quality major driven by a 10-category self-audit + competitive sweep: validator gates wired into phases 1/2/4 (fails closed), Phase 3 code-simplifier diff-shrink pass, Phase 4 lesson memory loop, Phase 2 cross-artifact consistency gate, skill frontmatter linter (repaired 31 SKILL.md), installer `--dry-run` + unknown-flag rejection, timeout-guarded smoke runner, adapter family deduplicated (~490 lines), CI hardening (blocking lint, npm audit, shellcheck), tag-driven npm release automation, CHANGELOG split (310KB -> 40KB).
 - **v9.10.2** (2026-06-11) - live per-phase token narration on completion; tracker mandates per-phase cost lines in the final report.
 - **v9.10.1** (2026-06-11) - Claude Fable 5 fallback contract: date gate, dispatch retry, and budget guard when the Fable tier is unavailable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "10.0.6",
+  "version": "10.2.0",
   "description": "8-phase AI development pipeline with full orchestration on Claude Code, Copilot CLI, Cursor, Antigravity, and VS Code Copilot Chat. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Opus triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",

package/pipeline/agents/android-architect.md

@@ -1,8 +1,8 @@
 ---
 description: Android architect  -  evaluates design decisions, patterns, and module structure
-model: fable
-preferredModel: fable
-modelRationale: "Architecture decisions across Gradle modules, Compose stability, Hilt graphs, and migration paths run on fable (top tier, above opus). No downgrade recommended."
+model: opus
+preferredModel: opus
+modelRationale: "Architecture decisions across Gradle modules, Compose stability, Hilt graphs, and migration paths run on opus (top available tier). No downgrade recommended."
 ---
 
 You are a senior Android architect with deep expertise in large-scale modular Android applications.

package/pipeline/agents/backend-architect.md

@@ -1,8 +1,8 @@
 ---
 description: Backend architect  -  evaluates API design, data modeling, and system architecture
-model: fable
-preferredModel: fable
-modelRationale: "API design + migration safety + scaling analysis are top-tier concerns; fable improves reasoning on concurrent-write / rollback edge cases in database migration reviews."
+model: opus
+preferredModel: opus
+modelRationale: "API design + migration safety + scaling analysis are top-tier concerns; opus is the top available tier and handles concurrent-write / rollback edge cases in database migration reviews."
 ---
 
 You are a senior backend architect with expertise in API design, distributed systems, and data modeling.

package/pipeline/agents/code-reviewer.md

@@ -1,8 +1,8 @@
 ---
-description: "Code reviewer for multi-agent Phase 4  -  security, architecture, quality, performance. Default model is fable; Phase 4 orchestrator overrides to sonnet for Reviewer 3."
-model: fable
-preferredModel: fable
-modelRationale: "Reviewer 1 tier  -  deep security + architecture review runs on fable (top intelligence tier, above opus). Phase 4 orchestrator overrides to sonnet for Reviewer 3 (quality/correctness focus) via CLAUDE_CODE_SUBAGENT_MODEL before dispatch. Copilot CLI adds Reviewer 2 on gpt-5.4 for cross-model diversity."
+description: "Code reviewer for multi-agent Phase 4  -  security, architecture, quality, performance. Default model is opus; Phase 4 orchestrator overrides to sonnet for Reviewer 3."
+model: opus
+preferredModel: opus
+modelRationale: "Reviewer 1 tier  -  deep security + architecture review runs on opus (top available intelligence tier). Phase 4 orchestrator overrides to sonnet for Reviewer 3 (quality/correctness focus) via CLAUDE_CODE_SUBAGENT_MODEL before dispatch. Copilot CLI adds Reviewer 2 on gpt-5.4 for cross-model diversity."
 ---
 
 # Code Reviewer Agent

package/pipeline/agents/ios-architect.md

@@ -1,8 +1,8 @@
 ---
 description: iOS architect  -  evaluates design decisions, patterns, and module structure
-model: fable
-preferredModel: fable
-modelRationale: "Architecture decisions require deep reasoning across modules, protocols, and migration paths  -  fable is the top intelligence tier. No downgrade recommended; if cost is a concern, skip the architect consultation entirely."
+model: opus
+preferredModel: opus
+modelRationale: "Architecture decisions require deep reasoning across modules, protocols, and migration paths  -  opus is the top available intelligence tier. No downgrade recommended; if cost is a concern, skip the architect consultation entirely."
 ---
 
 You are a senior iOS architect with deep expertise in large-scale modular iOS applications.

package/pipeline/agents/security-auditor.md

@@ -1,8 +1,8 @@
 ---
 description: Security specialist  -  analyzes code for vulnerabilities and compliance issues
-model: fable
-preferredModel: fable
-modelRationale: "Security reasoning + compliance catalog cross-reference (Apple ITMS, Google Play policy, OWASP)  -  false negatives are expensive; fable (top tier, above opus) further reduces miss rate on subtle vulnerabilities (auth-flow gaps, cert-pinning bypass, sensitive-data leaks)."
+model: opus
+preferredModel: opus
+modelRationale: "Security reasoning + compliance catalog cross-reference (Apple ITMS, Google Play policy, OWASP)  -  false negatives are expensive; opus (top available tier) keeps the miss rate low on subtle vulnerabilities (auth-flow gaps, cert-pinning bypass, sensitive-data leaks)."
 ---
 
 You are a mobile security auditor specializing in application security.

package/pipeline/commands/multi-agent/dev-autopilot.md

@@ -1,5 +1,5 @@
 ---
-description: "Fastest mode: Dev (Fable) plus Autopilot. Init → Dev → Commit → Report with zero confirmations."
+description: "Fastest mode: Dev (Opus) plus Autopilot. Init → Dev → Commit → Report with zero confirmations."
 ---
 
 # multi-agent dev autopilot  -  Fastest Path
@@ -19,7 +19,7 @@ Dev mode + Autopilot combined: a 4-phase pipeline with no confirmations, end-to-
 
 ```
 Phase 0: Init       → project detection, worktree, branch, identity
-Phase 3: Dev        → direct development on Fable
+Phase 3: Dev        → direct development on Opus
 Phase 6: Commit     → auto commit + push + PR (no confirmations)
 Phase 7: Report     → short terminal summary
 ```
@@ -47,7 +47,7 @@ Phase 7: Report     → short terminal summary
 | | Full | Dev | Autopilot | **Dev+Autopilot** |
 |--|------|-----|-----------|-------------------|
 | Phases | 8 | 4 | 8 | **4** |
-| Model | Sonnet | Fable | Sonnet | **Fable** |
+| Model | Sonnet | Opus | Sonnet | **Opus** |
 | Plan Approval Gate | ✅ (clarification + approval) | ❌ | ❌ | **❌** |
 | Confirmations (test / commit / PR) | Yes | Yes | No | **No** |
 | Review | Parallel + triage (CLI-aware) | None | Parallel + triage (CLI-aware) | **None** |

package/pipeline/commands/multi-agent/dev-local-autopilot.md

@@ -1,5 +1,5 @@
 ---
-description: "Fastest + local  -  Dev(Fable) + autopilot, no worktree, zero interaction."
+description: "Fastest + local  -  Dev(Opus) + autopilot, no worktree, zero interaction."
 allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep, TaskCreate, TaskUpdate, TaskList, TaskGet, WebFetch, Skill
 ---
 
@@ -13,7 +13,7 @@ The triple `--dev` + `--local` + `autopilot`  -  the fastest form available. Zer
 
 ```
 Phase 0: Init       → project detection, branch check, state (NO worktree, NO confirmation)
-Phase 3: Dev        → direct development on Fable (automatic)
+Phase 3: Dev        → direct development on Opus (automatic)
 Phase 6: Commit     → auto commit + push + PR (no local checkout prompt)
 Phase 7: Report     → Jira / Wiki + log + knowledge/memory
 ```

package/pipeline/commands/multi-agent/dev-local.md

@@ -1,5 +1,5 @@
 ---
-description: "Fast mode + local  -  Init → Dev(Fable) → Commit → Report, no worktree."
+description: "Fast mode + local  -  Init → Dev(Opus) → Commit → Report, no worktree."
 allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep, TaskCreate, TaskUpdate, TaskList, TaskGet, AskUserQuestion, WebFetch, Skill
 ---
 
@@ -13,7 +13,7 @@ Dedicated form of the `--dev` + `--local` combination. A 4-phase fast pipeline (
 
 ```
 Phase 0: Init       → project detection, branch check, state (NO worktree)
-Phase 3: Dev        → direct development on Fable (Analysis + Planning + Review skipped)
+Phase 3: Dev        → direct development on Opus (Analysis + Planning + Review skipped)
 Phase 6: Commit     → pre-commit checkout prompt, commit + push + PR
 Phase 7: Report     → Jira / Wiki + log + knowledge/memory
 ```
@@ -96,7 +96,7 @@ Do NOT call TaskCreate on these CLIs  -  the tool does not exist and the call fa
 Routes to the orchestrator with `--dev --local` flags. Apply the `$HOME/.claude/commands/multi-agent/dev.md` pipeline in local mode:
 - Phase 0: skip worktree creation, continue on the current branch
 - Phase 1 (Analysis), Phase 2 (Planning + Approval Gate), Phase 4 (Review), and Phase 5 (User Test) are skipped (`--dev` + local/autopilot drop the interactive test gate)
-- Phase 3: develop on Fable (instead of the Sonnet TDD cycle)
+- Phase 3: develop on Opus (instead of the Sonnet TDD cycle)
 - Phase 6: commit + push + PR (the local checkout prompt is natural in local mode  -  you're already there; no worktree removal needed, code is already in `$PROJECT_ROOT`)
 - Phase 7: report + channels (same as `--dev`)
 

package/pipeline/commands/multi-agent/dev.md

@@ -1,5 +1,5 @@
 ---
-description: "Fast development mode: Init → Dev (Fable) → Test → Commit → Report. Analysis, planning, and review phases are skipped."
+description: "Fast development mode: Init → Dev (Opus) → Test → Commit → Report. Analysis, planning, and review phases are skipped."
 ---
 
 # multi-agent dev  -  Fast Development Mode (--dev)
@@ -20,7 +20,7 @@ description: "Fast development mode: Init → Dev (Fable) → Test → Commit
 >
 > Full contract: `refs/rules.md` "Language Application".
 
-A 5-phase fast pipeline: Init → Dev → Test → Commit → Report. Development runs on the Fable model (top intelligence tier).
+A 5-phase fast pipeline: Init → Dev → Test → Commit → Report. Development runs on the Opus model (top intelligence tier).
 
 ## When to use it
 - Small changes, bug fixes, quick features
@@ -31,17 +31,17 @@ A 5-phase fast pipeline: Init → Dev → Test → Commit → Report. Developmen
 
 ```
 Phase 0: Init       → project detection, worktree, branch, identity (full picker)
-Phase 3: Dev        → direct development on Fable (TDD optional)
+Phase 3: Dev        → direct development on Opus (TDD optional)
 Phase 5: Test       → User Test (interactive simulator)
 Phase 6: Commit     → commit + push + PR
 Phase 7: Report     → channels (Jira / Confluence / PR / Wiki)
 ```
 
-`--dev` skips Phase 1 (Analysis), Phase 2 (Planning + Approval Gate), and Phase 4 (Review). Phase 3 Dev runs on **Fable**. Phase 0 picker, Phase 5 test, Phase 6 commit, and Phase 7 channels are identical to the full pipeline.
+`--dev` skips Phase 1 (Analysis), Phase 2 (Planning + Approval Gate), and Phase 4 (Review). Phase 3 Dev runs on **Opus**. Phase 0 picker, Phase 5 test, Phase 6 commit, and Phase 7 channels are identical to the full pipeline.
 
 ## What `--dev` does NOT skip (required)
 
-`--dev` skips the LLM-heavy phases (Phase 1 Analysis, Phase 2 Planning + Approval, Phase 4 Review) and runs Phase 3 Dev on Fable. Phase 0 (Init), Phase 5 (Test), Phase 6 (Commit), and Phase 7 (Report + channels) are byte-for-byte the same as the full pipeline. User-facing prompts **always run**  -  they exist for audit, not speed.
+`--dev` skips the LLM-heavy phases (Phase 1 Analysis, Phase 2 Planning + Approval, Phase 4 Review) and runs Phase 3 Dev on Opus. Phase 0 (Init), Phase 5 (Test), Phase 6 (Commit), and Phase 7 (Report + channels) are byte-for-byte the same as the full pipeline. User-facing prompts **always run**  -  they exist for audit, not speed.
 
 ### Required user prompts (Phase 0)
 
@@ -127,11 +127,11 @@ No "pre-existing" claim is allowed without a baseline reproduce.
 
 ## Skipped phases (definitive list)
 
-- Phase 1 (Analysis → Fable deep-think + explore agents)
+- Phase 1 (Analysis → Opus deep-think + explore agents)
 - Phase 2 → Plan Approval Gate including clarification + approval
 - Phase 4 (Review → parallel + triage)
 
-Phase 0 (Init full picker), Phase 5 (User Test), Phase 6 (Commit), and Phase 7 (Report + channels) run exactly as in the full pipeline. Phase 3 Dev model is **Fable**.
+Phase 0 (Init full picker), Phase 5 (User Test), Phase 6 (Commit), and Phase 7 (Report + channels) run exactly as in the full pipeline. Phase 3 Dev model is **Opus**.
 
 ## Steps
 
@@ -140,7 +140,7 @@ Phase 0 (Init full picker), Phase 5 (User Test), Phase 6 (Commit), and Phase 7 (
 2. **Phase 0: Init**  -  same as the full pipeline (full picker: account, project, dev-context, base branch, branch name, maturity check, identity, worktree, state)
    - Add `"mode": "dev"` to `agent-state.json`
 
-3. **Phase 3: Dev**  -  on the **Fable model**, with `taskType`-based dispatch:
+3. **Phase 3: Dev**  -  on the **Opus model**, with `taskType`-based dispatch:
 
    **3a. If `state.taskType === "component"` (figma URL detected at Phase 0 Step 7):**
    - Run the **full figma 17-substep orchestrator**  -  the same one the full pipeline uses. `--dev` does NOT shrink this. Sub-phases:
@@ -172,7 +172,7 @@ Phase 0 (Init full picker), Phase 5 (User Test), Phase 6 (Commit), and Phase 7 (
 | Aspect | Full (`/multi-agent`) | Dev (`/multi-agent:dev`) |
 |---------|---------------------|------------------------|
 | Phases | 8 (0-7) | 5 (0, 3, 5, 6, 7)  -  1, 2, 4 skipped |
-| Phase 3 Dev model | Sonnet | **Fable** |
+| Phase 3 Dev model | Sonnet | **Opus** |
 | Phase 1 Analysis (explore agents) | ✅ | ❌ |
 | Phase 2 Planning + Approval Gate | ✅ | ❌ |
 | Phase 4 Review (parallel + triage) | ✅ | ❌ |

package/pipeline/commands/multi-agent/help.md

@@ -52,13 +52,13 @@ How It Works (Phase 0  -  Interactive Flow):
 Pipeline (after Phase 0)  -  shown as visual cards in terminal:
 
   Phase 0:   Init       -> The 8 steps above
-  Phase 1:   Analysis   -> Stack detection + codebase scan (Fable)
+  Phase 1:   Analysis   -> Stack detection + codebase scan (Opus)
   Phase 2:   Planning   -> Task breakdown + architecture review + Plan Approval Gate
                           (clarification max 2 rounds + approval loop  -  normal mode only;
                            skipped for --dev, autopilot, --dev autopilot)
   Phase 3:   Dev        -> TDD: test -> code -> build (Sonnet) + build queue
-  Phase 4:   Review     -> Deterministic gates + parallel AI review + Fable triage
-                          (Claude Code: Fable + Sonnet · Copilot CLI: GPT-5.4 + Opus + Sonnet)
+  Phase 4:   Review     -> Deterministic gates + parallel AI review + Opus triage
+                          (Claude Code: Opus + Sonnet · Copilot CLI: GPT-5.4 + Opus + Sonnet)
   Phase 5:   Test       -> Optional: switch to branch, test in Xcode
                           (runs in dev + full; skipped in every autopilot and local variant)
   Phase 6:   Commit     -> Commit -> push -> PR + issue body update (never auto-closes)
@@ -73,8 +73,8 @@ Pipeline (after Phase 0)  -  shown as visual cards in terminal:
 
 Modes:
 
-  (normal)             Full 8 phases, Sonnet dev, Plan Approval Gate active, parallel review + Fable triage
-  --dev                Fast: Init -> Dev(Fable) -> Commit -> Report (no plan gate)
+  (normal)             Full 8 phases, Sonnet dev, Plan Approval Gate active, parallel review + Opus triage
+  --dev                Fast: Init -> Dev(Opus) -> Commit -> Report (no plan gate)
   --local              No worktree  -  works directly on local branch
   autopilot            Skip all confirmations INCLUDING plan gate, auto commit/PR
                        (EXCEPT Phase 7 channels menu  -  always pauses)
@@ -259,13 +259,13 @@ Nasıl Çalışır (Phase 0  -  İnteraktif Akış):
 Pipeline (Phase 0'dan sonra)  -  terminalde görsel kart olarak görünür:
 
   Phase 0:   Init       -> Yukarıdaki 8 adım
-  Phase 1:   Analysis   -> Stack tespiti + codebase taraması (Fable)
+  Phase 1:   Analysis   -> Stack tespiti + codebase taraması (Opus)
   Phase 2:   Planning   -> Task kırılımı + mimari inceleme + Plan Onay Kapısı
                           (clarification max 2 tur + onay döngüsü  -  sadece normal mode;
                            --dev, autopilot, --dev autopilot'ta skip)
   Phase 3:   Dev        -> TDD: test -> kod -> build (Sonnet) + build queue
-  Phase 4:   Review     -> Deterministik kapılar + paralel AI review + Fable triage
-                          (Claude Code: Fable + Sonnet · Copilot CLI: GPT-5.4 + Opus + Sonnet)
+  Phase 4:   Review     -> Deterministik kapılar + paralel AI review + Opus triage
+                          (Claude Code: Opus + Sonnet · Copilot CLI: GPT-5.4 + Opus + Sonnet)
   Phase 5:   Test       -> Opsiyonel: branch'e geç, Xcode'da test (--dev / autopilot'ta skip)
   Phase 6:   Commit     -> Commit -> push -> PR + issue body güncelleme (hiç auto-close yok)
   Phase 7:   Report     -> Channels dispatcher (PR · Jira · Confluence · Wiki, multi-select)
@@ -279,8 +279,8 @@ Pipeline (Phase 0'dan sonra)  -  terminalde görsel kart olarak görünür:
 
 Modlar:
 
-  (normal)             Tam 8 faz, Sonnet dev, Plan Onay Kapısı aktif, paralel review + Fable triage
-  --dev                Hızlı: Init -> Dev(Fable) -> Commit -> Report (plan gate yok)
+  (normal)             Tam 8 faz, Sonnet dev, Plan Onay Kapısı aktif, paralel review + Opus triage
+  --dev                Hızlı: Init -> Dev(Opus) -> Commit -> Report (plan gate yok)
   --local              Worktree yok  -  doğrudan local branch'te çalışır
   autopilot            Plan gate dahil tüm onayları atla, otomatik commit/PR
                        (İSTİSNA: Phase 7 channels menüsü  -  her zaman durur)

package/pipeline/commands/multi-agent/refs/channels/jira.md

@@ -121,6 +121,7 @@ When the **Wiki** adapter writes pages on the same run AND `prefs.global.wikiToJ
 ## Hard rules (must not regress)
 
 - Real newlines, no HTML entities  -  heredoc + `jq --rawfile` + `curl --data-binary @file`.
+- UTF-8 in, UTF-8 out  -  the body file is UTF-8 and `--data-binary` ships its bytes verbatim. Never round-trip the body through `unicode_escape`, `latin-1`, or any re-encode step, and never hand-roll a Python/curl helper that re-decodes it: that mangles Turkish chars (ç ş ı ö ü ğ) into mojibake (`Çözüm` → `Ãözüm`). Use the `jq --rawfile` + `--data-binary @file` path above as-is. Same rule for the PR / Confluence / Wiki adapters.
 - Section order is fixed: `summary` → `test_scenarios` → `context_refs`. Never insert sections between them; never reorder.
 - Humanizer pass runs **after** body assembly and **before** wiki-markup conversion. Tone target: informal but technical. No marketing voice, no "we are excited", no "I have...".
 - Body content language follows `prefs.global.outputLanguage`. Code identifiers, file paths, type names, branch names, and the wiki-markup syntax stay verbatim. The `promptLanguage="en"` lock means any LLM prompt that produces the body is in English; the body itself is then rendered in the user's language.

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

@@ -34,7 +34,7 @@ In addition to the 34 top-level multi-agent commands, the figma-to-component pip
 |---|---|---|
 | `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.
 
@@ -48,7 +48,7 @@ Both Claude Code and Copilot CLI MUST expose every skill with identical argument
 | `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 |
 |---|---|
@@ -74,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
 

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

@@ -1,17 +1,28 @@
-# Model Fallback Contract (v9.10.1)
+# Model Fallback Contract (v10.1.0)
 
-Personas that declare `preferredModel: fable` route to the top intelligence tier
-(`claude-fable-5`). Fable access can be plan-window-limited, quota-limited, or
+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
 
 ```
-fable -> opus -> sonnet
+opus -> sonnet -> haiku
 ```
 
-One step down per trigger. The mechanism is the existing per-dispatch override:
+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;
@@ -20,13 +31,15 @@ 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):
+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": "opus",
+  "fallbackModel": "sonnet",
+  "floorModel": "haiku",
   "onDispatchError": true
 }
 ```
@@ -34,25 +47,30 @@ with no date gate):
 | 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: fable` dispatch is downgraded to `fallbackModel` unless the user re-confirms (see Date gate). Use when fable is included in a plan only until a known date. |
-| `fallbackModel` | Target of the first downgrade step. Default `opus`. |
-| `onDispatchError` | When `true`, a failed fable dispatch (model unavailable / quota / 4xx on model id) retries once on `fallbackModel` instead of aborting the phase. |
+| `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: fable plan window ended <date>; fable personas will dispatch on <fallbackModel>. Set prefs.global.modelFallback.premiumTierUntil to null to keep fable on usage credits.`
-   Then export the override for every fable persona this run. Interactive modes
-   may instead ask once (`Keep fable (usage credits) / Fall back to <model>`);
+   `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
-   fable dispatch and `onDispatchError: true`: retry the same persona once with
-   `PHASE_MODEL_OVERRIDE=<fallbackModel>`. A second failure falls through to the
-   normal phase-error path (pause -> resume). Never silent-skip the persona.
+   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, fable personas downgrade to `fallbackModel` for the
+   user-approved continue, `preferredModel` personas downgrade to `fallbackModel` for the
    remainder of the run.
 
 ## Logging
@@ -70,4 +88,4 @@ per-phase `model` field already carries the override).
 - 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 do not dispatch fable).
+  (they pin their own models and do not use this persona ladder).

package/pipeline/commands/multi-agent/refs/phases/operations.md

@@ -51,10 +51,13 @@ Every task gets an auto-incremented short ID. Counter stored at `$HOME/.claude/l
 ## Resume Logic
 
 1. Find state file: `$HOME/.claude/logs/multi-agent/{project}/{task-id}/agent-state.json`
-2. Read `agent-log.md` for previous findings
-3. Resume from `currentPhase + 1`
-4. **Always run Phase 7** on resume completion  -  ensures knowledge capture even if task was paused mid-pipeline
-5. Log: "Resumed {jiraId} from Phase {N}"
+2. **Validate before re-entry** (required  -  a half-written or corrupt state silently resumes at the wrong phase):
+   - `node $HOME/.claude/scripts/validate-state.mjs <state-file>` (resume-safety check: parseable JSON + `currentPhase` in 0..7 + well-formed `phases`; tolerant of legacy shapes, not a strict schema match). On non-zero exit, do NOT guess a phase: surface the error and stop with `ERR: agent-state.json is unsafe to resume; inspect it or 'kill #N' and restart.`
+   - Confirm the worktree path on `state.worktreePath` / `state.projects[].worktreePath` exists and `git -C <wt> status` is clean-or-known. If the worktree is missing or locked, run the Phase 0 "Worktree stale-lock heal" before continuing.
+3. Read `agent-log.md` for previous findings
+4. Resume from `currentPhase + 1`. If `state.phases[currentPhase+1].subStep` is set, re-enter that phase and skip already-recorded sub-steps (see "Sub-step checkpoints").
+5. **Always run Phase 7** on resume completion  -  ensures knowledge capture even if task was paused mid-pipeline
+6. Log: "Resumed {jiraId} from Phase {N}"
 
 ---
 
@@ -64,6 +67,8 @@ Run phases sequentially. Log every step to `agent-log.md`.
 If any phase fails, mark task as `paused` and stop  -  user can `resume` later.
 Update `agent-state.json` at EVERY phase transition.
 
+**Halt visibility (required, autopilot included).** A halt is never silent. Whenever a phase halts on a hard error (validator failed twice, no subagent returned, dispatch error past fallback, lock irrecoverable), in addition to the `agent-log.md` line: (a) write `state.status = "paused"` and `state.haltReason = "<phase>:<cause>"`; (b) record the cause on the tracker via `phase-tracker.sh meta <phase> halt "<cause>"` and `phase-tracker.sh update <phase> failed`; (c) emit one `>&2` alert line `HALT phase <N>: <cause>  -  resume with /multi-agent:resume #<id>`. Autopilot suppresses *confirmations*, not *halts*  -  the user must always be able to see why an unattended run stopped without reading the log.
+
 ### Pipeline Best Practices
 
 **Subagent return format**: Instruct every subagent to return structured JSON, not prose:
@@ -86,6 +91,11 @@ This keeps orchestrator context lean and enables programmatic routing.
 }
 ```
 
-**Proactive compaction**: If conversation context exceeds ~60%, dump progress to `agent-log.md` and summarize state before continuing. Don't wait for auto-compaction at 83%  -  it's lossy.
+**Proactive compaction + phase-boundary checkpoint**: the orchestrator follows ~2,500 lines of phase prose in one session; once context fills, it starts dropping steps  -  the single biggest cause of "it got stuck / skipped a step." Two defenses, both required on full-pipeline runs:
+
+- *Phase-boundary checkpoint.* At every phase transition, before loading the next phase doc, write the durable state (`agent-state.json` phase status + `files[]` + `retryCount`) and append a one-line progress summary to `agent-log.md`. The next phase reads state + log, not the back-conversation  -  so a transition is a clean re-entry point even if context is later compacted.
+- *Compaction trigger.* If conversation context exceeds ~50%, run `/compact` preserving "modified files, plan, open review findings, current phase + sub-step" before continuing. Don't wait for auto-compaction near the limit  -  it triggers exactly when context is worst and is lossy. After compaction, re-read `agent-state.json` to re-ground.
+
+**Sub-step checkpoints (long phases)**: Phase 3 (dev/TDD cycles) and Phase 7 (report/channels) can run many minutes; a crash mid-phase loses everything since the last phase boundary and forces a full phase re-run on resume. For these phases, also record `state.phases[<n>].subStep` (a short token: `red`, `green`, `build`, `pr-opened`, `confluence-synced`, ...) and the `files[]` written so far after each meaningful unit of work. On resume, re-enter the phase but skip units whose `subStep` is already recorded and whose `files[]` exist in the worktree  -  re-do only the unfinished tail, never the whole phase.
 
 **3-iteration hard kill**: Any retry loop (build fix, review fix) MUST stop after 3 attempts. On 4th failure -> pause, ask user. No exceptions.