@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/commands/multi-agent/refs/phases/phase-7-report.md

@@ -0,0 +1,361 @@
+### Phase 7: Report
+
+> **TLDR** — Close the loop in two halves: **External delivery** delegated to `/multi-agent:channels` (multi-select kanal + content — always pauses in autopilot, 30-min timeout ends session). **Internal capture** stays inline: `agent-log.md` finalization, telemetry emission, knowledge base + memory update. Channels command is the single source of truth for Jira/Confluence/Wiki/PR-description delivery — full contract in `commands/multi-agent/channels.md`.
+
+<!-- progress-contract: applied -->
+Progress emission per `refs/progress-contract.md` — lines for channels dispatch entry, per-adapter result, agent-log finalization, telemetry emission, knowledge+memory write.
+
+## Sub-step Tracking (required)
+
+Phase 7 has **3 ordered sub-steps** (reduced from 5 in v5.7 — external delivery consolidated under channels). Register all of them in the tracker at Phase 7 entry.
+
+```bash
+bash ~/.claude/scripts/phase-tracker.sh update 7 in_progress
+for s in 1:Channels-Dispatch 2:Log+Telemetry 3:Knowledge+Memory; do
+  bash ~/.claude/scripts/phase-tracker.sh sub 7 "${s%%:*}" "${s#*:}" pending
+done
+```
+
+On entry: `phase-tracker.sh sub 7 <N> "<name>" in_progress`. On exit: `completed` / `failed` / `skipped` / `timeout`.
+
+---
+
+## Autopilot pause contract
+
+Phase 7 is the single exception to the autopilot zero-interaction rule. Full contract in `refs/phases/modes.md`:
+
+- **Normal / `--dev` / `autopilot`** — ALL modes pause at the channels multi-select menu.
+- **30-min timeout** — if user does not respond, session ends cleanly. External delivery is aborted (no silent apply of defaults — prevents accidental Jira comments / Confluence pages). Internal capture (Steps 2 + 3 below) STILL runs so `agent-log.md` + knowledge base are persisted.
+- **Resumable** — state written as `{phase: 7, waitingFor: "user-channels-choice", channelsInput: <state-bundle>}`. User can `/multi-agent:resume <task-id>` any time later; channels menu re-opens with same inputs.
+- **Timeout log line:** `Phase 7: channels menu timeout (30 min) — session ended, resume with /multi-agent:resume {taskId}`.
+
+---
+
+## Step 1 — External Delivery (delegated to channels)
+
+Phase 7 builds a state bundle and invokes `/multi-agent:channels` (Claude Code) or `multi-agent-channels` (Copilot CLI). This is the ONLY external-delivery step — no inline Jira/Confluence/Wiki/PR-description logic lives in Phase 7 any more.
+
+> **Local-only short-circuit**: when `state.offlineOnly == true` (all repos
+> are local — see Phase 0), Step 1 is **skipped entirely**. No channels menu,
+> no Jira/Wiki/Confluence/PR adapters, no autopilot pause. The tracker
+> records `step1.status = "skipped-offline"` and the run jumps straight to
+> the internal capture sub-steps (agent-log finalization, telemetry,
+> knowledge/memory write). The pipeline's only "report" for a local-only
+> run is the agent-log on disk at `$HOME/.claude/logs/multi-agent/<repo>/<taskId>/agent-log.md`.
+
+### State bundle passed to channels
+
+```json
+{
+  "jiraId": "PROJ-12345",
+  "prUrl": "https://.../pull/42",
+  "prNumber": 42,
+  "remoteType": "github" | "bitbucket",
+  "taskType": "component" | "bugfix" | "feature" | "refactor",
+  "figmaConfig": { /* from project figma-config.json, or null */ },
+  "agentState": { /* agent-state.json contents */ },
+  "pipelineLogPath": "$HOME/.claude/logs/multi-agent/<project>/<task-id>/agent-log.md",
+  "invokedFrom": "phase-7"
+}
+```
+
+Channels command reads this bundle, skips its own target-resolution step, goes straight to the multi-select menu.
+
+### Menu (identical to post-hoc `/channels` call — single source of truth)
+
+```
+Kanallar: [x] PR  [x] Jira  [ ] Confluence  [ ] Wiki
+İçerik:   [x] Normal analiz  [x] Test senaryoları  [ ] Auto-diff  [ ] Manuel not
+```
+
+Pre-ticks from `prefs.global.reportChannels` + `prefs.global.reportContent`. Greyed-out rules (pipeline context, PR linked, taskType=component, wiki.enabled) per `channels.md` Step 3.
+
+**User selects → channels dispatches → returns per-adapter results. Phase 7 records outcomes into tracker + summary block.**
+
+### Per-adapter outcomes (from channels return)
+
+```json
+{
+  "pr":         { "status": "posted|skipped|failed", "url": "...", "version": "3→4" },
+  "jira":       { "status": "posted|skipped|failed", "url": "...", "commentId": "2484780" },
+  "confluence": { "status": "posted|skipped|failed", "url": "..." },
+  "wiki":       { "status": "posted|skipped|failed", "paths": [...], "adapter": "github-wiki" }
+}
+```
+
+Tracker: `phase-tracker.sh sub 7 1 "Channels dispatch" completed` (or `failed` if ALL adapters failed; `skipped` if user declined all).
+
+---
+
+## Step 1.5 — GitHub Issue channel (when tracker is a GitHub issue)
+
+Runs only when `state.tracker.kind === "github-issue"`. The Issue adapter is mandatory whenever the run was triggered from a GitHub issue — no exceptions, no "I'll just update the flags" shortcut. Full template + rules: `refs/channels/issue-comment.md`.
+
+Two paired actions, in order:
+
+```bash
+# 1. Post the canonical comment (template per refs/channels/issue-comment.md).
+bash ~/.claude/scripts/phase-tracker.sh sub 7 1.5 "Issue comment" in_progress
+gh issue comment "$ISSUE_NUMBER" --repo "$ORG/$REPO" --body-file /tmp/channels-${TASK_ID}-issue.md
+bash ~/.claude/scripts/phase-tracker.sh sub 7 1.5 "Issue comment" completed
+
+# 2. Sync the Progress flag table from agent-state.json. Idempotent — the
+#    script no-ops if the body already matches.
+bash ~/.claude/scripts/phase-tracker.sh sub 7 1.6 "Progress flag sync" in_progress
+bash ~/.claude/scripts/update-issue-progress.sh "$TASK_ID"
+bash ~/.claude/scripts/phase-tracker.sh sub 7 1.6 "Progress flag sync" completed
+```
+
+Order matters: comment first (timestamp marks the run), flags second (one logical body diff). If the comment fails, do NOT update flags — the channel is incomplete and the user needs to retry.
+
+The Progress flag values come from `state.flags`:
+
+| state.flags key | Issue table label |
+|---|---|
+| `implementation` | Implementation |
+| `testing`        | Testing        |
+| `codeConnect`    | Code Connect   |
+| `wiki`           | Wiki           |
+
+Each value is `true` (🟢), `"yellow"` (🟡), or `false`/missing (⚪). Phase 3 / 5 / 6 are responsible for setting these honestly — Phase 7 only mirrors what's already in state.
+
+**Hard rule (per `refs/channels/issue-comment.md`):** never run only one of the two actions. The comment is the human-readable audit; flags are the machine-readable status. Either both or neither.
+
+---
+
+## Step 2 — Finalize Report (internal)
+
+Write `agent-log.md` with ALL sections:
+
+```markdown
+# {jiraId} — {Task Title}
+
+**Branch**: {branch-name} | **Project**: {project}
+**Started**: {datetime} | **Finished**: {datetime} | **Status**: Complete
+
+## Plan Todo Rollup (when `prefs.global.planTodos.enabled`)
+
+Rendered via `pipeline/lib/plan-todos.sh list "$TASK_ID"`. Inline the resulting markdown checklist verbatim — one line per todo with status marker ([x] / [~] / [/] / [!]), ID, task text, and notes when present. Status summary one-liner ("4/6 done, 1 skipped, 1 failed") goes at the top from `plan-todos.sh status`.
+
+Skipped sections: when `planTodos.enabled` is false or no `plan.todos[]` was emitted, the Plan Todo block is omitted (no empty header). Phase 3 task-by-task progress still appears in the Timeline section either way.
+
+## Timeline
+
+| #   | Phase | Model | Duration | Status | Detail |
+| --- | ----- | ----- | -------- | ------ | ------ |
+
+## Agent Activity Report
+
+| Agent | Calls | Duration | Model |
+| ----- | ----- | -------- | ----- |
+
+## Review Iterations
+
+| Iteration | Blocking | Important | Suggestion | Decision |
+| --------- | -------- | --------- | ---------- | -------- |
+
+## Files Changed
+
+(git diff --stat output)
+
+## Channels Summary
+
+| Channel    | Status             | Link                                       |
+| ---------- | ------------------ | ------------------------------------------ |
+| PR         | posted \| skipped  | {prUrl} (reviewers preserved, v X→Y)       |
+| Jira       | posted \| skipped  | {jiraUrl}?focusedCommentId={id}            |
+| Confluence | created \| skipped | {confluenceUrl}                            |
+| Wiki       | {N} files \| skip  | {wikiUrl} (adapter: {submodule\|...})      |
+
+## Pipeline Metrics (last 30 days)
+
+(embed `aggregate-metrics.mjs --since=<30 days ago> --json` output as collapsed JSON)
+```
+
+**Telemetry emission** (mandatory): emit final event:
+
+```bash
+pipeline/scripts/log-metric.sh "$TASK_ID" 7 task.completed \
+  phases=$PHASE_COUNT review_cycles=$CYCLES lang=$PROMPT_LANG \
+  channels_pr=$PR_STATUS channels_jira=$JIRA_STATUS \
+  channels_confluence=$CONF_STATUS channels_wiki=$WIKI_STATUS \
+  duration_ms=$TOTAL_DURATION
+```
+
+**Aggregate before reporting**: run `aggregate-metrics.mjs --since=$(date -u -v-30d +%Y-%m-%d)` and embed output in agent-log.md. Use `--json` for Jira. Aggregator handles missing files gracefully.
+
+**Cost Breakdown emission (mandatory):** as part of agent-log compose, append the per-task cost block produced by `render-agent-log-cost.sh`. Best-effort — exit 2 (no tracker data) silently skipped:
+
+```bash
+COST_BLOCK=$(bash pipeline/scripts/render-agent-log-cost.sh "$TASK_ID" 2>/dev/null) && \
+  printf '\n%s\n' "$COST_BLOCK" >> "$AGENT_LOG"
+```
+
+This is independent of the channels-side `reportContent.costSummary` (which gates the PR-body Cost Summary). agent-log always carries the breakdown when telemetry is present.
+
+**Triage memory ingest (mandatory):** after Phase 4 produces a final triage output, persist the accepted/deferred/rejected rows into the per-repo triage corpus so Phase 1 enrichment and Phase 4 prior-art lookup can recall them on future tasks. Idempotent — re-running on the same task writes 0 rows.
+
+```bash
+TRIAGE_PATH="$WORKTREE/triage-output.json"
+if [ -f "$TRIAGE_PATH" ]; then
+  node pipeline/scripts/triage-memory.mjs ingest \
+    --triage "$TRIAGE_PATH" \
+    --task-id "$TASK_ID" \
+    --task-title "$TASK_TITLE" \
+    --stack "$DETECTED_STACK" >/dev/null 2>&1 || true
+fi
+```
+
+Best-effort. The corpus is JSONL at `~/.claude/memory/multi-agent/<repo-slug>/triage-corpus.jsonl` (per-repo isolation — never cross-leaks between projects). Disabled when `prefs.global.priorArtEnrichment.ingestOnComplete = false`.
+
+Print compact summary to terminal:
+
+```
+{jiraId} complete
+Total: Xm Ys | Agents: N calls | Files: N changed
+Channels: PR ✓ · Jira ✓ · Confluence – · Wiki ✓ (3 files)
+Commit: abc1234 | PR: #87
+Full report: $HOME/.claude/logs/multi-agent/{project}/{task-id}/agent-log.md
+```
+
+Tracker: `phase-tracker.sh sub 7 2 "Log+Telemetry" completed`.
+
+## Step 3 — Knowledge Capture (incremental learning)
+
+Extract reusable knowledge from this task and **append** to `$HOME/.claude/knowledge/{project-name}/`:
+
+| File              | What to Add                                     | Source                            |
+| ----------------- | ----------------------------------------------- | --------------------------------- |
+| `architecture.md` | Newly discovered modules, relationships, deps   | Phase 1 Explore                   |
+| `patterns.md`     | Conventions, naming, recurring structures       | Phase 1 + Phase 4                 |
+| `gotchas.md`      | Build errors/solutions, edge cases, workarounds | Phase 3 retries, Phase 4 blocking |
+| `decisions.md`    | Architectural decisions + rationale             | Phase 2 plan + Phase 4            |
+
+**Rules:** Only save reusable knowledge (task-specific details stay in agent-log). Read existing files before appending — no duplicates. Add date: `<!-- captured: {date}, task: {jiraId} -->`. Conflicting info → update old entry, don't delete.
+
+**Entry format:**
+
+```markdown
+<!-- captured: {date}, task: {jiraId} -->
+
+### {Topic Title}
+
+{Concise, actionable description}
+```
+
+**First task** (no knowledge dir): `mkdir -p`, create initial architecture.md + patterns.md from Phase 1. Log: "Knowledge base initialized for {project}"
+
+**Save preferences**: Update prefs with Phase 7 selections (via channels return: `reportChannels`, `reportContent`, `confluenceUrls` per-project LRU).
+
+**Per-repo memory synthesis (opt-in via `prefs.global.perRepoMemory`):**
+
+After the knowledge-capture pass, dispatch a scoped synthesis subagent (sonnet, 10 turns max) that reads the current run's `agent-log.md` + the existing MEMORY.md index, and returns 0–3 new memory entries as a JSON array. Each entry: `{type: "user|feedback|project|reference", slug, title, description, body}`. The orchestrator then loops:
+
+```bash
+for entry in $(jq -c '.[]' memory-synthesis.json); do
+  body=$(jq -r '.body' <<< "$entry")
+  slug=$(jq -r '.slug' <<< "$entry")
+  type=$(jq -r '.type' <<< "$entry")
+  printf '%s\n' "$body" | bash pipeline/scripts/memory-save.sh "$PROJECT_ROOT" "$type" "$slug" -
+done
+```
+
+**Synthesis prompt scope** (keep narrow):
+- **feedback**: only if the user corrected a pipeline behavior during this run ("no, don't", "stop doing X", or explicit approval of an unusual choice)
+- **project**: only if someone named a new deadline, constraint, or stakeholder that wasn't already in the task description
+- **reference**: only if an external system URL / dashboard / channel was mentioned as the source of truth for some concern
+- **user**: only if the user disclosed new context about their role, expertise, or team layout
+- **Otherwise return `[]`** — blank is the correct default. Do not save derivable facts (code structure, git history, command outputs).
+
+Zero new memories is normal and expected. A typical run produces one or none.
+
+Tracker: `phase-tracker.sh sub 7 3 "Knowledge+Memory" completed`.
+
+Log: "Phase 7: Knowledge captured ({N} entries to {files})"
+
+---
+
+## Timeout behavior (30-min channels menu wait)
+
+If user does not respond at the channels multi-select menu within 30 minutes (wall clock from menu render):
+
+1. Channels command aborts its interactive prompt, returns `{status: "timeout"}`.
+2. Phase 7 records `phase-tracker.sh sub 7 1 "Channels dispatch" timeout`.
+3. **Internal capture still runs** — Steps 2 + 3 write `agent-log.md` (with `channels: timeout` in summary), emit telemetry, update knowledge base.
+4. Session exits cleanly. State persisted: `state.phase=7, state.waitingFor="user-channels-choice", state.channelsTimeout=true`.
+5. Resume contract: `/multi-agent:resume <task-id>` re-opens the channels menu with the original state bundle (pipeline log, PR metadata, prefs pre-ticks).
+
+Rationale: silently posting defaults to Jira / Confluence after a timeout would leak wrong-tone content to external systems. Hard-stop + resume is the safer policy.
+
+---
+
+#### Output Quality + Metrics Section
+
+Append to every Phase 7 report (knowledge-capture pass) a **Quality & Metrics** block built from `metrics.jsonl` and the latest task's artifacts:
+
+```
+## Quality & Metrics
+
+### Output Quality
+- Commit message format: ✓ pass / ✗ fail
+- PR body (real newlines, no HTML entities, sections present): ✓ / ✗
+- Jira comment format: ✓ / ✗
+- Reviewer JSON valid: N/N
+- Triage JSON valid + no contradictions: ✓ / ✗
+- Code review severity ratio (blocking : important : suggestion): X : Y : Z (target ≤ 1 : 2 : 4)
+
+### Token & Cost
+- Tokens in / out: <a> / <b>
+- Premium calls (opus + gpt): <c>
+- Estimated cost (USD): $<d.dd>
+- Budget status: under | at | over
+
+### Build / Push
+- Build success rate this task: <pass>/<total>
+- Push attempts (per repo): <n>
+- Multi-repo: <repo count> repos, <skipped count> skipped
+```
+
+The block is generated by `output-quality-check.sh` + `token-budget-report.mjs --task $TASK_ID --json` and pasted verbatim. If either script is missing, that subsection is omitted (best-effort).
+
+#### metrics.jsonl schema extension
+
+Telemetry events may carry an `outputQuality` object inside `details`, plus a `channels` sub-object with per-adapter status:
+
+```json
+{
+  "ts": "2026-04-21T...",
+  "task_id": "PROJ-12345",
+  "phase": "7",
+  "event": "task.completed",
+  "details": {
+    "phases": 8,
+    "review_cycles": 2,
+    "channels": {
+      "pr":         "posted",
+      "jira":       "posted",
+      "confluence": "skipped",
+      "wiki":       "posted"
+    },
+    "outputQuality": {
+      "commitFormat": "pass",
+      "prBody": "pass",
+      "jiraComment": "pass",
+      "reviewerJsonValid": true,
+      "triageJsonValid": true,
+      "severityRatio": "1:2:4"
+    }
+  }
+}
+```
+
+#### Final metrics report appended to PR body at release time
+
+When the pipeline cuts a release, append the latest 30-day rollup to the release PR body:
+
+```bash
+node $HOME/.claude/scripts/token-budget-report.mjs --period monthly --append
+gh pr edit "$RELEASE_PR" --body-file <(cat existing-body.md \
+  && printf '\n\n## Release-window metrics (last 30 days)\n\n' \
+  && tail -10 $HOME/.claude/logs/multi-agent/metrics-summary.md)
+```

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

