iriai-build 0.1.0

package/lib/state-machines/planning-role.js

@@ -0,0 +1,161 @@
+// planning-role.js — Planning pipeline role (PM, Designer, Architect, Plan-Compiler).
+// Replaces run-planning-role.sh in Slack mode. Sequential dispatch via bridge.
+//
+// IDLE ──[dispatch(task)]──→ RUNNING ──[signal:done]──→ COMPLETE
+//                                ├──[exit + no .done]──→ RETRYING → RUNNING
+//                                └──[signal:agentResponse]──→ post to Slack, stay RUNNING
+
+import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import path from "node:path";
+import AgentProcess from "../agent-process.js";
+import { buildPlanningRolePrompt } from "../prompt-builder.js";
+import {
+  PLANNING_BASE, IRIAI_TEAM_DIR, MAX_PLANNING_RETRIES,
+  FAST_EXIT_THRESHOLD_MS, FAST_EXIT_BACKOFF_S, NORMAL_BACKOFF_S,
+  SIGNAL, ROLE_DIRS,
+} from "../constants.js";
+
+export default class PlanningRole extends EventEmitter {
+  /**
+   * @param {object} opts
+   * @param {string} opts.role - Role name (pm, designer, architect, plan-compiler)
+   */
+  constructor({ role }) {
+    super();
+    this.role = role;
+    this.signalDir = ROLE_DIRS[role];
+    this.key = `planning-${role}`;
+
+    this._agent = null;
+    this._state = "idle";
+    this._crashCount = 0;
+    this._taskContent = "";
+    this._featureSlug = "";
+  }
+
+  get state() { return this._state; }
+
+  /**
+   * Dispatch this role with a task.
+   * @param {string} featureSlug
+   * @param {string} thread_ts
+   */
+  dispatch(featureSlug, thread_ts) {
+    if (this._state === "running") {
+      this.kill();
+    }
+
+    this._featureSlug = featureSlug;
+
+    // Build task header (same as index.js dispatchToRole)
+    const taskHeader = [
+      "SLACK_MODE=true",
+      `FEATURE_SLUG=${featureSlug}`,
+      `SIGNAL_DIR=${this.signalDir}`,
+      `THREAD_TS=${thread_ts}`,
+      "---",
+    ].join("\n");
+
+    // Check if there's an existing .task from planning lead
+    const taskPath = path.join(this.signalDir, SIGNAL.TASK);
+    let existingTask = "";
+    try {
+      if (fs.existsSync(taskPath)) {
+        existingTask = fs.readFileSync(taskPath, "utf-8");
+      }
+    } catch { /* ok */ }
+
+    this._taskContent = existingTask
+      ? `${taskHeader}\n${existingTask}`
+      : `${taskHeader}\nStart the ${this.role} phase for feature: ${featureSlug}`;
+
+    // Write task file
+    fs.writeFileSync(taskPath, this._taskContent);
+
+    // Parse Slack metadata from task content
+    const bodyMatch = this._taskContent.split("---\n").slice(1).join("---\n");
+    const taskBody = bodyMatch || this._taskContent;
+
+    this._crashCount = 0;
+    this._spawn(taskBody);
+  }
+
+  kill() {
+    if (this._agent) {
+      this._agent.kill();
+      this._agent = null;
+    }
+    this._state = "idle";
+  }
+
+  _spawn(taskBody) {
+    // Clean done/output signals
+    for (const sig of [SIGNAL.DONE, SIGNAL.OUTPUT]) {
+      try { fs.unlinkSync(path.join(this.signalDir, sig)); } catch { /* ok */ }
+    }
+
+    const prompt = buildPlanningRolePrompt({
+      task: taskBody || this._taskContent,
+      signalDir: this.signalDir,
+      featureSlug: this._featureSlug,
+    });
+
+    this._state = "running";
+    this._agent = new AgentProcess({
+      key: this.key,
+      cwd: this.signalDir,
+      extraEnv: { PLANNING_SIGNAL_BASE: PLANNING_BASE },
+      signalDir: this.signalDir,
+    });
+    this._agent.spawnClaude(prompt);
+
+    this._agent.on("exit", ({ exitCode, elapsed }) => {
+      this._agent = null;
+
+      // Check for .done (success)
+      if (fs.existsSync(path.join(this.signalDir, SIGNAL.DONE))) {
+        this._state = "complete";
+        this.emit("done", { key: this.key, role: this.role });
+        this.emit("lifecycle", { key: this.key, event: "done" });
+        return;
+      }
+
+      // Crash — retry
+      this._crashCount++;
+      if (this._crashCount <= MAX_PLANNING_RETRIES) {
+        const isFast = elapsed < FAST_EXIT_THRESHOLD_MS;
+        const backoffS = isFast
+          ? this._crashCount * FAST_EXIT_BACKOFF_S
+          : this._crashCount * NORMAL_BACKOFF_S;
+
+        this._state = "retrying";
+        this.emit("lifecycle", {
+          key: this.key,
+          event: "crash-retry",
+          retryCount: this._crashCount,
+          backoffS,
+        });
+
+        // Re-create .task for retry
+        try {
+          fs.writeFileSync(
+            path.join(this.signalDir, SIGNAL.TASK),
+            this._taskContent
+          );
+        } catch { /* ok */ }
+
+        setTimeout(() => {
+          const bodyMatch = this._taskContent.split("---\n").slice(1).join("---\n");
+          this._spawn(bodyMatch || this._taskContent);
+        }, backoffS * 1000);
+      } else {
+        this._state = "crashed";
+        this.emit("crashed", { key: this.key, role: this.role });
+        this.emit("lifecycle", { key: this.key, event: "crashed" });
+      }
+    });
+
+    this.emit("lifecycle", { key: this.key, event: "started" });
+  }
+}

