@mmerterden/multi-agent-pipeline 8.6.1 → 10.0.6

package/pipeline/commands/multi-agent/refs/phases/phase-3-dev.md

@@ -1,6 +1,35 @@
 ### Phase 3: Dev (Sonnet)
 
-> **TLDR** — Sonnet executes the plan task-by-task with TDD (red→green→refactor). Required: issue-tracker status moved to "In Progress" before any code, with a post-mutation verify step (re-reads the field, retries once on silent VALIDATION failures). Build verification after each task (up to 3 retries). Build-queue lock serializes concurrent xcodebuild. `--dev` mode uses Opus self-contained (no Phase 2 plan required). `taskType === component` **short-circuits the TDD path** and delegates the whole phase to the `figma-to-component` skill — see next subsection.
+> **TLDR**  -  Sonnet executes the plan task-by-task with TDD (red→green→refactor). Required: issue-tracker status moved to "In Progress" before any code, with a post-mutation verify step (re-reads the field, retries once on silent VALIDATION failures). Build verification after each task (up to 3 retries). Build-queue lock serializes concurrent xcodebuild. `--dev` mode uses Opus self-contained (no Phase 2 plan required). `taskType === component` **short-circuits the TDD path** and delegates the whole phase to the `figma-to-component` skill  -  see next subsection.
+
+## Phase 3 Pre-flight (BLOCKING, v9.0.0)
+
+Per Locked decision 30, Phase 3 Dev consumes the analysis document as the sole design source. MCP / Figma REST / Figma URL fetches are forbidden.
+
+Pre-flight steps (run in order, abort on failure):
+
+1. **Analysis document presence**: locate `analysis/<feature-slug>-<platform>.md` for the active platform.
+   - Path resolution: `state.run.repoPath` + `/analysis/<feature>-<platform>.md`
+   - Multi-repo runs: each selected repo MUST have the file under its working tree
+   - **Abort condition**: file missing -> exit with `ERR: analysis doc missing for <platform>. Run /multi-agent:analysis "<feature>" first to generate it.`
+
+2. **Parse YAML front-matter** (the doc has a `template_version: v3` header):
+   - `feature`, `platform`, `language`, `mode (full | lite)`, `evidence_digest`
+   - Persist into `state.analysis.frontMatter`
+   - **Abort condition (v9.0.x strict)**: `template_version` < `v3` -> exit with `ERR: analysis doc is template v<n>; v9 requires v3. Re-run analysis to regenerate.`
+   - **Soft-skip (v9.1.0+, Locked 30)**: when `prefs.global.legacyV2AnalysisAllowed == true` OR env `MULTI_AGENT_LEGACY_V2_ANALYSIS=allow` is set AND `template_version == v2`, emit `WARN: legacy v2 analysis doc detected; v3 expected. Continuing with reduced binding strength.` and persist `state.dev.legacyAnalysisMode = true`. Step 4 (Code Connect lookup) and Step 6 (conventions handoff) still run, but Step 5 (standards binding) and Pass B footnote enforcement degrade to warning level (Phase 4 reviewer flags missing citations rather than blocking). Escape hatch removed in v9.2.0.
+
+3. **Evidence digest match (cache validation)**: if `state.run.lastAnalysisDigest` is present AND matches `frontMatter.evidence_digest`, mark as fresh; otherwise WARN that analysis is stale (continue but flag).
+
+4. **Code Connect mapping lookup**: for each component named in analysis Section 6 (Bileşen Envanteri), search the repo for matching `*.figma.swift` / `*.figma.kt` files. Persist hits to `state.dev.codeConnect[<componentName>]`. Missing mappings are not blockers but the Phase 4 reviewer will flag them.
+
+5. **Standards binding citations**: read `analysis Section 21 References` table. For each row with `Rol: bağlayıcı / binding`, persist the source path into `state.dev.standardsBindings[]`. Phase 3 Dev tasks MUST cite at least one binding source per architectural decision (pre-existing Locked decision 8).
+
+6. **Conventions handoff**: read `analysis Section 13.1 Concept Table` (Pass B output with footnotes). Persist concept-to-realization mapping into `state.dev.conventions[<concept>]`. Phase 3 implementation uses these names verbatim (e.g., if Section 13.1 says "State holder: PassengerFlightViewModel", Phase 3 names the class exactly `PassengerFlightViewModel`).
+
+7. **MCP forbidden**: any attempt to call `mcp__claude_ai_Figma__*` in Phase 3 is a violation. The smoke gate `smoke-no-mcp-in-dev-phases.sh` (see CHANGELOG [9.0.0]) checks `state.telemetry.mcpCalls[]` after run and fails if Phase 3 contributed any entry.
+
+The analysis document is the SOLE design source in Phase 3. Variant choices, padding values, color tokens, copy strings, accessibility identifiers, and test method names all come from the rendered Pass B cells. If something is missing in the analysis doc, the fix is to re-run `/multi-agent:analysis`, not to fetch from Figma.
 
 <!-- progress-contract: applied -->
 
