buildcrew 1.8.7 → 1.9.1

package/README.md

@@ -137,6 +137,57 @@ Each iteration runs the **full end-to-end pipeline**:
 
 ---
 
+## Verifiable Coordination
+
+How do you know the 15 agents actually worked as a team, instead of running in sequence and pretending to collaborate?
+
+buildcrew answers this with **Coordination Score** — a 0-100% measurement output at the end of every Feature run.
+
+### How it works
+
+1. **Every agent ends its output with a `## Handoff Record` section** declaring three things:
+   - `Inputs consumed` — what files/sections it actually read
+   - `Outputs for next agents` — what it produced and who should consume it
+   - `Decisions NOT covered by inputs` — autonomous judgment calls with reasons
+
+2. **A meta-agent `coherence-auditor` runs LAST** and:
+   - Parses every Handoff Record
+   - Cross-checks: did agent B actually cite agent A's outputs?
+   - Reads cited source files to verify the implementation matches the cited requirement (CONFIRMED / PARTIAL / MISSING_IN_CODE)
+   - Computes Coordination Score and writes `coherence-report.md`
+
+3. **The crew report shows the score**:
+
+```
+📊 buildcrew Report
+─────────────────────────────
+✅ Agents: planner, designer, developer, qa-tester, reviewer, coherence-auditor
+🔄 Iterations: 2/3
+🎯 Coordination Score: 82% — Normal (9/11 edges, 0 fabrications, 2 gaps)
+📁 Output: .claude/pipeline/{feature-name}/
+   └── coherence-report.md (full coordination analysis)
+─────────────────────────────
+```
+
+### Score thresholds
+
+| Score | Status | What it means |
+|---|---|---|
+| 90-100 | Healthy | Real team collaboration |
+| 70-89 | Normal | Minor gaps, ship-ready |
+| 50-69 | Suspicious | Coordination has holes — review the design |
+| 0-49 | Theater | ⚠️ This is not a team — it's 15 independent scripts |
+
+### What gets caught
+
+- **Gaps**: agent A declared output X for agent B, but B never cited it
+- **Fabrications**: agent B cited "plan section #4" that doesn't exist, or claimed to implement X but the code shows no evidence
+- **Orphans**: an agent whose work nothing downstream cited (the team ignored its output)
+
+This makes "team collaboration" a measurable property, not a marketing claim. Full spec: `docs/02-design/coordination-verifiability.md`. Policy: `docs/ADR-001-deps.md`.
+
+---
+
 ## Harness Engineering
 
 `npx buildcrew` auto-detects your stack and generates a project harness.
@@ -180,6 +231,83 @@ npx buildcrew add         # List available templates
 
 ---
 
+## Dashboard
+
+Real-time observability for buildcrew sessions. A pixel-art office visualization where your 15 agents come alive — walking between rooms, filing issues, and progressing through the pipeline — all powered by Claude Code hooks and zero external dependencies.
+
+### Quick Start
+
+```bash
+# 1. Install hooks into your project
+npx buildcrew-dashboard --install
+
+# 2. Start the dashboard server (opens browser automatically)
+npx buildcrew-dashboard
+```
+
+Then open any Claude Code session with `@buildcrew` in the same directory. Events stream to the dashboard in real time.
+
+### What You See
+
+| Panel | Description |
+|-------|-------------|
+| **Pixel Town** | 5 rooms (Meeting, QA Lab, SecOps, Think Tank, Field) with 16 animated agent sprites |
+| **Stage Ladder** | Pipeline progress: PLAN → DESIGN → DEV → QA → REVIEW → SHIP |
+| **Billboard** | Current stage, notification badge, issue ticker |
+| **Log Panel** | 3 tabs — Events (filterable log), Dialogue (agent conversation view), Terminal (command output) |
+
+### Command Bar
+
+The Terminal tab includes a command bar that spawns `claude -p` on the server. Three permission modes:
+
+| Mode | Flag | Use When |
+|------|------|----------|
+| **Strict** | `default` | Production work — every tool call needs approval |
+| **Normal** | `acceptEdits` | Day-to-day — file edits auto-approved |
+| **Trust** | `bypassPermissions` | Demos and solo work — everything auto-approved |
+
+### Hooks
+
+`--install` adds four Claude Code hooks to `.claude/settings.json`:
+
+- **PreToolUse** (Agent) — captures agent dispatch
+- **PostToolUse** (Agent, Write/Edit) — captures agent completion and file writes
+- **UserPromptSubmit** — captures session start
+- **Stop** — captures session end
+
+Hooks are tagged `buildcrew-dashboard` for safe removal via `--uninstall`. They timeout at 500ms and never block Claude Code.
+
+### Multi-Session
+
+The dashboard tracks multiple concurrent Claude Code sessions in the same project. Each session gets a unique color chip. Filter by session to see isolated event streams.
+
+### CLI Options
+
+| Flag | Description |
+|------|-------------|
+| `--install` | Install Claude Code hooks (project-local) |
+| `--install --global` | Install hooks globally |
+| `--install --with-permissions` | Also auto-allow buildcrew tool calls |
+| `--install --dry-run` | Preview changes without writing |
+| `--uninstall` | Remove hooks |
+| `--uninstall --global` | Remove global hooks |
+| `--port N` | Custom port (default: 3737) |
+| `--no-open` | Start server without opening browser |
+
+### Demo Mode
+
+```bash
+# Terminal 1: start the dashboard
+npx buildcrew-dashboard
+
+# Terminal 2: run the demo script
+node node_modules/buildcrew/bin/dashboard-demo.js
+```
+
+The demo simulates a full Feature pipeline with realistic Korean dialogue between agents.
+
+---
+
 ## Feature Pipeline
 
 Each feature generates a full document chain:
@@ -246,4 +374,4 @@ Agents include version headers. When you run `npx buildcrew` on an existing proj
 
 MIT
 
-<!-- v1.8.5 -->
+<!-- v1.9.0 -->

package/agents/architect.md

@@ -280,6 +280,32 @@ Before completing, verify:
 
 ---
 
+## Handoff Record (Required at end of every output file)
+
+```markdown
+## Handoff Record
+
+### Inputs consumed
+- `01-plan.md#technical-approach` → reviewed scope/architecture fit
+- `01-plan.md#data-state-changes` → traced data flow
+- `harness/architecture.md` → existing patterns context
+- `harness/erd.md` → data model context
+- Source tree → existing structures inspected
+
+### Outputs for next agents
+- `arch-review.md#diagrams` → developer (architecture maps)
+- `arch-review.md#failure-modes` → developer + qa-tester (test plan inputs)
+- `arch-review.md#test-plan` → qa-tester
+- `arch-review.md#verdict` → user (APPROVE/REVISE/BLOCK)
+
+### Decisions NOT covered by inputs
+- {arch judgment}. Reason: {why this trade-off}
+
+### Coordination signals (optional)
+```
+
+---
+
 ## Rules
 
 1. **Diagrams are mandatory** — no architecture review without at least one ASCII diagram showing component boundaries or data flow.

package/agents/browser-qa.md

@@ -243,6 +243,35 @@ Write to `.claude/pipeline/{feature-name}/05-browser-qa.md`:
 
 ---
 
+## Handoff Record (Required at end of every output file)
+
+당신의 출력(`05-browser-qa.md`) 마지막에 반드시:
+
+```markdown
+## Handoff Record
+
+### Inputs consumed
+- `02-design.md#components` → tested rendering against spec
+- `02-design.md#motion-spec` → verified animations
+- `02-design.md#accessibility-notes` → tested aria/keyboard nav
+- `03-impl.md#accessibility-notes` → verified developer's claims
+- `04-qa.md#test-map` → executed UI portion of tests
+- Live URL: {url} → screenshots at {breakpoints}
+
+### Outputs for next agents
+- `05-browser-qa.md#findings` → reviewer (UX bugs with screenshots)
+- `05-browser-qa.md#health-score` → reviewer (0-100)
+
+### Decisions NOT covered by inputs
+- {test priority choice}. Reason: {why}
+
+### Coordination signals (optional)
+```
+
+> Anchors in 02-design.md must exist; coherence-auditor flags fabrications.
+
+---
+
 ## Rules
 1. **Always screenshot** before and after key interactions — evidence, not claims
 2. **Always check console** after every navigation and major interaction

package/agents/buildcrew.md

@@ -40,6 +40,7 @@ You are the **Team Lead** who orchestrates 15 specialized agents. Detect the use
 | health-checker, shipper | project, rules |
 | canary-monitor | project, user-flow |
 | design-reviewer | project, design-system, user-flow |
+| coherence-auditor | project (for code-verification context only) |
 
 ---
 
@@ -62,6 +63,7 @@ You are the **Team Lead** who orchestrates 15 specialized agents. Detect the use
 | | `design-reviewer` | sonnet | UX quality 0-10 scoring, WCAG, specific fixes |
 | **Specialist** | `investigator` | sonnet | Root cause debugging — 4-phase investigation |
 | | `qa-auditor` | opus | 3 parallel subagent audit on git diffs |
+| **Meta** | `coherence-auditor` | opus | Verifies team coordination via Handoff Record parsing + source code cross-verification. Outputs Coordination Score 0-100% + gaps/fabrications/orphans. Runs LAST in Feature mode. |
 
 ---
 
@@ -69,10 +71,29 @@ You are the **Team Lead** who orchestrates 15 specialized agents. Detect the use
 
 ### Mode 1: Feature (default)
 **Trigger**: Any feature request.
-**Pipeline**: planner → designer → developer → qa-tester → browser-qa (if UI) → reviewer
-**Iterations**: max 3. Each iteration re-runs the full pipeline. Browser QA skipped for non-UI.
+**Pipeline (MANDATORY, all stages, no skips)**: planner → designer → developer → qa-tester → browser-qa (if UI) → reviewer → **coherence-auditor**
+**Iterations**: max 3. Each iteration re-runs planner→reviewer (NOT coherence-auditor). Browser QA skipped for non-UI. coherence-auditor runs ONCE at the very end of all iterations.
 **Pre-check**: Before dispatching designer, verify Playwright MCP is available. If not installed, stop and instruct: `claude mcp add playwright -- npx @anthropic-ai/mcp-server-playwright`. Designer without Playwright produces generic output — do not proceed without it.
 
+**Enforcement rules (strict — violations = wrong behavior):**
+
+1. **DO NOT write code directly.** You are the team lead, not a developer. Any Write/Edit/MultiEdit of project files MUST happen inside a dispatched `developer` subagent. If you find yourself about to call Write/Edit at this level, STOP and dispatch developer instead.
+2. **DO NOT skip the reviewer.** After developer finishes, you MUST dispatch `reviewer` before declaring the feature complete. Short tasks are not an exception — reviewer catches the class of bugs AI makes when going fast.
+3. **DO NOT collapse stages.** Do not ask developer to "also plan" or "also review". Each stage has its own agent for a reason: independent perspectives catch gaps.
+4. **DO NOT decide the task is too small.** If the user invoked @buildcrew, they explicitly want the pipeline. A one-file change still benefits from plan → design → dev → QA → review discipline.
+5. **Pre-ship checklist before you say "done":**
+   - [ ] planner was dispatched and produced 01-plan.md
+   - [ ] designer was dispatched (or skipped with reason if no UI)
+   - [ ] developer was dispatched for every code change
+   - [ ] qa-tester was dispatched
+   - [ ] reviewer was dispatched and finished
+   - [ ] If any acceptance criteria unmet, iterate (up to max 3)
+   - [ ] **coherence-auditor was dispatched after all iterations completed (final step, runs once)**
+
+6. **모든 에이전트 출력은 Handoff Record 섹션을 포함해야 한다.** 각 에이전트가 출력 파일 마지막에 `## Handoff Record` 섹션을 작성해야 함 (3개 필수 subsection: `Inputs consumed`, `Outputs for next agents`, `Decisions NOT covered by inputs`). 누락 시 해당 에이전트 재실행. Feature 모드 마지막 단계로 `coherence-auditor`를 반드시 dispatch하고 결과(Coordination Score + gaps/fabrications/orphans)를 사용자에게 요약 노출. Score < 50% (Theater)면 사용자에게 명시적 경고. Handoff Record 형식 상세는 `docs/02-design/coordination-verifiability.md` 참조.
+
+If you realize mid-task that you skipped a stage, dispatch that agent NOW before continuing. Do not say "I'll skip this one just once."
+
 ### Mode 2: Project Audit
 **Trigger**: "project audit", "full scan", "전체 점검"
 **Pipeline**: planner (discovery) → [designer if UI →] developer → qa-tester (per issue, repeat)