package/lib/state-machines/role-agent.js

@@ -0,0 +1,186 @@
+// role-agent.js — Task lifecycle with retry for implementation roles.
+// Replaces run-role.sh. Direct PTY spawn, event-driven exit, crash retry.
+//
+// IDLE ──[signal:task]──→ RUNNING ──[signal:done]──→ IDLE
+//                             ├──[exit + no .done + retries left]──→ RETRYING → RUNNING
+//                             ├──[exit + no .done + no retries]──→ CRASHED
+//                             └──[signal:needsRestart]──→ RUNNING (handover)
+
+import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import path from "node:path";
+import AgentProcess from "../agent-process.js";
+import { buildRolePrompt } from "../prompt-builder.js";
+import {
+  IMPL_BASE, MAX_ROLE_RETRIES,
+  FAST_EXIT_THRESHOLD_MS, FAST_EXIT_BACKOFF_S, NORMAL_BACKOFF_S,
+  SIGNAL,
+} from "../constants.js";
+
+export default class RoleAgent extends EventEmitter {
+  /**
+   * @param {object} opts
+   * @param {string} opts.slug - Feature slug
+   * @param {string} opts.role - Role name
+   * @param {string} opts.signalDir - Role's signal directory
+   * @param {string} opts.cwd - Working directory (worktree)
+   * @param {string} [opts.teamNum] - Team number (for key generation)
+   * @param {string} [opts.model] - Claude model (default: "opus")
+   */
+  constructor({ slug, role, signalDir, cwd, teamNum, model }) {
+    super();
+    this.slug = slug;
+    this.role = role;
+    this.signalDir = signalDir;
+    this.cwd = cwd;
+    this.model = model || "opus";
+    this.key = teamNum
+      ? `role-${slug}-${teamNum}-${role}`
+      : `review-${slug}-${role}`;
+
+    this._agent = null;
+    this._state = "idle";
+    this._retryCount = 0;
+    this._handoverContent = "";
+    this._task = "";
+  }
+
+  get state() { return this._state; }
+
+  /**
+   * Handle a new .task file (triggered by SignalWatcher or orchestrator).
+   */
+  handleTask() {
+    if (this._state === "running") {
+      console.log(`[role] ${this.key}: already running, ignoring new task`);
+      return;
+    }
+
+    const taskPath = path.join(this.signalDir, SIGNAL.TASK);
+    try {
+      this._task = fs.readFileSync(taskPath, "utf-8").trim();
+      // Atomic rename: .task → .active-task
+      fs.renameSync(taskPath, path.join(this.signalDir, SIGNAL.ACTIVE_TASK));
+    } catch {
+      return;
+    }
+    if (!this._task) return;
+
+    this._retryCount = 0;
+    this._handoverContent = "";
+    this._spawn();
+  }
+
+  /**
+   * Handle .needs-restart signal (context handover).
+   */
+  handleNeedsRestart() {
+    // Read handover content before killing
+    const handoverPath = path.join(this.signalDir, SIGNAL.HANDOVER);
+    if (fs.existsSync(handoverPath)) {
+      this._handoverContent = fs.readFileSync(handoverPath, "utf-8");
+      fs.unlinkSync(handoverPath);
+    }
+
+    // Clean signal
+    const restartPath = path.join(this.signalDir, SIGNAL.NEEDS_RESTART);
+    try { fs.unlinkSync(restartPath); } catch { /* ignore */ }
+
+    // Kill current and respawn (NOT counted as crash)
+    if (this._agent) {
+      this._agent.kill();
+      this._agent = null;
+    }
+
+    this.emit("lifecycle", { key: this.key, event: "handover-restart" });
+    this._spawn();
+  }
+
+  kill() {
+    if (this._agent) {
+      this._agent.kill();
+      this._agent = null;
+    }
+    this._state = "idle";
+  }
+
+  _spawn() {
+    // Clean signals
+    for (const sig of [SIGNAL.DONE, SIGNAL.OUTPUT, SIGNAL.NEEDS_RESTART]) {
+      try { fs.unlinkSync(path.join(this.signalDir, sig)); } catch { /* ok */ }
+    }
+
+    let recoveryContext = null;
+    if (this._handoverContent) {
+      recoveryContext = { type: "handover", content: this._handoverContent };
+      this._handoverContent = "";
+    } else if (this._retryCount > 0) {
+      recoveryContext = { type: "crash", retryCount: this._retryCount };
+    }
+
+    const prompt = buildRolePrompt({
+      role: this.role,
+      signalDir: this.signalDir,
+      task: this._task,
+      recoveryContext,
+    });
+
+    this._state = "running";
+    this._agent = new AgentProcess({
+      key: this.key,
+      cwd: this.cwd,
+      extraEnv: { IMPL_SIGNAL_BASE: IMPL_BASE },
+      signalDir: this.signalDir,
+    });
+    this._agent.spawnClaude(prompt, { model: this.model });
+
+    // Write PID to .running so recovery can kill orphans
+    try { fs.writeFileSync(path.join(this.signalDir, SIGNAL.RUNNING), String(this._agent.pid)); } catch { /* ok */ }
+
+    this._agent.on("exit", ({ exitCode, elapsed }) => {
+      this._agent = null;
+      try { fs.unlinkSync(path.join(this.signalDir, SIGNAL.RUNNING)); } catch { /* ok */ }
+
+      // Check for .done
+      const donePath = path.join(this.signalDir, SIGNAL.DONE);
+      if (fs.existsSync(donePath)) {
+        this._state = "idle";
+        this.emit("done", { key: this.key, role: this.role });
+        this.emit("lifecycle", { key: this.key, event: "done" });
+        return;
+      }
+
+      // No .done — crash or unexpected exit
+      this._retryCount++;
+      if (this._retryCount <= MAX_ROLE_RETRIES) {
+        const isFast = elapsed < FAST_EXIT_THRESHOLD_MS;
+        const backoffS = isFast
+          ? this._retryCount * FAST_EXIT_BACKOFF_S
+          : this._retryCount * NORMAL_BACKOFF_S;
+
+        this._state = "retrying";
+        this.emit("lifecycle", {
+          key: this.key,
+          event: "crash-retry",
+          retryCount: this._retryCount,
+          backoffS,
+          fastExit: isFast,
+        });
+
+        setTimeout(() => this._spawn(), backoffS * 1000);
+      } else {
+        // Max retries exceeded
+        this._state = "crashed";
+        try {
+          fs.writeFileSync(path.join(this.signalDir, SIGNAL.DONE), "CRASHED");
+          fs.writeFileSync(path.join(this.signalDir, SIGNAL.CRASHED), "CRASHED");
+        } catch { /* ignore */ }
+
+        this.emit("crashed", { key: this.key, role: this.role, retries: MAX_ROLE_RETRIES });
+        this.emit("lifecycle", { key: this.key, event: "crashed" });
+      }
+    });
+
+    this.emit("lifecycle", { key: this.key, event: "started" });
+  }
+}