@@ -8,34 +37,34 @@
 
 #### Input contract
 
-Phase 3 consumes the Phase 2 output object conforming to `pipeline/schemas/planning-output.schema.json` — the task graph (`tasks[]` with `id`, `subject`, `targetFiles`, `complexity`, `blockedBy`) plus the architecture review notes. Tasks execute in dependency order; the schema's `blockedBy` field drives the ready-task picker. In `--dev` mode (no Phase 2), Sonnet/Opus generates the equivalent task list inline before entering the loop below.
+Phase 3 consumes the Phase 2 output object conforming to `pipeline/schemas/planning-output.schema.json`  -  the task graph (`tasks[]` with `id`, `subject`, `targetFiles`, `complexity`, `blockedBy`) plus the architecture review notes. Tasks execute in dependency order; the schema's `blockedBy` field drives the ready-task picker. In `--dev` mode (no Phase 2), Sonnet/Opus generates the equivalent task list inline before entering the loop below.
 
-**Plan Todo iteration (opt-in)**: gated by `prefs.global.planTodos.enabled` (default: `false`). When enabled and Phase 2 Step 4.5 emitted a `plan.todos[]`, Phase 3 iterates via `pipeline/lib/plan-todos.sh next/start/complete/fail` instead of walking `tasks[]` directly. When disabled, the loop walks `tasks[]` from `planning-output` — TDD contract is unchanged. Full helper loop + state semantics: `refs/features/plan-todos.md`.
+**Plan Todo iteration (opt-in)**: gated by `prefs.global.planTodos.enabled` (default: `false`). When enabled and Phase 2 Step 4.5 emitted a `plan.todos[]`, Phase 3 iterates via `pipeline/lib/plan-todos.sh next/start/complete/fail` instead of walking `tasks[]` directly. When disabled, the loop walks `tasks[]` from `planning-output`  -  TDD contract is unchanged. Full helper loop + state semantics: `refs/features/plan-todos.md`.
 
 **Shadow-Git checkpoints (opt-in)**: gated by `prefs.global.shadowGit.enabled` (default: `false`). When enabled, the orchestrator snapshots the worktree via `pipeline/lib/shadow-git.sh` so sub-phase rollback is possible without touching the project's real `.git` history. Cline-style. Lifecycle: `shadow-git.sh init` (Phase 0 baseline), `shadow-git.sh snapshot` (per step after `plan-todos complete`), `shadow-git.sh restore <sha> --files` (rollback). Modes: `per-todo-step` (default) or `per-tool-call`. Full wiring + storage cap: `refs/features/shadow-git.md`.
 
-#### Component tasks — delegated dispatch (taskType === "component")
+#### Component tasks  -  delegated dispatch (taskType === "component")
 
