@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.4

package/src/runtime/history-compactor.js

@@ -0,0 +1,237 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * History compactor (IC-005, IC-009). Moves the body of an artifact's `## <n>. History` section into
+ * `decisions/history/<artifact>.md` and leaves a comment-and-pointer stub behind, so the live
+ * artifact stops growing with the feature's age while every History line stays reachable
+ * (NFR-004).
+ *
+ * Mechanical by design (NFR-001): no model is asked to decide what to move. A line moves unless it
+ * is blank, part of an HTML comment, the pointer line, or the initial-version literal.
+ *
+ * Write order per artifact is the safety property (FR-014): append to the archive, read it back and
+ * confirm the block is there, and only then rewrite the artifact. A failure at any step leaves the
+ * artifact as it was. A crash between the two writes leaves the block in the archive and the
+ * artifact unchanged; the next run recognises the identical chunk and does not append it twice.
+ */
+
+const nodeFs = require('node:fs');
+const path = require('node:path');
+
+const HISTORY_HEADING = /^## ([0-9]+)\. History\s*$/;
+const ANY_H2 = /^## /;
+const POINTER = /^Earlier entries: \[decisions\/history\/[a-z-]+\.md\]/;
+const INITIAL_VERSION = 'None — initial version.';
+const TARGET_KEYS = ['requirement', 'design', 'specs', 'data_model', 'plan'];
+
+const FENCE_OPEN = /^ {0,3}(`{3,}|~{3,})/;
+
+/**
+ * Classifies every line as `text`, `fence` (a fence marker or a line inside a fenced block),
+ * `comment` (the first line of an HTML comment) or `comment-cont`. A `## ` line inside a fence or a
+ * comment is not a heading, and fence markers inside a comment (or the reverse) do not open
+ * anything, so a History example quoted in a code block cannot be mistaken for the real section.
+ * @returns {{kinds:string[], openFence:boolean, openComment:boolean, openAt:number}} the middle two
+ *   are true when a fence or an HTML comment is never closed, so everything after it was swallowed;
+ *   `openAt` is the line index where that construct opened (-1 when none is left open)
+ */
+function scan(lines          )                                                                                {
+  const kinds           = new Array(lines.length);
+  let fence                                     = null;
+  let comment = false;
+  let openedAt = -1;
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (fence) {
+      kinds[i] = 'fence';
+      const close = /^ {0,3}(`+|~+)\s*$/.exec(line);
+      if (close && close[1][0] === fence.ch && close[1].length >= fence.len) fence = null;
+      continue;
+    }
+    if (comment) {
+      kinds[i] = 'comment-cont';
+      if (line.includes('-->')) comment = false;
+      continue;
+    }
+    const open = FENCE_OPEN.exec(line);
+    if (open) { kinds[i] = 'fence'; fence = { ch: open[1][0], len: open[1].length }; openedAt = i; continue; }
+    const trimmed = line.trim();
+    if (trimmed.startsWith('<!--')) {
+      kinds[i] = 'comment';
+      if (!trimmed.includes('-->', 4)) { comment = true; openedAt = i; }
+      continue;
+    }
+    kinds[i] = 'text';
+  }
+  return { kinds, openFence: fence !== null, openComment: comment, openAt: fence !== null || comment ? openedAt : -1 };
+}
+
+/**
+ * Splits History body lines into what stays and what moves. Fenced content moves intact. Only the
+ * exact canonical pointer for this artifact is the pointer; any other line, including one that
+ * merely looks like a pointer, moves, so no text is dropped.
+ */
+function classify(bodyLines          , kinds          , canonicalPointer        )                                                                    {
+  const comments             = [];
+  const moved           = [];
+  let pointer                = null;
+  let block                  = null;
+  bodyLines.forEach((line, i) => {
+    const kind = kinds[i];
+    if (kind === 'comment-cont') { (block            ).push(line); return; }
+    block = null;
+    if (kind === 'comment') { block = [line]; comments.push(block); return; }
+    if (kind === 'fence') { moved.push(line); return; }
+    const trimmed = line.trim();
+    if (trimmed === '') return;
+    if (trimmed === canonicalPointer) { if (pointer === null) pointer = line; return; }
+    if (trimmed === INITIAL_VERSION) return;
+    moved.push(line);
+  });
+  return { comments, moved, pointer };
+}
+
+function writeAtomic(fsImpl     , file        , content        )       {
+  fsImpl.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  try {
+    fsImpl.writeFileSync(tmp, content, 'utf8');
+    fsImpl.renameSync(tmp, file);
+  } catch (error     ) {
+    try { fsImpl.rmSync(tmp, { force: true }); } catch { /* nothing to clean */ }
+    throw error;
+  }
+}
+
+function toPosix(p        )         {
+  return p.split(path.sep).join('/');
+}
+
+/**
+ * Whether the archive's most recent chunk is exactly this block. Only the last chunk counts: the
+ * crash this guards against (archive written, artifact not) always leaves the interrupted chunk
+ * last. The dated header is ignored, so a recovery on a later day does not append a second copy,
+ * and a block that merely prefixes an earlier chunk does not match.
+ *
+ * A chunk header is a `## Compacted` line `scan()` classifies as text: a moved block may quote such
+ * a line inside a code fence, and that must not be read as the start of a chunk. The dedupe and the
+ * post-write confirmation both use this one predicate.
+ */
+function lastChunkIs(archiveText        , blockLF        )          {
+  const lines = archiveText.replace(/\r\n/g, '\n').split('\n');
+  const { kinds } = scan(lines);
+  let header = -1;
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    if (kinds[i] === 'text' && lines[i].startsWith('## Compacted ')) { header = i; break; }
+  }
+  if (header === -1 || lines[header + 1] !== '') return false;
+  return lines.slice(header + 2).join('\n').replace(/\n+$/, '') === blockLF;
+}
+
+/**
+ * Compacts one artifact.
+ * @returns {{artifact:string, path:string, archive:string, lines:number}|null} null when there was
+ *   nothing to move
+ */
+function compactArtifact({ fsImpl, featureDir, file, date }                                                                 )                                                                            {
+  const text = fsImpl.readFileSync(file, 'utf8');
+  const crlf = text.includes('\r\n');
+  const lines = text.split('\n');
+  const { kinds, openFence, openComment, openAt } = scan(lines);
+  const unclosed                = openFence ? 'a code fence' : openComment ? 'an HTML comment' : null;
+  const refuse = ()        => {
+    throw new Error(`${unclosed} is never closed, so the end of the History section cannot be told`);
+  };
+  const start = lines.findIndex((l        , i        ) => kinds[i] === 'text' && HISTORY_HEADING.test(l));
+  // An unclosed construct swallows everything after it. It matters only when it opens before the
+  // History section ends (FR-001): then the section's end cannot be told. A History heading it
+  // swallowed is such a case; one that simply is not there, or that closed before the construct
+  // opened, is not, and the construct is treated as absent.
+  if (start === -1) {
+    if (unclosed && lines.some((l        , i        ) => i > openAt && HISTORY_HEADING.test(l))) refuse();
+    return null;
+  }
+  const section = Number((HISTORY_HEADING.exec(lines[start])                   )[1]);
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (kinds[i] === 'text' && ANY_H2.test(lines[i])) { end = i; break; }
+  }
+  if (unclosed && openAt < end) refuse();
+  const name = path.basename(file);
+  const archiveFile = path.join(featureDir, 'decisions', 'history', name);
+  const link = toPosix(path.relative(path.dirname(file), archiveFile));
+  const canonicalPointer = `Earlier entries: [decisions/history/${name}](${link}).`;
+  const { comments, moved, pointer } = classify(lines.slice(start + 1, end), kinds.slice(start + 1, end), canonicalPointer);
+  if (moved.length === 0) return null;
+
+  const rel = toPosix(path.relative(featureDir, file));
+  const archiveRel = toPosix(path.relative(featureDir, archiveFile));
+
+  // Chunks are built with LF and converted to the artifact's own line ending on write, so a CRLF
+  // artifact gets a CRLF archive and no file ends up mixed.
+  const eol = crlf ? '\r\n' : '\n';
+  const toEol = (t        ) => (crlf ? t.replace(/\n/g, '\r\n') : t);
+  const blockLF = moved.map((l) => l.replace(/\r$/, '')).join('\n');
+  const chunk = `## Compacted ${date} from ${rel} §${section}\n\n${blockLF}\n`;
+  const existing = fsImpl.existsSync(archiveFile) ? fsImpl.readFileSync(archiveFile, 'utf8') : null;
+  if (existing === null || !lastChunkIs(existing, blockLF)) {
+    const base = existing === null ? toEol(`# History archive: ${rel}\n`) : (existing.endsWith('\n') ? existing : `${existing}${eol}`);
+    writeAtomic(fsImpl, archiveFile, `${base}${eol}${toEol(chunk)}`);
+  }
+  if (!lastChunkIs(fsImpl.readFileSync(archiveFile, 'utf8'), blockLF)) {
+    throw new Error(`the moved block is not present in ${archiveRel} after the write`);
+  }
+
+  const blank = crlf ? '\r' : '';
+  const pointerLine = pointer !== null ? pointer : `${canonicalPointer}${blank}`;
+  const body = [blank];
+  for (const c of comments) body.push(...c, blank);
+  body.push(pointerLine, end === lines.length ? '' : blank);
+  writeAtomic(fsImpl, file, [...lines.slice(0, start + 1), ...body, ...lines.slice(end)].join('\n'));
+  return { artifact: name, path: rel, archive: archiveRel, lines: moved.length };
+}
+
+/**
+ * Compacts every existing artifact among requirement, design, specs, data model and plan.
+ *
+ * @param {Object} options
+ * @param {string} options.repoRoot repository root the resolver's paths are relative to
+ * @param {string} options.featureDir absolute feature folder
+ * @param {Object} options.paths the resolver's JSON (`requirement`, `design`, `specs`,
+ *   `data_model`, `plan`, repo-root-relative or null)
+ * @param {string} [options.date] YYYY-MM-DD stamped on the archive chunk; defaults to today (UTC)
+ * @param {Object} [options.fsImpl] fs implementation (tests substitute one)
+ *
+ * Not locked: concurrent callers can interleave archive appends. Call it through
+ * `compactDecisions` / `runDecision` in decision-register.js, which hold the register lock.
+ *
+ * Every artifact is attempted. One that cannot be compacted is left as it was and reported in
+ * `failed`; it does not stop the others (IC-005).
+ *
+ * @returns {{status:'compacted'|'unchanged'|'partial', moved:Object[], failed:Array<{artifact:string, path:string, message:string}>}}
+ *   `partial` means at least one artifact failed
+ */
+function compactHistory({ repoRoot, featureDir, paths, date, fsImpl = nodeFs }                                                                                   )                                                                                                                                      {
+  const stamp = date || new Date().toISOString().slice(0, 10);
+  const moved        = [];
+  const failed        = [];
+  for (const key of TARGET_KEYS) {
+    if (!paths || !paths[key]) continue;
+    const file = path.resolve(repoRoot, paths[key]);
+    if (!fsImpl.existsSync(file)) continue;
+    let result     ;
+    try {
+      result = compactArtifact({ fsImpl, featureDir, file, date: stamp });
+    } catch (error     ) {
+      const name = toPosix(path.relative(featureDir, file));
+      failed.push({ artifact: path.basename(file), path: name, message: `could not compact ${name}: ${error.message}; the artifact was left unchanged` });
+      continue;
+    }
+    if (result) moved.push(result);
+  }
+  return { status: failed.length ? 'partial' : moved.length ? 'compacted' : 'unchanged', moved, failed };
+}
+
+module.exports = { compactHistory, HISTORY_HEADING, POINTER, INITIAL_VERSION };

package/src/runtime/implementation-gate.js

@@ -0,0 +1,321 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { readReadinessRecord, newerVersionOf, RECORD_VERSION } = require('./readiness-record.js');
+const { listCheckouts } = require('./checkouts.js');
+const { readTaskState } = require('./task-state.js');
+const { resolveActiveFeature } = require('./feature-resolve.js');
+const { isSafeSlug } = require('./task-scope.js');
+const { REPO_ROOT } = require('../helper/repo-root.js');
+
+// The implementation gate: which stage of a workflow needs a READY readiness record before it is
+// handed off, whether a task has one, and the words every refusal uses.
+//
+// The held set is read from the workflow registry, never written here: the gated stage is the
+// first one that mutates source and carries a readiness template. The texts live here once, so the
+// orchestrator, `verify` and the edit hook (which prints the same bytes) say the same thing.
+
+const GATE = 'doflow gate readiness-before-implementation';
+
+/** What clears a record a newer DoFlow wrote; `readiness` here refuses to overwrite it. */
+const NEWER_NEXT = 'run this command with the DoFlow that wrote the record, or upgrade DoFlow here.';
+
+/**
+ * The first stage that mutates source and carries a readiness template; with `editTime`, the first
+ * such stage that has not opted out of the edit-time check.
+ * @param {Array<Object>} stages a resolved workflow's stages, or a run's stage nodes
+ * @param {{editTime?: boolean}} [options]
+ * @returns {{id: string, readinessTemplate: string, editTimeGate: boolean}|null}
+ */
+function gatedStage(stages     , { editTime = false }      = {}) {
+  const stage = (stages || []).find((s     ) => s && s.mutatesSource === true
+    && typeof s.readinessTemplate === 'string' && s.readinessTemplate !== ''
+    && (!editTime || s.editTimeGate !== false));
+  return stage ? { id: stage.id, readinessTemplate: stage.readinessTemplate, editTimeGate: stage.editTimeGate !== false } : null;
+}
+
+/**
+ * The classes whose workflow has a gated stage, in registry order.
+ * @param {Object} engine a WorkflowEngine
+ * @param {{editTime?: boolean}} [options]
+ * @returns {Array<string>}
+ */
+function heldClasses(engine     , { editTime = false }      = {}) {
+  return engine.listClasses().filter((cls     ) => gatedStage(engine.resolveWorkflow(cls).stages, { editTime }) !== null);
+}
+
+/** The command that clears every readiness refusal. */
+function nextCommand({ taskId, slug, template }     ) {
+  const withSlug = slug && slug !== taskId ? ` --slug=${slug}` : '';
+  return `doflow-run readiness --task-class ${template} --task-id ${taskId}${withSlug}`;
+}
+
+/**
+ * The refusal for one check code.
+ * @param {'missing'|'not-ready'|'wrong-template'|'unusable'|'ambiguous'} code
+ * @param {Object} options
+ * @param {string} options.taskId
+ * @param {string|null} [options.slug]
+ * @param {string} options.template the template the gated stage needs
+ * @param {Object|null} [options.record] the record read, for `not-ready` and `wrong-template`
+ * @param {Array<string>} [options.candidates] the files found, for `ambiguous`
+ * @param {string|null} [options.detail] why the record cannot be used, for `unusable`
+ * @param {string|null} [options.file] the record's file, for `unusable` when a newer DoFlow wrote it
+ * @param {number|null} [options.newerVersion] that newer record version; `readiness` would refuse to
+ *   replace such a record, so the text does not send the caller there
+ * @returns {string}
+ */
+function refusalText(code     , { taskId, slug = null, template, record = null, candidates = [], detail = null, file = null, newerVersion = null }     )         {
+  const next = nextCommand({ taskId, slug, template });
+  const tail = `Next: ${next}, then gather what it lists until it reports READY. Nothing was changed.`;
+  if (code === 'unusable' && newerVersion !== null) {
+    return `${GATE}: task '${taskId}' has a readiness record ${file} written by a newer DoFlow (record version ${newerVersion}; this runtime reads ${RECORD_VERSION}), `
+      + `so this runtime cannot read it and readiness cannot replace it. Next: ${NEWER_NEXT} Nothing was changed.`;
+  }
+  switch (code) {
+    case 'missing':
+      return `${GATE}: task '${taskId}' has no readiness record for the '${template}' template. ${tail}`;
+    case 'not-ready':
+      return `${GATE}: task '${taskId}' was last evaluated ${record.state} at ${record.evaluatedAt} against the '${template}' template, not READY. ${tail}`;
+    case 'wrong-template':
+      return `${GATE}: task '${taskId}' has a READY record for the '${record.taskClass}' template, and this stage needs '${template}'. ${tail}`;
+    case 'unusable':
+      return `${GATE}: task '${taskId}' has a readiness record that cannot be used (${detail}). ${tail}`;
+    case 'ambiguous':
+      return `${GATE}: task '${taskId}' has records in more than one other checkout (${candidates.join(', ')}). Next: run the command from the checkout that holds the one you mean, or run ${next} here. Nothing was changed.`;
+    case 'ambiguous-run':
+      // A readiness record written here cannot say which run is meant, so it is not offered.
+      return `${GATE}: task '${taskId}' has runs in more than one other checkout (${candidates.join(', ')}). Next: run verify from the checkout that holds the run you mean. Nothing was changed.`;
+    default:
+      throw new Error(`no readiness refusal text for code '${code}'`);
+  }
+}
+
+/**
+ * Which harnesses run this gate before each source edit and which meet it first at handoff, from the
+ * gate's own mapping in lifecycle.json (`pre-implementation-gate`): `supported`, or `different`
+ * with no prerequisite, runs it; a prerequisite (such as Codex's hook review) is named, since until
+ * it is met nothing was checked; `unavailable` has no hook layer for it. Empty when the registry
+ * cannot be read.
+ * @param {{repoRoot?: string}} [options]
+ * @returns {string}
+ */
+function harnessHookNote({ repoRoot = REPO_ROOT }      = {})         {
+  try {
+    const { policies } = JSON.parse(fs.readFileSync(path.join(repoRoot, 'core', 'registry', 'lifecycle.json'), 'utf8'));
+    const { mappings } = policies.find((p     ) => p.id === 'pre-implementation-gate');
+    const runs = [];
+    const gated = new Map();
+    const none = [];
+    for (const [id, m] of (Object.entries(mappings)                   )) {
+      const prerequisites = Array.isArray(m.prerequisites) ? m.prerequisites : [];
+      if (m.status === 'unavailable' || (m.status !== 'supported' && m.status !== 'different')) none.push(id);
+      else if (prerequisites.length === 0) runs.push(id);
+      else {
+        const key = prerequisites.join(' and ');
+        gated.set(key, [...(gated.get(key) || []), id]);
+      }
+    }
+    const parts = [];
+    if (runs.length) parts.push(`${runs.join(', ')} ${runs.length === 1 ? 'runs' : 'run'} this check before each source edit`);
+    for (const [key, ids] of gated) parts.push(`${ids.join(', ')} ${ids.length === 1 ? 'runs' : 'run'} it only after ${key}`);
+    if (none.length) parts.push(`${none.join(', ')} ${none.length === 1 ? 'has' : 'have'} no hook layer, so this refusal is ${none.length === 1 ? 'its' : 'their'} first check`);
+    return `Edit-time check: ${parts.join('; ')}.`;
+  } catch {
+    return '';
+  }
+}
+
+const isDir = (dir     ) => {
+  try {
+    return fs.statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+};
+const folderOf = (root     , slug     ) => path.join(root, 'agent-docs', 'doflow', slug);
+
+/** The branch's feature slug as the resolver names it, or null. */
+function branchFeatureSlug(cwd     ) {
+  try {
+    const found = resolveActiveFeature({ projectRoot: cwd });
+    const s = !found.error && found.paths ? found.paths.feature_slug : null;
+    return isSafeSlug(s) ? s : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The feature a task belongs to, as seen from `projectRoot`: `--slug`, else the task id when it
+ * names a feature folder there, else the branch's feature.
+ * @param {{projectRoot: string, taskId?: string|null, slug?: string|null}} options
+ * @returns {string|null}
+ */
+function featureSlugFor({ projectRoot, taskId = null, slug = null }     ) {
+  if (slug) return slug;
+  if (isSafeSlug(taskId) && isDir(folderOf(projectRoot, taskId))) return taskId;
+  return branchFeatureSlug(projectRoot);
+}
+
+/** The feature a run belongs to: the slug recorded when it started, else its task id when that names
+ * a feature folder in the checkout holding the run. */
+function runSlugOf(run     , root     ) {
+  if (run && typeof run.featureSlug === 'string' && run.featureSlug !== '') return run.featureSlug;
+  return run && isSafeSlug(run.taskId) && isDir(folderOf(root, run.taskId)) ? run.taskId : null;
+}
+
+/**
+ * A task's run file: in this checkout, else in exactly one other checkout whose run belongs to the
+ * same feature. Task ids repeat across features, so another checkout's run with the same id but
+ * another feature (or none) is not this task's and is never read or updated from here.
+ * @param {{stateRoot: string, taskId: string, slug: string|null, exec?: Function}} options
+ * @returns {{status: 'found'|'missing'|'ambiguous', file: string|null, root: string|null,
+ *   origin: 'current'|'other'|null, candidates: Array<string>}}
+ */
+function findRunFile({ stateRoot, taskId, slug, exec }     ) {
+  const rel = path.join('.doflow', 'state', 'orchestration', `${taskId}.json`);
+  const missing = { status: 'missing', file: null, root: null, origin: null, candidates: [] };
+  if (fs.existsSync(path.join(stateRoot, rel))) {
+    return { status: 'found', file: path.join(stateRoot, rel), root: stateRoot, origin: 'current', candidates: [] };
+  }
+  if (!slug) return missing;
+  const checkouts = listCheckouts({ cwd: stateRoot, ...(exec ? { exec } : {}) });
+  if (!checkouts.ok || checkouts.sandbox) return missing;
+  const matches = checkouts.others.filter((root     ) => {
+    const file = path.join(root, rel);
+    if (!fs.existsSync(file)) return false;
+    try {
+      return runSlugOf(JSON.parse(fs.readFileSync(file, 'utf8')), root) === slug;
+    } catch {
+      return false;
+    }
+  });
+  if (matches.length === 0) return missing;
+  if (matches.length > 1) return { ...missing, status: 'ambiguous', candidates: matches.map((root     ) => path.join(root, rel)) };
+  return { status: 'found', file: path.join(matches[0], rel), root: matches[0], origin: 'other', candidates: [] };
+}
+
+/** The slug a refusal's next command names: one whose feature folder exists in this checkout or in
+ * the main checkout, which is when `readiness --slug` resolves it the same way the edit hook does. */
+function nextSlugFor({ stateRoot, taskId, slug, exec }     ) {
+  if (!slug || slug === taskId) return null;
+  if (isDir(folderOf(stateRoot, slug))) return slug;
+  const checkouts = listCheckouts({ cwd: stateRoot, ...(exec ? { exec } : {}) });
+  return checkouts.main && isDir(folderOf(checkouts.main, slug)) ? slug : null;
+}
+
+/** Why a record cannot be read as an evaluation, or null when it can. */
+function unusableDetail(record     , now     ) {
+  if (!record || typeof record !== 'object' || Array.isArray(record)) return 'not a JSON object';
+  if (record.version !== RECORD_VERSION) return `version ${JSON.stringify(record.version)}, this runtime reads ${RECORD_VERSION}`;
+  for (const key of ['state', 'taskClass', 'evaluatedAt']) {
+    if (typeof record[key] !== 'string' || record[key] === '') return `no ${key}`;
+  }
+  const at = Date.parse(record.evaluatedAt);
+  if (Number.isNaN(at)) return `evaluatedAt '${record.evaluatedAt}' is not a time`;
+  if (at > now.getTime()) return `evaluated at ${record.evaluatedAt}, after this check at ${now.toISOString()}`;
+  return null;
+}
+
+/**
+ * Whether the task holds a READY record of `template` made no later than `now`.
+ * @param {Object} options
+ * @param {string} options.stateRoot
+ * @param {string} options.taskId
+ * @param {string|null} [options.slug] the task's feature slug: the record's namespace, and named in
+ *   the next command when its folder exists here or in the main checkout
+ * @param {string} options.template
+ * @param {Date} [options.now]
+ * @param {Function} [options.exec]
+ * @returns {{ok: boolean, code: 'ready'|'missing'|'not-ready'|'wrong-template'|'unusable'|'ambiguous',
+ *   record: Object|null, file: string|null, origin: string|null, candidates: Array<string>,
+ *   detail: string|null, nextSlug: string|null, message: string|null}}
+ */
+function checkReadiness({ stateRoot, taskId, slug = null, template, now = new Date(), exec }     ) {
+  const read = readReadinessRecord({ stateRoot, taskId, slug, exec });
+  const newerVersion = read.status === 'found' ? newerVersionOf(read.record) : null;
+  const nextSlug = nextSlugFor({ stateRoot, taskId, slug, exec });
+  const result = (code     , detail      = null) => ({
+    ok: code === 'ready',
+    code,
+    record: read.record,
+    file: read.file,
+    origin: read.origin,
+    candidates: read.candidates,
+    detail,
+    newerVersion,
+    nextSlug,
+    message: code === 'ready' ? null : refusalText(code, {
+      taskId, slug: nextSlug, template, record: read.record, candidates: read.candidates, detail, file: read.file, newerVersion,
+    }),
+  });
+  if (read.status === 'ambiguous') return result('ambiguous');
+  if (read.status === 'missing') return result('missing');
+  const detail = read.status === 'unreadable' ? read.detail : unusableDetail(read.record, now);
+  if (detail) return result('unusable', detail);
+  if (read.record.state !== 'READY') return result('not-ready');
+  if (read.record.taskClass !== template) return result('wrong-template');
+  return result('ready');
+}
+
+/**
+ * `verify`'s readiness check: whether a run for the task, or for its feature slug, is open with its
+ * gated stage pending, and if so whether a READY record exists. Reads only.
+ * @param {Object} options
+ * @param {string} options.stateRoot
+ * @param {string} options.taskId
+ * @param {string|null} [options.slug] the feature slug, for a run keyed by it and for the record's namespace
+ * @param {Date} [options.now]
+ * @param {Function} [options.exec]
+ * @returns {Object} `{applies: false, reason}` or `{applies: true, runTaskId, stage, template, ok, code,
+ *   record, message}`
+ */
+function verifyReadinessCheck({ stateRoot, taskId, slug = null, now = new Date(), exec }     ) {
+  let found = findRunFile({ stateRoot, taskId, slug, exec });
+  if (found.status === 'missing' && slug && slug !== taskId) found = findRunFile({ stateRoot, taskId: slug, slug, exec });
+  if (found.status === 'ambiguous') {
+    return {
+      applies: true, runTaskId: null, stage: null, template: null, ok: false, code: 'ambiguous', record: null,
+      message: refusalText('ambiguous-run', { taskId, candidates: found.candidates }),
+    };
+  }
+  if (found.status === 'missing') return { applies: false, reason: 'no-run' };
+  const run = readTaskState(fs, found.file);
+  if (run.state === 'COMPLETED' || run.state === 'REJECTED') return { applies: false, reason: 'run-finished' };
+  const stageNodes = (run.program || []).filter((n     ) => n.type === 'stage');
+  const stage = gatedStage(stageNodes);
+  if (!stage) return { applies: false, reason: 'no-gated-stage' };
+  const node = stageNodes.find((n     ) => n.id === stage.id);
+  if (node.status === 'completed' || node.status === 'skipped') return { applies: false, reason: 'gated-stage-done' };
+
+  const template = stage.readinessTemplate;
+  const check = checkReadiness({ stateRoot, taskId: run.taskId, slug, template, now, exec });
+  return {
+    applies: true,
+    runTaskId: run.taskId,
+    stage: stage.id,
+    template,
+    ok: check.ok,
+    code: check.code,
+    record: check.record ? {
+      file: check.file, origin: check.origin, state: check.record.state ?? null, taskClass: check.record.taskClass ?? null, evaluatedAt: check.record.evaluatedAt ?? null,
+    } : null,
+    message: check.message,
+  };
+}
+
+module.exports = {
+  gatedStage,
+  heldClasses,
+  refusalText,
+  harnessHookNote,
+  checkReadiness,
+  verifyReadinessCheck,
+  featureSlugFor,
+  runSlugOf,
+  findRunFile,
+};