@mmerterden/multi-agent-pipeline 8.6.0

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

@@ -0,0 +1,364 @@
+### 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.
+
+<!-- progress-contract: applied -->
+
+**Progress (per `refs/progress-contract.md`):** every non-trivial step emits one `→ <verb> <object>` line at immediate flush. Canonical set for standard TDD: `→ reading <file>`, `→ writing test <name>`, `→ running xcodebuild RED`, `→ writing code <file>`, `→ running xcodebuild GREEN`, `→ committing WIP <summary>`. Component-task dispatch emits the line `→ dispatching figma-to-component <componentName>` immediately before the delegation call and then relays the orchestrator's subphase lines verbatim under indent `    →`.
+
+#### 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.
+
+**Plan Todo iteration (opt-in)**: when `prefs.global.planTodos.enabled` is true and Phase 2 Step 4.5 emitted a `plan.todos[]` (conforming to `pipeline/schemas/plan-todos.schema.json`), Phase 3 iterates with the helper instead of walking `tasks[]` directly:
+
+```bash
+while next=$(bash "$HOME/.claude/lib/plan-todos.sh" next "$TASK_ID"); [ -n "$next" ]; do
+  id=$(printf '%s' "$next" | cut -f1)
+  task=$(printf '%s' "$next" | cut -f2)
+  bash "$HOME/.claude/lib/plan-todos.sh" start "$TASK_ID" "$id"
+  # ... TDD cycle for "$task" ...
+  if build_passed; then
+    bash "$HOME/.claude/lib/plan-todos.sh" complete "$TASK_ID" "$id" "${COMMIT_HASH} · tests:${TEST_COUNT}"
+  else
+    bash "$HOME/.claude/lib/plan-todos.sh" fail "$TASK_ID" "$id" "build failed after 3 retries"
+    break
+  fi
+done
+```
+
+When disabled, the loop still walks `tasks[]` from `planning-output` — `plan-todos.sh` adds visibility (status, notes, deps-respecting `next`) but the underlying TDD contract is unchanged.
+
+**Shadow-Git checkpoints (opt-in)**: when `prefs.global.shadowGit.enabled` is true, the orchestrator snapshots the worktree via `pipeline/lib/shadow-git.sh` so sub-phase rollback is possible without polluting the project's real `.git` history. Pattern source: Cline checkpoints (<https://docs.cline.bot/features/checkpoints>).
+
+```bash
+# Phase 0 (one-time per task): initialize shadow repo + baseline snapshot.
+bash "$HOME/.claude/lib/shadow-git.sh" init "$TASK_ID" "$WORKTREE"
+
+# Per-step (mode: per-todo-step — default): snapshot AFTER each plan-todos
+# step completes successfully, so restore lands on a known-good state.
+bash "$HOME/.claude/lib/plan-todos.sh" complete "$TASK_ID" "$id" "$notes"
+bash "$HOME/.claude/lib/shadow-git.sh" snapshot "$TASK_ID" "$WORKTREE" "step $id: $task"
+
+# Per-mutation (mode: per-tool-call): the orchestrator hooks into every Edit/
+# Write/MultiEdit/Bash-mutation tool call. Higher fidelity, ~50ms × tool-call
+# overhead — recommended only for security-critical paths or experimental
+# refactors where the user values fine-grained rollback over speed.
+
+# Rollback on demand (interactive helper):
+bash "$HOME/.claude/lib/shadow-git.sh" list "$TASK_ID"
+bash "$HOME/.claude/lib/shadow-git.sh" restore "$TASK_ID" "$WORKTREE" <sha> --files
+```
+
+Shadow repo location: `~/.claude/state/shadow-git/<task-id>/.git/`. Storage cap: `prefs.shadowGit.pruneAfterDays` (default 14). `/multi-agent:purge` honors this prune; manual cleanup via `shadow-git.sh prune <task-id>`.
+
+#### 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).
+
+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.
+
+When re-entering from Phase 4:
+
+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.
+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.
+
+**Telemetry**: at the start of every re-entry, emit:
+
+```bash
+pipeline/scripts/log-metric.sh "$TASK_ID" 3 rework.started \
+  iteration=$ITERATION accepted_blocking=$BLOCKING accepted_important=$IMPORTANT
+```
+
+---
+
+For each task (respecting dependency order):
+
+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`)
+     - GitHub Projects V2: `updateProjectV2ItemFieldValue` on the Status field (singleSelectOptionId)
+     - Internal state: `agent-state.json` → `phases["3"].status = "in_progress"`
+   - **Post-update verify** (catches silent VALIDATION errors from stale option IDs after board rebuilds):
+     - Re-read the Status field after mutation.
+     - If the value is NOT `In Progress` (Jira) / `In Develop` (Projects V2), re-fetch current option IDs and retry ONCE.
+     - If verify still fails after retry → log error, do NOT proceed to TDD. The mutation silently failed and continuing would leave the task mis-tracked.
+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
+3. **TDD cycle** (Launch Agent with `model: "sonnet"`):
+
+   **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
+   - Run test to confirm RED:
+     ```bash
+     acquire_build_lock "$TASK_ID"
+     xcodebuild test \
+       -scheme "{scheme}" \
+       -destination "platform=iOS Simulator,name={simulator}" \
+       -derivedDataPath "{worktreePath}/.DerivedData" \
+       -only-testing:"{testTarget}/{testClass}/{testMethod}" \
+       2>&1 | tail -5
+     release_build_lock
+     ```
+   - 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
+   - Run the same test again → must PASS
+   - Run full test suite → no regressions:
+     ```bash
+     acquire_build_lock "$TASK_ID"
+     xcodebuild test \
+       -scheme "{scheme}" \
+       -destination "platform=iOS Simulator,name={simulator}" \
+       -derivedDataPath "{worktreePath}/.DerivedData" \
+       2>&1 | tail -20
+     release_build_lock
+     ```
+
+   **REFACTOR (if needed):**
+   - Only if duplication or naming is poor
+   - Re-run tests after refactor → still GREEN
+
+   **Scheme + destination resolution** (auto-detect once per project, cache in `agent-state.json`):
+   ```bash
+   # List available schemes
+   xcodebuild -list -json -project "{projectPath}" 2>/dev/null \
+     || xcodebuild -list -json -workspace "{workspacePath}" 2>/dev/null
+   # Pick: prefer scheme matching project name, then first non-test scheme
+   
+   # Available simulators
+   xcrun simctl list devices available -j | jq '.devices | to_entries[] | select(.key | contains("iOS")) | .value[0].name'
+   ```
+
+   **Non-Xcode projects:**
+   - Python: `pytest {test_file}::{test_name}` → `pytest`
+   - Node.js: `npm test -- --testPathPattern={file}` → `npm test`
+   - Android: `./gradlew test --tests "{testClass}.{testMethod}"` → `./gradlew test`
+
+4. **Build verification with queue lock** (see Build Queue section below):
+
+   **Preferred — MCP tool (token-efficient, dev-toolkit-mcp ≥ 2.3.0):**
+   ```
+   acquire_build_lock "$TASK_ID"
+   mcp__dev_toolkit__ios_xcodebuild({
+     project: "{projectPath}",        // or workspace
+     scheme: "{scheme}",
+     configuration: "Release",
+     destination: "generic/platform=iOS",
+     derived_data_path: "{worktreePath}/.DerivedData"
+   })
+   release_build_lock
+   ```
+   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):
+   ```bash
+   acquire_build_lock "$TASK_ID"
+   xcodebuild build \
+     -scheme "{scheme}" \
+     -destination "generic/platform=iOS" \
+     -derivedDataPath "{worktreePath}/.DerivedData" \
+     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.
+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"
+
+---
+
+#### 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.
+
+**Solution**: Lock-file based queue using `mkdir` atomicity. Before ANY `xcodebuild` call, acquire the lock; release after completion.
+
+```bash
+BUILD_LOCK="/tmp/claude-xcodebuild.lock"
+
+acquire_build_lock() {
+  local TASK_ID="${1:-unknown}"
+  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; }
+    echo "Build queue: waiting ($OWNER, ${LOCK_AGE}s)"; sleep 5
+  done
+  echo "$TASK_ID" > "$BUILD_LOCK/owner"
+}
+
+release_build_lock() { rm -rf "$BUILD_LOCK"; }
+```
+
+**Usage**: `acquire_build_lock "{jiraId}"` → `xcodebuild -derivedDataPath "{worktreePath}/.DerivedData" ...` → `release_build_lock`
+
+**Key details:**
+
+- 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
+- Lock owner tracked for visibility: which task is currently building
+
+**This applies to ALL xcodebuild calls in the pipeline:**
+
+- Phase 3 Step 4 (build after development)
+- 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.
+
+---
+
+#### Step 3.5 — Dev Critic (Evaluator-Optimizer, opt-in)
+
+**Pattern**: Anthropic's evaluator-optimizer from "Building Effective Agents" (Dec 2024). Generator (Phase 3 Dev) and critic (`agents/dev-critic.md`) loop on deterministic criteria already written in `rules/*.md` before any Phase 4 reviewer call.
+
+**Gated by `prefs.global.devCritic.enabled`** (default: `false`). When enabled, after the generator's last edit and BEFORE Phase 4:
+
+1. Dispatch `dev-critic` sub-agent (Sonnet by default, tools: `Read, Grep, Glob, Bash`).
+2. Critic runs 4 mandatory deterministic gates (build / lint / test / secrets) — failure of any → `pass: false` with `blocking` finding.
+3. If gates green, critic walks the platform checklist (iOS 13-item / Android Kotlin / Backend generic — selected by Phase 1 `detectedStack`).
+4. Returns schema-validated JSON (`pipeline/schemas/dev-critic-output.schema.json`): `{pass, iteration, gates, findings[], escalate}`.
+
+**Loop cap (STRICT)**: max **2** iterations.
+
+| Round | Behavior |
+|---|---|
+| 1 | Full critic pass — all gates + full checklist |
+| 2 | Re-check only round-1 failures. No new findings allowed (scope creep prevention) |
+| 3+ | NOT ALLOWED. Critic returns `escalate: true`; orchestrator pauses (interactive) or proceeds to Phase 4 with logged failure (autopilot) |
+
+**Action by severity:**
+
+- `blocking` → generator MUST fix; another Dev iteration before re-critic
+- `important` → generator SHOULD fix; if skipped, pass through to Phase 4 (legitimate reviewer ground)
+- `suggestion` → generator's judgement; never blocks round 2
+
+**Telemetry**: each critic call emits `dev_critic.call` with `iteration`, `pass`, `gates_failed`, `blocking`, `important`, `duration_ms`, `tokens_in/out`. Phase 7 cost rollup lists these as `phase 3.5` line items so the net saving (Phase 4 reviewer/triage calls avoided) is measurable.
+
+**Off by default reason**: introduces ~1× Sonnet call per Dev iteration. On simple bug fixes the cost outweighs the benefit (Phase 4 would have caught the same thing for similar cost). Recommended on:
+
+- Feature work (≥200 LOC diff)
+- Security-touching paths (auth, keychain, network)
+- Multi-file refactors where rule violations compound
+
+**Reference**: see `pipeline/agents/dev-critic.md` for the full agent specification (mandatory gates, checklist enumeration, output schema, severity semantics).
+
+**Why this fits orchestrator-workers + evaluator-optimizer hybrid**: Phase 4 is parallelization-with-voting — good for *adversarial* perspectives (security, architecture). Phase 3.5 is evaluator-optimizer — good for *deterministic* criteria (build, tests, checklists). Sending failing builds into Phase 4 wastes 2–3 reviewer calls + Opus triage; Phase 3.5 absorbs that cost at one Sonnet call.
+
+---
+
+#### 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.
+
+**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
+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)
+
+**Key differences from normal mode:**
+
+| Aspect | Normal | Dev-Only |
+|--------|--------|----------|
+| Model | Sonnet | **Opus** |
+| Plan source | Phase 2 task list | Self-determined |
+| Task granularity | Per-plan-item | Agent decides |
+| Status updates | Per task item | Single in_progress → completed |
+| Scope confirmation | Phase 2 user approval | None (agent autonomous) |
+
+**Combinable with autopilot**: `--dev autopilot` = zero interaction. Init → Dev → auto-commit → auto-PR → Report.
+
+---
+
+#### 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.
+
+**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:
+
+```json
+{
+  "id": "T-3",
+  "title": "Add tokenResolver public API",
+  "repo": "common",                         // ← matches state.projects[i].name
+  "files": ["Sources/Common/TokenResolver.swift"],
+  "tdd": { "test": "...", "code": "..." }
+}
+```
+
+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.
+
+**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.
+
+**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
+
+**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
+pipeline/scripts/log-metric.sh "$TASK_ID" 3 build.completed repo=uicomponents duration_ms=$D status=ok
+```
+
+**Token forwarding:** every TDD round (red, green, refactor) that hits the dev model MUST forward token totals into the tracker so Phase 7's Cost Breakdown captures Phase 3:
+
+```bash
+LOG_METRIC_FORWARD_TO_TRACKER=1 pipeline/scripts/log-metric.sh "$TASK_ID" 3 dev.tdd_round \
+  model=<sonnet|opus> step=<red|green|refactor> \
+  tokens_in=$IN tokens_out=$OUT duration_ms=$DUR
+```
+
+Model resolves from the active mode: full pipeline runs Sonnet, `--dev` modes run Opus. Best-effort. See `refs/progress-contract.md#token-telemetry-forwarding-v83`.
+
+---
+
+## Token telemetry — invoke after every LLM call
+
+After every LLM call in this phase (analysis, plan generation, code/diff write, review verdict, triage), invoke:
+
+```bash
+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.