-When Phase 0 Step 7 classified the task as `component`, Phase 3 delegates the entire phase to the `figma-to-component` skill under `pipeline/skills/figma-ios/` (iOS) or `pipeline/skills/figma-android/` (Android) and does NOT run the TDD loop below. The orchestrator owns subphases 3.0 – 3.8 and writes them to `state.phases["3"].subphases[]` — multi-agent's `phase-tracker` reads that array with no special case. Dispatch contract, failure/resume semantics, multi-repo report, `--dev` elisions, and cross-CLI requirements live in `refs/component-dispatch.md` — read it before editing component-task behaviour here. Phase 3 still owns: progress line `→ dispatching figma-to-component <name>`, `retryCount` cap at 3, and fallthrough to the TDD path when dispatch prerequisites are missing (`taskType` / `figmaUrl` absent → log anomaly, run TDD).
+When Phase 0 Step 7 classified the task as `component`, Phase 3 delegates the entire phase to the `figma-to-component` skill under `pipeline/skills/figma-ios/` (iOS) or `pipeline/skills/figma-android/` (Android) and does NOT run the TDD loop below. The delegated skill consumes the analysis Section 6 (Bileşen Envanteri) entry + Section 13.1 conventions for the named component; it never re-fetches from Figma in v9.0.0. The orchestrator owns subphases 3.0 - 3.8 and writes them to `state.phases["3"].subphases[]` - multi-agent's `phase-tracker` reads that array with no special case. Dispatch contract, failure/resume semantics, multi-repo report, `--dev` elisions, and cross-CLI requirements live in `refs/component-dispatch.md` - read it before editing component-task behaviour here. Phase 3 still owns: progress line `-> dispatching figma-to-component <name>`, `retryCount` cap at 3, and fallthrough to the TDD path when dispatch prerequisites are missing (`taskType` absent OR analysis Section 6 has no row for the named component -> log anomaly, run TDD).
 
 For non-component taskTypes (`bugfix`, `feature`, `refactor`, `chore`), continue with the standard TDD section below.
 
 #### Re-entry from Phase 4 triage
 
-Phase 3 runs twice in the pipeline lifetime: first for initial development, then optionally for rework after Phase 4 review. **Phase 3 never acts on raw reviewer output.** It only consumes `triage.accepted` findings — Opus triage in Phase 4 already filtered false-positives, deferred out-of-scope items, and rejected noise.
+Phase 3 runs twice in the pipeline lifetime: first for initial development, then optionally for rework after Phase 4 review. **Phase 3 never acts on raw reviewer output.** It only consumes `triage.accepted` findings  -  Opus triage in Phase 4 already filtered false-positives, deferred out-of-scope items, and rejected noise.
 
 When re-entering from Phase 4:
 
-1. Read `state.reviewIterations[-1]` — the latest iteration's **accepted** list.
+1. Read `state.reviewIterations[-1]`  -  the latest iteration's **accepted** list.
 2. For each `accepted` finding where `severity === "blocking"` or `severity === "important"`:
    - Treat it exactly like a Phase 2 plan task (TDD cycle, build verify).
    - Quote the original `issue` + `fix` text in the task description so the dev agent has full context.
 3. `accepted.suggestion` items are applied opportunistically (no TDD loop required) unless the user asked for suggestions to be treated strictly.
-4. `deferred` items are NOT actioned in this re-entry — they surface in Phase 7's "Follow-up items" section.
+4. `deferred` items are NOT actioned in this re-entry  -  they surface in Phase 7's "Follow-up items" section.
 5. `rejected` items are never touched. Log their IDs + triage reasons for audit only.
 6. After rework, increment `state.phases["3"].retryCount`; hard-kill at `retryCount === 3` and escalate to the user. Do not loop indefinitely.
 
-If the latest iteration has `triage.approved === true` AND `accepted === []`, Phase 3 was entered by mistake — log the anomaly and return to Phase 5.
+If the latest iteration has `triage.approved === true` AND `accepted === []`, Phase 3 was entered by mistake  -  log the anomaly and return to Phase 5.
 
 **Telemetry**: at the start of every re-entry, emit:
 
@@ -48,7 +77,7 @@ pipeline/scripts/log-metric.sh "$TASK_ID" 3 rework.started \
 
 For each task (respecting dependency order):
 
-1. **Update task status: `in_progress` (required — do not skip or defer)**
+1. **Update task status: `in_progress` (required  -  do not skip or defer)**
    - **Why mandatory**: the board/tracker visually stays in "Todo" until this runs. Skipping it means reviewers and the rest of the team cannot see that work has started, and automations downstream (status reports, kanban swimlanes) will be wrong.
    - **Where it applies**:
      - Jira: transition issue to "In Progress" via REST API (`/rest/api/2/issue/{id}/transitions`)