@@ -0,0 +1,187 @@
+# Multi-Agent Pipeline — Phase Reference
+
+## Phase Files
+
+| Phase                             | File                                                                 |
+| --------------------------------- | -------------------------------------------------------------------- |
+| Modes (autopilot, --dev, --local) | `$HOME/.claude/commands/multi-agent/refs/phases/modes.md`            |
+| Operations (kill, purge, resume)  | `$HOME/.claude/commands/multi-agent/refs/phases/operations.md`       |
+| Phase 0: Init                     | `$HOME/.claude/commands/multi-agent/refs/phases/phase-0-init.md`     |
+| Phase 1: Analysis                 | `$HOME/.claude/commands/multi-agent/refs/phases/phase-1-analysis.md` |
+| Phase 2: Planning                 | `$HOME/.claude/commands/multi-agent/refs/phases/phase-2-planning.md` |
+| Phase 3: Dev              | `$HOME/.claude/commands/multi-agent/refs/phases/phase-3-dev.md`      |
+| Phase 4: Review                   | `$HOME/.claude/commands/multi-agent/refs/phases/phase-4-review.md`   |
+| Phase 5: Test                | `$HOME/.claude/commands/multi-agent/refs/phases/phase-5-test.md`     |
+| Phase 6: Commit & PR              | `$HOME/.claude/commands/multi-agent/refs/phases/phase-6-commit.md`   |
+| Phase 7: Report                  | `$HOME/.claude/commands/multi-agent/refs/phases/phase-7-report.md`  |
+| Log format                        | `$HOME/.claude/commands/multi-agent/refs/phases/log-format.md`       |
+
+## Pipeline Flow
+
+```
+Normal:    0-Init -> 1-Analysis -> 2-Planning -> 3-Dev -> 4-Review -> 5-Test -> 6-Commit -> 7-Report
+--dev:     0-Init ------------------------------------------> 3-Dev -----------> 6-Commit -> 7-Report
+--local:   Same as above but no worktree — works directly on local branch
+```
+
+## Visual Phase Tracker
+
+Two channels run in parallel at every phase boundary. Both are required in their target CLIs — skipping either is the #1 source of "I see no progress" complaints.
+
+| Mechanism                        | Available in     | Status        | Style                                                |
+| -------------------------------- | ---------------- | ------------- | ---------------------------------------------------- |
+| **`phase-tracker.sh`** (state)   | Every CLI        | required     | Drives `tracker-state.json`; powers `:resume`/`:log`/`:status` |
+| **`TaskCreate` / `TaskUpdate`**  | Claude Code only | required here | Native sticky TaskList widget — the only progress signal Claude Code surfaces |
+| **`phase-tracker.sh render`**    | Every other CLI  | required here | Bordered ANSI card printed as last tool result so the user sees the phase table |
+| **`phase-banner.sh`**            | Every CLI        | Optional      | One-shot ANSI banner per phase boundary (extra emphasis) |
+
+**Cross-CLI contract**: every phase boundary MUST update both the state channel (`phase-tracker.sh`) AND the visual channel (TaskList in Claude Code, render in every other CLI). The tracker is the cross-CLI source of truth; the visual is what the user actually sees.
+
+### Tracker bootstrap (Phase 0, mandatory)
+
+Phase 0 MUST initialize the tracker and register all 8 phases:
+
+```bash
+pipeline/scripts/phase-tracker.sh init "$TASK_ID"
+for p in 0:Init 1:Analysis 2:Planning 3:Dev 4:Review 5:Test 6:Commit 7:Report; do
+  pipeline/scripts/phase-tracker.sh add "${p%%:*}" "${p#*:}"
+done
+```
+
+This produces an initial card stack printed by both CLIs.
+
+### Tracker updates (every phase boundary)
+
+As each phase enters/exits:
+
+```bash
+pipeline/scripts/phase-tracker.sh update <N> in_progress    # phase starts
+# ...do the work...
+pipeline/scripts/phase-tracker.sh update <N> completed      # phase ends OK
+# or:
+pipeline/scripts/phase-tracker.sh update <N> failed         # phase failed
+pipeline/scripts/phase-tracker.sh update <N> skipped        # --dev mode etc.
+```
+
+For sub-phase progress (e.g. Phase 1's parallel Explore agents, Phase 4's reviewer dispatch + triage + validator gate, Phase 6's commit + push + PR sub-steps):
+
+```bash
+pipeline/scripts/phase-tracker.sh sub <N> 1 "<sub name>" pending      # register
+pipeline/scripts/phase-tracker.sh sub <N> 1 "<sub name>" in_progress  # advance
+pipeline/scripts/phase-tracker.sh sub <N> 1 "<sub name>" completed    # done
+```
+
+State persists at `$HOME/.claude/logs/multi-agent/<task_id>/tracker-state.json` — atomic writes mean concurrent worktrees don't corrupt each other.
+
+### Optional banner (single-event flair)
+
+Call alongside tracker update for extra emphasis:
+
+```bash
+pipeline/scripts/phase-banner.sh start <N> "<name>" "<one-line detail>"
+pipeline/scripts/phase-banner.sh end   <N> done   "<name>" "<short result>"
+pipeline/scripts/phase-banner.sh sub   <N> 2     "<sub>" "<detail>"
+```
+
+Banner status enum on `end`: `done` | `failed` | `skipped`. Anything else exits 64.
+
+### TaskCreate registration (Claude Code — required)
+
+In Claude Code the agent MUST register one TaskCreate tile per phase at Phase 0 startup (one per phase that the current mode runs — full pipeline = 0..7, `--dev` = 0/3/6/7). Capture the returned `taskId`, persist it via `phase-tracker.sh meta <N> tasklist_id "<taskId>"` so `:resume` can rebuild the widget.
+
+Per phase boundary:
+
+```text
+# Phase entry — flip the tile to in_progress alongside the state update
+TaskUpdate({ taskId: <saved>, status: "in_progress" })
+bash phase-tracker.sh update <N> in_progress
+
+# Active sub-step inside a phase — keeps the spinner header live
+TaskUpdate({ taskId: <saved>, activeForm: "Editing TopBarView.swift" })
+TaskUpdate({ taskId: <saved>, activeForm: "Running xcodebuild test" })
+
+# Phase exit — flip both channels
+TaskUpdate({ taskId: <saved>, status: "completed" })
+bash phase-tracker.sh update <N> completed
+```
+
+`--dev` mode does NOT TaskCreate phases 1/2/4 at all — those phases are not part of the `--dev` set (`0:Init 3:Dev 5:Test 6:Commit 7:Report`). Only register tiles for the active mode's phase set. (Earlier guidance suggested pre-marking 1/2/4 with `[SKIPPED]` activeForm; that produces visually scrambled tile stacks — see the v8.3.1 ordering rule below.)
+
+**(strict) TaskCreate ordering**: All TaskCreate calls MUST fire in strict phase-number order BEFORE any TaskUpdate is applied. The native widget renders by creation order, not by phase number — out-of-order calls produce visually scrambled tile stacks (e.g. `1 ✓ · 2 ✓ · 4 ✓ · 0 ▶ · 3 ☐`) even when the underlying state is correct. Pre-marking phases as completed/skipped before Phase 0 starts is FORBIDDEN — register the tile in order with default `pending` status, then flip status via TaskUpdate when the phase actually short-circuits. Full contract in `refs/tracker-contract.md` § "TaskCreate ordering (strict)".
+
+**Copilot CLI / Cursor / Windsurf / plain shell**: do NOT call TaskCreate — the tool does not exist on these CLIs. Instead, after every state update, call `bash phase-tracker.sh render` so the bordered ANSI card prints as the last tool result. That's the equivalent visual signal there.
+
+## Preferences File
+
+Path: `$HOME/.claude/multi-agent-preferences.json` — persistent state across sessions.
+
+## Host Configuration
+
+Pipeline uses placeholder hosts for corporate services. Set these before first use:
+
+| Placeholder         | Purpose                    | Example                  |
+| ------------------- | -------------------------- | ------------------------ |
+| `{JIRA_HOST}`       | Jira server hostname       | `jira.company.com`       |
+| `{BITBUCKET_HOST}`  | Bitbucket server hostname  | `bitbucket.company.com`  |
+| `{CONFLUENCE_HOST}` | Confluence server hostname | `confluence.company.com` |
+| `{CORP_DOMAIN}`     | Corporate domain           | `company.com`            |
+
+Configure via preferences or environment variables. If not set, VPN check (Phase 0) skips gracefully.
+
+Read modes.md first (always), then the phase file for the current stage.
+For operations (status, kill, resume, purge): read operations.md.
+
+## Token Budget
+
+Each phase doc is lazy-loaded — only the current phase's spec is in context. Budget enforced by `smoke-token-budget.sh`.
+
+| Phase       | File                | Max Tokens | Warn  |
+| ----------- | ------------------- | ---------- | ----- |
+| 0: Init     | phase-0-init.md     | 4,000      | 3,500 |
+| 1: Analysis | phase-1-analysis.md | 1,500      | 1,200 |
+| 2: Planning | phase-2-planning.md | 1,000      | 800   |
+| 3: Dev      | phase-3-dev.md      | 1,800      | 1,500 |
+| 4: Review   | phase-4-review.md   | 2,200      | 1,800 |
+| 5: Test     | phase-5-test.md     | 800        | 600   |
+| 6: Commit   | phase-6-commit.md   | 2,800      | 2,400 |
+| 7: Report  | phase-7-report.md  | 3,200      | 2,700 |
+| **Total**   |                     | **17,000** |       |
+
+Token estimate: `ceil(chars / 4)`. Budget covers phase-\*.md files only. Guides, rules, and agents are loaded separately on demand.
+
+## SubPhase Convention
+
+When a specialized skill takes over a main pipeline phase, progress is reported as **SubPhases** nested under the parent. Top-level stays 8 phases (0-7); specialized flows get sub-phase detail.
+
+**Visual example:**
+
+```
+■ Phase 0: Init              completed
+■ Phase 1: Analysis          completed
+■ Phase 2: Planning          completed
+* Phase 3: Dev (figma)       in progress
+  ■ SubPhase 3.0: Init            completed
+  ■ SubPhase 3.1: Gather          completed
+  ■ SubPhase 3.4A: Configuration  completed
+  ■ SubPhase 3.4B: View           completed
+  * SubPhase 3.4F: Wiki           writing wiki pages...
+  □ SubPhase 3.5A: ViewInspector  pending
+  □ SubPhase 3.6: Code Connect    pending
+  □ SubPhase 3.7: Issue Update    pending
+□ Phase 4: Review            pending
+□ Phase 5: Test              pending
+□ Phase 6: Commit            pending
+□ Phase 7: Report           pending
+  □ SubPhase 7.1: Jira comment      pending
+  □ SubPhase 7.2: Wiki + screenshots pending
+  □ SubPhase 7.3: Confluence        pending
+  □ SubPhase 7.4: Report + log      pending
+  □ SubPhase 7.5: Knowledge capture pending
+```
+
+**TaskCreate pattern:** Parent phase + SubPhases linked via `addBlockedBy`. SubPhases block parent from completing.
+
+**Why SubPhases, not separate phases:**
+
+- Main pipeline stays a fixed 8-phase contract (0-7) regardless of task type. Wiki, Confluence, and Figma screenshots all live as SubPhases under Phase 7 Report — external delivery grouped logically, internal report + knowledge after.
+- Conditional phases are a code smell — they force every reader to learn which phase runs when.