heyspex 0.1.0

package/vendor/heyspex-mcp/alignment-gate.mjs

@@ -0,0 +1,1347 @@
+/**
+ * Pre-execution alignment gate — pure logic backing the hierarchy-aware
+ * breakdown + corpus-drift surface that runs as the FIRST pre-flight on
+ * /hs-next, upstream of conflict resolution ([[pre-execution-alignment-gate]]).
+ *
+ * The gate exists because **AI agents are good at executing the wrong thing
+ * perfectly** ([[heyspex-north-star]]). Two surfaces:
+ *
+ *   - **No children → HARD breakdown gate.** Decomposition brief replaces the
+ *     task result. The agent must file children before executing.
+ *   - **Children + corpus drift → SOFT drift questions.** Prepended to the
+ *     task brief; the agent poses keep/update/drop questions to the user per
+ *     affected child, then calls `heyspex_record_alignment` to reset the
+ *     review timestamp. Never blocks execution.
+ *
+ * "Corpus drift" = the epic's reference corpus (`related:` + `depends_on:` +
+ * `milestone:`) has changed (file mtime / `updated:` frontmatter newer than
+ * `alignment_reviewed_at`). AGV2 redefined drift away from internal completeness
+ * (the v1 detectTaskDrift heuristics produced false positives) toward temporal
+ * staleness of *linked plans*. AGV2/DSIG removed signature hashing entirely —
+ * it was non-deterministic and produced false signature_changed re-fires.
+ *
+ * Pure-ish: every vault read is injected via `loadRef(idOrBasename) => spec|null`
+ * (same contract as blocker-resolver's `loadTask`); mtime reads via injected
+ * `lastModified(idOrBasename) => ms|null`. The module stays hermetic / unit-
+ * testable with synthetic loaders.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { readFileSync, existsSync } from 'node:fs';
+import { wikilinkTarget } from './blocker-resolver.mjs';
+import { spexConsoleSettingsCandidates } from './vault-settings.mjs';
+
+export const ALIGNMENT_FUSE_DAYS = 7;
+export const DEFAULT_FOCUS_PIN_EXPIRATION_DAYS = 7;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Git-time helpers — SSOT for "when did this spec enter the vault?" The
+// commit timestamp (`%ct`, seconds-since-epoch in committer's local timezone)
+// is hand-edit-immune, unlike frontmatter `updated:` which agents and humans
+// can spoof. Used by computeWorldStateDelta + canSkipAlignment.
+// ─────────────────────────────────────────────────────────────────────────────
+
+function runGit(vaultRoot, args) {
+  try {
+    return execFileSync('git', args, {
+      cwd: vaultRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Unix-ms when `path` was first committed under `vaultRoot`. Returns `null`
+ * when git has no history for it (e.g. untracked or never-committed file).
+ */
+export function gitFirstCommitTime(vaultRoot, path) {
+  if (!vaultRoot || !path) return null;
+  const out = runGit(vaultRoot, [
+    'log',
+    '--diff-filter=A',
+    '--follow',
+    '--format=%ct',
+    '--reverse',
+    '--',
+    path,
+  ]);
+  const first = out.split('\n').map((l) => l.trim()).filter(Boolean)[0];
+  if (!first) return null;
+  const secs = Number(first);
+  return Number.isFinite(secs) ? secs * 1000 : null;
+}
+
+/** Unix-ms of the most recent commit touching `path`. `null` when untracked. */
+export function gitLastCommitTime(vaultRoot, path) {
+  if (!vaultRoot || !path) return null;
+  const out = runGit(vaultRoot, ['log', '-1', '--format=%ct', '--', path]);
+  const last = out.trim();
+  if (!last) return null;
+  const secs = Number(last);
+  return Number.isFinite(secs) ? secs * 1000 : null;
+}
+
+/**
+ * Sorted unique list of `specs/` paths first committed after `sinceTs` (ms).
+ * Backs `computeWorldStateDelta` and the `new_specs_since_breakdown` skip
+ * reason. `since` of `0` or NaN returns `[]` (no baseline → no delta).
+ */
+export function gitFilesAddedSince(vaultRoot, sinceTs) {
+  if (!vaultRoot) return [];
+  if (!Number.isFinite(sinceTs) || sinceTs <= 0) return [];
+  const sinceSecs = Math.floor(sinceTs / 1000);
+  const out = runGit(vaultRoot, [
+    'log',
+    `--since=${sinceSecs}`,
+    '--diff-filter=A',
+    '--name-only',
+    '--pretty=format:',
+    '--',
+    'specs/',
+  ]);
+  return [
+    ...new Set(out.split('\n').map((l) => l.trim()).filter(Boolean)),
+  ].sort();
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// djb2 — deterministic, dependency-free hash. AGV2/DSIG retired the old
+// signature scheme because it hashed mutable frontmatter; this one hashes
+// only stable inputs (sorted child IDs + first-commit timestamps + git-derived
+// world-state hash), so it can be safely persisted and compared.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function djb2(str) {
+  const s = String(str);
+  let h = 5381;
+  for (let i = 0; i < s.length; i++) {
+    h = ((h << 5) + h + s.charCodeAt(i)) | 0;
+  }
+  return (h >>> 0).toString(16);
+}
+
+/**
+ * `{ addedPaths, hash }` snapshot of new spec files added since `sinceTs` (ms).
+ * Hash is stable for the same input set and changes when a new spec is added
+ * (AC #5 for T1). When `sinceTs` is missing / invalid, returns the empty
+ * baseline so callers can treat it as "no delta detected yet."
+ */
+export function computeWorldStateDelta(vaultRoot, sinceTs) {
+  const addedPaths = gitFilesAddedSince(vaultRoot, sinceTs);
+  return { addedPaths, hash: djb2(addedPaths.join('|')) };
+}
+
+/**
+ * Three-component alignment signature. `epicUpdated` is the parent epic's
+ * frontmatter `updated:` (string) — its inclusion catches deliberate scope
+ * edits even when no child IDs moved. `worldStateHash` ties the signature to
+ * the git-derived added-files snapshot.
+ */
+export function computeAlignmentSignature({ childIds, epicUpdated, worldStateHash }) {
+  const sortedChildren = (Array.isArray(childIds) ? [...childIds] : [])
+    .map((c) => String(c).trim())
+    .filter(Boolean)
+    .sort()
+    .join('|');
+  return djb2(`${sortedChildren}|${epicUpdated || ''}|${worldStateHash || ''}`);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Settings-driven fuse — read spex-console/settings.json (or .heyspex/ mirror) so
+// disabling `focusPinExpirationEnabled` in the UI also disables the alignment
+// fuse. Returns `{ enabled, days }`; when `enabled === false`, callers must
+// drop fuse_expired from the skip-reason ladder.
+// ─────────────────────────────────────────────────────────────────────────────
+
+function readJsonSafe(path) {
+  try {
+    if (!existsSync(path)) return null;
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function readAlignmentFuseSettings(vaultRoot) {
+  const fallback = { enabled: true, days: DEFAULT_FOCUS_PIN_EXPIRATION_DAYS };
+  for (const p of spexConsoleSettingsCandidates(vaultRoot)) {
+    const raw = readJsonSafe(p);
+    if (!raw || typeof raw !== 'object') continue;
+    const enabled = raw.focusPinExpirationEnabled !== false; // default true
+    const daysRaw = raw.focusPinExpirationDays;
+    const days =
+      typeof daysRaw === 'number' && Number.isFinite(daysRaw) && daysRaw > 0
+        ? daysRaw
+        : DEFAULT_FOCUS_PIN_EXPIRATION_DAYS;
+    return { enabled, days };
+  }
+  return fallback;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// canSkipAlignment — binary skip rule layered over evaluateCheckpoint. Returns
+// `{ skip: true, reason: "binary_skip_rule" }` only when ALL components agree
+// (no signature drift, no children predating the parent epic, no specs added
+// since the breakdown, fuse not blown). Otherwise the first failing reason.
+//
+// Reasons: 'signature_drift' | 'older_children' | 'new_specs_since_breakdown'
+//        | 'fuse_expired' | 'no_checkpoint' | 'binary_skip_rule'
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function canSkipAlignment(epic, vaultRoot, options = {}) {
+  const fm = epic?.frontmatter || {};
+  const reviewedAt = fm.alignment_reviewed_at;
+  const reviewedMs = reviewedAt ? Date.parse(String(reviewedAt)) : NaN;
+  if (!Number.isFinite(reviewedMs)) {
+    return { skip: false, reason: 'no_checkpoint' };
+  }
+
+  const fuse = options.fuse ?? readAlignmentFuseSettings(vaultRoot);
+  const now = typeof options.now === 'number' ? options.now : Date.now();
+  const fuseDays = options.fuseDays || fuse.days || ALIGNMENT_FUSE_DAYS;
+  if (fuse.enabled !== false && now - reviewedMs > fuseDays * 86_400_000) {
+    return { skip: false, reason: 'fuse_expired' };
+  }
+
+  const grain = options.grain || 'epic';
+  const childIds = getChildRefs(fm, grain);
+
+  // older_children: any child first-committed before the parent epic. Catches
+  // retroactive structuring (parent filed over pre-existing tasks) — the
+  // breakdown decision wasn't taken at the time the children were created, so
+  // alignment should be reviewed. Requires `childResolver(id) -> path` and
+  // `epicPath` to walk git history; without them this check is silent.
+  const epicPath = options.epicPath;
+  const childResolver = typeof options.childResolver === 'function' ? options.childResolver : null;
+  if (epicPath && childResolver) {
+    const epicFirst = gitFirstCommitTime(vaultRoot, epicPath);
+    if (Number.isFinite(epicFirst)) {
+      for (const cid of childIds) {
+        const childPath = childResolver(cid);
+        if (!childPath) continue;
+        const childFirst = gitFirstCommitTime(vaultRoot, childPath);
+        if (Number.isFinite(childFirst) && childFirst < epicFirst) {
+          return { skip: false, reason: 'older_children', child_id: cid };
+        }
+      }
+    }
+  }
+
+  // new_specs_since_breakdown — git-truth, immune to frontmatter spoofing.
+  const worldStateDelta =
+    options.worldStateDelta ?? computeWorldStateDelta(vaultRoot, reviewedMs);
+  if (worldStateDelta.addedPaths.length > 0) {
+    return {
+      skip: false,
+      reason: 'new_specs_since_breakdown',
+      world_state_delta: worldStateDelta,
+    };
+  }
+
+  // signature_drift — only fires when the epic stored a signature on its last
+  // alignment record AND it disagrees with the current inputs. A fresh epic
+  // with no `alignment_signature:` skips this check.
+  const currentSignature = computeAlignmentSignature({
+    childIds,
+    epicUpdated: fm.updated,
+    worldStateHash: worldStateDelta.hash,
+  });
+  if (fm.alignment_signature && fm.alignment_signature !== currentSignature) {
+    return {
+      skip: false,
+      reason: 'signature_drift',
+      previous: fm.alignment_signature,
+      current: currentSignature,
+    };
+  }
+
+  return { skip: true, reason: 'binary_skip_rule', signature: currentSignature };
+}
+
+/** Epic children live in `children:`; milestone children live in `epics:`. */
+export function childRefsField(grain) {
+  return grain === 'milestone' ? 'epics' : 'children';
+}
+
+/** The child entity kind for a given parent grain. */
+export function childKindFor(grain) {
+  return grain === 'milestone' ? 'epic' : 'task';
+}
+
+/** Pull the raw child-ref array (children: for epics, epics: for milestones). */
+export function getChildRefs(frontmatter, grain) {
+  const raw = frontmatter?.[childRefsField(grain)];
+  if (!Array.isArray(raw)) return [];
+  return raw.map(wikilinkTarget).filter(Boolean);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Markdown section helpers (deterministic — no LLM, no network)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Extract the body text under a `## Heading` (level-2) up to the next level-2
+ * heading. `headingRe` matches the heading text (case-insensitive). Returns ''
+ * when not found.
+ */
+export function extractSection(body, headingRe) {
+  if (typeof body !== 'string') return '';
+  const lines = body.split(/\r?\n/);
+  let capturing = false;
+  const out = [];
+  for (const line of lines) {
+    const h2 = line.match(/^##\s+(.+?)\s*$/);
+    if (h2 && !line.startsWith('###')) {
+      if (capturing) break; // next level-2 heading ends the section
+      if (headingRe.test(h2[1])) {
+        capturing = true;
+        continue;
+      }
+    }
+    if (capturing) out.push(line);
+  }
+  return out.join('\n').trim();
+}
+
+/** Bullet lines (`-`/`*`, checkbox, or numbered `1.` / `1)`) → trimmed text array. */
+export function extractBullets(text) {
+  if (typeof text !== 'string') return [];
+  const out = [];
+  for (const line of text.split(/\r?\n/)) {
+    const m = line.match(/^\s*(?:[-*]\s+(?:\[[ xX]\]\s+)?|\d+[.)]\s+)(.+?)\s*$/);
+    if (m) out.push(m[1].trim());
+  }
+  return out;
+}
+
+/**
+ * Parse the `## Acceptance criteria` block into decomposition seeds. When the
+ * block has `### subheadings` each becomes one seed (the natural one-task-per-
+ * section convention used across the vault, e.g. HS-EPIC-MILE → Entity type /
+ * Validator + MCP / All Docs filter / Specs filter / Bootstrap consistency).
+ * When the block is a flat checklist, returns a single seed carrying the
+ * bullets so the agent can split them.
+ *
+ * Returns `{ sections: [{ title, bullets }], hasSubsections }`.
+ */
+export function parseAcceptanceSubsections(body) {
+  // Match both the canonical `## Acceptance criteria` and the bare `## Acceptance`
+  // heading variant (~48 vault specs use the latter — and the console parser
+  // already accepts it, so anchoring exactly here broke cross-surface parity and
+  // wrongly routed those specs to the Tier-3 clarification floor). [[HS-TASK-I2Y8]]
+  const section = extractSection(body, /^acceptance(?:\s+criteria)?$/i);
+  if (!section) return { sections: [], hasSubsections: false };
+
+  const lines = section.split(/\r?\n/);
+  const subs = [];
+  let current = null;
+  for (const line of lines) {
+    const h3 = line.match(/^###\s+(.+?)\s*$/);
+    if (h3) {
+      current = { title: h3[1].trim(), bullets: [] };
+      subs.push(current);
+      continue;
+    }
+    if (current) {
+      const b = line.match(/^\s*(?:[-*]\s+(?:\[[ xX]\]\s+)?|\d+[.)]\s+)(.+?)\s*$/);
+      if (b) current.bullets.push(b[1].trim());
+    }
+  }
+
+  if (subs.length > 0) {
+    return { sections: subs, hasSubsections: true };
+  }
+  // Flat checklist — one implicit section carrying all bullets.
+  const bullets = extractBullets(section);
+  if (bullets.length === 0) return { sections: [], hasSubsections: false };
+  return {
+    sections: [{ title: 'Acceptance criteria', bullets }],
+    hasSubsections: false,
+  };
+}
+
+/**
+ * First non-empty paragraph stating the spec's intent: `## Goal`, else
+ * `## Problem`, else `## Scope`. Scope is included because it is this vault's
+ * dominant task/epic-template section (most specs carry `## Scope`, not
+ * `## Goal`), and the readiness floor's "non-trivial goal/scope" check
+ * ([[HS-TASK-RW3B]]) depends on it.
+ */
+export function extractGoal(body) {
+  const goal =
+    extractSection(body, /^goal$/i) ||
+    extractSection(body, /^problem$/i) ||
+    extractSection(body, /^scope$/i);
+  if (!goal) return '';
+  const para = goal.split(/\n\s*\n/)[0] || goal;
+  return para.replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Pull the `## Expected Breakage & Consequences` section out of a spec body
+ * verbatim ([[spec-hierarchy]] §Expected Breakage & Consequences).
+ */
+function extractBreakageSection(body) {
+  if (!body) return null;
+  const lines = body.split('\n');
+  let start = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^##\s+Expected Breakage & Consequences\s*$/i.test(lines[i].trim())) {
+      start = i;
+      break;
+    }
+  }
+  if (start === -1) return null;
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^#{1,2}\s+/.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+  const section = lines.slice(start, end).join('\n').trim();
+  return section.length > 0 ? section : null;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Hierarchy-aware decomposition context
+// ─────────────────────────────────────────────────────────────────────────────
+
+function shapeRef(loadRef, ref) {
+  const target = wikilinkTarget(ref);
+  if (!target) return null;
+  const spec = loadRef(target);
+  if (!spec) return { ref: target, resolved: false };
+  const fm = spec.frontmatter || {};
+  return {
+    ref: target,
+    resolved: true,
+    id: spec.id || fm.id || target,
+    name: spec.name || fm.name || target,
+    type: spec.type || fm.type || 'spec',
+    status: spec.status || fm.status || 'unknown',
+  };
+}
+
+/**
+ * Gather the deterministic context an agent needs to break down (or re-align)
+ * a node WITHOUT open-ended search. Resolves the milestone parent + sibling
+ * epics so the agent gets the whole chain handed to it.
+ *
+ * `node` is `{ id, name, frontmatter, body }`. `grain` is 'epic' | 'milestone'.
+ */
+export function extractDecompositionContext(node, loadRef, grain = 'epic') {
+  const fm = node.frontmatter || {};
+  const body = node.body || '';
+
+  const acceptance = parseAcceptanceSubsections(body);
+  const outOfScope = extractBullets(extractSection(body, /^out of scope/i));
+
+  const depBullets = extractBullets(extractSection(body, /^dependencies$/i));
+  const fmDeps = []
+    .concat(Array.isArray(fm.depends_on) ? fm.depends_on : [])
+    .concat(Array.isArray(fm.blocked_by) ? fm.blocked_by : [])
+    .map(wikilinkTarget)
+    .filter(Boolean);
+
+  const related = (Array.isArray(fm.related) ? fm.related : [])
+    .map((r) => shapeRef(loadRef, r))
+    .filter(Boolean);
+
+  // Milestone chain. For an epic, walk up via `milestone:`. For a milestone
+  // node itself, there's no parent — siblings are its own epics.
+  let milestone = null;
+  let milestoneBreakage = null;
+  if (grain === 'epic' && fm.milestone) {
+    const m = shapeRef(loadRef, fm.milestone);
+    if (m && m.resolved) {
+      const mSpec = loadRef(m.ref);
+      const mFm = mSpec?.frontmatter || {};
+      if (mSpec?.body) milestoneBreakage = extractBreakageSection(mSpec.body);
+      const selfId = (node.id || fm.id || '').toLowerCase();
+      const siblings = (Array.isArray(mFm.epics) ? mFm.epics : [])
+        .map((e) => shapeRef(loadRef, e))
+        .filter(Boolean)
+        .filter((e) => (e.id || e.ref || '').toLowerCase() !== selfId);
+      milestone = { ...m, siblings };
+    } else if (m) {
+      milestone = { ...m, siblings: [] };
+    }
+  }
+
+  return {
+    grain,
+    childKind: childKindFor(grain),
+    goal: extractGoal(body),
+    acceptance,
+    outOfScope,
+    dependencies: { fromBody: depBullets, fromFrontmatter: fmDeps },
+    related,
+    milestone,
+    tags: Array.isArray(fm.tags) ? fm.tags : [],
+    expectedBreakage: {
+      focus: extractBreakageSection(body),
+      milestone: milestoneBreakage,
+    },
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Corpus-drift detection (temporal staleness of linked plans — AGV2/DCRP)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Detect temporal corpus-staleness: any doc in the epic's reference corpus
+ * (`related:` + `depends_on:` + `milestone:`) whose last-modified time is newer
+ * than `alignment_reviewed_at`. Pure with injected loaders so it stays unit-
+ * testable; the cli wires `loadRef` to the vault loader and `lastModified` to
+ * `fs.statSync(...).mtimeMs` for fallback.
+ *
+ *   epic.frontmatter — the focus spec's frontmatter (read `milestone`, `related`,
+ *     `depends_on`).
+ *   reviewedAt       — ISO string. If missing or unparseable, returns no drift
+ *     (you can't detect change without a baseline; the user records alignment
+ *     once to establish one).
+ *   loadRef(ref)     — corpus-doc loader. Returns a spec with optional
+ *     `frontmatter.updated` (preferred timestamp source).
+ *   lastModified(ref)— mtime fallback when `frontmatter.updated` is missing or
+ *     unparseable. Returns ms epoch.
+ *
+ * Returns `{ stale, hasDrift }`. `stale` items are
+ *   `{ ref, source, lastModified }` where source ∈ 'milestone' | 'related' |
+ *   'depends_on' and `lastModified` is the resolved newest timestamp (ms).
+ */
+export function detectCorpusDrift({ epic, reviewedAt, loadRef, lastModified }) {
+  const stale = [];
+  const reviewedMs = reviewedAt ? Date.parse(String(reviewedAt)) : NaN;
+  if (!Number.isFinite(reviewedMs)) return { stale, hasDrift: false };
+
+  const fm = epic?.frontmatter || {};
+  const refs = [];
+  if (fm.milestone) {
+    const t = wikilinkTarget(fm.milestone);
+    if (t) refs.push({ ref: t, source: 'milestone' });
+  }
+  for (const r of Array.isArray(fm.related) ? fm.related : []) {
+    const t = wikilinkTarget(r);
+    if (t) refs.push({ ref: t, source: 'related' });
+  }
+  for (const r of Array.isArray(fm.depends_on) ? fm.depends_on : []) {
+    const t = wikilinkTarget(r);
+    if (t) refs.push({ ref: t, source: 'depends_on' });
+  }
+
+  // De-duplicate by ref (a doc may appear in multiple lists; keep the first
+  // source we saw — milestone > related > depends_on by enumeration order).
+  const seen = new Set();
+  for (const item of refs) {
+    if (seen.has(item.ref)) continue;
+    seen.add(item.ref);
+
+    let ts = null;
+    if (loadRef) {
+      const spec = loadRef(item.ref);
+      const updated = spec?.frontmatter?.updated;
+      if (updated) {
+        const ms = Date.parse(String(updated));
+        if (Number.isFinite(ms)) ts = ms;
+      }
+    }
+    if (ts === null && typeof lastModified === 'function') {
+      const mtime = lastModified(item.ref);
+      if (Number.isFinite(mtime)) ts = mtime;
+    }
+    if (ts !== null && ts > reviewedMs) {
+      stale.push({ ref: item.ref, source: item.source, lastModified: ts });
+    }
+  }
+
+  return { stale, hasDrift: stale.length > 0 };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Checkpoint state machine (frontmatter-backed, fuse-invalidated)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Decide whether the gate fires based on the timestamp checkpoint + fuse.
+ * Signature hashing was removed in AGV2 (HS-TASK-DSIG) — it was non-deterministic
+ * across reads (mutable `frontmatter.updated`) and produced false-positive
+ * re-fires of `signature_changed`. "Has the breakdown changed since review?" is
+ * now answered by corpus-staleness detection (HS-TASK-DCRP), not by hashing.
+ *
+ * `now` is injected (ms epoch) so the module stays deterministic in tests /
+ * harnesses where Date.now is unavailable.
+ *   reason: 'no_checkpoint' | 'fuse_expired' | 'ok'
+ */
+export function evaluateCheckpoint({
+  frontmatter,
+  fuseDays = ALIGNMENT_FUSE_DAYS,
+  now,
+}) {
+  const fm = frontmatter || {};
+  const reviewedAt = fm.alignment_reviewed_at;
+  if (!reviewedAt) return { fire: true, reason: 'no_checkpoint' };
+  const reviewedMs = Date.parse(reviewedAt);
+  const nowMs = typeof now === 'number' ? now : Date.parse(reviewedAt);
+  if (Number.isFinite(reviewedMs) && Number.isFinite(nowMs)) {
+    if (nowMs - reviewedMs > fuseDays * 24 * 60 * 60 * 1000) {
+      return { fire: true, reason: 'fuse_expired' };
+    }
+  }
+  return { fire: false, reason: 'ok' };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Frontmatter checkpoint upsert (raw-text surgical edit — no lossy reserialize)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Insert/replace top-level scalar keys inside the first `---…---` frontmatter
+ * block of `content`, preserving everything else byte-for-byte. Used by
+ * heyspex_record_alignment to stamp the checkpoint without round-tripping the
+ * whole YAML through the lossy parseSimpleYaml. Values are written as plain
+ * scalars (quote them yourself if they need it).
+ */
+export function upsertFrontmatterKeys(content, kv) {
+  const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return content; // no frontmatter block — refuse to mangle the file
+  let block = m[1];
+  const eol = content.includes('\r\n') ? '\r\n' : '\n';
+  for (const [key, value] of Object.entries(kv)) {
+    const line = `${key}: ${value}`;
+    const keyRe = new RegExp(`^${key}:.*$`, 'm');
+    if (keyRe.test(block)) {
+      block = block.replace(keyRe, line);
+    } else {
+      block = `${block}${eol}${line}`;
+    }
+  }
+  return content.replace(m[0], `---${eol}${block}${eol}---`);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Prompt builders (the agent-facing briefs)
+// ─────────────────────────────────────────────────────────────────────────────
+
+function regroundChecklist(context, idForRecall) {
+  const tagList = context.tags.length
+    ? `[${context.tags.map((t) => `"${t}"`).join(', ')}]`
+    : '[]';
+  return [
+    '### 0 · Re-ground (do this first — cheap, prevents expensive mistakes)',
+    '',
+    '- Read [[heyspex-north-star]], [[architecture-foundations]], [[entity-model]] if not already fresh in context.',
+    `- \`heyspex_recall_memories({ tags: ${tagList}, limit: 10 })\` — surface prior lessons/decisions for this area.`,
+    `- \`heyspex_preflight({ intent: "file_${context.childKind}" })\` then \`heyspex_get_procedure\` on each required row (start with \`spec-hierarchy\`, then \`spec-summary-authoring\`).`,
+    '',
+  ];
+}
+
+function hierarchyContextBlock(id, name, context, opts = {}) {
+  const outOfScopeNote = opts.outOfScopeNote || 'do NOT file tasks for these';
+  const lines = ['### Hierarchy context (handed to you — no search needed)', ''];
+  if (context.milestone) {
+    const m = context.milestone;
+    lines.push(`- **Milestone:** \`${m.id || m.ref}\` — ${m.name || '(unresolved)'} · ${m.status || '?'}`);
+    if (m.siblings && m.siblings.length) {
+      lines.push('- **Sibling epics in this milestone:**');
+      for (const s of m.siblings.slice(0, 12)) {
+        lines.push(`  - \`${s.id || s.ref}\`${s.name ? ` — ${s.name}` : ''} · ${s.status || '?'}`);
+      }
+    }
+  } else {
+    lines.push(`- **Milestone:** _none linked_ — confirm whether \`${id}\` should declare a \`milestone:\` parent.`);
+  }
+  lines.push(`- **This ${context.grain}:** \`${id}\` — ${name}`);
+  if (context.goal) lines.push(`- **Goal:** ${context.goal}`);
+  if (context.outOfScope.length) {
+    lines.push(`- **Out of scope (${outOfScopeNote}):**`);
+    for (const o of context.outOfScope.slice(0, 10)) lines.push(`  - ${o}`);
+  }
+  const deps = [
+    ...context.dependencies.fromFrontmatter,
+    ...context.dependencies.fromBody,
+  ];
+  if (deps.length) {
+    lines.push(`- **Dependencies:** ${deps.map((d) => `\`${d}\``).join(', ')}`);
+  }
+  lines.push('');
+  return lines;
+}
+
+function readingListBlock(context) {
+  const lines = ['### Targeted reading list (read these — they bound the work)', ''];
+  if (context.related.length === 0) {
+    lines.push('_No `related:` wikilinks on this spec. Add the protocols/specs this work touches before filing._');
+  } else {
+    for (const r of context.related) {
+      if (r.resolved) {
+        lines.push(`- [[${r.ref}]] — ${r.name} · ${r.type} · ${r.status}`);
+      } else {
+        lines.push(`- [[${r.ref}]] — ⚠️ unresolved (fix this wikilink)`);
+      }
+    }
+    lines.push('');
+    lines.push('Read these FIRST. Avoid open-ended repo search — the list above is the scope.');
+  }
+  lines.push('');
+  return lines;
+}
+
+function parentBreakageContextBlock(id, context) {
+  const childKind = context.childKind;
+  const eb = context.expectedBreakage || {};
+  const lines = [
+    '### Expected Breakage — parent context (read before filing children)',
+    '',
+    `When authoring each child ${childKind}'s \`## Expected Breakage & Consequences\`, **pre-allocate fix-up scope from these parent sections** — drill down to concrete files/fixtures/call sites; do not paste parent prose or invent breakage in isolation ([[spec-hierarchy]] §Expected Breakage cascade).`,
+    '',
+  ];
+
+  if (childKind === 'task') {
+    if (eb.focus) {
+      lines.push(`**Epic (\`${id}\`):**`, '', eb.focus, '');
+    } else {
+      lines.push(
+        `**Epic (\`${id}\`):** _No \`## Expected Breakage & Consequences\` section found — fill the epic's breakage before breakdown, or note explicitly in each task why breakage is none._`,
+        '',
+      );
+    }
+    if (context.milestone) {
+      const mid = context.milestone.id || context.milestone.ref;
+      if (eb.milestone) {
+        lines.push(`**Milestone (\`${mid}\`):**`, '', eb.milestone, '');
+      } else {
+        lines.push(
+          `**Milestone (\`${mid}\`):** _No Expected Breakage section found — fill the milestone's cross-epic seam breakage at plan ingest, or note in each task._`,
+          '',
+        );
+      }
+    }
+  } else if (childKind === 'epic') {
+    if (eb.focus) {
+      lines.push(`**Milestone (\`${id}\`):**`, '', eb.focus, '');
+    } else {
+      lines.push(
+        `**Milestone (\`${id}\`):** _No \`## Expected Breakage & Consequences\` section found — author cross-epic seam breakage on this milestone before filing epics._`,
+        '',
+      );
+    }
+  }
+
+  return lines;
+}
+
+function seedBlock(_id, context) {
+  const lines = [`### Candidate ${context.childKind} seeds (deterministic — adjust with judgment)`, ''];
+  if (context.acceptance.sections.length === 0) {
+    lines.push(
+      `_No \`## Acceptance criteria\` subsections found. Derive ${context.childKind}s from the goal + the reading list, then add an Acceptance criteria section to this ${context.grain}._`,
+    );
+    lines.push('');
+    return lines;
+  }
+  lines.push(
+    `One ${context.childKind} per acceptance area below is the vault convention. These are seeds, not gospel — split, merge, or reorder as the work demands.`,
+    '',
+  );
+  context.acceptance.sections.forEach((s, i) => {
+    lines.push(`${i + 1}. **${s.title}**`);
+    for (const b of s.bullets.slice(0, 6)) lines.push(`   - ${b}`);
+    if (s.bullets.length > 6) lines.push(`   - …(${s.bullets.length - 6} more)`);
+  });
+  lines.push('');
+  lines.push(
+    context.childKind === 'task'
+      ? `Order them by \`depends_on\` so the foundation lands first. File each task via \`heyspex_file_spec\` per **How to file** below — include \`summary\` in the same call. **Tasks are filed only from this What's Next Launch \`/hs-next\` breakdown** — never during plan ingest and never alongside epics.`
+      : `Order them by \`depends_on\` so the foundation lands first. File each epic via \`heyspex_file_spec\` per **How to file** below — include \`summary\` in the same call. **Milestones and epics are filed in the planning phase** — never co-filed with tasks.`,
+  );
+  lines.push('');
+  return lines;
+}
+
+/**
+ * Count BLOCKER + SIBLING findings from a `runPlanReview({ scope: "breakdown" })`
+ * return value. Pure — no vault I/O. Callers pass the review result they already
+ * hold when composing the decomposition brief ([[HS-TASK-SQWL]]).
+ */
+export function countBreakdownFindings(planReviewResult) {
+  if (!planReviewResult || typeof planReviewResult !== 'object') {
+    return { blockers: 0, siblings: 0 };
+  }
+  const blockers = Array.isArray(planReviewResult.code_audit)
+    ? planReviewResult.code_audit.filter((c) => c?.severity === 'BLOCKER').length
+    : 0;
+  const siblings = Array.isArray(planReviewResult.in_flight_overlap)
+    ? planReviewResult.in_flight_overlap.filter((o) => o?.classification === 'SIBLING').length
+    : 0;
+  return { blockers, siblings };
+}
+
+function formatBreakdownFindingsInline(planReviewResult) {
+  const { blockers, siblings } = countBreakdownFindings(planReviewResult);
+  if (blockers === 0 && siblings === 0) return '';
+  return `⚠ ${blockers} BLOCKER(s), ${siblings} SIBLING(s) — resolve before filing. `;
+}
+
+function filingBlock(id, context, focusSpecPath, breakdownReview) {
+  const childKind = context.childKind;
+  const milestoneRef = context.milestone ? `[[${context.milestone.id || context.milestone.ref}]]` : '(none)';
+  const lines = [
+    '### How to file (then the gate clears)',
+    '',
+    `1. For each ${childKind}: call \`heyspex_file_spec({ type: "${childKind}", name: "<title>", summary: "<plain-language summary per spec-summary-authoring>", frontmatter: { parent: "[[${id}]]"${context.grain === 'epic' ? `, milestone: "${milestoneRef}"` : ''}, depends_on: [/* ordering */] } })\` — the server allocates the \`id\`; author \`summary\` in this call (required — do not defer).${childKind === 'task' ? ' Tasks are never filed during plan ingest.' : ' Epics are never filed alongside tasks.'} Do **not** copy a sibling's frontmatter.`,
+  ];
+  if (childKind === 'task') {
+    const findingsInline = formatBreakdownFindingsInline(breakdownReview);
+    lines.push(
+      `1b. **Breakdown review (advisory — v1)** — once titles/scopes are drafted, call \`heyspex_plan_review({ scope: "breakdown", epic_id: "${id}", proposed_tasks: [{ title: "...", scope: "...", files: ["vendor/..."], symbols: ["fnName"] }, ...] })\`. ${findingsInline}Resolve code-audit BLOCKERs and SIBLING overlaps before filing. Advisory in v1 — does not block \`heyspex_record_alignment\`. At step 3, pass \`skipped_despite_findings: false\` if you resolved all findings before filing, or \`skipped_despite_findings: true\` if you filed despite unresolved BLOCKER/SIBLING findings — this stamps the plan-review marker for skip-rate telemetry ([[HS-TASK-MEN2]]).`,
+      `1c. **Expected Breakage (required per task)** — read **Expected Breakage — parent context** above. Each task body must include \`## Expected Breakage & Consequences\` naming the concrete cascade (files/fixtures/call sites) that realizes its slice of the epic's blast radius, allocated from the epic + milestone sections. Include baseline→exit ([[spec-hierarchy]] §Expected Breakage).`,
+      `1d. **Builder brief (required per task)** — each task must carry fleet-calibrated dispatch hints so the local Ollama builder gets the right context (not too much, not truncated). Consult \`heyspex_get_procedure({ name: "builder-fleet-capability-reference" })\` or \`node dev-factory/lib/fleet-manifest.mjs --self-test\` + \`buildFleetManifest()\` before filing.`,
+      '',
+      '**Frontmatter (optional but recommended):** `target:`, `suggested_model:`, `suggested_machine:`, `recommended_num_ctx:` (16384|32768|65536|131072), `estimated_context_tokens:`, `context_files:` (YAML list → builder `--extra`).',
+      '',
+      '**Body section `## Builder brief` (required):**',
+      '',
+      '```markdown',
+      '## Builder brief',
+      '- **Target:** `path/to/file.ts`',
+      '- **Context files:** `types/foo.ts`, `lib/bar.ts` (explicit — builder hallucinates without them)',
+      '- **Estimated context:** ~45,000 tokens',
+      '- **recommended_num_ctx:** 65536',
+      '- **suggested_model:** qwen3-coder:30b',
+      '- **suggested_machine:** specops-gpu1',
+      '- **Do not include:** entire epic body — link [[HS-…-TASK-sibling]] instead',
+      '```',
+      '',
+      'Copy fleet fields from the breakdown JSON draft (`suggested_model`, `suggested_machine`, `estimated_context_tokens`, `recommended_num_ctx`, `context_files`, `fit_assessment`). For epics >~100K estimated context, split tasks — do not assign one monolithic local build.',
+      '',
+    );
+  } else if (childKind === 'epic') {
+    lines.push(
+      `1b. **Expected Breakage (required per epic)** — read **Expected Breakage — parent context** above. Each epic body must include \`## Expected Breakage & Consequences\` naming subsystem blast radius allocated from the milestone's cross-epic seams ([[spec-hierarchy]] §Expected Breakage cascade).`,
+      '',
+    );
+  }
+  lines.push(
+    `2. Update \`${id}\` \`${childRefsField(context.grain)}:\` to list every new ${childKind} as a \`[[wikilink]]\`.`,
+    `3. Record the checkpoint — the response carries the next on-deck brief inline (no \`/hs-next\` re-invoke needed):`,
+    `   \`heyspex_record_alignment({ spec_id: "${id}", summary: "<what you broke it into>", skipped_despite_findings: false })\` — set \`skipped_despite_findings: true\` only when you filed despite unresolved BLOCKER/SIBLING findings from step 1b.`,
+    '',
+    `_Pinned via \`.heyspex/focus.yaml\` (\`${focusSpecPath || 'n/a'}\`). This ${context.grain} has no ${childKind}s — surfacing a breakdown brief instead of a body excerpt._`,
+  );
+  return lines;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// world-state delta sections — surfaced in BOTH the decomposition brief and
+// the drift brief when the canSkipAlignment pre-pass found a non-empty world-
+// state delta (new files or graph-linked changes since alignment_reviewed_at).
+// Deterministic enumeration: agents read this list instead of grepping.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const KIND_FROM_PATH = [
+  { match: /^specs\/research\//i, label: 'research' },
+  { match: /^specs\/memory\/decisions\//i, label: 'decisions' },
+  { match: /^specs\/memory\/lessons\//i, label: 'lessons' },
+  { match: /^specs\/memory\/references\//i, label: 'references' },
+  { match: /^specs\/memory\/ui-patterns\//i, label: 'ui-patterns' },
+  { match: /^specs\/tasks\//i, label: 'sibling Tasks' },
+  { match: /^specs\/epics\//i, label: 'sibling Epics' },
+  { match: /^specs\/milestones?\//i, label: 'sibling Milestones' },
+  { match: /^specs\/protocols\//i, label: 'protocols' },
+  { match: /^specs\/adr\//i, label: 'ADRs' },
+];
+
+function kindForPath(p) {
+  for (const { match, label } of KIND_FROM_PATH) {
+    if (match.test(p)) return label;
+  }
+  return 'other';
+}
+
+function groupByKind(paths) {
+  const groups = new Map();
+  for (const p of paths) {
+    const k = kindForPath(p);
+    if (!groups.has(k)) groups.set(k, []);
+    groups.get(k).push(p);
+  }
+  return groups;
+}
+
+/**
+ * Body-grep helper: does `body` wikilink any of `targetIds`? Cheap substring
+ * match — wikilinks are unique enough that false positives are rare. Used by
+ * worldStateDeltaSections to compute the graph_delta subset.
+ */
+function bodyLinksAny(body, targetIds) {
+  if (typeof body !== 'string' || body.length === 0) return false;
+  for (const id of targetIds) {
+    if (!id) continue;
+    if (body.includes(`[[${id}]]`) || body.includes(`[[${id}-`)) return true;
+  }
+  return false;
+}
+
+/**
+ * Render the three world-state delta sections (when non-empty) plus the
+ * 4-option menu. `delta.addedPaths` is the git-derived list of `specs/` files
+ * first committed since `alignment_reviewed_at`. `delta.modifiedPaths` is the
+ * (optional) caller-supplied list of files touched since baseline.
+ * `loadByPath(path) -> spec|null` enables the graph_delta carve-out: specs
+ * whose body wikilinks the focus epic or any of its children.
+ */
+export function buildWorldStateDeltaSections({
+  delta,
+  focusId,
+  childIds = [],
+  loadByPath,
+}) {
+  if (!delta || (!delta.addedPaths?.length && !delta.modifiedPaths?.length)) {
+    return [];
+  }
+  const addedPaths = Array.isArray(delta.addedPaths) ? delta.addedPaths : [];
+  const modifiedPaths = Array.isArray(delta.modifiedPaths) ? delta.modifiedPaths : [];
+  const lines = [];
+
+  if (addedPaths.length) {
+    lines.push('### world_state_new (specs added since the breakdown)', '');
+    const grouped = groupByKind(addedPaths);
+    const labelsInOrder = [
+      'research',
+      'decisions',
+      'lessons',
+      'references',
+      'ui-patterns',
+      'sibling Tasks',
+      'sibling Epics',
+      'sibling Milestones',
+      'protocols',
+      'ADRs',
+      'other',
+    ];
+    for (const label of labelsInOrder) {
+      const arr = grouped.get(label);
+      if (!arr || arr.length === 0) continue;
+      lines.push(`- **${label}** (${arr.length})`);
+      for (const p of arr.slice(0, 12)) lines.push(`  - \`${p}\``);
+      if (arr.length > 12) lines.push(`  - …(${arr.length - 12} more)`);
+    }
+    lines.push('');
+  }
+
+  if (modifiedPaths.length) {
+    lines.push('### world_state_modified (existing specs touched since the breakdown)', '');
+    for (const p of modifiedPaths.slice(0, 20)) lines.push(`- \`${p}\``);
+    if (modifiedPaths.length > 20) lines.push(`- …(${modifiedPaths.length - 20} more)`);
+    lines.push('');
+  }
+
+  // graph_delta — subset of addedPaths whose body wikilinks the focus epic or
+  // any of its existing children. Optional (requires a loader); when absent,
+  // the section is skipped.
+  if (addedPaths.length && typeof loadByPath === 'function') {
+    const targets = [focusId, ...childIds].filter(Boolean);
+    const graphHits = [];
+    for (const p of addedPaths) {
+      let spec = null;
+      try {
+        spec = loadByPath(p);
+      } catch {
+        spec = null;
+      }
+      if (spec && bodyLinksAny(spec.body || '', targets)) {
+        graphHits.push({ path: p, id: spec.id || null, name: spec.name || null });
+      }
+    }
+    if (graphHits.length) {
+      lines.push(
+        `### graph_delta (new specs that wikilink \`${focusId || 'this'}\` or its children)`,
+        '',
+      );
+      for (const h of graphHits.slice(0, 20)) {
+        const label = h.id ? `\`${h.id}\`${h.name ? ` — ${h.name}` : ''}` : `\`${h.path}\``;
+        lines.push(`- ${label}`);
+      }
+      if (graphHits.length > 20) lines.push(`- …(${graphHits.length - 20} more)`);
+      lines.push('');
+    }
+  }
+
+  return lines;
+}
+
+/**
+ * 4-option menu rendered at the end of the brief — see [[HS-TASK-SQGT]] (skill
+ * reply parser). The agent surfaces these options to the user; the user picks
+ * one verbatim. Options [2]/[3] dispatch the HSN1 regen tools ([[HS-TASK-0CKW]])
+ * once they land; until then the skill returns a stub.
+ */
+export function buildFourOptionMenu({ focusId, claimableId } = {}) {
+  const target = claimableId || focusId || 'this spec';
+  return [
+    '### Your options',
+    '',
+    `- **[1] proceed** — accept the brief, claim \`${target}\`, start executing. Reply: \`1\` / \`proceed\` / \`yes\`.`,
+    '- **[2] regen_task** — re-derive this task from its parent epic + linked plans. Old version is soft-deleted to `.trash/`. Reply: `2` / `refresh task`.',
+    '- **[3] regen_tasks_for_epic** — regenerate every task under the focus epic (Stage 1 generate → Stage 2 reconcile → Stage 3 retire). Reply: `3` / `refresh epic`.',
+    '- **[4] defer** — close the brief without claiming. Reply: `4` / `defer` / `skip`.',
+    '',
+  ];
+}
+
+/**
+ * Robust HARD-gate prompt for the no-children case (epic_empty /
+ * milestone_needs_breakdown). Re-ground → hierarchy context → seeds →
+ * reading list → filing.
+ */
+export function buildDecompositionPromptMarkdown({
+  grain,
+  id,
+  name,
+  context,
+  roadmapId,
+  focusSpecPath,
+  worldStateDelta,
+  childIds,
+  loadByPath,
+  includeOptionsMenu,
+  breakdownReview,
+}) {
+  const childKind = context.childKind;
+  const lines = [
+    `## ⛔ needs_breakdown — ${id}`,
+    '',
+    `**${grain[0].toUpperCase()}${grain.slice(1)}:** ${name}`,
+    roadmapId ? `**Roadmap:** ${roadmapId}` : '',
+    '',
+    `> **Execution is blocked.** This ${grain} has **no ${childKind}s**. Do not start implementing — your job this session is to decompose it. _AI agents are good at executing the wrong thing perfectly_ ([[heyspex-north-star]]); a clean breakdown is the cheapest defense.`,
+    '',
+  ].filter((l) => l !== '');
+
+  lines.push(...regroundChecklist(context, id));
+  lines.push(...hierarchyContextBlock(id, name, context));
+  lines.push(...parentBreakageContextBlock(id, context));
+  lines.push(...seedBlock(id, context));
+  lines.push(...readingListBlock(context));
+  lines.push(
+    ...buildWorldStateDeltaSections({
+      delta: worldStateDelta,
+      focusId: id,
+      childIds,
+      loadByPath,
+    }),
+  );
+  lines.push(...filingBlock(id, context, focusSpecPath, breakdownReview));
+  if (includeOptionsMenu) {
+    lines.push(...buildFourOptionMenu({ focusId: id }));
+  }
+  return lines.join('\n');
+}
+
+/**
+ * The acceptance criteria rendered AS THE CONTRACT to satisfy (Tier 1), or the
+ * Tier-2 minimal fallback with an inline gap marker when none exist. Distinct
+ * from `seedBlock`, which frames the same data as "candidates to split" for a
+ * breakdown — here the agent EXECUTES against them.
+ */
+function executionContractBlock(context) {
+  const lines = ['### Acceptance criteria — your contract (close-out verifies these)', ''];
+  const sections = context.acceptance?.sections || [];
+  if (sections.length === 0) {
+    // Tier 2 — no acceptance criteria. Mark the gap inline and point at the
+    // goal/reading list (rendered below) as the working contract; never error.
+    lines.push(
+      context.goal
+        ? '**[NEEDS CLARIFICATION: no `## Acceptance criteria` on this spec — treat the Goal (in Hierarchy context below) + the reading list as the contract, and add explicit criteria.]**'
+        : '**[NEEDS CLARIFICATION: no `## Acceptance criteria` and no `## Goal` — too thin to derive a contract. Add at least a goal before claiming.]**',
+      '',
+    );
+    return lines;
+  }
+  for (const s of sections) {
+    lines.push(`**${s.title}**`);
+    for (const b of s.bullets) lines.push(`- [ ] ${b}`);
+    lines.push('');
+  }
+  return lines;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tier-3 readiness floor ([[HS-TASK-RW3B]]) — a separable pre-synthesis check
+// that runs BEFORE buildExecutionBrief. Below a minimum-viable-input threshold,
+// the caller routes to a recoverable clarification surface naming the specific
+// missing fields, never a thin brief and never a hard throw. Decoupled from the
+// composer so it is independently testable (epic §6).
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Synthesizability floor. A spec is brief-able at Tier 1/2 when it has a title
+ * AND at least one of: an `## Acceptance criteria` section carrying
+ * ≥ `minAcceptanceBullets` bullets, OR a non-trivial goal/scope of
+ * ≥ `minGoalChars` characters. Config-surfaced via `readReadinessFloorSettings`
+ * so it is tunable without a deploy (AC #3).
+ */
+export const DEFAULT_READINESS_FLOOR = { minAcceptanceBullets: 1, minGoalChars: 12 };
+
+/**
+ * Read the (tunable) readiness floor from spex-console/settings.json or its
+ * .heyspex mirror under a `briefReadinessFloor: { minAcceptanceBullets,
+ * minGoalChars }` key. Missing / malformed values fall back per-field to
+ * DEFAULT_READINESS_FLOOR. Mirrors readAlignmentFuseSettings' lookup order.
+ */
+export function readReadinessFloorSettings(vaultRoot) {
+  for (const p of spexConsoleSettingsCandidates(vaultRoot)) {
+    const raw = readJsonSafe(p);
+    const floor = raw && typeof raw === 'object' ? raw.briefReadinessFloor : null;
+    if (!floor || typeof floor !== 'object') continue;
+    const pick = (v, fallback) =>
+      typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : fallback;
+    return {
+      minAcceptanceBullets: pick(floor.minAcceptanceBullets, DEFAULT_READINESS_FLOOR.minAcceptanceBullets),
+      minGoalChars: pick(floor.minGoalChars, DEFAULT_READINESS_FLOOR.minGoalChars),
+    };
+  }
+  return { ...DEFAULT_READINESS_FLOOR };
+}
+
+/**
+ * Assess whether a spec carries enough structured content to derive a reliable
+ * execution brief. Pure: reads only `name` + the `context` produced by
+ * `extractDecompositionContext`. Returns
+ *   `{ ready, missing: [{ field, need }], floor, metrics }`
+ * `missing` is empty iff `ready`; each entry names a field and the concrete
+ * thing to add, so the clarification surface can render them verbatim (AC #2).
+ */
+export function assessBriefReadiness({ name, context, floor } = {}) {
+  const f = { ...DEFAULT_READINESS_FLOOR, ...(floor || {}) };
+  const missing = [];
+
+  const title = typeof name === 'string' ? name.trim() : '';
+  if (!title) {
+    missing.push({ field: 'title', need: 'a non-empty title/name on the spec' });
+  }
+
+  const sections = context?.acceptance?.sections || [];
+  const acceptanceBullets = sections.reduce(
+    (n, s) => n + (Array.isArray(s.bullets) ? s.bullets.length : 0),
+    0,
+  );
+  const goal = typeof context?.goal === 'string' ? context.goal.trim() : '';
+  const goalChars = goal.length;
+
+  const hasAcceptance = acceptanceBullets >= f.minAcceptanceBullets;
+  const hasGoal = goalChars >= f.minGoalChars;
+  if (!hasAcceptance && !hasGoal) {
+    missing.push({
+      field: 'goal_or_acceptance',
+      need:
+        `at least one of: a \`## Acceptance criteria\` section with ≥${f.minAcceptanceBullets} bullet(s), ` +
+        `or a non-trivial \`## Goal\`/scope (≥${f.minGoalChars} characters)`,
+    });
+  }
+
+  return {
+    ready: missing.length === 0,
+    missing,
+    floor: f,
+    metrics: { acceptanceBullets, goalChars },
+  };
+}
+
+/**
+ * Classify which synthesis tier a brief was served at ([[HS-TASK-68NO]]). Pure —
+ * the observability counterpart records/logs the returned label. The ladder:
+ *   'override' — Tier 0: an authored `## NEXT STEP` override is present.
+ *   'derived'  — Tier 1: an `## Acceptance criteria` contract was derived.
+ *   'minimal'  — Tier 2: no acceptance criteria; goal-only gap-marked brief.
+ *   'skip'     — Tier 3: below the readiness floor → clarification surface.
+ * 'minimal' and 'skip' are the *degraded* tiers (below 'derived').
+ */
+export function classifyBriefTier({ override, context, ready } = {}) {
+  if (ready === false) return 'skip';
+  const hasOverride = typeof override === 'string' && override.trim().length > 0;
+  if (hasOverride) return 'override';
+  const sections = context?.acceptance?.sections || [];
+  if (sections.length > 0) return 'derived';
+  return 'minimal';
+}
+
+/** The tiers served below 'derived' — the degraded-mode set for the SLO signal. */
+export const DEGRADED_BRIEF_TIERS = ['minimal', 'skip'];
+
+/**
+ * Tier-3 clarification surface. Replaces the brief when `assessBriefReadiness`
+ * fails: a friendly, recoverable note naming exactly what to add (AC #2/#4),
+ * never an error/throw. Same shape as the other prompt builders so callers can
+ * drop it straight into `prompt_markdown`.
+ */
+export function buildClarificationPrompt({ id, name, status, roadmapId, missing, focusSpecPath, grain = 'task' } = {}) {
+  const grainLabel =
+    grain === 'milestone' ? 'Milestone' : grain === 'epic' ? 'Epic' : 'Task';
+  const lines = [
+    `## 🟡 needs_clarification — ${id || '(unknown spec)'}`,
+    '',
+    `**${grainLabel}:** ${name || '(untitled)'}`,
+    status ? `**Status:** ${status}` : '',
+    roadmapId ? `**Roadmap:** ${roadmapId}` : '',
+    '',
+    `> **This spec is too thin to derive a reliable execution brief.** Rather than hand you a low-quality brief, here is exactly what to add. Fill these in, then re-run \`/hs-next\` — the brief builds itself once the floor is met.`,
+    '',
+    "### What's missing",
+    '',
+  ].filter((l) => l !== '');
+
+  const items = Array.isArray(missing) ? missing : [];
+  if (items.length === 0) {
+    lines.push('- _(no specific fields flagged — re-run `/hs-next` to retry)_');
+  } else {
+    for (const m of items) {
+      lines.push(`- **${m.field}** — ${m.need}`);
+    }
+  }
+
+  lines.push(
+    '',
+    '### How to recover',
+    '',
+    `1. Open the spec on disk (\`${focusSpecPath || 'n/a'}\`) and add the fields above.`,
+    '2. Re-run `/hs-next` (or `heyspex_next_on_deck`) — the readiness floor re-checks and the brief is derived automatically once the threshold is met.',
+    '',
+  );
+  return lines.join('\n');
+}
+
+/**
+ * Derive an agent EXECUTION brief from a spec's structured content — the
+ * deterministic, on-read replacement for hand-authored NEXT STEP blocks
+ * ([[HS-EPIC-DXBR]] / [[HS-TASK-ULKL]]). Pure: composes only from the passed-in
+ * `context` + `override`; no fs/Neon/index reads, no frontmatter writes. Same
+ * input ⇒ byte-identical output.
+ *
+ * Synthesis chain Tiers 0–2 (the Tier-3 readiness floor lives in the caller):
+ *   Tier 0 — `override` (a pre-extracted `## NEXT STEP` block) is PREPENDED under
+ *            a labeled heading with the derived contract below it. Never drops,
+ *            never replaces — a stale override stays visible beside the contract.
+ *   Tier 1 — derive from `context.acceptance` (the executable contract) + goal +
+ *            out-of-scope + dependencies + reading list.
+ *   Tier 2 — no acceptance criteria ⇒ derive from goal + reading list and mark
+ *            the gap inline; no error, no disclaimer.
+ *
+ *   `context` is the output of `extractDecompositionContext(node, loadRef, grain)`.
+ *   `override` is the verbatim NEXT STEP body, or null/'' when absent.
+ */
+export function buildExecutionBrief({ id, name, status, roadmapId, context, override }) {
+  const lines = [
+    `## Execution brief — ${id}`,
+    '',
+    `**Task:** ${name}`,
+    status ? `**Status:** ${status}` : '',
+    roadmapId ? `**Roadmap:** ${roadmapId}` : '',
+    '',
+  ].filter((l) => l !== '');
+
+  // Tier 0 — authored override, prepended (never replaces the contract).
+  const overrideText = typeof override === 'string' ? override.trim() : '';
+  if (overrideText) {
+    lines.push(
+      '### Authored override (`## NEXT STEP`)',
+      '',
+      '_A human pinned this prompt. Follow it — the derived contract below stays visible so you can spot any drift between the two._',
+      '',
+      overrideText,
+      '',
+      '---',
+      '',
+    );
+  }
+
+  lines.push(...executionContractBlock(context));
+  lines.push(...hierarchyContextBlock(id, name, context, { outOfScopeNote: 'do NOT implement these' }));
+  lines.push(...readingListBlock(context));
+  return lines.join('\n');
+}
+
+/**
+ * SOFT corpus-drift prompt (children exist, reference corpus moved). Prepended
+ * to the task brief, NEVER a hard block. The agent reads each stale doc,
+ * identifies what changed, and poses keep/update/drop to the user per affected
+ * child task. Then `heyspex_record_alignment` resets the timestamp so the next
+ * `/hs-next` is quiet.
+ *
+ *   stale — `[{ ref, source, lastModified }]` from detectCorpusDrift.
+ */
+export function buildDriftResolutionPrompt({
+  grain,
+  id,
+  name,
+  context,
+  existingChildren,
+  stale,
+  roadmapId,
+  focusSpecPath,
+  worldStateDelta,
+  childIds,
+  loadByPath,
+  includeOptionsMenu,
+}) {
+  const childKind = context.childKind;
+  const lines = [
+    `## ⚠️ corpus_drift — ${id}`,
+    '',
+    `**${grain[0].toUpperCase()}${grain.slice(1)}:** ${name}`,
+    roadmapId ? `**Roadmap:** ${roadmapId}` : '',
+    '',
+    `> **Soft re-ground (not a block).** ${stale.length} doc(s) in this ${grain}'s reference corpus moved since the last alignment review. Read each one, identify what's stale or contradicted in the breakdown, then pose **keep / update / drop** to the user per affected ${childKind}. Apply the answers and reset the checkpoint — then the task brief below is yours to execute.`,
+    '',
+  ].filter((l) => l !== '');
+
+  lines.push('### Stale corpus (newer than alignment_reviewed_at)', '');
+  for (const s of stale) {
+    const ts = Number.isFinite(s.lastModified) ? new Date(s.lastModified).toISOString() : 'unknown';
+    lines.push(`- [[${s.ref}]] — ${s.source} · last-modified \`${ts}\``);
+  }
+  lines.push('');
+
+  lines.push(`### Existing ${childKind}s (use these as the resolution surface)`, '');
+  for (const c of existingChildren) {
+    lines.push(`- \`${c.id}\`${c.name ? ` — ${c.name}` : ''} · ${c.status || '?'}`);
+  }
+  lines.push('');
+
+  lines.push(
+    '### Resolution loop (then the drift section clears)',
+    '',
+    `1. Read each stale doc above and identify what changed — direction shifts, new acceptance, retired scope, renamed concepts.`,
+    `2. For each ${childKind} potentially affected, pose to the user: **keep** (no change needed), **update** (open the ${childKind}, restate scope), or **drop** (retire it, add a replacement if needed).`,
+    `3. Apply the user's answers (edit ${childKind}s, file new ones, retire stale ones).`,
+    `4. Record the new baseline: \`heyspex_record_alignment({ spec_id: "${id}", summary: "<one-line resolution>" })\` — this resets \`alignment_reviewed_at\` so \`/hs-next\` is quiet on the next call.`,
+    `5. **False positive?** Audit trail: \`heyspex_record_alignment({ spec_id: "${id}", override_reason: "<why this drift is not real>" })\`.`,
+    '',
+    `_Pinned via \`.heyspex/focus.yaml\` (\`${focusSpecPath || 'n/a'}\`). The task brief follows below — work it once drift questions are resolved._`,
+  );
+
+  const deltaLines = buildWorldStateDeltaSections({
+    delta: worldStateDelta,
+    focusId: id,
+    childIds: childIds || (Array.isArray(existingChildren) ? existingChildren.map((c) => c.id) : []),
+    loadByPath,
+  });
+  if (deltaLines.length) {
+    lines.push('', ...deltaLines);
+  }
+  if (includeOptionsMenu) {
+    lines.push(
+      ...buildFourOptionMenu({
+        focusId: id,
+        claimableId: existingChildren?.[0]?.id || id,
+      }),
+    );
+  }
+  return lines.join('\n');
+}