package/lib/state-machines/team-orchestrator.js

@@ -0,0 +1,160 @@
+// team-orchestrator.js — Team orchestrator state machine.
+// Replaces run-team.sh orchestrator logic. Direct PTY spawn.
+//
+// IDLE ──[signal:task]──→ RUNNING ──[signal:gateReady]──→ GATE_READY
+//                             └──[exit + no .gate-ready + retry ≤1]──→ RETRYING → RUNNING
+
+import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import path from "node:path";
+import AgentProcess from "../agent-process.js";
+import { buildOrchestratorPrompt } from "../prompt-builder.js";
+import {
+  IMPL_BASE, IRIAI_TEAM_DIR, MAX_ORCH_RETRIES,
+  FAST_EXIT_THRESHOLD_MS, FAST_EXIT_BACKOFF_S, NORMAL_BACKOFF_S,
+  SIGNAL,
+} from "../constants.js";
+
+export default class TeamOrchestrator extends EventEmitter {
+  /**
+   * @param {object} opts
+   * @param {string} opts.slug - Feature slug
+   * @param {string} opts.teamNum - Team number
+   * @param {string} opts.teamDir - Team directory (signal base for team)
+   * @param {string} opts.orchDir - Orchestrator signal directory
+   * @param {string} [opts.model] - Claude model (default: "opus")
+   */
+  constructor({ slug, teamNum, teamDir, orchDir, model }) {
+    super();
+    this.slug = slug;
+    this.teamNum = teamNum;
+    this.teamDir = teamDir;
+    this.orchDir = orchDir;
+    this.model = model || "opus";
+    this.key = `team-${slug}-${teamNum}`;
+
+    this._agent = null;
+    this._state = "idle";
+    this._crashCount = 0;
+    this._task = "";
+  }
+
+  get state() { return this._state; }
+
+  /**
+   * Handle a new .task file from Feature Lead.
+   */
+  handleTask() {
+    if (this._state === "running") {
+      console.log(`[orch] ${this.key}: already running, ignoring task`);
+      return;
+    }
+
+    const taskPath = path.join(this.orchDir, SIGNAL.TASK);
+    try {
+      this._task = fs.readFileSync(taskPath, "utf-8").trim();
+      fs.unlinkSync(taskPath);
+    } catch {
+      return;
+    }
+    if (!this._task) return;
+
+    // Clean previous gate signals
+    for (const sig of [SIGNAL.DONE, SIGNAL.GATE_READY, SIGNAL.CRASHED,
+                        SIGNAL.GATE_APPROVED, SIGNAL.QUESTION, SIGNAL.ANSWER]) {
+      try { fs.unlinkSync(path.join(this.orchDir, sig)); } catch { /* ok */ }
+    }
+
+    this._crashCount = 0;
+    this._spawn();
+  }
+
+  kill() {
+    if (this._agent) {
+      this._agent.kill();
+      this._agent = null;
+    }
+    this._state = "idle";
+  }
+
+  _spawn() {
+    let recoveryContext = null;
+    if (this._crashCount > 0) {
+      recoveryContext = { retryCount: this._crashCount };
+    }
+
+    const prompt = buildOrchestratorPrompt({
+      teamDir: this.teamDir,
+      orchDir: this.orchDir,
+      task: this._task,
+      recoveryContext,
+    });
+
+    // Determine CWD — prefer worktree if available
+    const teamsRoot = path.join(path.dirname(IRIAI_TEAM_DIR), ".teams", `team-${this.teamNum}`);
+    const cwd = fs.existsSync(teamsRoot) ? teamsRoot : this.teamDir;
+
+    this._state = "running";
+
+    this._agent = new AgentProcess({
+      key: this.key,
+      cwd,
+      extraEnv: { IMPL_SIGNAL_BASE: IMPL_BASE },
+      signalDir: this.orchDir,
+    });
+    this._agent.spawnClaude(prompt, { model: this.model });
+
+    // Write PID to .running so recovery can kill orphans
+    fs.writeFileSync(path.join(this.orchDir, SIGNAL.RUNNING), String(this._agent.pid));
+
+    this._agent.on("exit", ({ exitCode, elapsed }) => {
+      this._agent = null;
+      try { fs.unlinkSync(path.join(this.orchDir, SIGNAL.RUNNING)); } catch { /* ok */ }
+
+      // Check for gate-ready (success)
+      if (fs.existsSync(path.join(this.orchDir, SIGNAL.GATE_READY))) {
+        this._state = "gate-ready";
+        this.emit("gateReady", { key: this.key, teamNum: this.teamNum });
+        this.emit("lifecycle", { key: this.key, event: "gate-ready" });
+        return;
+      }
+
+      // Check for .done (single-team fallback)
+      if (fs.existsSync(path.join(this.orchDir, SIGNAL.DONE))) {
+        this._state = "idle";
+        this.emit("done", { key: this.key, teamNum: this.teamNum });
+        this.emit("lifecycle", { key: this.key, event: "done" });
+        return;
+      }
+
+      // Crash — retry with backoff
+      this._crashCount++;
+      if (this._crashCount <= MAX_ORCH_RETRIES) {
+        const isFast = elapsed < FAST_EXIT_THRESHOLD_MS;
+        const backoffS = isFast
+          ? this._crashCount * FAST_EXIT_BACKOFF_S
+          : this._crashCount * NORMAL_BACKOFF_S;
+
+        this._state = "retrying";
+        this.emit("lifecycle", {
+          key: this.key,
+          event: "crash-retry",
+          retryCount: this._crashCount,
+          backoffS,
+        });
+
+        setTimeout(() => this._spawn(), backoffS * 1000);
+      } else {
+        this._state = "crashed";
+        try {
+          fs.writeFileSync(path.join(this.orchDir, SIGNAL.CRASHED), "CRASHED");
+        } catch { /* ignore */ }
+
+        this.emit("crashed", { key: this.key, teamNum: this.teamNum });
+        this.emit("lifecycle", { key: this.key, event: "crashed" });
+      }
+    });
+
+    this.emit("lifecycle", { key: this.key, event: "started" });
+  }
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "iriai-build",
+  "version": "0.1.0",
+  "description": "Iriai Build tool — AI agent orchestration CLI",
+  "main": "index.js",
+  "type": "module",
+  "bin": {
+    "iriai-build": "./bin/iriai-build.js"
+  },
+  "files": [
+    "bin/",
+    "cli/",
+    "lib/",
+    "v3/",
+    "index.js",
+    "bridge-v3.js"
+  ],
+  "scripts": {
+    "start": "node index.js",
+    "start:v2": "node bridge-v2.js",
+    "start:v3": "node bridge-v3.js"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.3.0",
+    "@slack/socket-mode": "^2.0.1",
+    "@slack/web-api": "^7.8.0",
+    "chokidar": "^4.0.3",
+    "commander": "^14.0.3",
+    "iriai-feedback": "^0.1.0"
+  }
+}

