@smartmemory/compose 0.2.7-beta → 0.2.9-beta

package/lib/build-stream-schema.js

@@ -7,15 +7,17 @@
  * Design decisions:
  * - Uses AJV (already in compose deps) compiled once at module load.
  * - On validation failure the caller should warn+drop — never throw.
- * - KNOWN_VERSIONS: set of accepted schema_version strings. v0.2.5 accepted for
- *   one-cycle backward compatibility; v0.2.6 is current.
+ * - KNOWN_VERSIONS: set of accepted schema_version strings. v0.2.5/v0.2.6 accepted
+ *   for backward compatibility; v0.2.7 is current (STRAT-PAR-STREAM-TOOLDETAIL:
+ *   enriched tool_use_summary.input + tool_use_id, new tool_result kind — both
+ *   ride the open catch-all, so no closed metadata schema is added here).
  * - reply_required (Option A, STRAT-PAR-STREAM-CONSUMER-VALIDATE design):
  *   optional boolean reserved for future gate/permission/question kinds.
  */
 
 import Ajv2020 from 'ajv/dist/2020.js';
 
-export const KNOWN_VERSIONS = new Set(['0.2.5', '0.2.6']);
+export const KNOWN_VERSIONS = new Set(['0.2.5', '0.2.6', '0.2.7']);
 
 // ---------------------------------------------------------------------------
 // Envelope schema (top-level fields only; metadata shape is kind-specific)

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
@@ -2947,12 +2949,24 @@ export async function executeParallelDispatchServer(
   progress,
   streamWriter,
   baseCwd,
+  opts = {},
 ) {
   const { flow_id: flowId, step_id: stepId,
           step_number: stepNum, total_steps: totalSteps,
           tasks } = dispatchResponse;
   const emittedStates = new Map();
 
+  // COMP-GSD-5: optional stuck detector. ONLY the gsd path passes one; build
+  // 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) {
     streamWriter.write({
       type: 'build_step_start', stepId,
@@ -2982,11 +2996,22 @@ 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) {
+  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.
+      if (stuckDetector && (event.kind === 'tool_use_summary' || event.kind === 'tool_result')) {
+        try { stuckDetector.record(event); } catch (err) { console.error('[build] stuck detector record failed:', err); }
+      }
+      if (!streamWriter) return;
       try {
         streamWriter.write({ type: 'build_stream_event', event });
       } catch (err) {
@@ -2995,9 +3020,17 @@ 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;
+    let stuckVerdict = null;
     const intervalMs = SERVER_DISPATCH_POLL_MS();
     while (true) {
       pollResult = await stratum.parallelPoll(flowId, stepId);
@@ -3006,11 +3039,90 @@ 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).
+      // For each running task: establish a wall-clock baseline on first sight,
+      // then ask the detector for a verdict. On the first stuck task, cancel the
+      // step via the terminal cascade primitive (parallelAdvance 'conflict' —
+      // the same path T2-F5 uses) and break with a stuck outcome.
+      if (stuckDetector) {
+        const now = Date.now();
+        for (const [taskId, ts] of Object.entries(pollResult.tasks ?? {})) {
+          if (ts.state === 'running') stuckDetector.startTask(taskId, now);
+          if (ts.state !== 'running') continue;
+          const v = stuckDetector.check(taskId, now);
+          if (v?.stuck) {
+            stuckVerdict = {
+              ...v,
+              taskId,
+              attemptCounts: stuckDetector.attemptCounts(taskId),
+            };
+            if (streamWriter) {
+              streamWriter.write({
+                type: 'system', subtype: 'gsd_stuck',
+                stepId, taskId, signal: v.signal, detail: v.detail, parallel: true,
+              });
+            }
+            const cancel = await stratum.parallelAdvance(flowId, stepId, 'conflict');
+            if (cancel?.error) {
+              throw new Error(
+                `stratum_parallel_advance (stuck cancel) failed: ${cancel.error}: ${cancel.message || ''}`,
+              );
+            }
+            pollResult = { ...pollResult, outcome: cancel };
+            break;
+          }
+        }
+      }
+      if (stuckVerdict) break;
+
       if (pollResult.outcome != null) break;
       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
+    // nothing to merge for a cancelled task.
+    if (stuckVerdict) {
+      if (streamWriter) {
+        streamWriter.write({
+          type: 'build_step_done', stepId, parallel: true,
+          summary: { ...(pollResult.summary ?? {}), stuck: stuckVerdict.signal }, flowId,
+        });
+      }
+      // unsubscribePush is invoked by the enclosing finally.
+      return { ...(pollResult.outcome ?? {}), stuck: stuckVerdict };
+    }
+
+    // COMP-GSD-4: budget_exhausted is a stratum terminal status. When the run
+    // budget trips mid-dispatch, the flow has already cascade-cancelled the
+    // in-flight siblings (server-side) and the poll returns the terminal
+    // envelope (carrying budget_state). There is nothing to merge — short-circuit
+    // like stuck and hand the envelope back so the gsd run loop halts. No-op for
+    // build mode: build flows declare no `budget:` block, so the status never
+    // appears and this branch is never taken (byte-identical). The
+    // advance-carried case (a parallelAdvance that returns budget_exhausted)
+    // falls through to the final `return pollResult.outcome` below.
+    if (pollResult.outcome?.status === 'budget_exhausted') {
+      if (streamWriter) {
+        streamWriter.write({
+          type: 'build_step_done', stepId, parallel: true,
+          summary: { ...(pollResult.summary ?? {}), budget_exhausted: true }, flowId,
+        });
+      }
+      return pollResult.outcome;
+    }
+
     if (pollResult.outcome.status === 'already_advanced') {
       throw new Error(
         `stratum_parallel_poll returned already_advanced for step ${stepId} — ` +
@@ -3254,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/feature-validator.js

@@ -385,6 +385,17 @@ function normalizeStatus(s) {
   return String(s).toUpperCase();
 }
 
+// vision-state's status vocabulary (contracts/vision-state.schema.json) is the
+// tracker's set MINUS `PARTIAL` — it cannot represent "partially shipped". A
+// tracker status of PARTIAL is the same lifecycle reality as vision's
+// IN_PROGRESS (partially shipped = still in progress), so project the tracker
+// side onto the vision vocabulary before any *_VS_VISION_STATE comparison.
+// Tracker↔tracker comparisons (ROADMAP_VS_FEATUREJSON) keep the full
+// vocabulary — PARTIAL vs IN_PROGRESS there is a real distinction.
+function projectToVisionStatus(s) {
+  return s === 'PARTIAL' ? 'IN_PROGRESS' : s;
+}
+
 function runStateMismatchChecks(fctx, findings) {
   const { code, roadmap, vision, featureJson } = fctx;
   const rStatus = normalizeStatus(roadmap?.status);
@@ -401,22 +412,43 @@ function runStateMismatchChecks(fctx, findings) {
       'STATUS_MISMATCH_ROADMAP_VS_FEATUREJSON', code,
       `ROADMAP says ${rStatus}, feature.json says ${fStatus}`));
   }
-  if (rStatus && vStatus && rStatus !== vStatus) {
-    findings.push(finding(statusSeverity(rStatus, vStatus),
+  // Project BOTH sides to the vision vocabulary (PARTIAL→IN_PROGRESS) before
+  // comparing. Projecting the tracker side stops a legitimately-PARTIAL feature
+  // false-firing against a vision item that can only say in_progress; projecting
+  // the vision side keeps it symmetric so a malformed/legacy vision status of
+  // "partial" (schema-invalid — reported as VISION_STATE_SCHEMA_VIOLATION) still
+  // aligns with tracker PARTIAL instead of double-reporting. Real drift (PARTIAL
+  // vs complete/planned) still differs and fires.
+  const rVis = projectToVisionStatus(rStatus);
+  const fVis = projectToVisionStatus(fStatus);
+  const vVis = projectToVisionStatus(vStatus);
+  if (rStatus && vStatus && rVis !== vVis) {
+    findings.push(finding(statusSeverity(rVis, vVis),
       'STATUS_MISMATCH_ROADMAP_VS_VISION_STATE', code,
       `ROADMAP says ${rStatus}, vision-state says ${vStatus}`));
   }
-  if (fStatus && vStatus && fStatus !== vStatus) {
-    findings.push(finding(statusSeverity(fStatus, vStatus),
+  if (fStatus && vStatus && fVis !== vVis) {
+    findings.push(finding(statusSeverity(fVis, vVis),
       'STATUS_MISMATCH_FEATUREJSON_VS_VISION_STATE', code,
       `feature.json says ${fStatus}, vision-state says ${vStatus}`));
   }
-  // CONTRADICTORY_PHASE_CLAIM
-  const fPhase = featureJson?.phase || featureJson?.lifecycle?.currentPhase;
-  const vPhase = vision?.phase || vision?.lifecycle?.currentPhase;
+  // CONTRADICTORY_PHASE_CLAIM — compare LIFECYCLE phase to LIFECYCLE phase.
+  // feature.json's top-level `phase` holds the ROADMAP heading (e.g. "Phase 7:
+  // MCP Writers"), NOT a lifecycle stage; comparing it to vision-state's
+  // lifecycle phase ("vision"/"explore_design"/…) is a category mismatch that
+  // false-fired on ~every feature with a vision item. Use only the lifecycle
+  // sources on both sides — which is what the "does not involve the roadmap"
+  // comment above always intended. (feature.json doesn't currently carry a
+  // lifecycle phase, so this correctly yields no finding until it does.)
+  const fPhase = featureJson?.lifecycle?.currentPhase;
+  // Lifecycle phase ONLY on both sides. Do NOT fall back to vision.phase — that
+  // is the legacy board-column taxonomy (planning|implementation|…), a different
+  // vocabulary from lifecycle.currentPhase (explore_design|blueprint|…), and
+  // mixing them reintroduces the category mismatch this fix removes (Codex).
+  const vPhase = vision?.lifecycle?.currentPhase;
   if (fPhase && vPhase && fPhase !== vPhase) {
     findings.push(finding('error', 'CONTRADICTORY_PHASE_CLAIM', code,
-      `feature.json phase '${fPhase}' vs vision-state phase '${vPhase}'`));
+      `feature.json lifecycle phase '${fPhase}' vs vision-state phase '${vPhase}'`));
   }
   // COMPLEXITY_OR_DESCRIPTION_DRIFT
   if (roadmap && featureJson) {

package/lib/gsd-budget.js

@@ -0,0 +1,205 @@
+/**
+ * gsd-budget.js — COMP-GSD-4 budget-ceiling helpers for autonomous `compose gsd`.
+ *
+ * This module does NOT count tokens or enforce budgets — that is the stratum
+ * flow budget (STRAT-WORKFLOW-BUDGET): a `budget:` block on the flow makes
+ * stratum debit every server-dispatched agent and halt the run with a terminal
+ * `budget_exhausted` status that carries `budget_state = {caps, consumed}`.
+ *
+ * GSD-4's job is purely compose-side glue:
+ *   - readGsdBudgetConfig: read `.compose/compose.json` `gsd.budget.*` (no defaults).
+ *   - buildBudgetBlock:     map that config → the stratum flow `budget` block
+ *                           (+ a per-task task_timeout in seconds).
+ *   - injectBudget:         inject the block into the gsd spec YAML — IDENTITY
+ *                           when nothing is configured (byte-identical guarantee).
+ *   - composeBudgetDiagnostic: render budget.json + budget.md from budget_state.
+ *
+ * Enforced axes (stratum): ms (wall-clock), max_agent_dispatches, max_tokens, usd.
+ * See: docs/features/COMP-GSD-4/{design,blueprint}.md, stratum run_budget.py.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import YAML from 'yaml';
+
+/**
+ * Read `.compose/compose.json` → `gsd.budget`. Returns {} when absent or
+ * unparseable. NO defaults (gate decision 7): a gsd run is unbounded unless the
+ * user sets a budget. Mirrors readGsdStuckConfig in gsd.js.
+ */
+export function readGsdBudgetConfig(cwd) {
+  const configPath = join(cwd, '.compose', 'compose.json');
+  if (!existsSync(configPath)) return {};
+  try {
+    const cfg = JSON.parse(readFileSync(configPath, 'utf-8'));
+    return cfg?.gsd?.budget ?? {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Map snake_case `gsd.budget.*` config → the stratum flow budget block and an
+ * optional per-task timeout (seconds). Only keys the user set appear.
+ *
+ * Config keys:
+ *   max_tokens, max_agent_dispatches, usd        → flow budget axes
+ *   per_run_ms (alias: ms)                        → flow budget `ms` (wall-clock)
+ *   per_task_ms                                   → execute step `task_timeout` (sec)
+ *   cumulative: { max_total_tokens, max_total_cost_usd } → cross-session ceiling
+ *
+ * @returns {{ budget?: object, taskTimeoutSec?: number, cumulative?: object }}
+ */
+export function buildBudgetBlock(cfg = {}) {
+  const out = {};
+
+  const budget = {};
+  if (cfg.max_tokens != null) budget.max_tokens = cfg.max_tokens;
+  if (cfg.max_agent_dispatches != null) budget.max_agent_dispatches = cfg.max_agent_dispatches;
+  if (cfg.usd != null) budget.usd = cfg.usd;
+  const ms = cfg.per_run_ms ?? cfg.ms;
+  if (ms != null) budget.ms = ms;
+  if (Object.keys(budget).length > 0) out.budget = budget;
+
+  if (cfg.per_task_ms != null) {
+    // stratum parallel_dispatch per-task timeout is `task_timeout` in SECONDS
+    // (spec.py:145, schema minimum 1). Convert from ms, floor at 1s.
+    out.taskTimeoutSec = Math.max(1, Math.ceil(cfg.per_task_ms / 1000));
+  }
+
+  if (cfg.cumulative && typeof cfg.cumulative === 'object') {
+    const cum = {};
+    if (cfg.cumulative.max_total_tokens != null) cum.maxTotalTokens = cfg.cumulative.max_total_tokens;
+    if (cfg.cumulative.max_total_cost_usd != null) cum.maxTotalCostUsd = cfg.cumulative.max_total_cost_usd;
+    if (Object.keys(cum).length > 0) out.cumulative = cum;
+  }
+
+  return out;
+}
+
+/**
+ * Inject the budget block into the gsd flow spec YAML.
+ *
+ * BYTE-IDENTICAL GUARANTEE: when nothing is configured (no flow budget AND no
+ * per-task timeout), the original `specYaml` string is returned VERBATIM — no
+ * YAML.parse/stringify round-trip (which would reorder/reformat). This keeps an
+ * un-budgeted `compose gsd` (and plain `compose build`) bit-for-bit unchanged.
+ *
+ * @param {string} specYaml — the gsd.stratum.yaml contents
+ * @param {object} cfg — raw gsd.budget config (from readGsdBudgetConfig)
+ * @returns {string}
+ */
+export function injectBudget(specYaml, cfg = {}) {
+  const built = buildBudgetBlock(cfg);
+  if (!built.budget && built.taskTimeoutSec == null) {
+    return specYaml; // identity — nothing to inject
+  }
+
+  const parsed = YAML.parse(specYaml);
+  const flow = parsed?.flows?.gsd;
+  if (!flow) {
+    // Defensive: spec shape changed. Don't silently drop the budget — surface it.
+    throw new Error('injectBudget: spec has no flows.gsd to attach a budget to');
+  }
+
+  if (built.budget) flow.budget = built.budget;
+
+  if (built.taskTimeoutSec != null && Array.isArray(flow.steps)) {
+    const execute = flow.steps.find((s) => s && s.id === 'execute');
+    if (execute) execute.task_timeout = built.taskTimeoutSec;
+  }
+
+  return YAML.stringify(parsed);
+}
+
+// Maps a stratum budget axis → human label for diagnostics.
+const AXIS_LABEL = {
+  max_tokens: 'tokens',
+  max_agent_dispatches: 'agent dispatches',
+  ms: 'wall-clock',
+  usd: 'cost (USD)',
+};
+
+/**
+ * Identify which enforced axis tripped, comparing consumed vs caps.
+ * Mirrors stratum run_budget.budget_exhausted() (consumed >= cap), in the same
+ * precedence order. Returns null if nothing is over (shouldn't happen on a
+ * budget_exhausted terminal, but the diagnostic stays honest).
+ */
+export function trippedAxis(budgetState) {
+  const caps = budgetState?.caps ?? {};
+  const consumed = budgetState?.consumed ?? {};
+  if (caps.ms != null && (consumed.wall_s ?? 0) >= caps.ms / 1000) return 'ms';
+  if (caps.max_agent_dispatches != null && (consumed.dispatches ?? 0) >= caps.max_agent_dispatches) return 'max_agent_dispatches';
+  if (caps.max_tokens != null && (consumed.tokens ?? 0) >= caps.max_tokens) return 'max_tokens';
+  if (caps.usd != null && (consumed.dollars ?? 0) >= caps.usd) return 'usd';
+  return null;
+}
+
+/**
+ * Build the budget.json + budget.md diagnostic from the stratum terminal
+ * envelope's budget_state.
+ *
+ * @param {object} budgetState — {caps, consumed:{tokens,dispatches,wall_s,dollars}}
+ * @param {{feature:string, decomposedTasks?:Array, completedTaskIds?:Array, cumulative?:object}} meta
+ * @returns {{ json: object, md: string }}
+ */
+export function composeBudgetDiagnostic(budgetState, meta = {}) {
+  const caps = budgetState?.caps ?? {};
+  const consumed = budgetState?.consumed ?? {};
+  const axis = meta.axis ?? trippedAxis(budgetState);
+  const feature = meta.feature ?? '';
+
+  const completed = new Set(meta.completedTaskIds ?? []);
+  const remaining = (meta.decomposedTasks ?? [])
+    .map((t) => t.id)
+    .filter((id) => id && !completed.has(id));
+
+  const json = {
+    feature,
+    kind: 'budget',
+    axis,
+    caps,
+    consumed,
+    remainingTaskIds: remaining,
+    ts: new Date().toISOString(),
+  };
+
+  const rows = [];
+  if (caps.max_tokens != null) rows.push(`| tokens | ${consumed.tokens ?? 0} | ${caps.max_tokens} |`);
+  if (caps.max_agent_dispatches != null) rows.push(`| agent dispatches | ${consumed.dispatches ?? 0} | ${caps.max_agent_dispatches} |`);
+  if (caps.ms != null) rows.push(`| wall-clock (s) | ${Math.round(consumed.wall_s ?? 0)} | ${Math.round(caps.ms / 1000)} |`);
+  if (caps.usd != null) rows.push(`| cost (USD) | ${(consumed.dollars ?? 0).toFixed(4)} | ${Number(caps.usd).toFixed(4)} |`);
+
+  const md = [
+    `# GSD budget halt — ${feature}`,
+    '',
+    `**Tripped axis:** ${AXIS_LABEL[axis] ?? axis ?? 'cumulative'}`,
+    `**When:** ${json.ts}`,
+    '',
+    '## Consumed vs cap',
+    '',
+    '| Axis | Consumed | Cap |',
+    '|------|----------|-----|',
+    ...rows,
+    '',
+    `## Remaining tasks (${remaining.length})`,
+    '',
+    remaining.length ? remaining.map((id) => `- ${id}`).join('\n') : '_none — all tasks completed before the halt._',
+    '',
+    '## Resume',
+    '',
+    'Raise the relevant `gsd.budget.*` cap in `.compose/compose.json` (or run with',
+    '`--reset-budget` to clear the cumulative ledger), then:',
+    '',
+    '```',
+    `compose gsd ${feature} --resume`,
+    '```',
+    '',
+    'Completed task results are preserved in the blackboard; --resume re-dispatches',
+    'only the remaining tasks.',
+    '',
+  ].join('\n');
+
+  return { json, md };
+}

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 */ }
+}