@mmerterden/multi-agent-pipeline 10.0.6 → 10.2.0

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

@@ -37,7 +37,7 @@ OUTPUT_LANG=$(jq -r '.global.outputLanguage // "en"' "$PREFS_FILE" 2>/dev/null |
 
 From this point on, every assistant-authored conversational line (status updates, findings, phase headers, summaries, error explanations) renders in `$OUTPUT_LANG`. `AskUserQuestion` payloads stay English. External payloads stay English. See `refs/rules.md` "Language Application" for the full contract. Skipping this step is the failure mode where the user sees an English wall of text in a Turkish session.
 
-**Model fallback date gate** (same step, once per run): read `prefs.global.modelFallback`. If `premiumTierUntil` is set and in the past, apply the date-gate trigger from `refs/features/model-fallback.md` - fable personas dispatch on `fallbackModel` for this run, with the one-line WARN. Dispatch-error and budget triggers in that contract apply per-dispatch later; nothing else to do here.
+**Model fallback date gate** (same step, once per run): read `prefs.global.modelFallback`. If `premiumTierUntil` is set and in the past, apply the date-gate trigger from `refs/features/model-fallback.md` - `preferredModel` personas dispatch on `fallbackModel` for this run, with the one-line WARN. Dispatch-error and budget triggers in that contract apply per-dispatch later; nothing else to do here.
 
 **First-run guard**: After loading prefs, check if `keychainMapping` has at least one non-null value. If ALL values are null (template defaults  -  setup never ran), show:
 ```
@@ -387,7 +387,18 @@ git -C $PROJECT_ROOT config user.email "{identity.email}"
 
 `worktreePath` = `$PROJECT_ROOT`, `localMode` = `true`.
 
-**If normal mode** (worktree  -  default): 2. Worktree path: Jira → `.worktrees/{jiraId}/`, GitHub → `.worktrees/GH{issueNo}/`, free-text → `.worktrees/task-{shortId}/` 3. `git -C $PROJECT_ROOT worktree add {path} -b {branch} origin/{baseBranch}` (if exists: enter, pull) 4. Set identity: `git -C {worktree-path} config user.name/email` 5. Create log dir + `agent-log.md` + `agent-state.json`:
+**If normal mode** (worktree  -  default): 2. Worktree path: Jira → `.worktrees/{jiraId}/`, GitHub → `.worktrees/GH{issueNo}/`, free-text → `.worktrees/task-{shortId}/` 3. **Heal stale admin state first** (see "Worktree stale-lock heal" below), then `git -C $PROJECT_ROOT worktree add {path} -b {branch} origin/{baseBranch}` (if exists: enter, pull) 4. Set identity: `git -C {worktree-path} config user.name/email` 5. Create log dir + `agent-log.md` + `agent-state.json`:
+
+**Worktree stale-lock heal (required before every `worktree add`):** a run killed mid-`worktree add` (OOM, SIGTERM, disk full) leaves a locked or broken admin entry under `.git/worktrees/{id}/`, so the retry fails with `fatal: '<path>' already exists`. Always run the heal first  -  it is a no-op on a clean repo:
+
+```bash
+git -C "$proj" worktree prune 2>/dev/null || true            # drop entries whose dir is gone
+if git -C "$proj" worktree list --porcelain | grep -qF "$WT_PATH"; then
+  git -C "$proj" worktree unlock "$WT_PATH" 2>/dev/null || true   # clear a stale .locked marker
+fi
+```
+
+If the path is still registered and healthy after the heal, enter + pull instead of re-adding (existing behavior). Only when `worktree add` still fails after the heal do the rollback / collision flow in the multi-repo block below.
 
 **v2.1.0+ Multi-Repo Worktree Setup**:
 
@@ -396,6 +407,9 @@ When `state.projects[].length > 1`, repeat steps 2-4 **serially per repo** (work
 ```bash
 for proj in "${PROJECTS[@]}"; do
   WT_PATH="$proj/.worktrees/$BRANCH_DIR/"
+  git -C "$proj" worktree prune 2>/dev/null || true               # heal stale admin state
+  git -C "$proj" worktree list --porcelain | grep -qF "$WT_PATH" \
+    && git -C "$proj" worktree unlock "$WT_PATH" 2>/dev/null || true
   git -C "$proj" worktree add "$WT_PATH" -b "$BRANCH" "origin/$BASE_BRANCH"
   git -C "$WT_PATH" config user.name  "${proj_identity_name}"
   git -C "$WT_PATH" config user.email "${proj_identity_email}"

package/pipeline/commands/multi-agent/refs/phases/phase-1-analysis.md

@@ -1,4 +1,4 @@
-### Phase 1: Analysis (Fable)
+### Phase 1: Analysis (Opus)
 
 > **TLDR**  -  Opus-driven codebase exploration. Detects if the issue is already fixed (git blame, closed PRs), then launches parallel Explore sub-agents to map the affected code paths. Outputs: impact analysis, stack detection (auto-selects platform guide), relevant files, risk areas. Feeds Phase 2 planning.
 
@@ -117,10 +117,15 @@ Launch parallel Explore agents to scan codebase:
 - Existing patterns and conventions
 - Potential impact areas
 
-Use `subagent_type: "Explore"` with thoroughness based on knowledge availability:
+Use `subagent_type: "Explore"` with thoroughness scaled to task size AND knowledge availability (first match wins):
 
+- `taskType` is `bugfix`/`chore` AND scope is small (single named file, or a referenced crash/stack frame that pinpoints the site) → "light" (cheapest  -  scan only the named area + its direct callers)
 - Knowledge exists → "medium" (targeted, cheaper)
-- No knowledge → "very thorough" (full scan, first time investment)
+- No knowledge, or `taskType` is `feature`/`refactor`/`component` → "very thorough" (full scan, first-time investment)
+
+The light tier keeps a one-line bug fix from triggering a full-repo scan; pairing it with the deterministic `taskType` (Phase 0 Step 7) prevents the cheap path from firing on feature work.
+
+**Dispatch resilience (required).** Explore agents run in parallel and the analyst synthesis waits on them, so a single stalled agent hangs the phase. Bound each Explore dispatch by a wall-clock budget (`EXPLORE_TIMEOUT_SECONDS`, default 180). If an agent has not returned by the budget: log `explore.timeout agent=<id>`, drop that agent's slice, and synthesize from the agents that did return. Proceed as long as at least one Explore agent returned; if zero returned, retry the cheapest single Explore once, then HALT with `ERR: no Explore agent returned within ${EXPLORE_TIMEOUT_SECONDS}s; resume with /multi-agent:resume #N.`. Never block indefinitely on a slow or dead dispatch.
 
 #### Output contract
 

package/pipeline/commands/multi-agent/refs/phases/phase-2-planning.md

@@ -1,4 +1,4 @@
-### Phase 2: Planning (Fable)
+### Phase 2: Planning (Opus)
 
 > **TLDR**  -  Opus decomposes the analysis into concrete tasks with file-level targets, risk grading, and architecture review. Before Phase 3 a **Plan Approval Gate** runs in normal mode: if the Jira/issue description is ambiguous the orchestrator asks the user structured clarification questions (max 2 rounds)  -  once scope is clear it renders the plan and loops on free-text edit requests until the user approves or aborts. The gate is **skipped entirely** for `--dev`, `autopilot`, and `--dev autopilot` (their speed/zero-interaction contracts are preserved).
 

package/pipeline/commands/multi-agent/refs/phases/phase-4-review.md

@@ -1,6 +1,6 @@
 ### Phase 4: Review (deterministic gates + parallel + triage)
 
-> **TLDR**  -  Three-stage review. Stage 1: deterministic gates (build + lint + test + secret scan) that MUST pass. Stage 2: AI models in parallel  -  reviewer set is **CLI-aware**: Claude Code dispatches 2 reviewers (Fable + Sonnet); Copilot CLI dispatches 3 reviewers (GPT-5.4 + Opus + Sonnet). Stage 3: Fable triage  -  evaluates raw findings, filters false-positives/out-of-scope, keeps only actionable items. Only triage-accepted blocking items loop back to Phase 3.
+> **TLDR**  -  Three-stage review. Stage 1: deterministic gates (build + lint + test + secret scan) that MUST pass. Stage 2: AI models in parallel  -  reviewer set is **CLI-aware**: Claude Code dispatches 2 reviewers (Opus + Sonnet); Copilot CLI dispatches 3 reviewers (GPT-5.4 + Opus + Sonnet). Stage 3: Opus triage  -  evaluates raw findings, filters false-positives/out-of-scope, keeps only actionable items. Only triage-accepted blocking items loop back to Phase 3.
 
 <!-- progress-contract: applied -->
 Progress emission per `refs/progress-contract.md`  -  lines for each gate, each reviewer dispatch + finish, triage start, triage verdict, fix dispatch.
@@ -81,6 +81,14 @@ If changes include UI files (iOS: `*View.swift`, `*Screen.swift`, `*Cell.swift`;
 - Missing safe area / keyboard avoidance → **important**
 - Hardcoded colors instead of system/semantic colors → **suggestion**
 
+**iOS  -  SwiftUI interaction & accessibility conventions** (skills: `figma-navigation`, `figma-overlays`, `figma-bottom-sheets`, plus the enriched `figma-to-swiftui` accessibility rules). Gated to changed SwiftUI files; each is native-SwiftUI-first unless the project's `figma-config` `ui.*` declares a custom system, in which case check against that system instead:
+- A reusable component that **routes itself** (hardcoded `NavigationLink(destination: ConcreteScreen())`, calls a router) instead of emitting a typed `Output` → **important** (breaks reuse).
+- A reusable component that **presents its own app-level overlay** (toast/alert/modal) instead of emitting an intent for the caller → **important** (double-fires when composed).
+- `AnyView` routed through an overlay center / data-modal path (rich content should be a local `.sheet/.modal { }`) → **important**.
+- Loading HUD not **ref-counted** / missing `end` on an error path / no min-show (flash) → **important**.
+- A pinned bottom CTA built as a presented sheet instead of `.safeAreaInset(edge:.bottom)`, or detents that aren't ascending / use magic-number heights → **suggestion**.
+- **Accessibility over-annotation** (redundant `.isButton` on `Button` / `.isStaticText` on `Text`, `.accessibilityLabel` duplicating visible text, a per-enum-variant a11y key for non-interactive visual state, hints on self-explanatory actions) → **suggestion**; **missing** decorative-image hiding or interactive-state `.accessibilityValue` → **important**.
+
 **Android  -  Material Design compliance** (skills: `compose-components`, `android-architecture`):
 - Non-Material3 component when M3 equivalent exists → **suggestion**
 - Missing `contentDescription` on icons/images → **blocking**
@@ -159,6 +167,14 @@ Visual-fidelity mismatches against the captured screenshot are BLOCKING findings
 
 When `state.figmaAccess.tier === 3` (user-attached screenshot, no Code Connect snippet), the reviewer additionally sets `findings[i].severity = "blocking"` and `findings[i].tag = "review_blocking_tier3"` on every UI atom that lacks a confirmed canonical-component mapping. The triage step preserves these findings unless the user has explicitly cleared the open question.
 
+#### Step 1.9  -  Context economy (cache prefix + diff cap)
+
+Phase 4 sends the same diff to every reviewer and then to triage, so the diff is the dominant token cost. Two measures keep it bounded:
+
+**Shared cache prefix.** Build the reviewer and triage prompts so the large invariant context  -  the full diff, the Phase 1 analysis summary, the Phase 2 plan  -  is a byte-identical leading block across all dispatches in this iteration. Only the per-reviewer focus + skill line varies, and it goes AFTER the shared block. When the host supports prompt caching, the 2nd/3rd reviewer and the triage call then read that prefix at the discounted cache-read rate instead of re-billing it as fresh input. Forward the host-reported cache-read count as `tokens_cached` per the Token telemetry contract so the saving lands in the cost ledger.
+
+**Single-repo diff cap.** If the diff exceeds the Phase 4 token allowance (`token-budget.json`), truncate the largest files and append a footer `[truncated  -  full diff in file://$WORKTREE/.review-diff.txt]`, writing the full diff to that path. Reviewers and triage receive the same capped view + the marker so they can flag "review the full diff manually." Log `review.diff_truncated bytes_dropped=<N>`. (Multi-repo already caps the combined diff at 80% of budget; this is the single-repo equivalent.)
+
 #### Step 2  -  Parallel AI Review (CLI-aware reviewer set)
 
 Launch Agent instances **in parallel** using the shared `code-reviewer` subagent definition (`~/.claude/agents/code-reviewer.md`). The reviewer set is determined by the host CLI  -  GPT-5.4 is only available on Copilot CLI, so Claude Code skips that reviewer and runs a 2-model parallel review; Copilot CLI runs all three.
@@ -171,7 +187,7 @@ Launch Agent instances **in parallel** using the shared `code-reviewer` subagent
 
 Each reviewer inherits the `code-reviewer` agent's focus areas (Security, Architecture, Quality, Performance) and output contract. The orchestrator overrides only the model and the stack-specific skill per-reviewer  -  no prompt duplication.
 
-**Model override wiring:** `code-reviewer.md` declares `preferredModel: fable`, so Reviewer 1 uses the persona default. Reviewer 2 (Copilot-only, `gpt-5.4`) and Reviewer 3 (`claude-sonnet-4.6`) set `PHASE_MODEL_OVERRIDE=<model>` before dispatch  -  the orchestrator exports `CLAUDE_CODE_SUBAGENT_MODEL` on Claude Code, or passes `--model` on Copilot CLI. Full precedence rule: `skills/shared/core/multi-agent/SKILL.md#agent-dispatch--per-persona-model-routing-v610`. Fable dispatches are additionally subject to the fallback contract (`refs/features/model-fallback.md`): date gate, dispatch-error retry on `fallbackModel`, and budget-ceiling downgrade.
+**Model override wiring:** `code-reviewer.md` declares `preferredModel: opus`, so Reviewer 1 uses the persona default. Reviewer 2 (Copilot-only, `gpt-5.4`) and Reviewer 3 (`claude-sonnet-4.6`) set `PHASE_MODEL_OVERRIDE=<model>` before dispatch  -  the orchestrator exports `CLAUDE_CODE_SUBAGENT_MODEL` on Claude Code, or passes `--model` on Copilot CLI. Full precedence rule: `skills/shared/core/multi-agent/SKILL.md#agent-dispatch--per-persona-model-routing-v610`. Opus dispatches are additionally subject to the fallback contract (`refs/features/model-fallback.md`): dispatch-error retry on `fallbackModel` (sonnet) and budget-ceiling downgrade.
 
 **Adapter platforms (Cursor / Antigravity / VS Code Copilot Chat) - reviewer set.** The native trio above is a Claude-Code / Copilot-CLI capability. On the adapter platforms the pipeline configures a 2-model cross-vendor review using the models each platform actually exposes (lineup in `pipeline/adapters/_base.mjs#REVIEWER_MODELS`; update as the platforms ship new versions):
 
@@ -185,7 +201,7 @@ So cross-vendor review IS restored on the adapter platforms (two different model
 
 **Stack-specific skills loaded per reviewer** (from Phase 1 `detectedStack`). On Claude Code, Reviewer 2 (GPT-5.4) is not dispatched  -  its skill column is ignored. On Copilot CLI all three columns are used.
 
-| Stack | Reviewer 1 (Fable) | Reviewer 2 (GPT-5.4  -  Copilot CLI only) | Reviewer 3 (Sonnet) |
+| Stack | Reviewer 1 (Opus) | Reviewer 2 (GPT-5.4  -  Copilot CLI only) | Reviewer 3 (Sonnet) |
 |-------|-------------------|-----------------------------------------|---------------------|
 | iOS/Swift | `ios-security`, `swiftui-performance`, `hig-patterns` | `swift-concurrency`, `ios-accessibility` | `swiftui-pro`, `swift-testing` |
 | Android/Kotlin | `android-security`, `android-performance` | `compose-testing`, `android-architecture` | `compose-components`, `kotlin-coroutines-expert` |
@@ -196,9 +212,13 @@ So cross-vendor review IS restored on the adapter platforms (two different model
 
 Skills are injected into reviewer prompt context  -  the reviewer uses them as reference, not as commands.
 
+**iOS/Swift  -  interaction & convention skills (conditional).** When the diff touches SwiftUI UI files (`*View.swift`, `*Screen.swift`, `*Configuration.swift`, `*+Modifiers.swift`), additionally inject the relevant `figma-common` convention skills as reference for the iOS reviewers: `figma-navigation`, `figma-overlays`, `figma-bottom-sheets` (interaction: emit-intent vs self-route/self-present; native-SwiftUI-first vs the project's `ui.*` custom system), and the enriched `figma-to-swiftui` accessibility rules (minimalism). These back the Step 1.5 iOS convention checks. Generic across SwiftUI projects  -  not tied to any one app. Omit when the diff has no SwiftUI UI changes (keeps the reviewer prompt lean).
+
+**Dispatch timeout (required, mirrors triage 3.3).** Reviewers run in parallel and triage waits on all of them, so one stalled reviewer hangs the phase. Bound each reviewer dispatch by `REVIEWER_TIMEOUT_SECONDS` (default 180). If a reviewer has not returned by the budget: log `review.reviewer_timeout reviewer=<name>`, treat that reviewer as absent, and proceed to triage with the reviewers that did return. The merged-findings count and `consensus.reviewerCount` reflect only the reviewers that returned. If **zero** reviewers return, retry the Opus reviewer once; on a second total failure HALT with `ERR: no reviewer returned within ${REVIEWER_TIMEOUT_SECONDS}s; resume with /multi-agent:resume #N.`. The Step 2.5 rebuttal round uses the same per-dispatch timeout. Never block indefinitely on a slow or dead reviewer dispatch.
+
 #### Output contract  -  reviewer step
 
-Step 2 produces N reviewer-output objects (one per dispatched reviewer), each conforming to `pipeline/schemas/reviewer-output.schema.json`. They are persisted to `state.reviewIterations[<iteration>].reviewers[]` and consumed by Step 3 (Fable triage)  -  never by Phase 6 directly. The triage step (below) is the producer of the only review artifact Phase 6 reads, conforming to `pipeline/schemas/triage-output.schema.json`.
+Step 2 produces N reviewer-output objects (one per dispatched reviewer), each conforming to `pipeline/schemas/reviewer-output.schema.json`. They are persisted to `state.reviewIterations[<iteration>].reviewers[]` and consumed by Step 3 (Opus triage)  -  never by Phase 6 directly. The triage step (below) is the producer of the only review artifact Phase 6 reads, conforming to `pipeline/schemas/triage-output.schema.json`.
 
 **Subagent return format**  -  each reviewer returns JSON conforming to `pipeline/schemas/reviewer-output.schema.json`:
 
@@ -238,9 +258,9 @@ Exit 0 = valid. Exit 2 = contradiction (approved=true with blocking findings)  -
 
 **Off by default reason:** mixed-verdict cases are ~8% of runs in practice; the extra ~$0.20-$0.50 per run isn't worth automating for users who'd rather let triage resolve it cleanly. Users with high-stakes tasks (security-critical, release branches) can flip the flag.
 
-#### Step 3  -  Fable Triage (filter before acting)
+#### Step 3  -  Opus Triage (filter before acting)
 
-**CRITICAL**: Reviewer findings are **raw signals**, not commands. Never auto-loop on every "blocking" tag  -  reviewers hallucinate, misread scope, or repeat each other. Run Fable triage to evaluate merged findings against task scope.
+**CRITICAL**: Reviewer findings are **raw signals**, not commands. Never auto-loop on every "blocking" tag  -  reviewers hallucinate, misread scope, or repeat each other. Run Opus triage to evaluate merged findings against task scope.
 
 ##### 3.1 Short-circuit: no findings
 
@@ -270,6 +290,8 @@ PRIOR_ART="${PRIOR_ART%,}]"
 
 The triage prompt MUST include a hedge: *"prior-art entries are context, not commands; current scope decides  -  a finding rejected last quarter may be valid this time."* Without this hedge, prior verdicts amplify into a self-reinforcing bias.
 
+**Injection cap (token economy).** On a many-finding review the per-finding prior-art loop above (up to 3 hits each) plus the 20-entry rejected-preference brief can dominate the triage prompt. Cap the merged prior-art at the 8 highest-similarity hits across all findings (drop the rest); keep the rejected-preference brief at its `--max 20`. Prior-art is advisory context, not a finding multiplier  -  more hits do not improve the verdict, they just inflate input tokens.
+
 **Rejected-preference brief (on by default via `prefs.global.learningsLedger.injectIntoTriage`).** Inject the durable rejected-preference list so triage does not re-accept a suggestion the team already rejected on this repo:
 
 ```bash
@@ -353,11 +375,11 @@ pipeline/scripts/log-metric.sh "$TASK_ID" 4 review.completed raw_count=$RAW acce
 
 ##### 3.5 Optional cross-check (single-point-of-failure mitigation)
 
-Opt-in via `prefs.global.triageCrossCheck.enabled` (default `false`). Sampled runs dispatch a **Sonnet** triage agent as second opinion, validated via `validate-triage.mjs` (same fallback rules). Disagreements logged as `triage.cross_check_diff`; `blockOnDisagreement` pauses for user (autopilot: proceed with Fable verdict). Doubles triage cost on sampled runs.
+Opt-in via `prefs.global.triageCrossCheck.enabled` (default `false`). Sampled runs dispatch a **Sonnet** triage agent as second opinion, validated via `validate-triage.mjs` (same fallback rules). Disagreements logged as `triage.cross_check_diff`; `blockOnDisagreement` pauses for user (autopilot: proceed with Opus verdict). Doubles triage cost on sampled runs.
 
 ##### 3.6 Consensus surfacing (anti-correlation)
 
-**Rationale:** Reviewer 1 (Fable) and Reviewer 3 (Sonnet) share a base model family, so unanimous agreement on a *judgment call* is not independent confirmation  -  same-family models drift the same way on ambiguous prompts. Treating "both approved" as proof produces false-consensus passes. Triage therefore records a `consensus` block (schema v3.1.0) and surfaces disagreement and unverified agreement to the user rather than burying it.
+**Rationale:** Reviewer 1 (Opus) and Reviewer 3 (Sonnet) share a base model family, so unanimous agreement on a *judgment call* is not independent confirmation  -  same-family models drift the same way on ambiguous prompts. Treating "both approved" as proof produces false-consensus passes. Triage therefore records a `consensus` block (schema v3.1.0) and surfaces disagreement and unverified agreement to the user rather than burying it.
 
 After the triage verdict is computed, populate `triage.consensus`:
 

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

@@ -13,9 +13,12 @@ Resume a paused or failed task from the last successful phase.
 
 1. **Find the task**  -  parse `#N` from the argument, or pick the most recent worktree with `status != "done"`.
 
-2. **Read state**  -  parse `agent-state.json`:
+2. **Read + validate state**  -  parse `agent-state.json`:
+   - Validate first: `node $HOME/.claude/scripts/validate-state.mjs <state-file>` (resume-safety check, tolerant of legacy shapes). On non-zero exit, do NOT guess a phase  -  surface the errors and stop with `ERR: agent-state.json is unsafe to resume; inspect it or 'kill #N' and restart.`
+   - Confirm the worktree (`worktreePath` / `projects[].worktreePath`) exists and is usable; if missing or locked, run the Phase 0 "Worktree stale-lock heal" before continuing.
    - `currentPhase`  -  last completed phase
    - `status`  -  `paused` | `failed` | `in_progress`
+   - `haltReason`  -  if set, show it so the user knows why the run stopped; clear it on successful re-entry
    - `autopilot`  -  preserve the mode
 
 3. **Load context**  -  read prior-phase findings from `agent-log.md`:

package/pipeline/commands/multi-agent.md

@@ -1,5 +1,5 @@
 ---
-description: "Task orchestrator  -  full pipeline via Jira ID + branch or GitHub Issue URL: analysis, plan, TDD development, parallel review + Fable triage (CLI-aware: 2-model on Claude Code, 3-model on Copilot CLI), commit, log"
+description: "Task orchestrator  -  full pipeline via Jira ID + branch or GitHub Issue URL: analysis, plan, TDD development, parallel review + Opus triage (CLI-aware: 2-model on Claude Code, 3-model on Copilot CLI), commit, log"
 allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep, TaskCreate, TaskUpdate, TaskList, TaskGet, AskUserQuestion, WebFetch, WebSearch, NotebookEdit, Skill
 ---
 
@@ -82,8 +82,8 @@ Lib scripts (`~/.claude/lib/`):
 | `stack [ios\|android\|backend\|mobile\|all]` | Swap skills for next conversation. No arg = show current stack. |
 | `language [en\|tr]` | Show or set the assistant `outputLanguage` (explanations and chat replies). `promptLanguage` is locked to `en` and is not toggleable. No arg = show current `outputLanguage`. With `en` or `tr` = set and persist `outputLanguage`. External payloads (commits, PR bodies, Jira) stay English. |
 | `setup` | Keychain token + Git Identity onboarding |
-| `--dev` | Dev-only: Init -> Dev(Fable) -> Commit -> Report |
-| `--dev autopilot` or `dev-autopilot` | Fastest path  -  Dev(Fable) + zero interaction |
+| `--dev` | Dev-only: Init -> Dev(Opus) -> Commit -> Report |
+| `--dev autopilot` or `dev-autopilot` | Fastest path  -  Dev(Opus) + zero interaction |
 | `--local` | No worktree  -  works directly on local branch |
 | `autopilot` | Skip user confirmations, auto commit/PR |
 | No args / `help` | Show usage guide |
@@ -220,7 +220,7 @@ Save to `prefs.projects[{project}].branches`.
 ```
 Pipeline mode:
   1. Full pipeline (8 phases, Sonnet dev, parallel review + triage  -  CLI-aware reviewer set)
-  2. --dev (fast: Init → Dev(Fable) → Commit → Report)
+  2. --dev (fast: Init → Dev(Opus) → Commit → Report)
 Select [1/2]:
 ```
 
@@ -247,7 +247,7 @@ When called with `review`:
 1. Detect current branch and project from cwd (or ask)
 2. Get diff: `git diff HEAD` (unstaged + staged)
 3. If no diff, get diff against base branch: `git diff origin/{baseBranch}...HEAD`
-4. Launch Phase 4 review (parallel + Fable triage  -  2-model on Claude Code, 3-model on Copilot CLI) on the diff
+4. Launch Phase 4 review (parallel + Opus triage  -  2-model on Claude Code, 3-model on Copilot CLI) on the diff
 5. No worktree, no state file  -  lightweight one-shot review
 6. Print findings to terminal
 

package/pipeline/lib/fetch-confluence.sh

@@ -147,7 +147,7 @@ m = re.match(r'/display/[^/]+/(.+)', p.path)
 print(up.unquote(m.group(1)) if m else '')
 " URL_PARSE_INPUT="$URL")
   if [ -n "$TITLE_RAW" ]; then
-    LOOKUP=$(curl -sS --fail --max-time "$TIMEOUT" \
+    LOOKUP=$(curl -sS --fail --max-time "$TIMEOUT" --connect-timeout 5 \
       -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
       --data-urlencode "spaceKey=$SPACE_KEY" \
       --data-urlencode "title=$TITLE_RAW" \
@@ -171,7 +171,7 @@ if [ -z "$PAGE_ID_RESOLVED" ]; then
 fi
 
 # Fetch the page body in storage format.
-PAGE_JSON=$(curl -sS --fail --max-time "$TIMEOUT" \
+PAGE_JSON=$(curl -sS --fail --max-time "$TIMEOUT" --connect-timeout 5 \
   -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
   "$API_BASE/content/$PAGE_ID_RESOLVED?expand=body.storage,space" 2>/dev/null || true)
 

package/pipeline/lib/fetch-crashlytics.sh

@@ -244,7 +244,7 @@ fi
 APP_REF="$PLATFORM:$BUNDLE"
 ISSUE_URL_API="https://firebasecrashlytics.googleapis.com/v1alpha/projects/$PROJECT_ID/apps/$APP_REF/issues/$ISSUE_ID"
 
-ISSUE_JSON=$(curl -sS --fail --max-time "$TIMEOUT" \
+ISSUE_JSON=$(curl -sS --fail --max-time "$TIMEOUT" --connect-timeout 5 \
   -H "Authorization: Bearer $ACCESS_TOKEN" -H "Accept: application/json" \
   "$ISSUE_URL_API" 2>/dev/null || true)
 
@@ -256,7 +256,7 @@ fi
 SESSION_JSON=""
 if [ -n "$SESSION_ID" ]; then
   SESSION_URL_API="$ISSUE_URL_API/sessions/$SESSION_ID"
-  SESSION_JSON=$(curl -sS --fail --max-time "$TIMEOUT" \
+  SESSION_JSON=$(curl -sS --fail --max-time "$TIMEOUT" --connect-timeout 5 \
     -H "Authorization: Bearer $ACCESS_TOKEN" -H "Accept: application/json" \
     "$SESSION_URL_API" 2>/dev/null || true)
 fi

package/pipeline/lib/fetch-fortify.sh

@@ -153,7 +153,7 @@ fortify_get() {
     else
       hdr="Authorization: FortifyToken $(printf '%s' "$TOKEN" | base64 | tr -d '\n')"
     fi
-    resp=$(curl -sS --max-time "$TIMEOUT" -w "\n%{http_code}" \
+    resp=$(curl -sS --max-time "$TIMEOUT" --connect-timeout 5 -w "\n%{http_code}" \
              -H "$hdr" -H "Accept: application/json" "$url" 2>/dev/null || true)
     http=$(printf '%s' "$resp" | tail -n1)
     if [ "$http" = "200" ]; then

package/pipeline/lib/fetch-swagger.sh

@@ -55,7 +55,7 @@ trap 'rm -f "$TMP_RAW"' EXIT
 
 # Pull the spec with a size cap (curl --max-filesize doesn't exist on every
 # platform; we let curl run with --output then check the size).
-CURL_ARGS=(-sS --fail --max-time "$TIMEOUT" --location --output "$TMP_RAW" \
+CURL_ARGS=(-sS --fail --max-time "$TIMEOUT" --connect-timeout 5 --location --output "$TMP_RAW" \
            --write-out "%{http_code}\n%{content_type}\n%{size_download}\n")
 if [ -n "${SWAGGER_AUTH_HEADER:-}" ]; then
   CURL_ARGS+=(-H "$SWAGGER_AUTH_HEADER")

package/pipeline/lib/figma-screenshot.sh

@@ -171,7 +171,7 @@ curl_figma() {
   local code attempt sleep_s
   for attempt in 1 2 3; do
     code=$(curl -sS -o "$out" -w '%{http_code}' \
-              --max-time "$HTTP_TIMEOUT" \
+              --max-time "$HTTP_TIMEOUT" --connect-timeout 5 \
               -H "X-Figma-Token: $FIGMA_TOKEN" \
               "$url" || echo "000")
     case "$code" in
@@ -273,7 +273,7 @@ render_and_download() {
           printf "%s\tFAIL\t0\n" "$nid"
           exit 0
         fi
-        if curl -sS --max-time "$2" -o "$out" "$url"; then
+        if curl -sS --max-time "$2" --connect-timeout 5 -o "$out" "$url"; then
           size=$(wc -c < "$out" | tr -d " ")
           printf "%s\t%s\t%s\n" "$nid" "$out" "$size"
         else

package/pipeline/preferences-template.json

@@ -61,8 +61,15 @@
     "modelFallback": {
       "enabled": true,
       "premiumTierUntil": null,
-      "fallbackModel": "opus",
+      "fallbackModel": "sonnet",
       "onDispatchError": true
+    },
+    "costBudget": {
+      "enabled": true,
+      "maxUsd": 5.0,
+      "warnPct": 80,
+      "onExceed": "warn",
+      "pricingModel": "opus"
     }
   },
   "projects": {},

package/pipeline/schemas/agent-state.schema.json

@@ -81,6 +81,10 @@
     },
     "startedAt": { "type": "string", "format": "date-time" },
     "finishedAt": { "type": ["string", "null"], "format": "date-time" },
+    "haltReason": {
+      "type": ["string", "null"],
+      "description": "Set when a phase halts on a hard error (validator failed twice, no subagent returned, dispatch error past fallback, lock irrecoverable). Format '<phase>:<cause>'. Surfaced to the user and cleared on successful resume. See operations.md 'Halt visibility'."
+    },
     "telemetry": {
       "type": "object",
       "additionalProperties": true,
@@ -145,6 +149,10 @@
               "description": "Files produced or modified by this phase. Used for semantic revert."
             },
             "retryCount": { "type": "integer", "minimum": 0, "maximum": 3 },
+            "subStep": {
+              "type": "string",
+              "description": "Sub-step checkpoint for long phases (3, 7) so resume re-does only the unfinished tail instead of the whole phase. Short token, e.g. 'red'|'green'|'build'|'pr-opened'|'confluence-synced'. See operations.md 'Sub-step checkpoints'."
+            },
             "notes": { "type": "string" },
             "clarificationRounds": {
               "type": "integer",

package/pipeline/schemas/figma-project-config.schema.json

@@ -224,6 +224,45 @@
         }
       }
     },
+    "ui": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "UI interaction systems. Consumed by the figma-navigation / figma-overlays / figma-bottom-sheets convention skills and by Phase 4 review. When a section is absent or its mode is 'native', the pipeline uses stock SwiftUI (NavigationStack, .alert/.sheet(item:), .sheet+presentationDetents). Set mode 'custom' to route to a project-supplied system by the type names below.",
+      "properties": {
+        "navigationSystem": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "mode": { "type": "string", "enum": ["native", "custom"], "default": "native" },
+            "router": { "type": "string", "description": "Router type that dispatches routes (custom mode)." },
+            "routeEnum": { "type": "string", "description": "Exhaustive cross-surface route enum (custom mode)." },
+            "sceneType": { "type": "string", "description": "Headless screen container type (custom mode, optional)." },
+            "navigatorProtocol": { "type": "string", "description": "DI'd selection/present API (custom mode, optional)." }
+          }
+        },
+        "overlaySystem": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "mode": { "type": "string", "enum": ["native", "custom"], "default": "native" },
+            "center": { "type": "string", "description": "DI'd overlay center protocol callable from VM/coordinator (custom mode)." },
+            "surfaces": { "type": "array", "items": { "type": "string" }, "description": "Independent render surfaces, e.g. root/currentScene (custom mode, optional)." }
+          }
+        },
+        "sheetSystem": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "mode": { "type": "string", "enum": ["native", "custom"], "default": "native" },
+            "brandedModifier": { "type": "string", "description": "Branded sheet entry modifier, e.g. bottomSheet (custom mode)." },
+            "headlessModifiers": { "type": "array", "items": { "type": "string" }, "description": "Headless sheet modifiers, e.g. modalSheet/dockedSheet/expandableSheet/detentNavigationSheet (custom mode)." },
+            "detentType": { "type": "string", "description": "Detent enum type (custom mode)." },
+            "backdropType": { "type": "string", "description": "Backdrop enum type (custom mode)." },
+            "cornerRadiusToken": { "type": "string", "description": "Branded top-corner radius token (custom mode)." }
+          }
+        }
+      }
+    },
     "teams": {
       "type": "array",
       "description": "Team definitions. Each entry maps a logical team to a GitHub label and a Jira custom-field value.",

package/pipeline/schemas/prefs.schema.json

@@ -803,12 +803,12 @@
         "costBudget": {
           "type": "object",
           "additionalProperties": false,
-          "description": "v9.2+  -  Proactive per-task cost ceiling. Complements the end-of-run cost summary: pipeline/scripts/cost-budget-check.mjs reads the phase-tracker token accumulators after each phase, prices them via cost-table.json, and warns or halts before spend runs away. Top user-cited reason to abandon an AI coding tool is opaque/spiralling cost; this surfaces it live. Disabled by default.",
+          "description": "v9.2+  -  Proactive per-task cost ceiling. Complements the end-of-run cost summary: pipeline/scripts/cost-budget-check.mjs reads the phase-tracker token accumulators after each phase, prices them via cost-table.json, and warns or halts before spend runs away. Top user-cited reason to abandon an AI coding tool is opaque/spiralling cost; this surfaces it live. Enabled by default in warn mode (v10.1+); set enabled:false to opt out, or onExceed:halt to make the ceiling blocking.",
           "properties": {
             "enabled": {
               "type": "boolean",
-              "default": false,
-              "description": "Master switch. When off, cost-budget-check.mjs exits 0 silently and the pipeline behaves exactly as before."
+              "default": true,
+              "description": "Master switch. Default true (warn mode) so runaway cost is visible live. When off, cost-budget-check.mjs exits 0 silently and the pipeline behaves exactly as before."
             },
             "maxUsd": {
               "type": "number",

package/pipeline/scripts/cost-table.json

@@ -2,12 +2,6 @@
   "_readme": "Per-model unit prices in USD per million tokens. Source: Anthropic public pricing (verified 2026-04-21). Update when Anthropic publishes new tiers. Unknown models render USD as ' - ' and emit a footnote  -  never block PR-body generation. cacheReadPerMtok is the discounted rate for prompt-cache hits (~10% of inPerMtok); the renderer prices a phase's tokens_cached at this rate when the tracker records it, so resume/cache reuse is visible in the ledger.",
   "schemaVersion": "1.1.0",
   "prices": {
-    "fable": {
-      "inPerMtok": 10.0,
-      "outPerMtok": 50.0,
-      "cacheReadPerMtok": 1.0,
-      "modelId": "claude-fable-5"
-    },
     "opus": {
       "inPerMtok": 5.0,
       "outPerMtok": 25.0,

package/pipeline/scripts/fixtures/install-layout.tsv

@@ -5,12 +5,12 @@
 .claude/multi-agent-preferences.json	1
 .claude/rules	12
 .claude/schemas	23
-.claude/scripts	173
+.claude/scripts	174
 .claude/settings.json	1
 .claude/skills	555
 .copilot/agents	8
 .copilot/copilot-instructions.md	1
 .copilot/lib	23
 .copilot/schemas	23
-.copilot/scripts	173
+.copilot/scripts	174
 .copilot/skills	590

package/pipeline/scripts/phase-tracker.sh

@@ -74,6 +74,13 @@ if [ -z "$TRACKER_FILE" ]; then
     TASK_ID_FROM_ENV="$1"
   fi
   if [ -z "$TASK_ID_FROM_ENV" ]; then
+    # Strict mode: refuse the global pointer fallback entirely. Concurrent-safe by
+    # construction  -  the orchestrator must export MULTI_AGENT_TASK_ID. Opt in with
+    # MULTI_AGENT_STRICT_TASK_ID=1 (recommended whenever more than one run can be live).
+    if [ "${MULTI_AGENT_STRICT_TASK_ID:-0}" = "1" ]; then
+      echo "phase-tracker: MULTI_AGENT_STRICT_TASK_ID=1 but no MULTI_AGENT_TASK_ID in scope; refusing global pointer fallback. Export MULTI_AGENT_TASK_ID=<id>." >&2
+      exit 64
+    fi
     # Fallback to the file written by the most recent init.
     # WARNING: this pointer is global and flips when ANY shell on this user account runs
     # `phase-tracker.sh init <other-task>`. In concurrent multi-agent runs (two terminals,

package/pipeline/scripts/smoke-model-fallback.sh

@@ -1,9 +1,10 @@
 #!/usr/bin/env bash
-# smoke-model-fallback.sh  -  lint the model fallback contract wiring (v9.10.1).
-# The contract lets fable-personas degrade to opus on a plan-window date gate,
-# a dispatch error, or a budget ceiling - via PHASE_MODEL_OVERRIDE, never by
-# editing persona files. This smoke asserts the doc, the prefs knob, and the
-# phase wiring all exist and agree. No network, no credentials.
+# smoke-model-fallback.sh  -  lint the model fallback contract wiring (v10.1.0).
+# The contract lets preferredModel (opus) personas degrade to sonnet on a
+# plan-window date gate, a dispatch error, or a budget ceiling - via
+# PHASE_MODEL_OVERRIDE, never by editing persona files. This smoke asserts the
+# doc, the prefs knob, and the phase wiring all exist and agree. No network,
+# no credentials.
 
 set -uo pipefail
 
@@ -26,7 +27,7 @@ if [ -f "$DOC" ]; then
   grep -q "onDispatchError" "$DOC" && ok "doc documents dispatch-error retry" || fail "doc missing onDispatchError"
   grep -q "cost-budget-check" "$DOC" && ok "doc documents budget-ceiling trigger" || fail "doc missing budget trigger"
   grep -q "PHASE_MODEL_OVERRIDE" "$DOC" && ok "doc uses the existing override mechanism" || fail "doc missing PHASE_MODEL_OVERRIDE"
-  grep -q "fable -> opus -> sonnet" "$DOC" && ok "tier ladder declared" || fail "tier ladder missing"
+  grep -q "opus -> sonnet" "$DOC" && ok "tier ladder declared" || fail "tier ladder missing"
 else
   fail "model-fallback.md missing"
 fi
@@ -42,7 +43,7 @@ if not isinstance(mf, dict):
 checks = [
     mf.get("enabled") is True,
     "premiumTierUntil" in mf and mf["premiumTierUntil"] is None,
-    mf.get("fallbackModel") == "opus",
+    mf.get("fallbackModel") == "sonnet",
     mf.get("onDispatchError") is True,
 ]
 print("ok" if all(checks) else "bad-defaults")
@@ -61,12 +62,19 @@ echo "→ 3. Phase wiring references the contract"
 grep -q "model-fallback.md" "$P0" && ok "phase-0-init wires the date gate" || fail "phase-0-init missing fallback wiring"
 grep -q "model-fallback.md" "$P4" && ok "phase-4-review wires the per-dispatch triggers" || fail "phase-4-review missing fallback wiring"
 
-echo "→ 4. Personas keep fable as preferred (fallback is dispatch-time, not file-time)"
-FABLE_COUNT=$(grep -l "^preferredModel: fable" "$REPO_ROOT"/pipeline/agents/*.md 2>/dev/null | wc -l | tr -d ' ')
-if [ "$FABLE_COUNT" -ge 5 ]; then
-  ok "fable personas intact ($FABLE_COUNT files)"
+echo "→ 4. Personas declare opus as preferred (fallback is dispatch-time, not file-time)"
+OPUS_COUNT=$(grep -l "^preferredModel: opus" "$REPO_ROOT"/pipeline/agents/*.md 2>/dev/null | wc -l | tr -d ' ')
+if [ "$OPUS_COUNT" -ge 5 ]; then
+  ok "opus personas intact ($OPUS_COUNT files)"
 else
-  fail "expected >=5 fable personas, found $FABLE_COUNT"
+  fail "expected >=5 opus personas, found $OPUS_COUNT"
+fi
+# Fable 5 is retired - no persona should still pin it.
+FABLE_LEFT=$(grep -l "^preferredModel: fable" "$REPO_ROOT"/pipeline/agents/*.md 2>/dev/null | wc -l | tr -d ' ')
+if [ "$FABLE_LEFT" -eq 0 ]; then
+  ok "no persona still pins retired fable tier"
+else
+  fail "expected 0 fable personas (fable retired), found $FABLE_LEFT"
 fi
 
 echo ""