@smartmemory/compose 0.2.2-beta → 0.2.4-beta

package/lib/checkpoint/atomic.js

@@ -0,0 +1,83 @@
+/**
+ * lib/checkpoint/atomic.js — small fs helpers for the checkpoint stores.
+ *
+ * COMP-RESUME slice S2 (correction C6): existing stores copy-paste the
+ * temp-file + rename atomic-write idiom (see server/vision-store.js:132-143)
+ * and the JSONL append/idempotent-read idiom (see server/gate-log-store.js:46-102).
+ * This module is the one shared helper the new JSONL checkpoint backend uses,
+ * so we don't churn the existing stores.
+ *
+ * No external dependencies; Node built-ins only.
+ */
+
+import {
+  mkdirSync,
+  writeFileSync,
+  renameSync,
+  appendFileSync,
+  readFileSync,
+  existsSync,
+} from 'node:fs';
+import { dirname } from 'node:path';
+
+/**
+ * Atomically write `str` to `file`: write to a unique temp sibling, then rename.
+ * The rename is atomic on POSIX, so readers never observe a half-written file.
+ * Creates the parent directory recursively.
+ *
+ * @param {string} file — absolute or relative target path
+ * @param {string} str  — exact bytes to write (caller controls trailing newline)
+ */
+export function writeAtomic(file, str) {
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.tmp.${Date.now()}`;
+  writeFileSync(tmp, str, 'utf8');
+  renameSync(tmp, file);
+}
+
+/**
+ * Append one object as a single JSON line to `file` (creating parent dirs).
+ *
+ * @param {string} file
+ * @param {object} obj
+ */
+export function appendJsonl(file, obj) {
+  mkdirSync(dirname(file), { recursive: true });
+  appendFileSync(file, JSON.stringify(obj) + '\n', 'utf8');
+}
+
+/**
+ * Read all valid JSON objects from a JSONL `file`.
+ * Returns `[]` if the file is absent. Blank and malformed lines are skipped
+ * (tolerant read — a torn final line never poisons the whole log).
+ *
+ * @param {string} file
+ * @returns {object[]}
+ */
+export function readJsonl(file) {
+  if (!existsSync(file)) return [];
+  const raw = readFileSync(file, 'utf8');
+  const out = [];
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      out.push(JSON.parse(trimmed));
+    } catch {
+      // malformed line — skip
+    }
+  }
+  return out;
+}
+
+/**
+ * Return the last valid JSON object in `file`, or `null` if there is none
+ * (absent file, empty file, or only blank/malformed lines).
+ *
+ * @param {string} file
+ * @returns {object|null}
+ */
+export function readLastJsonl(file) {
+  const all = readJsonl(file);
+  return all.length ? all[all.length - 1] : null;
+}

package/lib/checkpoint/checkpoint-writer.js

@@ -0,0 +1,131 @@
+/**
+ * checkpoint-writer.js — COMP-RESUME S9 (lib side of the MCP `write_checkpoint` tool).
+ *
+ * Reads directly from disk (no server dependency) so a checkpoint can be written
+ * even when the Compose server is not running — same stance as compose-mcp-tools.js.
+ *
+ * The resume path (`compose_resume`) is NOT here: it HTTP-delegates to the server
+ * route POST /api/session/bind/reconcile, because reconcile must run server-side
+ * where the live vision item / lifecycle state and broadcasts exist.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { captureFingerprint } from './fingerprint.js';
+import { captureAnchor } from './anchor.js';
+import { scribePrompt } from './prompts.js';
+import { createCheckpointStore } from './store/index.js';
+
+/**
+ * Resolve the checkpoint config block from .compose/compose.json with defaults
+ * applied EXPLICITLY (loadProjectConfig does not merge defaults — Codex #4).
+ */
+export function checkpointConfig(targetRoot) {
+  let raw = {};
+  try {
+    raw = JSON.parse(readFileSync(path.join(targetRoot, '.compose', 'compose.json'), 'utf-8'));
+  } catch {
+    raw = {};
+  }
+  const c = raw.checkpoint ?? {};
+  return {
+    enabled: c.enabled !== false,
+    backend: c.backend ?? 'jsonl',
+    confidenceThreshold: typeof c.confidenceThreshold === 'number' ? c.confidenceThreshold : 0.6,
+  };
+}
+
+/** Best-effort read of a feature's lifecycle phase label from feature.json. */
+function readFeaturePhase(featureDir) {
+  try {
+    const fj = JSON.parse(readFileSync(path.join(featureDir, 'feature.json'), 'utf-8'));
+    return fj.phase || fj.status || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write a checkpoint to the configured backend.
+ *
+ * @param {string} targetRoot  Project root (git repo / cwd to fingerprint).
+ * @param {object} args
+ * @param {string} args.featureCode
+ * @param {string} [args.phase]      Lifecycle phase label; falls back to feature.json then 'unknown'.
+ * @param {string} [args.trigger]    Schema enum; default 'manual'.
+ * @param {object|null} [args.soft]  {goal,nextStep,risks} for a narrative checkpoint; null → anchor.
+ * @param {string|null} [args.flowId]
+ * @param {number} [args.confidence] Present only on resume-sync checkpoints.
+ * @returns {{ checkpoint: object, scribePrompt: string|null }} the written
+ *   Checkpoint, plus — when `soft` was NOT provided (an anchor write at a
+ *   boundary) — a `scribePrompt` the orchestrator can answer and re-submit as a
+ *   narrative checkpoint (the hybrid "anchor now, narrative on-demand" flow).
+ *   `scribePrompt` is null when `soft` was supplied (already a narrative cp).
+ */
+export function writeCheckpoint(targetRoot, {
+  featureCode,
+  phase = null,
+  trigger = 'manual',
+  soft = null,
+  flowId = null,
+  confidence = null,
+} = {}) {
+  if (!featureCode) throw new Error('write_checkpoint: featureCode is required');
+  const cfg = checkpointConfig(targetRoot);
+  const dataDir = path.join(targetRoot, '.compose', 'data');
+  const composeDir = path.join(targetRoot, '.compose');
+  const featureDir = path.join(targetRoot, 'docs', 'features', featureCode);
+
+  const store = createCheckpointStore(cfg.backend, { dataDir });
+  // The prior checkpoint (read before writing) seeds the scribe prompt's context.
+  const priorCheckpoint = soft ? null : store.readLatest(featureCode);
+
+  const cp = {
+    id: randomUUID(),
+    featureCode,
+    phase: phase ?? readFeaturePhase(featureDir) ?? 'unknown',
+    createdAt: new Date().toISOString(),
+    trigger,
+    fingerprint: captureFingerprint(targetRoot, { featureDir, composeDir, dataDir, flowId }),
+    soft: soft ?? null,
+    artifactIds: [],
+  };
+  if (typeof confidence === 'number') cp.confidence = confidence;
+  store.write(cp);
+
+  // No soft → this is an anchor; hand back the scribe prompt so the orchestrator
+  // can generate {goal,nextStep,risks} (anchored to the fingerprint) and write a
+  // narrative checkpoint. Wires scribePrompt into the production path (impl #3).
+  const prompt = soft
+    ? null
+    : scribePrompt({ fingerprint: cp.fingerprint, journalTail: '', priorCheckpoint });
+
+  return { checkpoint: cp, scribePrompt: prompt };
+}
+
+/**
+ * Server-side boundary convenience: write an anchor checkpoint for a live vision
+ * `item` at a lifecycle boundary. Resolves config/store/paths and delegates to
+ * captureAnchor. Gated on `checkpoint.enabled`. BEST-EFFORT — never throws (so a
+ * checkpoint failure can never break a route handler); returns the cp or null.
+ *
+ * @param {string} targetRoot
+ * @param {{ item: object, trigger: string, flowId?: string|null }} opts
+ */
+export function anchorBoundary(targetRoot, { item, trigger, flowId = null } = {}) {
+  try {
+    const cfg = checkpointConfig(targetRoot);
+    if (!cfg.enabled) return null;
+    const featureCode = item?.lifecycle?.featureCode;
+    if (!featureCode) return null;
+    const dataDir = path.join(targetRoot, '.compose', 'data');
+    const composeDir = path.join(targetRoot, '.compose');
+    const featureDir = path.join(targetRoot, 'docs', 'features', featureCode);
+    const store = createCheckpointStore(cfg.backend, { dataDir });
+    return captureAnchor({ item, trigger, cwd: targetRoot, featureDir, composeDir, dataDir, store, flowId });
+  } catch (err) {
+    console.warn('[checkpoint] anchorBoundary failed:', err?.message ?? err);
+    return null;
+  }
+}

package/lib/checkpoint/fingerprint.js

@@ -0,0 +1,145 @@
+/**
+ * COMP-RESUME S3 — environment fingerprinting + drift classification.
+ *
+ * captureFingerprint() produces an EnvFingerprint (contracts/checkpoint.schema.json
+ * $defs/EnvFingerprint): a deterministic snapshot of the environment that
+ * records what exists and never interprets it (no pass/fail verdicts).
+ *
+ * classify() is a pure function comparing two fingerprints to decide whether
+ * the environment is unchanged ('clean'), moved forward cleanly ('advanced'),
+ * or drifted in a way that needs reconciliation ('diverged').
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { head, branch, porcelain, dirtyHash } from './git.js';
+
+// Phase artifacts whose presence is part of the build signature. Order is the
+// canonical phase order: design → blueprint → plan.
+const PHASE_ARTIFACT_FILES = {
+  design: 'design.md',
+  blueprint: 'blueprint.md',
+  plan: 'plan.md',
+};
+
+/**
+ * Resolve a phase artifact to its absolute path if it exists under featureDir,
+ * else null.
+ */
+function artifactPath(featureDir, fileName) {
+  if (!featureDir) return null;
+  const p = join(featureDir, fileName);
+  return existsSync(p) ? p : null;
+}
+
+/**
+ * Read the `_seq` of the last VALID JSON line of <composeDir>/build-stream.jsonl.
+ * NOTE: the build stream is written to `.compose/build-stream.jsonl` (composeDir),
+ * NOT `.compose/data/` — see lib/build-stream-writer.js:28 (`join(composeDir, ...)`).
+ *
+ * Crash tolerance (Codex impl review #2): a crash can leave a torn final line, so
+ * we scan BACKWARD from the end and return the _seq of the first line that parses
+ * with a numeric _seq — rather than giving up if only the very last line is
+ * corrupt. Returns null when the file is absent, empty, or has no parseable _seq.
+ */
+function lastBuildStreamSeq(composeDir) {
+  if (!composeDir) return null;
+  const file = join(composeDir, 'build-stream.jsonl');
+  if (!existsSync(file)) return null;
+  let content;
+  try {
+    content = readFileSync(file, 'utf-8').trimEnd();
+  } catch {
+    return null;
+  }
+  if (!content) return null;
+  const lines = content.split('\n');
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i].trim();
+    if (!line) continue;
+    try {
+      const obj = JSON.parse(line);
+      if (typeof obj._seq === 'number') return obj._seq;
+      // a valid line without a numeric _seq → keep scanning backward
+    } catch {
+      // torn / malformed line (e.g. interrupted final write) → keep scanning
+    }
+  }
+  return null;
+}
+
+/**
+ * Capture a deterministic snapshot of the environment.
+ *
+ * @param {string} cwd  Repo / working directory to fingerprint.
+ * @param {object} [opts]
+ * @param {string} [opts.featureDir]  Dir holding phase artifacts (design/blueprint/plan).
+ * @param {string|null} [opts.flowId]  Stratum flow id, passed through.
+ * @param {string|null} [opts.composeDir]  `.compose` dir for build-stream lookup. Defaults to dirname(dataDir).
+ * @param {string|null} [opts.dataDir]  `.compose/data` dir; used only to derive composeDir when composeDir is absent.
+ * @returns {object} EnvFingerprint
+ */
+export function captureFingerprint(cwd, { featureDir, flowId = null, composeDir = null, dataDir = null } = {}) {
+  const streamDir = composeDir ?? (dataDir ? dirname(dataDir) : null);
+  const status = porcelain(cwd); // '' clean, null no-repo, non-empty dirty
+  return {
+    capturedAt: new Date().toISOString(),
+    git: {
+      head: head(cwd),
+      branch: branch(cwd),
+      dirty: typeof status === 'string' && status.length > 0,
+      dirtyHash: dirtyHash(cwd),
+    },
+    phaseArtifacts: {
+      design: artifactPath(featureDir, PHASE_ARTIFACT_FILES.design),
+      blueprint: artifactPath(featureDir, PHASE_ARTIFACT_FILES.blueprint),
+      plan: artifactPath(featureDir, PHASE_ARTIFACT_FILES.plan),
+      implementFiles: [],
+      contracts: [],
+    },
+    testRef: null,
+    buildStreamSeq: lastBuildStreamSeq(streamDir),
+    flowId,
+  };
+}
+
+/**
+ * Names of phase artifacts that are present (non-null) in a fingerprint's
+ * phaseArtifacts. Used to detect artifact removal between captures.
+ */
+function presentArtifacts(fp) {
+  const pa = fp.phaseArtifacts ?? {};
+  return Object.keys(PHASE_ARTIFACT_FILES).filter((k) => pa[k] != null);
+}
+
+/**
+ * Pure drift classifier.
+ *
+ * @param {object|null} prev  Prior fingerprint (null if none).
+ * @param {object} curr  Live fingerprint.
+ * @returns {'clean'|'advanced'|'diverged'}
+ *
+ * Rules:
+ *  - !prev → 'clean' (nothing to drift from).
+ *  - same head AND same dirtyHash → 'clean'.
+ *  - else if clean tree AND head moved AND no prior artifact was removed → 'advanced'.
+ *  - else → 'diverged'.
+ */
+export function classify(prev, curr) {
+  if (!prev) return 'clean';
+
+  const p = prev.git ?? {};
+  const c = curr.git ?? {};
+
+  if (p.head === c.head && p.dirtyHash === c.dirtyHash) return 'clean';
+
+  if (c.dirty === false && c.head !== p.head) {
+    // Every artifact that existed in prev must still exist in curr.
+    const prevPresent = presentArtifacts(prev);
+    const currPresent = new Set(presentArtifacts(curr));
+    const allRetained = prevPresent.every((name) => currPresent.has(name));
+    if (allRetained) return 'advanced';
+  }
+
+  return 'diverged';
+}

package/lib/checkpoint/git.js

@@ -0,0 +1,58 @@
+/**
+ * COMP-RESUME S2 — thin git wrapper for environment fingerprinting.
+ *
+ * A deliberately small spawnSync wrapper (pattern: lib/bug-bisect.js `git()`).
+ * Every helper returns trimmed stdout or null on failure, so callers outside a
+ * git repo (or with git unavailable) degrade gracefully rather than throwing.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+
+/**
+ * Run a git command, return trimmed stdout. Returns null on any non-zero exit
+ * or other failure (e.g. not a git repo, git missing).
+ * @param {string} cwd
+ * @param {string[]} args
+ * @returns {string|null}
+ */
+export function git(cwd, args) {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  if (r.status !== 0) return null;
+  return (r.stdout ?? '').trim();
+}
+
+/** Current HEAD sha, or null outside a repo. */
+export function head(cwd) {
+  return git(cwd, ['rev-parse', 'HEAD']);
+}
+
+/** Current branch name (or 'HEAD' when detached), null outside a repo. */
+export function branch(cwd) {
+  return git(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']);
+}
+
+/**
+ * Working-tree status in porcelain form. '' when the tree is clean, null when
+ * not a git repo. (Note: empty string is "clean", null is "no repo" — callers
+ * must distinguish the two.)
+ */
+export function porcelain(cwd) {
+  return git(cwd, ['status', '--porcelain']);
+}
+
+/**
+ * Deterministic hash of the working-tree state: sha256 of
+ * `git status --porcelain` concatenated with `git diff`.
+ *
+ * Returns null when (a) not a git repo, or (b) the tree is clean (porcelain is
+ * the empty string) — there is no drift to fingerprint.
+ * @returns {string|null}
+ */
+export function dirtyHash(cwd) {
+  const status = porcelain(cwd);
+  // null → not a repo; '' → clean tree. Either way, no dirty hash.
+  if (status === null || status === '') return null;
+  const diff = git(cwd, ['diff']) ?? '';
+  return createHash('sha256').update(status).update(diff).digest('hex');
+}

package/lib/checkpoint/prompts.js

@@ -0,0 +1,206 @@
+/**
+ * COMP-RESUME S6 — agent prompt builders (pure string functions).
+ *
+ * These build the prompts handed to the scribe and reconciliation agents.
+ * They are PURE: no fs, no git, no network, no imports from other checkpoint
+ * modules. The caller captures the fingerprint and passes it in; these
+ * functions only format it into instructions.
+ *
+ * Design anchors:
+ *  - Decision 1/4: the scribe writes ONLY the soft layer {goal,nextStep,risks},
+ *    merged onto a fresh anchor by the caller.
+ *  - Decision 2/4: the fingerprint records, never interprets. The scribe must
+ *    NOT assert verdicts ("tests pass"); every factual claim must reference an
+ *    anchor in the provided fingerprint (e.g. point at testRef).
+ *  - Decision 5: the reconciliation agent treats the live ENVIRONMENT as ground
+ *    truth; the stale checkpoint is advisory and may be wrong. It emits a synced
+ *    checkpoint {soft, confidence, resumeAction} and lowers confidence when
+ *    uncertain.
+ *
+ * @see docs/features/COMP-RESUME/blueprint.md (slice S6)
+ * @see docs/features/COMP-RESUME/design.md (Decisions 1, 2, 4, 5)
+ */
+
+/**
+ * Pretty-print a value as a fenced JSON block for embedding in a prompt.
+ * Falls back to String(value) if the value isn't serializable.
+ * @param {unknown} value
+ * @returns {string}
+ */
+function jsonBlock(value) {
+  let body;
+  try {
+    body = JSON.stringify(value ?? null, null, 2);
+  } catch {
+    body = String(value);
+  }
+  return '```json\n' + body + '\n```';
+}
+
+/**
+ * Render the git portion of a fingerprint as a compact human-readable line.
+ * @param {object} fp - EnvFingerprint
+ * @returns {string}
+ */
+function gitSummary(fp) {
+  const git = (fp && fp.git) || {};
+  const head = git.head == null ? '(no repo)' : git.head;
+  const branch = git.branch == null ? '(detached/none)' : git.branch;
+  const dirty = git.dirty ? 'dirty' : 'clean';
+  return `head=${head} branch=${branch} tree=${dirty}`;
+}
+
+/**
+ * Build the scribe prompt.
+ *
+ * The scribe is invoked at major boundaries to author the soft layer. It must
+ * return ONLY a JSON object `{ "goal": string, "nextStep": string, "risks":
+ * string[] }` and nothing else, with every factual claim anchored to the
+ * provided fingerprint (never a remembered verdict).
+ *
+ * @param {object} args
+ * @param {object} args.fingerprint - EnvFingerprint captured at this boundary (ground truth).
+ * @param {string} [args.journalTail] - Recent journal/build-stream tail for context.
+ * @param {object|null} [args.priorCheckpoint] - The previous narrative checkpoint, if any.
+ * @returns {string} prompt text
+ */
+export function scribePrompt({ fingerprint, journalTail = '', priorCheckpoint = null }) {
+  const fp = fingerprint || {};
+  const sections = [];
+
+  sections.push(
+    'You are the Compose **scribe**. Your sole job is to record the *intent* of the current build state — what the goal is, what the single next step is, and what risks are live right now.',
+  );
+
+  sections.push(
+    [
+      'CRITICAL RULES:',
+      '1. Return ONLY a single JSON object and nothing else — no prose, no markdown, no code fences. The object MUST be exactly:',
+      jsonBlock({ goal: 'string', nextStep: 'string', risks: ['string'] }),
+      '2. The ENVIRONMENT FINGERPRINT below is ground truth. Every factual claim you make MUST reference an anchor that appears in the fingerprint (a git head/branch, an artifact path, the testRef). Do NOT invent state that is not anchored there.',
+      "3. Do NOT claim results or verdicts. Specifically: do NOT claim tests pass or fail — reference the fingerprint's testRef (the raw test-output path) instead and let the reader inspect it. The fingerprint records what exists; it never interprets.",
+      '4. `goal` and `nextStep` are required and must be non-empty. `risks` is an array (use [] if none).',
+    ].join('\n'),
+  );
+
+  sections.push(
+    [
+      'ENVIRONMENT FINGERPRINT (ground truth — anchor every claim to this):',
+      `Git: ${gitSummary(fp)}`,
+      jsonBlock(fp),
+    ].join('\n'),
+  );
+
+  if (journalTail && String(journalTail).trim()) {
+    sections.push(
+      ['RECENT JOURNAL / BUILD-STREAM TAIL (context only — not authoritative):', String(journalTail).trim()].join('\n'),
+    );
+  }
+
+  if (priorCheckpoint && priorCheckpoint.soft) {
+    const soft = priorCheckpoint.soft;
+    sections.push(
+      [
+        'PRIOR NARRATIVE CHECKPOINT (the last recorded intent — may be stale; reconcile against the fingerprint):',
+        `- goal: ${soft.goal ?? ''}`,
+        `- nextStep: ${soft.nextStep ?? ''}`,
+        Array.isArray(soft.risks) && soft.risks.length
+          ? `- risks: ${soft.risks.join('; ')}`
+          : '- risks: (none recorded)',
+      ].join('\n'),
+    );
+  }
+
+  sections.push('Now emit the JSON object describing the current intent, and nothing else.');
+
+  return sections.join('\n\n');
+}
+
+/**
+ * Build the reconciliation prompt.
+ *
+ * Used on resume only when the environment has DIVERGED from the stale
+ * checkpoint. The agent treats the live environment as ground truth, reconciles
+ * the stale checkpoint's intent against what the environment shows now, and
+ * returns ONLY a JSON object `{ "soft": {goal,nextStep,risks}, "confidence":
+ * number 0..1, "resumeAction": string }`.
+ *
+ * @param {object} args
+ * @param {object} args.staleCheckpoint - The last stored checkpoint (advisory, may be wrong).
+ * @param {object} args.liveFingerprint - The freshly captured EnvFingerprint (ground truth).
+ * @param {string} [args.envScan] - Extra environment scan text (diffs, file listings, test output excerpt).
+ * @returns {string} prompt text
+ */
+export function reconcilePrompt({ staleCheckpoint, liveFingerprint, envScan = '' }) {
+  const stale = staleCheckpoint || {};
+  const staleSoft = stale.soft || {};
+  const live = liveFingerprint || {};
+  const sections = [];
+
+  sections.push(
+    'You are the Compose **reconciliation agent**. A build is being resumed after an interruption. Your job is to reconcile the recorded intent against the current environment and produce a corrected, synced checkpoint.',
+  );
+
+  sections.push(
+    [
+      'GROUND TRUTH RULE:',
+      'The live ENVIRONMENT (git state + on-disk artifacts + logs) is GROUND TRUTH. The stale checkpoint below is ADVISORY ONLY and may be wrong, out of date, or contradicted by the environment. When they disagree, the environment wins — every time.',
+    ].join('\n'),
+  );
+
+  sections.push(
+    [
+      'OUTPUT RULES:',
+      'Return ONLY a single JSON object and nothing else — no prose, no markdown, no code fences. The object MUST be exactly:',
+      jsonBlock({
+        soft: { goal: 'string', nextStep: 'string', risks: ['string'] },
+        confidence: 'number between 0 and 1',
+        resumeAction: 'string',
+      }),
+      '- `confidence` is a number from 0 to 1 expressing how sure you are that the synced intent matches the environment. Lower confidence when the environment is ambiguous, the divergence is large, or you cannot tell what was in progress.',
+      '- `resumeAction` is a short imperative describing the concrete next action to take to resume the build.',
+      '- `soft.goal` and `soft.nextStep` are required and must be non-empty; `soft.risks` is an array (use [] if none).',
+    ].join('\n'),
+  );
+
+  sections.push(
+    [
+      'LIVE ENVIRONMENT FINGERPRINT (ground truth):',
+      `Git: ${gitSummary(live)}`,
+      jsonBlock(live),
+    ].join('\n'),
+  );
+
+  sections.push(
+    [
+      'STALE CHECKPOINT (advisory — what the build *expected*; may be wrong):',
+      `- phase: ${stale.phase ?? '(unknown)'}`,
+      `- goal: ${staleSoft.goal ?? '(none recorded)'}`,
+      `- nextStep: ${staleSoft.nextStep ?? '(none recorded)'}`,
+      Array.isArray(staleSoft.risks) && staleSoft.risks.length
+        ? `- risks: ${staleSoft.risks.join('; ')}`
+        : '- risks: (none recorded)',
+      '',
+      'Its captured fingerprint (what the environment looked like when this was recorded):',
+      jsonBlock(stale.fingerprint ?? null),
+    ].join('\n'),
+  );
+
+  if (envScan && String(envScan).trim()) {
+    sections.push(
+      ['ADDITIONAL ENVIRONMENT SCAN (ground truth — diffs / listings / raw test output):', String(envScan).trim()].join(
+        '\n',
+      ),
+    );
+  }
+
+  sections.push(
+    [
+      'TASK:',
+      'Compare what the environment shows NOW against what the checkpoint expected. Reconcile any divergence: where they conflict, follow the environment. Produce the corrected `soft` intent reflecting the current reality, set `resumeAction` to the next concrete step, and set `confidence` honestly — lower the confidence whenever you are uncertain or the divergence cannot be cleanly explained.',
+      'Now emit the JSON object, and nothing else.',
+    ].join('\n'),
+  );
+
+  return sections.join('\n\n');
+}