@smartmemory/compose 0.2.8-beta → 0.2.9-beta

package/lib/build.js

@@ -58,6 +58,8 @@ import { CrossLayerAudit, loadDebugConfig } from './cross-layer-audit.js';
 import { emitCheckpoint } from './bug-checkpoint.js';
 import { appendHypothesisEntry, readHypotheses } from './bug-ledger.js';
 import { tier1CodexReview, tier2FreshAgent } from './bug-escalation.js';
+import { recordTaskStates, writeTimingSidecar } from './gsd-timing.js';
+import { writeGsdTaskDiff } from './gsd-diff-capture.js';
 
 // ---------------------------------------------------------------------------
 // COMP-FIX-HARD T5: per-step retries cap parser
@@ -2958,6 +2960,11 @@ export async function executeParallelDispatchServer(
   // mode invokes this fn with 6 args (opts={}) so every detector branch below
   // is skipped and build behavior stays byte-identical.
   const stuckDetector = opts.stuckDetector ?? null;
+  // COMP-GSD-6: optional per-task heartbeat. ONLY the gsd headless path passes
+  // one; build mode (opts={}) leaves it null so behavior stays byte-identical.
+  // Bumped from the push-event callback so a long task sitting in the dispatch
+  // poll loop keeps state.json's heartbeat fresh (else it would look crashed).
+  const onHeartbeat = typeof opts.onHeartbeat === 'function' ? opts.onHeartbeat : null;
   const startedTasks = new Set();
 
   if (streamWriter) {
@@ -2989,11 +2996,15 @@ export async function executeParallelDispatchServer(
   // state-machine driver. Forward valid events through streamWriter so the
   // bridge rebroadcasts them via SSE under the buildStreamEvent wrapper.
   let unsubscribePush = null;
-  if (typeof stratum.onEvent === 'function' && (streamWriter || stuckDetector)) {
+  if (typeof stratum.onEvent === 'function' && (streamWriter || stuckDetector || onHeartbeat)) {
     unsubscribePush = stratum.onEvent(flowId, stepId, (event) => {
       // Accept all KNOWN_VERSIONS (producer emits 0.2.6); pinning '0.2.5' dropped
       // every push event from the current producer. Client already validated.
       if (!event || !KNOWN_VERSIONS.has(event.schema_version)) return;
+      // COMP-GSD-6: any accepted event proves the run is alive — bump heartbeat.
+      if (onHeartbeat) {
+        try { onHeartbeat(event); } catch (err) { console.error('[build] heartbeat hook failed:', err); }
+      }
       // COMP-GSD-5: feed the per-task stuck detector (no-op in build mode —
       // stuckDetector is null there). record() ignores all but
       // tool_use_summary/tool_result and keys by event.task_id.
@@ -3009,6 +3020,13 @@ export async function executeParallelDispatchServer(
     });
   }
 
+  // COMP-GSD-7: capture poll-observed per-task timing (gsd path only). Stratum's
+  // poll response carries no per-task timing, so we stamp first-sight / first-
+  // terminal from our own poll loop and persist a timing.json sidecar for the
+  // milestone report. Gated on context.gsd so build mode is byte-identical.
+  const captureTiming = context?.gsd === true && !!context?.featureCode;
+  const taskTiming = {};
+
   try {
     // Poll until outcome is present (NOT can_advance — see design §3)
     let pollResult;
@@ -3021,6 +3039,7 @@ export async function executeParallelDispatchServer(
           `stratum_parallel_poll failed: ${pollResult.error}: ${pollResult.message || ''}`,
         );
       }
+      if (captureTiming) recordTaskStates(taskTiming, pollResult.tasks, new Date().toISOString());
       emitPerTaskProgress(streamWriter, pollResult, emittedStates);
 
       // COMP-GSD-5: real-time stuck detection (gsd path only — null in build).
@@ -3063,6 +3082,13 @@ export async function executeParallelDispatchServer(
       await new Promise((resolve) => setTimeout(resolve, intervalMs));
     }
 
+    // COMP-GSD-7: persist the timing sidecar on every terminal path (complete,
+    // stuck, budget) — best-effort; a write failure must never derail dispatch.
+    if (captureTiming) {
+      try { writeTimingSidecar(baseCwd, context.featureCode, taskTiming); }
+      catch (err) { console.error('[build] gsd timing sidecar write failed:', err.message); }
+    }
+
     // COMP-GSD-5: short-circuit return on a stuck verdict. The cancel outcome is
     // returned verbatim with the verdict attached; the gsd run loop branches on
     // `.stuck`. This bypasses the merge/advance bookkeeping below — there is
@@ -3340,7 +3366,15 @@ function applyServerDispatchDiffsCore(taskList, pollTasks, baseCwd, streamWriter
       }
       continue;
     }
-    if (ts?.diff != null) diffMap.set(taskId, ts.diff);
+    if (ts?.diff != null) {
+      diffMap.set(taskId, ts.diff);
+      // COMP-GSD-7: snapshot the diff before the worktree is cleaned up, so the
+      // milestone report can inline it. gsd path only (context.gsd); best-effort.
+      if (context?.gsd === true && context?.featureCode) {
+        try { writeGsdTaskDiff(baseCwd, context.featureCode, taskId, ts.diff); }
+        catch (err) { console.error('[build] gsd diff snapshot write failed:', err.message); }
+      }
+    }
   }
 
   if (diffMap.size === 0) {

package/lib/gsd-diff-capture.js

@@ -0,0 +1,34 @@
+// lib/gsd-diff-capture.js
+//
+// COMP-GSD-7 S3: persist per-task diff snapshots for the milestone report.
+//
+// When a GSD parallel task runs in a worktree with capture_diff:true, Stratum
+// returns the unified diff in the poll payload (ts.diff). build.js consumes it
+// at the merge site and then drops it once the worktree is cleaned up. This
+// helper snapshots that diff to .compose/gsd/<feature>/diffs/<taskId>.diff so
+// the report (lib/gsd-milestone-report.js) can inline it. The path helper is the
+// single source of truth shared with the report reader.
+//
+// Atomic write: tmp+rename, mirrors lib/gsd-state.js:44.
+
+import { writeFileSync, existsSync, mkdirSync, renameSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function gsdDiffsDir(cwd, featureCode) {
+  return join(cwd, '.compose', 'gsd', featureCode, 'diffs');
+}
+
+export function gsdTaskDiffPath(cwd, featureCode, taskId) {
+  return join(gsdDiffsDir(cwd, featureCode), `${taskId}.diff`);
+}
+
+/** Atomic write of a task's unified diff. Returns the path. */
+export function writeGsdTaskDiff(cwd, featureCode, taskId, diffText) {
+  mkdirSync(gsdDiffsDir(cwd, featureCode), { recursive: true });
+  const target = gsdTaskDiffPath(cwd, featureCode, taskId);
+  const tmp = `${target}.tmp`;
+  if (existsSync(tmp)) { try { unlinkSync(tmp); } catch { /* ignore */ } }
+  writeFileSync(tmp, diffText);
+  renameSync(tmp, target);
+  return target;
+}

package/lib/gsd-events.js

@@ -0,0 +1,61 @@
+// lib/gsd-events.js
+//
+// COMP-GSD-7-EVENTLOG: append-only GSD run-event log at
+// .compose/gsd/<feature>/events.jsonl — one JSON object per line,
+// { ts, kind, ...detail }. GSD otherwise persists only snapshots, so the
+// milestone report's timeline (COMP-GSD-7) had to reconstruct order from
+// whatever artifacts happened to exist. This log records what happened, in
+// order, across resume sessions; the report consumes it (snapshot fallback).
+//
+// All writes are BEST-EFFORT — an event-log failure must never affect the run.
+// The reader tolerates a torn/corrupt final line (crash mid-append) by skipping
+// unparseable lines.
+//
+// Contract: `detail` must NOT contain `ts` or `kind` keys (the event kind would
+// be clobbered). For a `paused` event the stuck/budget discriminator is
+// `pauseKind`, not `kind`.
+
+import { appendFileSync, readFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+function gsdDir(cwd, featureCode) {
+  return join(cwd, '.compose', 'gsd', featureCode);
+}
+
+export function gsdEventsPath(cwd, featureCode) {
+  return join(gsdDir(cwd, featureCode), 'events.jsonl');
+}
+
+export function appendGsdEvent(cwd, featureCode, kind, detail = {}) {
+  try {
+    mkdirSync(gsdDir(cwd, featureCode), { recursive: true });
+    const line = JSON.stringify({ ts: new Date().toISOString(), kind, ...detail }) + '\n';
+    appendFileSync(gsdEventsPath(cwd, featureCode), line);
+  } catch { /* best-effort — never affect the run */ }
+}
+
+export function readGsdEvents(cwd, featureCode) {
+  const p = gsdEventsPath(cwd, featureCode);
+  if (!existsSync(p)) return [];
+  let raw;
+  try { raw = readFileSync(p, 'utf-8'); } catch { return []; }
+  const out = [];
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    let parsed;
+    try { parsed = JSON.parse(line); } catch { continue; /* skip torn/corrupt line */ }
+    // Only event OBJECTS are usable — a parseable scalar/array/null is not an
+    // event (and would throw in the report's label mapping). Treat as "no event".
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) out.push(parsed);
+  }
+  return out;
+}
+
+// COMP-GSD-7-EVENTLOG: fresh-run truncate. Empties the log so a new run's
+// timeline doesn't inherit a prior (abandoned) run's events. Called at the
+// planning checkpoint, AFTER preconditions pass (so a failed fresh invocation
+// doesn't destroy a prior run's history).
+export function clearGsdEvents(cwd, featureCode) {
+  const p = gsdEventsPath(cwd, featureCode);
+  try { if (existsSync(p)) writeFileSync(p, ''); } catch { /* best-effort */ }
+}

package/lib/gsd-headless-config.js

@@ -0,0 +1,110 @@
+// lib/gsd-headless-config.js
+//
+// COMP-GSD-6 S05: headless auto-resume policy. Reads `gsd.headless.*` from
+// .compose/compose.json and merges over conservative defaults. Every pause kind
+// is independently overridable (per the product decision): crash and stuck
+// auto-resume by default, budget does NOT (opting in would defeat the GSD-4
+// ceiling), but a user MAY set budget.enabled:true for a fully-unattended burn.
+//
+// Unset config ⇒ defaults ⇒ behavior is a plain run plus supervision.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const HEADLESS_DEFAULTS = Object.freeze({
+  autoResume: {
+    crash: { enabled: true, maxAttempts: 5 },
+    stuck: { enabled: true, maxAttempts: 2 },
+    budget: { enabled: false, maxAttempts: 0 },
+    // COMP-GSD-6-WATCHDOG: a hung child (heartbeat frozen on a live pid) is
+    // killed + resumed like a crash. On by default — that's the whole point of
+    // unattended robustness.
+    hung: { enabled: true, maxAttempts: 3 },
+  },
+  backoff: { baseMs: 2000, factor: 2, maxMs: 60000 },
+  heartbeatStaleMs: 90000,
+  // COMP-GSD-6-WATCHDOG: supervisor poll cadence, SIGTERM→SIGKILL grace, and the
+  // child's independent wall-clock heartbeat cadence (must be < heartbeatStaleMs).
+  watchdogPollMs: 15000,
+  watchdogKillGraceMs: 5000,
+  watchdogHeartbeatMs: 30000,
+});
+
+function num(v, fallback) {
+  return typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : fallback;
+}
+function bool(v, fallback) {
+  return typeof v === 'boolean' ? v : fallback;
+}
+
+function mergeKind(override, def) {
+  const o = override ?? {};
+  return {
+    enabled: bool(o.enabled, def.enabled),
+    maxAttempts: num(o.maxAttempts, def.maxAttempts),
+  };
+}
+
+// Merge a raw `gsd.headless` object over HEADLESS_DEFAULTS with per-field type
+// validation (a malformed field falls back to its default, never throws).
+export function resolveHeadlessConfig(raw) {
+  const h = raw && typeof raw === 'object' ? raw : {};
+  const ar = h.autoResume && typeof h.autoResume === 'object' ? h.autoResume : {};
+  const bo = h.backoff && typeof h.backoff === 'object' ? h.backoff : {};
+  const d = HEADLESS_DEFAULTS;
+
+  // COMP-GSD-6-WATCHDOG: enforce the load-bearing invariant
+  // `watchdogHeartbeatMs < heartbeatStaleMs`. The child must restamp its heartbeat
+  // at least twice within the stale window, or a healthy quiet child trips the
+  // watchdog. Two guards:
+  //   - a degenerate stale window (< 2ms, incl. 0) is unusable — there's no room
+  //     for a smaller heartbeat — so it falls back to the default.
+  //   - a heartbeat cadence ≥ the (now positive) stale window is clamped to half
+  //     it (always strictly < stale for stale ≥ 2), rather than honored.
+  let heartbeatStaleMs = num(h.heartbeatStaleMs, d.heartbeatStaleMs);
+  if (heartbeatStaleMs < 2) heartbeatStaleMs = d.heartbeatStaleMs;
+  let watchdogHeartbeatMs = num(h.watchdogHeartbeatMs, d.watchdogHeartbeatMs);
+  if (watchdogHeartbeatMs >= heartbeatStaleMs) {
+    watchdogHeartbeatMs = Math.floor(heartbeatStaleMs / 2);
+  }
+
+  return {
+    autoResume: {
+      crash: mergeKind(ar.crash, d.autoResume.crash),
+      stuck: mergeKind(ar.stuck, d.autoResume.stuck),
+      budget: mergeKind(ar.budget, d.autoResume.budget),
+      hung: mergeKind(ar.hung, d.autoResume.hung),
+    },
+    backoff: {
+      baseMs: num(bo.baseMs, d.backoff.baseMs),
+      factor: num(bo.factor, d.backoff.factor),
+      maxMs: num(bo.maxMs, d.backoff.maxMs),
+    },
+    heartbeatStaleMs,
+    watchdogPollMs: num(h.watchdogPollMs, d.watchdogPollMs),
+    watchdogKillGraceMs: num(h.watchdogKillGraceMs, d.watchdogKillGraceMs),
+    watchdogHeartbeatMs,
+  };
+}
+
+// Read .compose/compose.json gsd.headless.* and resolve against defaults.
+export function readHeadlessConfig(cwd) {
+  const configPath = join(cwd, '.compose', 'compose.json');
+  let raw = {};
+  if (existsSync(configPath)) {
+    try {
+      const cfg = JSON.parse(readFileSync(configPath, 'utf-8'));
+      raw = cfg?.gsd?.headless ?? {};
+    } catch {
+      /* malformed config → defaults */
+    }
+  }
+  return resolveHeadlessConfig(raw);
+}
+
+// Backoff for attempt N (1-based): base * factor^(N-1), capped at maxMs.
+export function backoffMs(cfg, attempt) {
+  const { baseMs, factor, maxMs } = cfg.backoff;
+  const raw = baseMs * Math.pow(factor, Math.max(0, attempt - 1));
+  return Math.min(raw, maxMs);
+}

package/lib/gsd-milestone-report.js

@@ -0,0 +1,323 @@
+// lib/gsd-milestone-report.js
+//
+// COMP-GSD-7: milestone report generator. On GSD feature completion (and via
+// `compose gsd report <feature>`), assemble a read-only data model from the
+// persisted run artifacts and render a single self-contained HTML report to
+// docs/gsd-reports/<feature>.html — auto-discovered by the cockpit DocsView.
+//
+// Data sources (all read-only):
+//   .compose/gsd/<f>/state.json        run state + completedAt (gsd-state.js)
+//   .compose/gsd/<f>/blackboard.json   per-task TaskResults (gsd-blackboard.js)
+//   .compose/gsd/<f>/timing.json       per-task elapsed (gsd-timing.js sidecar)
+//   .compose/gsd/<f>/diffs/<id>.diff   per-task diff snapshots (build.js capture)
+//   budget-final.json | budget.json    budget actuals vs caps (gsd-budget shape)
+//
+// HTML shape mirrors server/graph-export.js: one template literal, inline CSS,
+// no external assets. Atomic write mirrors gsd-state.js:44.
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { readGsdState } from './gsd-state.js';
+import { read as readBlackboard } from './gsd-blackboard.js';
+import { readTimingSidecar } from './gsd-timing.js';
+import { gsdTaskDiffPath } from './gsd-diff-capture.js';
+import { readGsdEvents } from './gsd-events.js';
+
+const DIFF_INLINE_CAP_BYTES = 200 * 1024; // 200 KB per task
+
+function gsdDir(cwd, featureCode) {
+  return join(cwd, '.compose', 'gsd', featureCode);
+}
+
+function readJsonOrNull(p) {
+  if (!existsSync(p)) return null;
+  try { return JSON.parse(readFileSync(p, 'utf-8')); } catch { return null; }
+}
+
+// ---------- Model assembly ----------
+
+function resolveBudget(cwd, featureCode, opts) {
+  // Precedence: in-process budget_state → budget-final.json → halt budget.json → none.
+  const fromOpts = opts?.budgetState;
+  const src = fromOpts
+    ?? readJsonOrNull(join(gsdDir(cwd, featureCode), 'budget-final.json'))
+    ?? readJsonOrNull(join(gsdDir(cwd, featureCode), 'budget.json'));
+  if (!src || (!src.caps && !src.consumed)) return { configured: false, caps: {}, consumed: {}, axis: null };
+  return { configured: true, caps: src.caps ?? {}, consumed: src.consumed ?? {}, axis: src.axis ?? null };
+}
+
+function readDiff(cwd, featureCode, taskId) {
+  const p = gsdTaskDiffPath(cwd, featureCode, taskId);
+  if (!existsSync(p)) return null;
+  try { return readFileSync(p, 'utf-8'); } catch { return null; }
+}
+
+// COMP-GSD-7-EVENTLOG: map a run-event to a timeline row. Unknown future kinds
+// render their kind verbatim rather than dropping out.
+function eventLabel(e) {
+  switch (e.kind) {
+    case 'run_started': return `Run started (${e.mode ?? 'fresh'})`;
+    case 'phase': return `Phase: ${e.phase ?? '?'}`;
+    case 'task_completed': return `Task completed: ${e.taskId ?? '?'}`;
+    case 'paused': return `Paused (${e.pauseKind ?? '?'})`;
+    case 'completed': return 'Run completed';
+    case 'failed': return `Run failed${e.reason ? `: ${e.reason}` : ''}`;
+    default: return String(e.kind ?? 'event');
+  }
+}
+
+function buildTimeline(state, cwd, featureCode) {
+  // COMP-GSD-7-EVENTLOG: prefer the real append-only event stream. Fall back to
+  // the snapshot-derived timeline only when there are ZERO usable events (a run
+  // that predates the log, or a truncated/torn/corrupt file) — never render an
+  // empty timeline because the file happens to exist.
+  const events = readGsdEvents(cwd, featureCode);
+  if (events.length > 0) {
+    return events.map((e) => ({ label: eventLabel(e), ts: e.ts ?? null }));
+  }
+
+  const dir = gsdDir(cwd, featureCode);
+  const tl = [];
+  if (state.startedAt) tl.push({ label: 'Run started', ts: state.startedAt });
+  if (existsSync(join(dir, 'stuck.json'))) {
+    const s = readJsonOrNull(join(dir, 'stuck.json'));
+    tl.push({ label: `Stuck halt${s?.taskId ? ` (${s.taskId})` : ''}`, ts: s?.ts ?? null });
+  }
+  if (existsSync(join(dir, 'budget.json'))) {
+    const b = readJsonOrNull(join(dir, 'budget.json'));
+    tl.push({ label: `Budget halt${b?.axis ? ` (${b.axis})` : ''}`, ts: b?.ts ?? null });
+  }
+  if (existsSync(join(dir, 'pause.json'))) {
+    const p = readJsonOrNull(join(dir, 'pause.json'));
+    tl.push({ label: `Paused${p?.kind ? ` (${p.kind})` : ''}`, ts: p?.ts ?? null });
+  }
+  if (state.completedAt) {
+    tl.push({ label: `Run ${state.status === 'complete' ? 'completed' : `ended (${state.status})`}`, ts: state.completedAt });
+  }
+  return tl;
+}
+
+/**
+ * Read all persisted artifacts for a completed GSD feature and return a flat,
+ * render-ready model. Returns null if there is no run state at all.
+ */
+export function assembleReportModel(featureCode, cwd, opts = {}) {
+  const state = readGsdState(cwd, featureCode);
+  if (!state) return null;
+
+  const blackboard = readBlackboard(featureCode, { cwd });
+  const timing = readTimingSidecar(cwd, featureCode);
+
+  // Order by decomposedTasks; append any blackboard tasks not in the graph.
+  const order = Array.isArray(state.decomposedTasks)
+    ? state.decomposedTasks.map((t) => t.id).filter(Boolean)
+    : [];
+  const ids = [...order];
+  for (const id of Object.keys(blackboard)) if (!ids.includes(id)) ids.push(id);
+
+  const tasks = ids.map((id) => {
+    const tr = blackboard[id] ?? {};
+    const tm = timing[id] ?? {};
+    const diff = readDiff(cwd, featureCode, id);
+    return {
+      id,
+      status: tr.status ?? 'unknown',
+      attempts: tr.attempts ?? null,
+      filesChanged: Array.isArray(tr.files_changed) ? tr.files_changed : [],
+      summary: tr.summary ?? '',
+      startedAt: tm.startedAt ?? null,
+      completedAt: tm.completedAt ?? null,
+      durationMs: typeof tm.durationMs === 'number' ? tm.durationMs : null,
+      hasDiff: diff != null,
+      diff: diff ?? null,
+    };
+  });
+
+  const completedSet = new Set(Array.isArray(state.completedTaskIds) ? state.completedTaskIds : []);
+  const completed = completedSet.size || tasks.filter((t) => t.status === 'passed').length;
+  const taskCount = tasks.length;
+  const totalWallClockMs = state.startedAt && state.completedAt
+    ? Math.max(0, Date.parse(state.completedAt) - Date.parse(state.startedAt))
+    : null;
+
+  return {
+    feature: featureCode,
+    status: state.status ?? 'unknown',
+    phase: state.phase ?? null,
+    startedAt: state.startedAt ?? null,
+    completedAt: state.completedAt ?? null,
+    flowId: state.flowId ?? null,
+    tasks,
+    budget: resolveBudget(cwd, featureCode, opts),
+    timeline: buildTimeline(state, cwd, featureCode),
+    totals: {
+      taskCount,
+      completed,
+      completionRate: taskCount > 0 ? completed / taskCount : 0,
+      totalWallClockMs,
+    },
+  };
+}
+
+// ---------- HTML render ----------
+
+function esc(s) {
+  return String(s ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function fmtMs(ms) {
+  if (ms == null) return '—';
+  if (ms < 1000) return `${ms} ms`;
+  const s = ms / 1000;
+  if (s < 60) return `${s.toFixed(1)} s`;
+  const m = Math.floor(s / 60);
+  return `${m}m ${Math.round(s - m * 60)}s`;
+}
+
+const BUDGET_ROWS = [
+  { axis: 'tokens', cap: 'max_tokens', use: 'tokens', fmt: (v) => String(v ?? 0) },
+  { axis: 'agent dispatches', cap: 'max_agent_dispatches', use: 'dispatches', fmt: (v) => String(v ?? 0) },
+  { axis: 'wall-clock (s)', cap: 'ms', use: 'wall_s', fmt: (v) => String(Math.round(v ?? 0)), capFmt: (v) => String(Math.round((v ?? 0) / 1000)) },
+  { axis: 'cost (USD)', cap: 'usd', use: 'dollars', fmt: (v) => Number(v ?? 0).toFixed(4), capFmt: (v) => Number(v ?? 0).toFixed(4) },
+];
+
+function renderBudget(budget) {
+  if (!budget.configured) {
+    return `<p class="muted">Unbudgeted run — no GSD budget caps were enforced.</p>`;
+  }
+  const rows = BUDGET_ROWS
+    .filter((r) => budget.caps[r.cap] != null)
+    .map((r) => {
+      const cap = r.capFmt ? r.capFmt(budget.caps[r.cap]) : String(budget.caps[r.cap]);
+      const used = r.fmt(budget.consumed[r.use]);
+      return `<tr><td>${esc(r.axis)}</td><td>${esc(used)}</td><td>${esc(cap)}</td></tr>`;
+    })
+    .join('\n');
+  if (!rows) return `<p class="muted">Budget configured but no enforced axes recorded.</p>`;
+  return `<table><thead><tr><th>Axis</th><th>Consumed</th><th>Cap</th></tr></thead><tbody>${rows}</tbody></table>`;
+}
+
+function renderTaskDiff(task) {
+  if (!task.hasDiff) {
+    const files = task.filesChanged.length
+      ? `<p class="muted">No diff captured. Files changed: ${task.filesChanged.map(esc).join(', ')}</p>`
+      : `<p class="muted">No diff captured.</p>`;
+    return files;
+  }
+  let body = task.diff;
+  let note = '';
+  if (Buffer.byteLength(body, 'utf-8') > DIFF_INLINE_CAP_BYTES) {
+    body = body.slice(0, DIFF_INLINE_CAP_BYTES);
+    note = `<p class="muted">Diff truncated at ${Math.round(DIFF_INLINE_CAP_BYTES / 1024)} KB — see .compose/gsd/&lt;feature&gt;/diffs/${esc(task.id)}.diff for the full text.</p>`;
+  }
+  return `<details><summary>diff (${task.filesChanged.length} file${task.filesChanged.length !== 1 ? 's' : ''})</summary>${note}<pre class="diff">${esc(body)}</pre></details>`;
+}
+
+function renderTasks(tasks) {
+  return tasks.map((t) => `
+    <div class="task">
+      <h3>${esc(t.id)} <span class="status status-${esc(t.status)}">${esc(t.status)}</span></h3>
+      <div class="meta">attempts: ${esc(t.attempts ?? '—')} · files: ${t.filesChanged.length} · elapsed: ${esc(fmtMs(t.durationMs))}</div>
+      ${t.summary ? `<p class="summary">${esc(t.summary)}</p>` : ''}
+      ${renderTaskDiff(t)}
+    </div>`).join('\n');
+}
+
+function renderTimeline(timeline) {
+  if (!timeline.length) return '';
+  const items = timeline.map((e) => `<li><span class="ts">${esc(e.ts ?? '—')}</span> ${esc(e.label)}</li>`).join('\n');
+  return `<ul class="timeline">${items}</ul>`;
+}
+
+/** Pure: model → self-contained HTML string. */
+export function renderReportHtml(model) {
+  const t = model.totals;
+  const pct = `${Math.round(t.completionRate * 100)}%`;
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>${esc(model.feature)} — GSD Milestone Report</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { font: 14px/1.5 -apple-system, system-ui, sans-serif; max-width: 980px; margin: 2rem auto; padding: 0 1rem; }
+  h1 { margin-bottom: .25rem; } h2 { margin-top: 2rem; border-bottom: 1px solid #8884; padding-bottom: .25rem; }
+  .sub { color: #888; margin-top: 0; }
+  table { border-collapse: collapse; width: 100%; margin: .5rem 0; }
+  th, td { text-align: left; padding: .35rem .6rem; border-bottom: 1px solid #8883; }
+  .muted { color: #888; }
+  .cards { display: flex; gap: 1rem; flex-wrap: wrap; }
+  .card { border: 1px solid #8884; border-radius: 8px; padding: .75rem 1rem; min-width: 120px; }
+  .card .n { font-size: 1.6rem; font-weight: 600; }
+  .task { border: 1px solid #8884; border-radius: 8px; padding: .75rem 1rem; margin: .75rem 0; }
+  .task h3 { margin: 0 0 .25rem; } .task .meta { color: #888; font-size: .85rem; }
+  .status { font-size: .7rem; padding: .1rem .4rem; border-radius: 4px; background: #8883; vertical-align: middle; }
+  .status-passed { background: #2e7d3233; } .status-failed { background: #c6282833; }
+  pre.diff { overflow: auto; background: #8881; padding: .6rem; border-radius: 6px; font-size: 12px; }
+  ul.timeline { list-style: none; padding-left: 0; } ul.timeline .ts { color: #888; font-variant-numeric: tabular-nums; }
+  footer { margin-top: 3rem; color: #888; font-size: .8rem; }
+</style>
+</head>
+<body>
+<h1>${esc(model.feature)}</h1>
+<p class="sub">GSD milestone report · status <strong>${esc(model.status)}</strong>${model.phase ? ` · phase ${esc(model.phase)}` : ''}</p>
+
+<div class="cards">
+  <div class="card"><div class="n">${t.taskCount}</div>tasks</div>
+  <div class="card"><div class="n">${t.completed}</div>completed</div>
+  <div class="card"><div class="n">${pct}</div>completion</div>
+  <div class="card"><div class="n">${esc(fmtMs(t.totalWallClockMs))}</div>wall-clock</div>
+</div>
+
+<h2>Budget — actuals vs caps</h2>
+${renderBudget(model.budget)}
+
+<h2>Timeline</h2>
+${renderTimeline(model.timeline) || '<p class="muted">No timeline events recorded.</p>'}
+
+<h2>Tasks</h2>
+${renderTasks(model.tasks) || '<p class="muted">No tasks recorded.</p>'}
+
+<footer>
+Generated by COMP-GSD-7. Per-task elapsed time is poll-granularity-approximate
+(bounded by the dispatch poll interval). Diffs over ${Math.round(DIFF_INLINE_CAP_BYTES / 1024)} KB are truncated.
+</footer>
+</body>
+</html>`;
+}
+
+// ---------- Write + orchestrate ----------
+
+export function reportPath(cwd, featureCode) {
+  return join(cwd, 'docs', 'gsd-reports', `${featureCode}.html`);
+}
+
+/** Atomic write to docs/gsd-reports/<feature>.html. Returns the path. */
+export function writeGsdReport(cwd, featureCode, html) {
+  const target = reportPath(cwd, featureCode);
+  mkdirSync(join(cwd, 'docs', 'gsd-reports'), { recursive: true });
+  const tmp = `${target}.tmp`;
+  if (existsSync(tmp)) { try { unlinkSync(tmp); } catch { /* ignore */ } }
+  writeFileSync(tmp, html);
+  renameSync(tmp, target);
+  return target;
+}
+
+/**
+ * Assemble → render → write. Returns { ok, path, model, html } on success or
+ * { ok:false, error } when there is no run state to report on. Never throws on
+ * a missing-state condition (callers use it best-effort).
+ */
+export function generateGsdMilestoneReport(featureCode, cwd, opts = {}) {
+  const model = assembleReportModel(featureCode, cwd, opts);
+  if (!model) return { ok: false, error: `no GSD run state for ${featureCode} (no state.json)` };
+  const html = renderReportHtml(model);
+  const path = writeGsdReport(cwd, featureCode, html);
+  return { ok: true, path, model, html };
+}