@@ -61,16 +90,16 @@ For each task (respecting dependency order):
 2. **Multi-submodule awareness**: If the project has submodules (detected in Phase 0 Step 7), development may span multiple submodules. For example, a UI component might need:
    - New types/tokens in the **common** submodule
    - The component itself in the **uicomponents** submodule
-   - Work in BOTH submodules in the same task — this is normal and expected
+   - Work in BOTH submodules in the same task  -  this is normal and expected
 3. **TDD cycle** (Launch Agent with `model: "sonnet"`):
 
-   **RED — Write ONE failing test first:**
+   **RED  -  Write ONE failing test first:**
    - Test framework: use whatever the project already uses. Detect from existing test files:
      - `@Test` / `#expect` → Swift Testing
      - `XCTestCase` / `XCTAssert` → XCTest
      - `describe` / `it` → Quick/Nimble
    - Test naming: `test{Scenario}_{Expected}` (e.g. `testKeychainReturnsNil_doesNotCrash`)
-   - One test per behavior change — not one test per file
+   - One test per behavior change  -  not one test per file
    - Run test to confirm RED:
      ```bash
      acquire_build_lock "$TASK_ID"
@@ -84,8 +113,8 @@ For each task (respecting dependency order):
      ```
    - Must fail for the RIGHT reason (expected assertion, not compilation error)
 