package/v3/.handover-html-evidence.md

@@ -0,0 +1,35 @@
+# Handover: HTML Evidence Hardening
+
+## Session 1 (2026-03-05)
+
+### Completed Files
+- [x] File 1: `v3/roles/implementer/CLAUDE.md` — Added deviations, self_reported_risks to Output, steps 6-7 to Process, replaced Context Management with .output.partial protocol (file_complete, deviation, risk entry types)
+- [x] File 2: `v3/roles/backend-implementer/CLAUDE.md` — Same as #1 (steps 5-6 added as "Process continued")
+- [x] File 3: `v3/roles/frontend-implementer/CLAUDE.md` — Same as #1
+- [x] File 4: `v3/roles/database-implementer/CLAUDE.md` — Same as #1
+- [x] File 5: `v3/roles/code-reviewer/CLAUDE.md` — Added gaps field (categories: error-handling, input-validation, pattern-compliance, edge-cases, test-coverage), .output.partial protocol (file_review, gap entry types)
+- [x] File 6: `v3/roles/security-auditor/CLAUDE.md` — Added gaps field (categories: auth, injection, rate-limiting, secrets, cors, csrf, data-exposure), .output.partial protocol (endpoint_review, gap entry types)
+- [x] File 7: `v3/roles/integration-tester/CLAUDE.md` — Added comprehensive E2E mandate section (happy path + error cases per journey + gap reporting), gaps field (categories: untested-journey, missing-error-case, missing-edge-case, visual-gap), .output.partial protocol (journey, gap entry types)
+- [x] File 8: `v3/roles/regression-tester/CLAUDE.md` — Added gaps field (categories: untested-regression, missing-backward-compat, skipped-test-suite), .output.partial protocol (test_suite, gap entry types)
+- [x] File 9: `v3/roles/verifier/CLAUDE.md` — Added gaps field (categories: unverified-criterion, insufficient-evidence, missing-acceptance-check), .output.partial protocol (criterion_check, gap entry types)
+- [x] File 10: `v3/roles/orchestrator/CLAUDE.md` — Added steps 4b (review gaps), 4c (aggregate deviations/risks), 4d (build coverage matrix). Updated gate evidence YAML example with coverage_matrix, deviations, self_reported_risks, reviewer_comments, error-case journeys, gaps in qa_verdicts. Added note about team HTML compilation (no buttons, doc_type: "team")
+- [x] File 11: `v3/roles/feature-lead/CLAUDE.md` — Added steps 4b (review gaps across levels), 4c (cross-team integration surface), 4d (feature-level coverage matrix), 4e (FL comments). Updated step 6 (merge evidence with new fields), step 7 (doc_type: "feature", team_html_paths), step 8 (HTML IS the message, no text summary)
+- [x] File 12: `tools/visual-verification-mcp/evidence-compiler.js` — Major overhaul: validateEvidence() warns on missing gaps/deviations/coverage_matrix, errors on missing reviewer_comments for feature docs. buildHtml() now renders: coverage matrix table, deviation cards, self-reported risk cards, happy path / error case journey grouping, QA gaps subsections, pending QA sections, reviewer comments, cross-team surface (feature only), team evidence links (feature only). New CSS: .section-pending, .gap-item, .coverage-* classes. handleCompileGateEvidence() accepts doc_type and team_html_paths params.
+- [x] File 13: `iriai-build/v3/prompt-builder.js` — Updated buildGateReviewInstructions() step 6 (include coverage_matrix, deviations, self_reported_risks, reviewer_comments, cross_team_surface), step 7 (doc_type: "feature", team_html_paths), step 8 (HTML IS the message, no text summary)
+- [x] File 14: `iriai-build/v3/constants.js` — Added OUTPUT_PARTIAL: ".output.partial" to SIGNAL object
+- [x] File 15: `iriai-build/v3/orchestrator.js` — Removed text status messages: _requestPhaseReview (summary post), handlePhaseReviewApproval ("Phase approved..."), handlePhaseReviewRejection ("phase rejected..."), handlePlanApproval ("Plan approved!", "Creating branches...", "Feature branches created...", "Implementation launched..."), handleGateApproval ("Gate approved!"), handleGateRejection ("Gate rejected...")
+
+### In Progress
+(none — all complete)
+
+### Not Started
+(none — all complete)
+
+### Decisions Made
+- Used `_doc_type` and `_team_html_links` as internal properties on the evidence object (prefixed with underscore) to pass doc_type/team_html_paths from handler to buildHtml/validateEvidence without polluting the YAML schema
+- Kept `nextLabel` variable in handlePhaseReviewApproval even though channel post was removed — it may be used elsewhere or for logging
+- Removed ALL text status posts from planning thread in handlePlanApproval including "Implementation launched" (not explicitly listed in plan but follows the principle of "NO text-based status messages in the planning thread")
+- For pending QA sections, check against EXPECTED_QA_ROLES constant defined in buildHtml
+
+### Notes for Next Session
+All 15 files are complete. No further work needed.

