iriai-build 0.1.0

package/v3/PLAN-HTML-EVIDENCE-HARDENING.md

@@ -0,0 +1,603 @@
+# Plan: HTML Evidence Document Hardening
+
+## Problem Statement
+
+The current gate review process uses YAML-based `.output` files and `.gate-evidence.yaml` compiled into basic HTML. The orchestrator and feature lead make pass/fail decisions, but:
+
+1. **No structured gaps reporting** - Review agents report findings but don't explicitly call out what's MISSING in their domain
+2. **No deviation tracking** - Implementers diverge from the plan silently; reviewers have no visibility
+3. **No self-reported risks** - Implementers know where the bodies are buried but aren't asked
+4. **No coverage matrix** - No way to see "what from the plan is done vs not done" at a glance
+5. **Incomplete E2E coverage** - Integration-tester tests journeys but doesn't mandate error case GIFs
+6. **Context loss on long tasks** - Agents that span multiple context windows lose structured findings; handover is prose-based
+7. **HTML doc lacks reviewer commentary** - Orchestrator/FL decisions aren't captured in the evidence artifact
+8. **No visual distinction between complete and pending sections** - Can't tell what's filled vs awaiting
+
+## Solution Overview
+
+### Two-tier HTML evidence documents
+
+- **Team gate HTML** - One per team per gate. Compiled by team orchestrator after QA agents finish. NO approve/reject buttons — this is evidence only, reviewed by the feature lead internally.
+- **Feature gate HTML** - One per feature per gate. Compiled by feature lead. Links to team gate HTMLs. This is the ONLY doc that gets approve/reject buttons and is the ONLY doc posted to the Slack impl channel.
+
+### Planning channel thread communication policy
+
+The planning channel thread (where `[FEATURE]` was posted) receives ONLY:
+- **HTML evidence documents** — the feature gate HTML is posted as a thread update
+- **Approve/reject buttons** — only on the feature gate HTML, one per gate
+
+NO text-based status messages in the planning thread ("Pipeline started", "Phase approved", "Launching implementation", etc.). The HTML document IS the update. If you want to know the state, open the HTML.
+
+The impl channel (`#impl-<slug>`) is **unchanged** — it still receives questions, operator relay messages, and gate decisions as before.
+
+### Incremental structured output (.output.partial)
+
+Agents write append-only partial output as they complete each unit of work, preventing context loss.
+
+### Enriched output schemas
+
+Implementers report deviations and risks. Review agents report gaps. Orchestrator/FL add comments.
+
+---
+
+## Detailed Changes
+
+### 1. Incremental Output Protocol (.output.partial)
+
+**Applies to:** ALL agents that produce `.output` (implementers + review agents)
+
+**Format:** Append-only multi-document YAML (separated by `---`)
+
+```yaml
+---
+type: journey
+name: auth-login
+verdict: PASS
+checks:
+  - criterion: "Login with valid credentials"
+    result: PASS
+    detail: "200 response, session cookie set"
+gif_path: .recordings/gifs/auth-login.gif
+completed_at: "2026-03-05T10:00:00Z"
+---
+type: journey
+name: auth-login-invalid-password
+verdict: PASS
+checks:
+  - criterion: "Login with wrong password"
+    result: PASS
+    detail: "401 response, error message shown"
+gif_path: .recordings/gifs/auth-login-error.gif
+completed_at: "2026-03-05T10:02:00Z"
+---
+type: gap
+category: error-handling
+description: "Timeout scenario not tested"
+severity: major
+plan_reference: "journey-3, step 4"
+```
+
+**Rules:**
+- After completing each unit of work (journey, file review, acceptance criterion check), append a `---` separated YAML document to `.output.partial`
+- Each entry is self-contained and independently parseable
+- On restart, read `.output.partial` to know exactly what's done (structured, not prose)
+- On completion, consolidate `.output.partial` into final `.output` with aggregated verdict, checks, gaps, issues
+- Handover becomes lightweight: "read `.output.partial` for completed work, remaining: X, Y, Z"
+- If agent hard-crashes without handover, `.output.partial` preserves all completed work on disk
+- Parse with `yaml.loadAll()` — standard multi-document YAML
+- Orchestrator can read `.output.partial` for progress visibility before agent finishes
+
+**Entry types by agent:**
+
+| Agent | Entry types |
+|-------|-------------|
+| Implementer | `file_complete` (per file modified), `deviation`, `risk` |
+| Code reviewer | `file_review` (per file), `gap` |
+| Security auditor | `endpoint_review` (per endpoint/flow), `gap` |
+| Integration tester | `journey` (per journey), `gap` |
+| Regression tester | `test_suite` (per suite), `gap` |
+| Verifier | `criterion_check` (per acceptance criterion), `gap` |
+| Smoke tester | `critical_path` (per path), `gap` |
+
+### 2. Implementer Output Schema Changes
+
+**Files:** `roles/implementer/CLAUDE.md`, `roles/backend-implementer/CLAUDE.md`, `roles/frontend-implementer/CLAUDE.md`, `roles/database-implementer/CLAUDE.md`
+
+**Add to Output section:**
+
+```yaml
+task_id: [id]
+role: implementer
+summary_oneliner: "[one line]"
+files_created: [list]
+files_modified: [list]
+deviations:                          # NEW
+  - plan_said: "[what the task specified]"
+    i_did: "[what was actually implemented]"
+    reason: "[why the deviation was necessary]"
+self_reported_risks:                 # NEW
+  - description: "[what you're not confident about]"
+    severity: major|minor
+    file: "[path]"
+```
+
+**Add to Process section:** After step 5 (verify), add:
+- Step 6: Document any deviations from the task spec and why
+- Step 7: Flag anything you're not confident about as a self-reported risk
+
+**Add .output.partial protocol:** After each file is completed, append a `file_complete` entry.
+
+### 3. Review Agent Output Schema Changes
+
+**Files:** `roles/code-reviewer/CLAUDE.md`, `roles/security-auditor/CLAUDE.md`, `roles/regression-tester/CLAUDE.md`, `roles/verifier/CLAUDE.md`, `roles/integration-tester/CLAUDE.md`
+
+**Add `gaps` field to Output section (all 5 agents):**
+
+```yaml
+task_id: [id]
+role: [role]
+verdict: PASS|FAIL|CONDITIONAL
+summary_oneliner: "[counts]"
+checks:
+  - criterion: "[review area]"
+    result: PASS|FAIL
+    detail: "[evidence]"
+issues:
+  - severity: blocker|major|minor|nit
+    description: "[what's wrong]"
+    file: "[path]"
+    line: [number]
+gaps:                                # NEW
+  - category: "[domain-specific]"
+    description: "[what's missing or not covered]"
+    severity: blocker|major|minor
+    plan_reference: "[task ID or acceptance criterion]"
+duration_seconds: [elapsed]
+```
+
+**Gap categories by agent:**
+
+| Agent | Gap categories |
+|-------|---------------|
+| Code reviewer | error-handling, input-validation, pattern-compliance, edge-cases, test-coverage |
+| Security auditor | auth, injection, rate-limiting, secrets, cors, csrf, data-exposure |
+| Integration tester | untested-journey, missing-error-case, missing-edge-case, visual-gap |
+| Regression tester | untested-regression, missing-backward-compat, skipped-test-suite |
+| Verifier | unverified-criterion, insufficient-evidence, missing-acceptance-check |
+
+**Add .output.partial protocol to all 5:** After each review item, append entry to `.output.partial`.
+
+### 4. Integration Tester: Comprehensive E2E Coverage Mandate
+
+**File:** `roles/integration-tester/CLAUDE.md`
+
+**Add new section "Comprehensive Journey Coverage - MANDATORY":**
+
+```
+## Comprehensive Journey Coverage - MANDATORY
+
+For EVERY user journey defined in the plan:
+
+### Happy Path (Golden Path)
+- Execute the full journey step by step
+- Generate a GIF of the complete flow
+- Every verify block must produce evidence
+
+### Error Cases (per journey)
+For each journey, test ALL of the following error scenarios that apply:
+- Invalid input (wrong types, missing fields, too long, empty)
+- Authentication failures (expired token, wrong credentials, no token)
+- Authorization failures (wrong role, insufficient permissions)
+- Network/timeout scenarios (if applicable)
+- Empty state (no data, first-time user)
+- Boundary conditions (max items, zero items, concurrent access)
+
+Each error case gets:
+- Its own GIF showing the error flow and recovery/message
+- A check entry in the output
+
+### Gap Reporting
+After testing, cross-reference the plan's journey list against what you tested.
+For any journey or error case NOT tested, write a gap entry with:
+- Which journey/error case was skipped
+- Why it was skipped (MCP unavailable, environment limitation, time constraint)
+- Severity assessment (blocker if it's a critical path, major otherwise)
+```
+
+### 5. Orchestrator CLAUDE.md Updates
+
+**File:** `roles/orchestrator/CLAUDE.md`
+
+**Key change: Team orchestrator compiles team gate HTML but does NOT post it to Slack or attach approve/reject buttons.** The team gate HTML is written to disk for the feature lead to review internally. The orchestrator signals `.gate-ready` as before — the feature lead is the only one who presents evidence to the user.
+
+**Changes to "Per-Phase Adversarial Review + Gate Evidence" section:**
+
+Add after step 4 (QA roles complete), before visual review:
+
+```
+4b. **Review gaps from every review agent.** Read the `gaps` field in each QA agent's
+    `.output`. These are the primary inputs to your gate decision. A gap with severity
+    `blocker` means the phase cannot pass — re-dispatch the responsible agent.
+
+4c. **Aggregate implementer deviations and risks.** Read `deviations` and
+    `self_reported_risks` from each implementer's `.output`. Cross-reference deviations
+    against the plan — if a deviation contradicts a requirement, it's a blocker.
+
+4d. **Build coverage matrix.** For every task and acceptance criterion in the plan,
+    determine status:
+    - `implemented_verified` — implementer completed it AND a review agent verified it
+    - `implemented_unverified` — implementer completed it but no review agent checked it
+    - `not_implemented` — no implementer output references this item
+    Include the matrix in `.gate-evidence.yaml`.
+```
+
+**Update gate evidence YAML schema in the example:**
+
+```yaml
+gate: 1
+feature: my-feature
+recommendation:
+  verdict: APPROVE
+  reasoning: "All journeys pass with visual evidence verified"
+pr:
+  url: https://github.com/org/repo/pull/123
+  branch: feature/my-feature
+  files_changed: 15
+  additions: 420
+  deletions: 50
+summary: "Implemented auth flow with login, registration, and password reset."
+coverage_matrix:                     # NEW
+  - plan_item: "task-1.1: Login endpoint"
+    status: implemented_verified
+    evidence_ref: "code-reviewer check 1, integration-tester journey auth-login"
+  - plan_item: "task-1.2: Rate limiting"
+    status: implemented_unverified
+    evidence_ref: "implementer output only"
+  - plan_item: "task-1.3: Password reset"
+    status: not_implemented
+    evidence_ref: null
+deviations:                          # NEW (aggregated from implementers)
+  - source: backend-implementer
+    task_id: "1.1"
+    plan_said: "Use bcrypt for password hashing"
+    i_did: "Used argon2id"
+    reason: "argon2id is the current OWASP recommendation"
+self_reported_risks:                 # NEW (aggregated from implementers)
+  - source: frontend-implementer
+    task_id: "1.2"
+    description: "Rate limit UI feedback relies on 429 status code; not tested with proxy"
+    severity: minor
+    file: "src/components/LoginForm.tsx"
+reviewer_comments:                   # NEW
+  orchestrator:
+    verdict: convinced
+    reasoning: "All gaps are minor. Deviation on argon2id is an improvement. Coverage matrix shows 12/14 items verified."
+    concerns:
+      - "Rate limiting not visually verified — only unit tested"
+journey_results:
+  - name: auth-login
+    verdict: PASS
+    type: happy-path
+    # ... existing fields ...
+  - name: auth-login-invalid-password   # NEW: error case journeys
+    verdict: PASS
+    type: error-case
+    # ...
+tasks:
+  - id: "1.1"
+    title: "Implement login endpoint"
+    role: backend-implementer
+    verdict: PASS
+qa_verdicts:
+  - role: code-reviewer
+    verdict: PASS
+    issue_count: 0
+    gaps:                            # NEW
+      - category: test-coverage
+        description: "No unit tests for rate limiter middleware"
+        severity: major
+  - role: security-auditor
+    verdict: PASS
+    issue_count: 0
+    gaps: []
+```
+
+### 6. Feature Lead CLAUDE.md Updates
+
+**File:** `roles/feature-lead/CLAUDE.md`
+
+**Key change: The feature gate HTML is the ONLY artifact posted to the impl Slack channel, and it is the ONLY place approve/reject buttons appear.** One HTML per gate, one approval decision per gate. Team gate HTMLs are internal evidence reviewed by the FL — they are linked from the feature gate HTML but never posted to Slack independently.
+
+**Changes to "Gate Evidence Document Protocol" section:**
+
+After step 4 (wait for review agents), before step 5 (adversarial cross-check):
+
+```
+4b. **Review gaps across all levels.** Read `gaps` from:
+    - Each team orchestrator's `.gate-evidence.yaml` (team-level QA gaps)
+    - Each team's compiled `.gate-evidence.html` (review visually)
+    - Each feature-level review agent's `.output` (cross-team gaps)
+    Any blocker-severity gap that hasn't been addressed = REJECT.
+
+4c. **Build cross-team integration surface.** Document:
+    - APIs/contracts that Team A's work exposes and Team B consumes
+    - Shared database tables or state modified by multiple teams
+    - Any cross-team dependency that could break if one team's work changes
+
+4d. **Build feature-level coverage matrix.** Cross-reference the FULL plan
+    (all phases, all tasks, all acceptance criteria) against evidence from
+    all teams. This is the master view — status of every plan item.
+
+4e. **Add Feature Lead comments.** Write your assessment:
+    - verdict: convinced|not_convinced
+    - reasoning: reference specific gaps, deviations, and cross-team concerns
+    - concerns: list remaining items even if you're convinced overall
+```
+
+**Update step 7 (compile HTML):**
+
+```
+7. **Compile feature gate HTML** — Call `compile_gate_evidence` MCP tool:
+   - `evidence_yaml_path`: your merged `.gate-evidence.yaml`
+   - `output_html_path`: `<featureDir>/.gate-evidence.html`
+   - `doc_type`: "feature"
+   - `team_html_paths`: list of team-level HTML paths to link to
+   - If tool returns ERROR -> re-dispatch affected role -> retry
+```
+
+**Update step 8 (post to Slack):**
+
+```
+8. **Post feature gate HTML to impl channel** via `.agent-response`:
+   - Include `[evidence:<path to .gate-evidence.html>]` marker — HTML uploaded as attachment
+   - Include `[SLACK:decision]` block with approve/reject buttons
+   - This is the ONE approval point per gate — no per-team approvals
+   - The HTML links to team gate HTMLs for drill-down
+   - User reviews the HTML, then clicks approve/reject
+```
+
+### 7. Evidence Compiler HTML Template Overhaul
+
+**File:** `tools/visual-verification-mcp/evidence-compiler.js`
+
+#### New HTML sections (in order):
+
+1. **Header** (existing) — feature, gate, date, recommendation badge
+2. **Scoreboard** (existing) — tasks, journeys, regression, QA counts
+3. **Coverage Matrix** (NEW) — table:
+   - Column 1: Plan item (task ID + title)
+   - Column 2: Status badge
+   - Column 3: Evidence reference (link to check/journey)
+   - Styling:
+     - `implemented_verified`: normal text, green checkmark icon
+     - `implemented_unverified`: italic text, yellow/amber background
+     - `not_implemented`: strikethrough text, grey color
+4. **Deviations from Plan** (NEW) — cards showing plan_said vs i_did vs reason
+5. **Self-Reported Risks** (NEW) — cards with severity badges
+6. **Pull Request** (existing)
+7. **Summary** (existing)
+8. **Journey Evidence** (existing, enhanced):
+   - Happy path journeys grouped together
+   - Error case journeys grouped separately
+   - Each journey card shows embedded GIF
+9. **Tasks** (existing)
+10. **QA Verdicts** (existing, enhanced):
+    - Each QA agent card now has two subsections:
+      - **Findings** — existing checks + issues
+      - **Gaps** — new gaps field, rendered with warning/yellow background styling
+    - If a QA agent hasn't reported yet, render section as:
+      ```html
+      <div class="section-pending">
+        <h3>Security Audit</h3>
+        <p class="pending-label">Awaiting: security-auditor</p>
+      </div>
+      ```
+11. **Reviewer Comments** (NEW) — orchestrator and FL comments:
+    - Verdict badge (convinced/not_convinced)
+    - Reasoning text
+    - Concerns list
+12. **Cross-Team Integration Surface** (NEW, feature-level only):
+    - Shared APIs/contracts table
+    - Cross-team dependencies
+13. **Team Evidence Links** (NEW, feature-level only):
+    - Summary table: each team's section statuses (green check / grey dash)
+    - Links to team gate HTML files
+14. **Risks** (existing)
+15. **Deferred** (existing)
+16. **Recommendation** (existing)
+
+#### Pending section styling (CSS):
+
+```css
+.section-pending {
+  opacity: 0.5;
+  font-style: italic;
+  border: 1px dashed var(--border);
+}
+.section-pending .pending-label {
+  color: var(--muted);
+  font-style: italic;
+}
+.gap-item {
+  background: #fef3c7; /* yellow-100 */
+  border-left: 3px solid #f59e0b; /* amber-500 */
+  padding: 8px 12px;
+  margin: 4px 0;
+}
+.coverage-verified { color: var(--fg); }
+.coverage-unverified { font-style: italic; background: #fef9c3; }
+.coverage-missing { text-decoration: line-through; color: var(--muted); }
+```
+
+#### compile_gate_evidence MCP tool changes:
+
+Add optional parameters:
+- `doc_type`: `"team"` (default) or `"feature"`
+- `team_html_paths`: array of `{ team_num, html_path }` (feature-level only, for linking)
+
+Update `validateEvidence()`:
+- Warn (not error) on missing `gaps`, `deviations`, `coverage_matrix` — backwards compatible with in-flight features
+- Error on missing `reviewer_comments` only when `recommendation` is present AND `doc_type` is `"feature"`
+
+### 8. prompt-builder.js Updates
+
+**File:** `iriai-build/v3/prompt-builder.js`
+
+**Changes to `buildGateReviewInstructions()`:**
+
+Update step 6 (merge evidence) instruction to include new fields:
+
+```javascript
+6. **Merge evidence** — Combine all team YAMLs + feature-level review outputs into:
+   - Include: coverage_matrix, deviations, self_reported_risks (aggregated from all teams)
+   - Include: reviewer_comments with your FL assessment
+   - Include: cross_team_surface (APIs, contracts, shared state)
+```
+
+Update step 7 (compile HTML) to pass doc_type and team paths.
+
+Update step 8 (post to Slack): Remove text summary — the HTML file IS the message. Only include
+`[evidence:path]` marker and `[SLACK:decision]` block.
+
+### 8b. orchestrator.js Updates — Suppress Text Status Messages in Planning Thread
+
+**File:** `iriai-build/v3/orchestrator.js`
+
+The planning channel thread should only receive HTML evidence docs (with approve/reject buttons).
+Remove text-based status messages currently posted to the planning thread:
+
+- `handlePlanApproval()`: Remove `"Plan approved! Launching implementation..."` and
+  `"Feature branches created. Launching agents..."` thread posts to planning channel.
+- `handleGateApproval()`: Remove `"Gate approved! Feature Lead will advance..."` text post.
+- `handleGateRejection()`: Remove `"Gate rejected..."` text post.
+- `_requestPhaseReview()`: Remove the text summary post (`"PM phase complete. Output: ..."`).
+  The planning phase review gates (PM/Designer/Architect approve/reject buttons) still post — but
+  the accompanying text summary is replaced by the artifact upload only.
+- `handlePhaseReviewApproval()`: Remove `"Phase approved. Starting X phase..."` text post.
+- `handlePhaseReviewRejection()`: Remove `"X phase rejected. Re-dispatching..."` text post.
+
+**What stays in the planning thread:**
+- HTML evidence document uploads (feature gate HTML with buttons)
+- Planning phase artifact uploads (PRD, design-decisions, plan.yaml) with approve/reject buttons
+- Feature completion message
+
+**Impl channel change:**
+- Gate approval decisions in the impl channel MUST now include the feature gate HTML as an attachment.
+  The `[evidence:<path>]` marker + `[SLACK:decision]` block are posted together — the user reviews
+  the HTML before clicking approve/reject.
+- Everything else in impl channel is unchanged (questions, operator relay, status updates).
+
+### 9. constants.js Update
+
+**File:** `iriai-build/v3/constants.js`
+
+Add new signal file name:
+
+```javascript
+export const SIGNAL = {
+  // ... existing ...
+  OUTPUT_PARTIAL: ".output.partial",  // NEW
+};
+```
+
+### 10. Context Management Updates in Role CLAUDE.md files
+
+**All agent CLAUDE.md files** — update the Context Management section:
+
+Replace the handover instructions with:
+
+```
+## Context Management - MANDATORY
+
+### Incremental Output (.output.partial)
+After completing each unit of work, append a `---` separated YAML entry to .output.partial:
+```bash
+cat >> $SIGNAL_DIR/.output.partial << 'ENTRY_EOF'
+---
+type: [entry_type]
+[structured fields for this unit of work]
+completed_at: "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+ENTRY_EOF
+```
+
+This ensures completed work survives context exhaustion or crashes.
+
+### On Restart
+Read .output.partial FIRST. It contains your completed work in structured form.
+Do NOT redo any work that has an entry in .output.partial.
+
+### At 40% Context Remaining
+1. Ensure .output.partial is up to date (all completed work appended)
+2. Write .handover with: remaining items list only (completed work is in .output.partial)
+3. Signal: echo "context_threshold" > $SIGNAL_DIR/.needs-restart
+
+### Final Output
+When all work is complete, consolidate .output.partial into .output:
+1. Read all entries from .output.partial
+2. Aggregate into final verdict, checks, gaps, issues
+3. Write consolidated .output
+4. Signal: echo DONE > .done
+```
+
+---
+
+## Files Modified (Summary)
+
+| # | File | Change |
+|---|------|--------|
+| 1 | `v3/roles/implementer/CLAUDE.md` | Add deviations, self_reported_risks, .output.partial |
+| 2 | `v3/roles/backend-implementer/CLAUDE.md` | Same as #1 |
+| 3 | `v3/roles/frontend-implementer/CLAUDE.md` | Same as #1 |
+| 4 | `v3/roles/database-implementer/CLAUDE.md` | Same as #1 |
+| 5 | `v3/roles/code-reviewer/CLAUDE.md` | Add gaps, .output.partial |
+| 6 | `v3/roles/security-auditor/CLAUDE.md` | Add gaps, .output.partial |
+| 7 | `v3/roles/integration-tester/CLAUDE.md` | Add gaps, comprehensive E2E mandate, .output.partial |
+| 8 | `v3/roles/regression-tester/CLAUDE.md` | Add gaps, .output.partial |
+| 9 | `v3/roles/verifier/CLAUDE.md` | Add gaps, .output.partial |
+| 10 | `v3/roles/orchestrator/CLAUDE.md` | Coverage matrix, deviation aggregation, reviewer comments, team HTML compilation (no buttons) |
+| 11 | `v3/roles/feature-lead/CLAUDE.md` | Cross-team surface, FL comments, feature-level coverage matrix, sole Slack poster with buttons |
+| 12 | `tools/visual-verification-mcp/evidence-compiler.js` | HTML template overhaul, new sections, pending styling |
+| 13 | `iriai-build/v3/prompt-builder.js` | Gate review instructions update, remove text summaries |
+| 14 | `iriai-build/v3/constants.js` | Add OUTPUT_PARTIAL signal |
+| 15 | `iriai-build/v3/orchestrator.js` | Remove text status messages from impl channel (gate approved/rejected posts) |
+
+## Files NOT Modified
+
+- `agent-supervisor.js` — No retry/backoff changes.
+- `operator.js` — No relay changes.
+- `schema.sql` — No DB schema changes.
+- `db.js`, `queries.js` — No query changes.
+- Planning pipeline roles (pm, designer, architect, plan-compiler) — Not in scope.
+- `slack-adapter.js` — No Slack API changes.
+
+## Execution Order
+
+```
+Phase 1 (parallel, no dependencies):
+  - Files 1-4: Implementer CLAUDE.md updates
+  - Files 5-9: Review agent CLAUDE.md updates
+  - File 14: constants.js (one line)
+
+Phase 2 (depends on Phase 1):
+  - File 10: Orchestrator CLAUDE.md (references new output fields, team HTML compilation)
+  - File 11: Feature Lead CLAUDE.md (references new output fields, sole Slack poster)
+
+Phase 3 (parallel with Phase 2):
+  - File 12: evidence-compiler.js (HTML template, can be built independently)
+  - File 13: prompt-builder.js (gate review instructions, remove text summaries)
+  - File 15: orchestrator.js (remove text status messages from impl channel)
+```
+
+## Backwards Compatibility
+
+- In-flight features won't have new YAML fields. The evidence compiler renders missing fields as "pending" sections, not errors.
+- `.output.partial` is additive — existing agents that don't write it still work; they just lose the crash-recovery benefit until updated.
+- `validateEvidence()` warns (not errors) on missing new fields.
+- `doc_type` defaults to `"team"` — existing `compile_gate_evidence` calls work unchanged.
+
+## Risk Assessment
+
+- **Integration-tester runtime increase**: Mandating error case GIFs per journey significantly increases work. This is intentional — comprehensive visual evidence is the goal.
+- **Agent context cost**: New output fields add ~10-20 lines per agent. Minimal context impact.
+- **HTML file size**: More embedded GIFs (error cases) means larger HTML. The existing 18MB cap and resize logic in evidence-compiler.js handles this.
+- **.output.partial disk usage**: Append-only files grow over time. Each entry is small (~20 lines YAML). Even 50 entries is <5KB. Not a concern.