-   **GREEN — Minimal code to pass:**
-   - Smallest change that makes the test green — no extras
+   **GREEN  -  Minimal code to pass:**
+   - Smallest change that makes the test green  -  no extras
    - Run the same test again → must PASS
    - Run full test suite → no regressions:
      ```bash
@@ -120,7 +149,7 @@ For each task (respecting dependency order):
 
 4. **Build verification with queue lock** (see Build Queue section below):
 
-   **Preferred — MCP tool (token-efficient, dev-toolkit-mcp ≥ 2.3.0):**
+   **Preferred  -  MCP tool (token-efficient, dev-toolkit-mcp ≥ 2.3.0):**
    ```
    acquire_build_lock "$TASK_ID"
    mcp__dev_toolkit__ios_xcodebuild({
@@ -134,7 +163,7 @@ For each task (respecting dependency order):
    ```
    Returns one line: `Build: SUCCESS|FAILURE (E errors, W warnings) [xcresult-<id>]`. On failure, drill in only when needed via `mcp__dev_toolkit__ios_xcresult({id, mode: "errors"})`. Saves thousands of tokens per build cycle vs. raw xcodebuild output.
 
-   **Fallback — raw xcodebuild** (when MCP server is unavailable):
+   **Fallback  -  raw xcodebuild** (when MCP server is unavailable):
    ```bash
    acquire_build_lock "$TASK_ID"
    xcodebuild build \
@@ -144,21 +173,21 @@ For each task (respecting dependency order):
      2>&1 | tail -5
    release_build_lock
    ```
-5. If build fails → fix → rebuild (max 3 attempts, track `retryCount` in state). With MCP path: pass the captured xcresult ID to `ios_xcresult` mode `errors` first, then `warnings` only if needed — never dump full log into context.
+5. If build fails → fix → rebuild (max 3 attempts, track `retryCount` in state). With MCP path: pass the captured xcresult ID to `ios_xcresult` mode `errors` first, then `warnings` only if needed  -  never dump full log into context.
 6. **Intermediate commit** (after each completed task in the plan):
    ```bash
    git -C "{worktreePath}" add -A
    git -C "{worktreePath}" commit -m "wip({scope}): {task summary} [{jiraId}]"
    ```
    WIP commits are squashed in Phase 6 before PR. This prevents work loss if a later task fails or the session crashes.
-7. Update task status: `completed` (apply the same verify rule — re-read the Status field and retry once on mismatch)
-8. Log: "Phase 3: {task} — Test + Build passed"
+7. Update task status: `completed` (apply the same verify rule  -  re-read the Status field and retry once on mismatch)
+8. Log: "Phase 3: {task}  -  Test + Build passed"
 
 ---
 
 #### Build Queue (parallel task serialization)
 
-**Problem**: Multiple parallel worktrees may reach build/test phase simultaneously. `xcodebuild` cannot run in parallel — DerivedData, simulators, and project locks cause conflicts.
+**Problem**: Multiple parallel worktrees may reach build/test phase simultaneously. `xcodebuild` cannot run in parallel  -  DerivedData, simulators, and project locks cause conflicts.
 
 **Solution**: Lock-file based queue using `mkdir` atomicity. Before ANY `xcodebuild` call, acquire the lock; release after completion.
 
@@ -170,7 +199,7 @@ acquire_build_lock() {
   while ! mkdir "$BUILD_LOCK" 2>/dev/null; do
     OWNER=$(cat "$BUILD_LOCK/owner" 2>/dev/null || echo "unknown")
     LOCK_AGE=$(( $(date +%s) - $(stat -f "%m" "$BUILD_LOCK/owner" 2>/dev/null || echo 0) ))
-    [ "$LOCK_AGE" -gt 900 ] && { echo "Stale lock (${LOCK_AGE}s) — removing"; rm -rf "$BUILD_LOCK"; continue; }
+    [ "$LOCK_AGE" -gt 900 ] && { echo "Stale lock (${LOCK_AGE}s)  -  removing"; rm -rf "$BUILD_LOCK"; continue; }
     echo "Build queue: waiting ($OWNER, ${LOCK_AGE}s)"; sleep 5
   done
   echo "$TASK_ID" > "$BUILD_LOCK/owner"
@@ -186,7 +215,7 @@ release_build_lock() { rm -rf "$BUILD_LOCK"; }
 - Lock path: `/tmp/claude-xcodebuild.lock` (shared across all Claude instances)
 - Stale lock timeout: 15 minutes (auto-cleanup if a session crashes)
 - Each worktree uses its OWN `-derivedDataPath` to avoid cache poisoning
-- `sleep 5` between retries — not aggressive polling
+- `sleep 5` between retries  -  not aggressive polling
 - Lock owner tracked for visibility: which task is currently building
 
 **This applies to ALL xcodebuild calls in the pipeline:**
@@ -195,24 +224,50 @@ release_build_lock() { rm -rf "$BUILD_LOCK"; }
 - Phase 4 Step 1 Gate 1 (build gate before review)
 - Phase 4 Step 1 Gate 3 (test gate before review)
 
-**Non-Xcode projects** (Python, Node.js): No lock needed — these can build/test in parallel without conflicts.
+**Non-Xcode projects** (Python, Node.js): No lock needed  -  these can build/test in parallel without conflicts.
+
+---
+
+#### Step 3.5  -  Dev Critic (Evaluator-Optimizer, opt-in)
+
+Gated by `prefs.global.devCritic.enabled` (default: `false`). When enabled, after the generator's last edit and BEFORE Phase 4: dispatch `dev-critic` sub-agent (Sonnet), run 4 deterministic gates (build / lint / test / secrets), then platform checklist. STRICT loop cap  -  **max 2 iterations** (round 2 re-checks round-1 failures only); round 3+ returns `escalate: true`. Severity routing: `blocking` → generator must fix; `important` → SHOULD fix or pass through to Phase 4; `suggestion` → generator's judgement. Full agent contract, schema, telemetry, when-to-enable: `refs/features/dev-critic.md` + `pipeline/agents/dev-critic.md`.
 
 ---
 
-#### Step 3.5 — Dev Critic (Evaluator-Optimizer, opt-in)
+#### Step 3.6  -  Code-simplifier pass (required diff shrink, before Phase 4 handoff)
+
+After the build/test green step and BEFORE Phase 4 handoff, run one diff-shrink round (bloated diffs waste Phase 4 reviewer tokens and unfocus the PR).
+
+1. **Dispatch ONE subagent** (`subagent_type: "general-purpose"`, model: `sonnet`); input is ONLY the working diff (`git -C "$WORKTREE" diff "origin/$BASE_BRANCH"...HEAD`) + task summary. No correctness re-review (Phase 4's job), no new features. Exactly four smells:
+   - **Comment bloat**  -  comments restating code, scaffolding notes, TODO chatter
+   - **Unrelated rewrites**  -  hunks outside task scope (re-formatting, unrequested rename sweeps)
+   - **Dead code**  -  unused symbols, unreachable branches, commented-out blocks from this diff
+   - **Over-abstraction**  -  single-call-site protocols/wrappers/helpers from this diff
+
+   Progress line: `    → dispatching code-simplifier diff-shrink`
+2. **Return contract**  -  a list of shrink edits `{ "file", "lines", "edit", "rationale", "risk": "safe|unsafe" }`; the subagent never writes files.
+3. **Apply safe edits only**  -  skip `unsafe` (logged). Zero edits is normal  -  log and continue. Progress line: `    → applying shrink edits ({N} applied, {M} skipped)`
+4. **Re-run build + tests** (same build-queue lock + evidence-gate rule as Step 4). Any breakage -> revert shrink edits wholesale and proceed pre-shrink; the simplifier must never cost a green state.
+5. **Record tokens in the cost ledger** so Phase 7's Cost Breakdown captures the pass:
 
-Gated by `prefs.global.devCritic.enabled` (default: `false`). When enabled, after the generator's last edit and BEFORE Phase 4: dispatch `dev-critic` sub-agent (Sonnet), run 4 deterministic gates (build / lint / test / secrets), then platform checklist. STRICT loop cap — **max 2 iterations** (round 2 re-checks round-1 failures only); round 3+ returns `escalate: true`. Severity routing: `blocking` → generator must fix; `important` → SHOULD fix or pass through to Phase 4; `suggestion` → generator's judgement. Full agent contract, schema, telemetry, when-to-enable: `refs/features/dev-critic.md` + `pipeline/agents/dev-critic.md`.
+```bash
+LOG_METRIC_FORWARD_TO_TRACKER=1 pipeline/scripts/log-metric.sh "$TASK_ID" 3 dev.simplifier_pass \
+  model=sonnet tokens_in=$IN tokens_out=$OUT duration_ms=$DUR \
+  edits_returned=$RET edits_applied=$APPLIED edits_skipped=$SKIPPED
+```
+
+Scope guard: a single pass, never looped. Runs in `--dev` mode too; component tasks (`taskType === "component"`) skip it (the figma skill owns its own checklist).
 
 ---
 
 #### Dev-Only Mode (`--dev`)
 
-When `agent-state.json.onlyDevelop === true`, Phase 3 runs self-contained with **Opus** (not Sonnet). No Phase 2 plan exists — the agent creates its own scope.
+When `agent-state.json.onlyDevelop === true`, Phase 3 runs self-contained with **Opus** (not Sonnet). No Phase 2 plan exists  -  the agent creates its own scope.
 
 **Flow:**
 1. Read task description (from Jira, GitHub issue, or free-text)
-2. Lightweight file scan — grep/glob for relevant code (not full Explore agents)
-3. Determine scope autonomously — no task breakdown, no user confirmation
+2. Lightweight file scan  -  grep/glob for relevant code (not full Explore agents)
+3. Determine scope autonomously  -  no task breakdown, no user confirmation
 4. Implement with TDD cycle (same RED→GREEN→REFACTOR as normal mode)
 5. Build verification (same lock, same retry logic)
 6. Intermediate commits (same WIP pattern)
@@ -233,7 +288,7 @@ When `agent-state.json.onlyDevelop === true`, Phase 3 runs self-contained with *
 
 #### v2.1.0+ Multi-Repo Mode
 
-Active when `state.projects[].length > 1` (set by Phase 0 multi-select). Single-repo flow above is preserved verbatim — this section adds the deltas.
+Active when `state.projects[].length > 1` (set by Phase 0 multi-select). Single-repo flow above is preserved verbatim  -  this section adds the deltas.
 
 **Todo tagging**: Phase 2 plan items in multi-repo mode carry a `repo` field naming the target project root. The dev agent uses this tag to dispatch each todo:
 
@@ -249,19 +304,27 @@ Active when `state.projects[].length > 1` (set by Phase 0 multi-select). Single-
 
 If a todo has no `repo` tag in multi-repo mode → log warning + ask user, do not auto-pick.
 
-**Per-todo worktree switch**: Before each todo's TDD cycle, resolve `WT_PATH = state.projects[ findIndex(name === todo.repo) ].worktreePath` and run **all** subsequent commands with `git -C "$WT_PATH"` and `cd "$WT_PATH"` for build/test. Identity (`user.name`/`user.email`) was already pinned per worktree by Phase 0 Step 8 — no re-config needed here.
+**Per-todo worktree switch**: Before each todo's TDD cycle, resolve `WT_PATH = state.projects[ findIndex(name === todo.repo) ].worktreePath` and run **all** subsequent commands with `git -C "$WT_PATH"` and `cd "$WT_PATH"` for build/test. Identity (`user.name`/`user.email`) was already pinned per worktree by Phase 0 Step 8  -  no re-config needed here.
 
-**Status update (single ticket, multi-repo)**: The Jira/GitHub issue is shared across all repos in the group — call the status-update API exactly **once per todo** (not once per repo per todo). The post-mutation verify rule still applies.
+**Status update (single ticket, multi-repo)**: The Jira/GitHub issue is shared across all repos in the group  -  call the status-update API exactly **once per todo** (not once per repo per todo). The post-mutation verify rule still applies.
 
 **Build serialization**:
-- Xcode worktrees still share `BUILD_LOCK = /tmp/claude-xcodebuild.lock` — multi-repo just means more callers contending for the same lock; the existing `mkdir`-based queue handles it correctly.
-- Non-Xcode repos may build in parallel across worktrees — but ONLY when builds are independent. If repo B's build depends on repo A's freshly-published artifact (e.g. SPM local path dependency), serialize them in dependency order. Plan items declare dependencies via Phase 2's `dependsOn` field; multi-repo dispatch respects that order.
+- Xcode worktrees still share `BUILD_LOCK = /tmp/claude-xcodebuild.lock`  -  multi-repo just means more callers contending for the same lock; the existing `mkdir`-based queue handles it correctly.
+- Non-Xcode repos may build in parallel across worktrees  -  but ONLY when builds are independent. If repo B's build depends on repo A's freshly-published artifact (e.g. SPM local path dependency), serialize them in dependency order. Plan items declare dependencies via Phase 2's `dependsOn` field; multi-repo dispatch respects that order.
 
 **Failure isolation**: A build/test failure in one repo's worktree must NOT silently leave the other repos in a half-built state. On failure:
 1. Capture the failure into `state.projects[i].buildStatus = { ok: false, attempts: N, lastError: "..." }`
 2. The ENTIRE Phase 3 retries within that repo's worktree (max 3, same as single-repo)
 3. After 3 attempts, escalate; do NOT proceed to Phase 4 with any unbuilt repo
 
+**Recording a pass (default-FAIL evidence gate):** before setting `buildStatus.ok = true`, the build output must be tee'd to a log and that log must substantiate the success  -  a zero exit code alone is not trusted. Run the evidence gate; on exit 1, do NOT record a pass:
+```bash
+<build-command> 2>&1 | tee "$WORKTREE/.build.log"
+node pipeline/scripts/evidence-gate.mjs --claim build --status passed --evidence "$WORKTREE/.build.log" \
+  || { echo "build pass unverified  -  treat as failure"; /* keep buildStatus.ok=false */ }
+```
+This closes the gap where an agent records "built" without ever producing build output.
+
 **Telemetry**: Per-repo metrics in addition to per-task metrics:
 ```bash
 pipeline/scripts/log-metric.sh "$TASK_ID" 3 build.completed repo=common duration_ms=$D status=ok
@@ -280,7 +343,7 @@ Model resolves from the active mode: full pipeline runs Sonnet, `--dev` modes ru
 
 ---
 
-## Token telemetry — invoke after every LLM call
+## Token telemetry  -  invoke after every LLM call
 
 After every LLM call in this phase (analysis, plan generation, code/diff write, review verdict, triage), invoke:
 
@@ -290,4 +353,4 @@ bash $HOME/.claude/scripts/phase-tracker.sh tokens 3 <input_count> <output_count
 
 The tracker accumulates the totals additively, so multiple calls in the same phase compound. The render output then shows live cost on the active phase tile (e.g. `Phase 3  Dev   2m 14s · 12.4k tok`). This satisfies the contract in `refs/tracker-contract.md` and the `smoke-tracker-tokens-invocation.sh` enforcement gate. Skipping this call is the #1 cause of "I can't see how much it cost" complaints.
 
-If you do not have access to the model's reported token counts, pass best-effort estimates derived from input length / output length — partial cost data is better than none.
+If you do not have access to the model's reported token counts, pass best-effort estimates derived from input length / output length  -  partial cost data is better than none.