package/v3/KICKOFF-HTML-EVIDENCE.md

@@ -0,0 +1,98 @@
+# Kickoff: HTML Evidence Document Hardening
+
+## Your Mission
+
+Implement the plan at `iriai-build/v3/PLAN-HTML-EVIDENCE-HARDENING.md`. Read it fully before starting.
+
+## Key Files (absolute paths)
+
+### Plan & Handover
+- Plan: `/Users/danielzhang/src/iriai/iriai-build/v3/PLAN-HTML-EVIDENCE-HARDENING.md`
+- Handover: `/Users/danielzhang/src/iriai/iriai-build/v3/.handover-html-evidence.md`
+
+### Files to Modify (15 total)
+
+**Phase 1 — Implementer CLAUDE.md (add deviations, self_reported_risks, .output.partial):**
+1. `/Users/danielzhang/src/iriai/iriai-build/v3/roles/implementer/CLAUDE.md`
+2. `/Users/danielzhang/src/iriai/iriai-build/v3/roles/backend-implementer/CLAUDE.md`
+3. `/Users/danielzhang/src/iriai/iriai-build/v3/roles/frontend-implementer/CLAUDE.md`
+4. `/Users/danielzhang/src/iriai/iriai-build/v3/roles/database-implementer/CLAUDE.md`
+
+**Phase 1 — Review agent CLAUDE.md (add gaps, .output.partial):**
+5. `/Users/danielzhang/src/iriai/iriai-build/v3/roles/code-reviewer/CLAUDE.md`
+6. `/Users/danielzhang/src/iriai/iriai-build/v3/roles/security-auditor/CLAUDE.md`
+7. `/Users/danielzhang/src/iriai/iriai-build/v3/roles/integration-tester/CLAUDE.md` (also: comprehensive E2E mandate)
+8. `/Users/danielzhang/src/iriai/iriai-build/v3/roles/regression-tester/CLAUDE.md`
+9. `/Users/danielzhang/src/iriai/iriai-build/v3/roles/verifier/CLAUDE.md`
+
+**Phase 1 — Constants:**
+14. `/Users/danielzhang/src/iriai/iriai-build/v3/constants.js` (add OUTPUT_PARTIAL signal)
+
+**Phase 2 — Orchestrator & Feature Lead CLAUDE.md:**
+10. `/Users/danielzhang/src/iriai/iriai-build/v3/roles/orchestrator/CLAUDE.md` (coverage matrix, deviation aggregation, reviewer comments, team HTML compilation — no buttons)
+11. `/Users/danielzhang/src/iriai/iriai-build/v3/roles/feature-lead/CLAUDE.md` (cross-team surface, FL comments, feature-level coverage matrix, sole poster of approve/reject with HTML)
+
+**Phase 3 — Code changes:**
+12. `/Users/danielzhang/src/iriai/tools/visual-verification-mcp/evidence-compiler.js` (HTML template overhaul, new sections, pending styling, doc_type param)
+13. `/Users/danielzhang/src/iriai/iriai-build/v3/prompt-builder.js` (gate review instructions update)
+15. `/Users/danielzhang/src/iriai/iriai-build/v3/orchestrator.js` (remove text status messages from planning thread)
+
+## Execution Rules
+
+1. Read the plan fully before making any changes
+2. Read each file before editing it
+3. Work through phases in order (Phase 1 files can be done in parallel, Phase 2 depends on Phase 1, Phase 3 parallel with Phase 2)
+4. For CLAUDE.md files: ADD new sections/fields to existing content — do not rewrite entire files
+5. For evidence-compiler.js: this is a major overhaul of the buildHtml() function and validateEvidence() — read the full file first
+6. For orchestrator.js: surgical removal of specific `postToChannel`/`postToThread` calls in planning thread — do not change dispatch logic
+
+## Recursive Handover Protocol
+
+You will likely not finish all 15 files in one context window. Before your context runs low:
+
+1. Write your progress to `/Users/danielzhang/src/iriai/iriai-build/v3/.handover-html-evidence.md` using this format:
+
+```markdown
+# Handover: HTML Evidence Hardening
+
+## Session N (date)
+
+### Completed Files
+- [x] File 1: `/path/to/file` — description of changes made
+- [x] File 2: ...
+
+### In Progress
+- [ ] File X: `/path/to/file` — what was started, what remains
+
+### Not Started
+- [ ] File Y: `/path/to/file`
+- [ ] File Z: ...
+
+### Decisions Made
+- [any judgment calls or deviations from the plan]
+
+### Notes for Next Session
+- [anything the next session needs to know]
+```
+
+2. Tell the user: "Context getting low. Handover written. Start a new session with this prompt."
+
+## Resuming From Handover
+
+If `.handover-html-evidence.md` exists, read it FIRST. It contains:
+- Which files are done (do NOT re-edit them)
+- Which file was in progress (finish it)
+- Which files remain (continue in order)
+
+Then continue executing the plan from where the previous session left off. Update the handover file before your own context runs low, incrementing the session number.
+
+## Summary of What We're Building
+
+- **Incremental output (.output.partial)**: Append-only multi-doc YAML so agents don't lose work on context exhaustion
+- **Enriched schemas**: Implementers report deviations + risks. Review agents report gaps. Orchestrator/FL add reviewer comments.
+- **Integration-tester mandate**: Comprehensive GIFs for every golden path AND every error case
+- **Coverage matrix**: Plan items mapped to implemented/verified/missing status
+- **HTML overhaul**: New sections (coverage matrix, deviations, risks, gaps per agent, reviewer comments, cross-team surface), pending section styling, feature-level doc links to team docs
+- **Approve/reject buttons**: ONLY on feature gate HTML in impl channel (not per-team)
+- **Planning thread**: HTML evidence docs only, no text status messages
+- **Impl channel**: Gate approvals must now include the feature gate HTML attachment. Everything else unchanged.