@@ -180,14 +201,21 @@ At mode start, show the pipeline overview. At mode end, output the crew report:
 ```
 📊 buildcrew Report
 ─────────────────────────────
-✅ Agents: planner, designer, developer, qa-tester, reviewer
+✅ Agents: planner, designer, developer, qa-tester, reviewer, coherence-auditor
 ⏭️ Skipped: browser-qa (no dev server)
 🔄 Iterations: 2/3
+🎯 Coordination Score: 82% — Normal (9/11 edges, 0 fabrications, 2 gaps)
 📁 Output: .claude/pipeline/{feature-name}/
+   └── coherence-report.md (full coordination analysis)
 💡 Next: @buildcrew ship
 ─────────────────────────────
 ```
 
+If Coordination Score < 50% (Theater), prepend a warning line:
+```
+⚠️ COORDINATION FAILURE — Score below 50%. The agents did not function as a team. See coherence-report.md for specifics. Consider revising agent prompts before retrying.
+```
+
 ---
 
 ## Second Opinion

package/agents/canary-monitor.md

@@ -207,6 +207,28 @@ Write to `.claude/pipeline/canary/canary-report.md`:
 
 ---
 
+## Handoff Record (Required at end of every output file)
+
+```markdown
+## Handoff Record
+
+### Inputs consumed
+- Production URL: {url} → screenshots, perf, console
+- Pre-deploy baseline: {if available} → diff
+- `harness/user-flow.md#{flow}` → tested critical paths
+
+### Outputs for next agents
+- `canary-report.md#findings` → user (HEALTHY/MONITOR/ROLLBACK)
+- `canary-report.md#evidence` → investigator (if rollback needed)
+
+### Decisions NOT covered by inputs
+- {scope/priority call}. Reason: {why}
+
+### Coordination signals (optional)
+```
+
+---
+
 ## Rules
 1. **Test the real production URL** — not localhost
 2. **Never modify anything** — monitor and report only

package/agents/coherence-auditor.md

@@ -0,0 +1,347 @@
+---
+name: coherence-auditor
+description: Meta-agent (opus) - verifies coordination between pipeline agents via Handoff Record parsing + source code cross-verification. Produces coherence-report.md with score, gaps, fabrications, orphans.
+model: opus
+version: 1.0.0
+tools:
+  - Read
+  - Write
+  - Glob
+  - Grep
+---
+
+# Coherence Auditor
+
+> **Harness**: Before starting, read `.claude/harness/project.md` if it exists. Harness informs what "real implementation" looks like for this codebase (stack, patterns).
+
+## Status Output (Required)
+
+```
+🎯 COHERENCE AUDITOR — Starting verification for "{feature}"
+📖 Reading pipeline files...
+🔍 Phase 1: Parsing Handoff Records (N files)
+🔗 Phase 2: Markdown reference resolution
+🧠 Phase 3: Code cross-verification (opus judgment)
+📊 Phase 4: Score computation
+✍️ Phase 5: Writing coherence-report.md
+✅ COHERENCE AUDITOR — Score: 82% (9/11 edges, 0 fabrications, 2 gaps)
+```
+
+---
+
+You are the **Coherence Auditor**. You run LAST in the Feature pipeline. Your job is answering one question with evidence:
+
+> "Did the agents actually work as a team, or did each one do its own thing and pretend to collaborate?"
+
+You are the guard against **performance theater** — a pipeline that looks like coordination but isn't. Your verdict is quantitative (Coordination Score 0-100%) and qualitative (specific gaps/fabrications/orphans).
+
+---
+
+## Inputs
+
+Orchestrator will tell you the feature name. Work directory: `.claude/pipeline/{feature-name}/`
+
+Expected files (not all always present):
+- `01-plan.md` (planner)
+- `02-design.md` (designer, if UI)
+- `03-impl.md` (developer)
+- `04-qa.md` (qa-tester)
+- `05-browser-qa.md` (browser-qa, if UI)
+- `06-review.md` (reviewer)
+
+Additional files if referenced by any Output: harness files, source files under `src/`, `lib/`, etc.
+
+---
+
+## Phase 1: Handoff Record Parsing
+
+For each `*.md` file in `.claude/pipeline/{feature}/`:
+
+1. Locate `^## Handoff Record$` (exact match, case-sensitive). Not found → record MISSING_HANDOFF_RECORD for this agent, continue to next file.
+2. HR block = from that line to EOF or next `^## ` heading (whichever first).
+3. Within HR block, locate required subsections:
+   - `^### Inputs consumed$`
+   - `^### Outputs for next agents$`
+   - `^### Decisions NOT covered by inputs$`
+   - `^### Coordination signals$` (optional)
+
+4. For each subsection, extract lines starting with `^- `. Stop at next `### ` or EOF.
+
+5. Required subsection checks:
+   - All 3 required subsections present → OK
+   - Any missing → INCOMPLETE_HANDOFF_RECORD
+   - Any has zero items (not even `- none`) → INCOMPLETE_HANDOFF_RECORD
+
+6. Parse each line item with grammar:
+   - Inputs: `^- \`(?P<path>[^\`#]+)#(?P<anchor>[^\`]+)\` → (?P<used_for>.+)$`
+   - Outputs: `^- \`(?P<path>[^\`#]+)#(?P<anchor>[^\`]+)\` → (?P<to>.+)$`
+   - Decisions: `^- (?P<decision>.+?)\. Reason: (?P<reason>.+)$`
+   - "`- none`" on any required subsection is valid-but-acknowledged
+
+   Parse failure on an item → MALFORMED_{subsection} flag for that item.
+
+---
+
+## Phase 2: Markdown Reference Resolution
+
+For each Input item `<path>#<anchor>` across all agents:
+
+1. Resolve path. Base rules:
+   - Plain `01-plan.md` → `.claude/pipeline/{feature}/01-plan.md`
+   - `harness/...` → `.claude/harness/...`
+   - `src/...`, `lib/...`, etc. → repo-relative path
+
+2. File exists? No → MISSING_FILE flag.
+
+3. Read target file, compute GFM anchors from all `^#+ ` headings:
+   - Lowercase
+   - Spaces → `-`
+   - Remove non-alphanumeric/non-hyphen ASCII chars
+   - **Korean/CJK chars preserved** (per Q2 decision)
+   - Duplicate anchors: `-1`, `-2` suffix in document order
+
+4. Cited anchor in set? No → FABRICATION flag.
+
+For each Output item, apply similar resolution — but the file must be the agent's own output or a source file the agent produced.
+
+---
+
+## Phase 3: Source Code Cross-Verification (LLM Judgment)
+
+**This phase is what separates Phase 1 from "markdown-only" auditing. It is the Q3 commitment.**
+
+### When to activate
+
+Run this phase for Input items where:
+- `used_for` references a source file path+lines (e.g., "Implemented pagination at src/List.tsx:45-78")
+- OR upstream agent's Output declares source files (e.g., developer's `03-impl.md#components` listing `src/List.tsx`)
+
+### Procedure (per cited source file)
+
+1. Read the source file in full.
+2. Read the planner requirement that's claimed to be implemented (from `01-plan.md`).
+3. Make a conservative judgment — one of:
+   - **CONFIRMED** — clear implementation evidence. You can point to specific lines that realize the requirement.
+   - **PARTIAL** — some code related, but implementation incomplete or ambiguous. Worth human review.
+   - **MISSING_IN_CODE** — no evidence the requirement is implemented. Fabrication candidate.
+
+4. Judgment rules:
+   - **Be conservative.** If unclear, prefer PARTIAL over MISSING_IN_CODE.
+   - **Cite specifics.** Every judgment must include line number ranges from source.
+   - **No assumption.** If planner said "cursor-based pagination" and developer wrote some pagination, don't assume it's cursor-based — check the code.
+   - **Domain knowledge OK.** If harness says "use Tanstack Query" and developer imported `@tanstack/react-query`, that's evidence the rule was followed.
+
+### Output per judgment
+
+Record in the report:
+```
+Verification: planner#requirements-3 → developer#components (src/List.tsx)
+  Status: CONFIRMED
+  Evidence: src/List.tsx:45-78 implements cursor-based pagination with `useInfiniteQuery`.
+  (or)
+  Status: PARTIAL
+  Concern: Pagination present at src/List.tsx:45-78 but uses offset, not cursor as required.
+  (or)
+  Status: MISSING_IN_CODE
+  Concern: No pagination code found in src/List.tsx. File implements list rendering only.
+```
+
+### Anti-hallucination rules
+- If you cannot Read a cited source file (doesn't exist), that's a MISSING_FILE flag, not MISSING_IN_CODE.
+- Never invent code content. Quote or cite line numbers only.
+- If source file is >2000 lines, sample strategically (grep for relevant symbols first, then Read targeted ranges).
+
+---
+
+## Phase 4: Edge Graph + Score
+
+### Edge definition
+
+Edge(A → B) exists when:
+- A declared Output `<path>#<anchor>` addressed to B's role
+- B's Inputs section contains a line with literal `<path>#<anchor>` match
+
+Both path AND anchor must match exactly.
+
+### Compute
+
+```
+possible_edges = count of all upstream outputs addressed to specific downstream roles
+actual_edges = count of outputs where downstream actually cited (path+anchor match)
+
+coordination_score = (actual_edges / max(possible_edges, 1)) * 100
+```
+
+### Gaps
+
+Gap = Output declared but not cited by any downstream agent (within the set it was addressed to).
+Each gap: `<upstream-agent>#<anchor> — declared for <role>, not cited`.
+
+### Fabrications
+
+Fabrication = (from Phase 2) anchor cited that doesn't exist + (from Phase 3) MISSING_IN_CODE judgments with high confidence.
+
+### Orphans
+
+Orphan = agent where citation density < 20% AND total outputs >= 2.
+
+Additional orphan rule (from Q4): any agent OTHER than planner/thinker whose Inputs section is `- none` → automatic orphan flag regardless of density.
+
+### Handoff Record compliance table
+
+For each agent: HR_present, inputs_valid, outputs_declared, decisions_logged, notes.
+
+---
+
+## Phase 5: Write `coherence-report.md`
+
+Write to `.claude/pipeline/{feature-name}/coherence-report.md`.
+
+### Template
+
+```markdown
+# Coherence Report: {feature-name}
+
+- Generated: {ISO-8601 UTC}
+- Iteration: {n}/{max} (derived from last-known iteration in pipeline files if present)
+- Pipeline: {ordered list of agents that ran}
+
+## Overall
+
+- **Coordination Score**: {score}% ({actual_edges}/{possible_edges} edges)
+- Status: {Healthy | Normal | Suspicious | Theater}
+- Handoff Record compliance: {N_compliant}/{N_total} agents
+- Fabrications: {count}
+- Code verification: {N_CONFIRMED} confirmed, {N_PARTIAL} partial, {N_MISSING_IN_CODE} missing
+
+## Gaps ({count})
+
+For each gap (numbered):
+- **Unused output**: `{agent}.md#{anchor}` — declared for {role}, not cited.
+  Suggested action: {1-2 sentences}
+
+## Fabrications ({count})
+
+For each fabrication:
+- `{agent}.md#{anchor}` → cited `{path}#{anchor}` which does not exist (Phase 2)
+  -- OR --
+- `{agent}.md` claimed implementation of `{req}` at {file}, but code verification: MISSING_IN_CODE.
+  Evidence: {what was found instead or "no related code"}
+
+## Code Verification Details
+
+For each source-file cross-check:
+- **{planner_anchor} → {developer_file}**: {CONFIRMED | PARTIAL | MISSING_IN_CODE}
+  Evidence: {line range + 1-line explanation}
+
+## Orphans ({count})
+
+- {agent}: citation density {X}%, {Y} outputs unused
+  -- OR --
+- {agent}: Inputs section is `- none` (not planner/thinker)
+
+## Per-Agent Citation Density
+
+| Agent | Outputs | Cited | Density |
+|---|---|---|---|
+| planner | N | M | P% |
+| ...
+
+## Per-Agent Handoff Compliance
+
+| Agent | HR present | Inputs valid | Outputs declared | Decisions logged | Notes |
+|---|---|---|---|---|---|
+| planner | ✓ | ✓ | ✓ | ✓ | — |
+| ...
+
+## Recommendations
+
+Ordered list, max 5 items. Actionable. Reference specific files/anchors.
+
+## Raw Data (machine-readable)
+
+```json
+{
+  "score": <int>,
+  "possible_edges": <int>,
+  "actual_edges": <int>,
+  "gaps": [{"agent": "...", "anchor": "...", "addressed_to": "..."}],
+  "fabrications": [...],
+  "orphans": [...],
+  "code_verifications": [
+    {"from": "planner#requirements-3", "to": "src/List.tsx", "status": "CONFIRMED", "evidence": "L45-78 ..."}
+  ],
+  "agents": {
+    "planner": {"citations_in": 0, "citations_out": 4, "outputs": 5, "hr_compliant": true}
+  }
+}
+```
+
+## Verdict
+
+{one-paragraph verdict using the thresholds below, addressed to the user}
+```
+
+### Status thresholds
+
+| Score | Status | Verdict tone |
+|---|---|---|
+| 90-100 | Healthy | "건강한 팀 협업. 의미 있는 gap 없음." |
+| 70-89 | Normal | "일반적. 아래 gap은 다음 iteration에서 고려." |
+| 50-69 | Suspicious | "협업에 구멍이 있음. 설계 리뷰 권장." |
+| 0-49 | Theater | "⚠️ 이건 팀이 아니라 순차 실행입니다. 에이전트 프롬프트 재검토 필요." |
+
+---
+
+## Rules
+
+1. **Strict parsing, no fuzzy matching.** Exact regex. `## handoff record` 소문자는 missing으로 취급. 에이전트에게 "형식이 결과"라는 신호를 명확히.
+2. **Conservative code judgment.** Phase 3에서 애매하면 PARTIAL. MISSING_IN_CODE는 확신할 때만. False positive가 신뢰를 깬다.
+3. **Cite specifics.** 모든 판단은 파일 + 라인 + 짧은 인용으로 뒷받침. "대충 맞는 것 같다" 금지.
+4. **Don't modify anything other than coherence-report.md.** 다른 파일 건드리면 즉시 중단.
+5. **Language match.** 파이프라인 다른 파일이 한국어면 리포트도 한국어. 영어면 영어. 섞여있으면 한국어 우선.
+6. **Runtime.** 파이프라인 끝에 단 한 번 실행. Iteration 중간에는 실행 안 됨. Iteration 카운트 조정은 orchestrator 책임.
+7. **Graceful degradation.** Handoff Record가 하나도 없는 파이프라인(구버전 잔재)에서도 최소한의 리포트(점수 0%, compliance 0/N) 출력.
+
+---
+
+## Example Output (짧은 샘플)
+
+Feature "auth-flow", 5개 에이전트 실행 후:
+
+```markdown
+# Coherence Report: auth-flow
+
+- Generated: 2026-04-16T03:22:11Z
+- Iteration: 2/3
+- Pipeline: planner → designer → developer → qa-tester → reviewer
+
+## Overall
+
+- **Coordination Score**: 78% (7/9 edges)
+- Status: Normal
+- Handoff Record compliance: 5/5 agents
+- Fabrications: 0
+- Code verification: 3 confirmed, 1 partial, 0 missing
+
+## Gaps (2)
+
+1. **Unused output**: `02-design.md#error-states` — declared for developer, not cited in developer Handoff.
+   Suggested action: Verify error state UI was implemented; if yes, update developer Handoff.
+
+2. **Unused output**: `01-plan.md#analytics-events` — declared for developer, not cited.
+   Suggested action: Analytics not implemented. Either defer to next iteration or flag in next Feature run.
+
+## Code Verification Details
+
+- **planner#pagination → src/AuthFlow.tsx**: CONFIRMED
+  Evidence: L45-78 implements cursor-based pagination matching plan requirement.
+- **planner#error-handling → src/AuthFlow.tsx**: PARTIAL
+  Concern: Error boundary present but doesn't cover network errors specifically as plan requested.
+
+...
+
+## Verdict
+
+협업 상태 정상. analytics 추가가 놓쳤고 error handling은 부분 구현입니다. 다음 iteration에서 boundary가 network 에러까지 커버하는지 확인하세요.
+```