package/v3/adapters/desktop-adapter.js

@@ -0,0 +1,78 @@
+// desktop-adapter.js — DesktopAdapter implementing InterfaceAdapter.
+// For iriai-command Tauri desktop app.
+// Stub — implementation deferred to Phase 7.
+// Will use WebSocket or stdin/stdout JSON protocol as Tauri sidecar.
+
+import { InterfaceAdapter } from "./interface.js";
+
+export class DesktopAdapter extends InterfaceAdapter {
+  constructor({ port } = {}) {
+    super();
+    this.port = port || 9721;
+    this._connections = new Set();
+    // TODO: Start WebSocket server or stdin/stdout JSON protocol
+  }
+
+  async createFeatureChannel(featureId, slug) {
+    this._emit("feature:created", { featureId, slug });
+    return `desktop-${slug}`;
+  }
+
+  async postMessage(featureId, text) {
+    const ref = Date.now().toString();
+    this._emit("message", { featureId, text, ref });
+    return { ref };
+  }
+
+  async postThreadMessage(featureId, text) {
+    this._emit("thread-message", { featureId, text });
+  }
+
+  async postPipelineMessage(featureId, text) {
+    const ref = Date.now().toString();
+    this._emit("pipeline-message", { featureId, text, ref });
+    return { ref };
+  }
+
+  async postAgentResponse(featureId, agentLabel, content) {
+    const ref = Date.now().toString();
+    this._emit("agent-response", { featureId, agentLabel, content, ref });
+    return { ref };
+  }
+
+  async uploadArtifact(featureId, filePath, title) {
+    this._emit("artifact", { featureId, filePath, title });
+  }
+
+  async postDecision(featureId, decision) {
+    const ref = Date.now().toString();
+    this._emit("decision", { featureId, decision, ref });
+    // TODO: Wait for response event from Tauri client
+    return { ref };
+  }
+
+  async resolveDecisionMessage(featureId, messageRef, decisionId, selectedOption, selectedLabel, resolvedBy, feedback) {
+    this._emit("decision-resolved", { featureId, decisionId, selectedOption, selectedLabel, resolvedBy, feedback });
+  }
+
+  async postPlanForApproval(featureId, planDir) {
+    return this.postDecision(featureId, {
+      id: "plan-approval",
+      title: "Plan ready for approval",
+      context: "All planning phases complete.",
+      options: [
+        { id: "approve", label: "Approve Plan", style: "primary" },
+        { id: "reject", label: "Reject Plan", style: "danger" },
+      ],
+    });
+  }
+
+  async postFeatureComplete(featureId) {
+    this._emit("feature-complete", { featureId });
+  }
+
+  _emit(event, data) {
+    // TODO: Send over WebSocket / stdout
+    console.log(`[desktop] ${event}:`, JSON.stringify(data).slice(0, 200));
+  }
+}