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

package/src/runtime/failure/cli.js

@@ -0,0 +1,178 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * The `failure` verb (IC-019): `list`, `settle` and `capture` over the machine-wide failure store
+ * (IC-011 to IC-015). The store is per machine, so the verb ignores `-g` and works from any
+ * directory; only `settle --as imported` looks at the project, and only to find the DoFlow
+ * repository's follow-up store (IC-001 root). `--json` prints the result object unmodified; exit 0 =
+ * answered or written, 1 = a refusal, 2 = usage. A refusal is returned, never thrown, so it cannot
+ * reach failure capture (NFR-005).
+ */
+
+const fs = require('node:fs');
+const { finishRuntime, usageError } = require('../cli-result.js');
+const { maskLine, printSafe } = require('../mask.js');
+const { failureHome, captureSwitch, sentinelPath } = require('./home.js');
+const { rotateIfDue } = require('./capture.js');
+const store = require('./store.js');
+const { projectRoot } = require('../lifecycle/root.js');
+const { appendEvents, readFold, randomChars, StoreUnsafeError, StoreLockedError } = require('../lifecycle/event-store.js');
+const { prepareStore } = require('../lifecycle/store-upkeep.js');
+
+const ACTIONS = ['list', 'settle', 'capture'];
+const STATEMENT_MAX = 280;
+const FP = /^[0-9a-f]{16}$/;
+const CONTROL = /[\u0000-\u001F\u007F-\u009F\u2028\u2029\u202A-\u202E\u2066-\u2069]/g;
+
+/** A caller mistake (exit 2). */
+class FailureUsageError extends Error {}
+
+const refusal = (action        , finding        , message        ) => ({ ok: false, action, finding, message });
+
+/** A one-line reason, masked like any other free text, or null when none was given. */
+function cleanReason(raw     )                {
+  if (raw === undefined) return null;
+  const rawLength = String(raw).length;
+  if (rawLength > STATEMENT_MAX * 4) throw new FailureUsageError(`--reason is ${rawLength} characters; the limit is ${STATEMENT_MAX}`);
+  const text = maskLine(raw).text.trim();
+  if (text === '') throw new FailureUsageError('--reason is empty');
+  if (/[\r\n\u2028\u2029\u0085]/.test(text)) throw new FailureUsageError('--reason must be one line');
+  if (text.length > STATEMENT_MAX) throw new FailureUsageError(`--reason is ${text.length} characters; the limit is ${STATEMENT_MAX}`);
+  return text;
+}
+
+/** `DoFlow <command> <kind>: <message>`, built only from stored fields, masked and cut to 280 characters. */
+function importedStatement(entry     )         {
+  const raw = `DoFlow ${entry.command} ${entry.kind}${entry.message ? `: ${entry.message}` : ''}`;
+  return maskLine(raw.replace(CONTROL, ' ')).text.replace(/\s+/g, ' ').trim().slice(0, STATEMENT_MAX);
+}
+
+// ── list ───────────────────────────────────────────────────────────────────────────────────────
+
+function listFailures({ all = false, env = process.env } = {})      {
+  const home = failureHome(env);
+  if (home) rotateIfDue(home);
+  const loaded = store.loadEntries({ env });
+  const shown = loaded.entries.filter((entry     ) => all || store.SHOWN_BY_DEFAULT.has(entry.status)).map(store.listedEntry);
+  const result      = { ok: true, action: 'list', capture: loaded.capture };
+  if (loaded.home === null) result.home = null;
+  result.entries = shown;
+  result.counts = loaded.counts;
+  result.skippedLines = loaded.skippedLines;
+  result.unreadable = loaded.unreadable;
+  result.next = shown.length
+    ? ['Settle each entry: doflow-run failure --action settle --fp <fp> --as noise|fixed|imported --reason "<why>"']
+    : [];
+  return result;
+}
+
+// ── settle ─────────────────────────────────────────────────────────────────────────────────────
+
+function settleFailure({ fp, as, reason, cwd, env = process.env, now = new Date() }     )      {
+  if (typeof fp !== 'string' || !FP.test(fp)) throw new FailureUsageError('--fp is required: the 16 hex characters of an entry from `failure --action list`');
+  if (!store.SETTLE_AS.includes(as)) throw new FailureUsageError(`--as must be one of ${store.SETTLE_AS.join(', ')}${as ? ` (got '${as}')` : ''}`);
+  const cleaned = cleanReason(reason);
+  if ((as === 'noise' || as === 'fixed') && cleaned === null) throw new FailureUsageError(`--reason is required for --as ${as}`);
+  const home = failureHome(env);
+  if (home === null) return { ok: true, action: 'settle', home: null, entries: [], next: [] };
+
+  let root = null;
+  if (as === 'imported') {
+    root = projectRoot(cwd || process.cwd());
+    if (!store.isDoflowRepo(root)) {
+      return refusal('settle', 'not-doflow-repo', `${root} is not the DoFlow repository (its package.json is not named @khoavu882/doflow), so a failure cannot be imported as a follow-up here. Nothing was written.`);
+    }
+    const prepared = prepareStore(root);
+    for (const text of prepared.lines) console.error(printSafe(`doflow failure: ${text}`));
+    if (!prepared.ok) return refusal('settle', prepared.finding, prepared.message);
+  }
+  const entry = store.loadEntries({ env }).entries.find((e     ) => e.fp === fp);
+  if (!entry) return refusal('settle', 'unknown-fp', `${fp} is not a failure entry on this machine; list them with doflow-run failure --action list. Nothing was written.`);
+
+  if (as !== 'imported') {
+    store.appendSettlement(home, { fp, as, reason: cleaned, now });
+    return { ok: true, action: 'settle', fp, as, reason: cleaned, followup: null };
+  }
+  // Deduplicated on the project's own follow-ups, whatever the settlements say: a follow-up that
+  // already comes from this fingerprint is never created twice, even after a noise or fixed settlement.
+  const followups = readFold(root, { now }).followups;
+  const existing = followups.find((f     ) => f.source && f.source.kind === 'failure' && f.source.ref === fp);
+  if (existing) return refusal('settle', 'already-imported', `${fp} was already imported as ${existing.id}. Nothing was written.`);
+  const taken = new Set(followups.map((f     ) => f.id));
+  let id        ;
+  do { id = `FU-${randomChars(6)}`; } while (taken.has(id));
+  const statement = importedStatement(entry);
+  const source = { kind: 'failure', ref: fp };
+  // The settlement goes first: if the follow-up write then fails, a retry finds no follow-up in the
+  // project and creates exactly one, so a failure between the two steps can never duplicate it.
+  store.appendSettlement(home, { fp, as, reason: cleaned, followup: id, now });
+  const out = appendEvents(root, [{ type: 'followup.added', by: 'agent', data: { id, statement, source } }], { now });
+  if (!out.ok) return refusal('settle', out.finding, `${out.message} The settlement was recorded without a follow-up; run the same command again.`);
+  return {
+    ok: true, action: 'settle', fp, as,
+    followup: { id, statement, source, state: 'open' },
+    events: out.written.map((w     ) => w.file),
+  };
+}
+
+// ── capture ────────────────────────────────────────────────────────────────────────────────────
+
+function captureState({ set, env = process.env, now = new Date() }      = {})      {
+  if (set !== undefined && set !== 'on' && set !== 'off') throw new FailureUsageError(`--set must be on or off (got '${set}')`);
+  const home = failureHome(env);
+  if (home !== null && set === 'off') {
+    fs.mkdirSync(home, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(sentinelPath(home), `${now.toISOString()}\n`, { mode: 0o600 });
+  } else if (home !== null && set === 'on') {
+    fs.rmSync(sentinelPath(home), { force: true });
+  }
+  const state = captureSwitch(home, env);
+  // With no failure home nothing is captured, whatever the switch says.
+  const result      = { ok: true, action: 'capture', effective: home === null ? 'off' : state.effective, sentinel: state.sentinel, env: state.env };
+  if (home === null) result.home = null;
+  return result;
+}
+
+// ── verb ───────────────────────────────────────────────────────────────────────────────────────
+
+function lines(result     )           {
+  if (result.home === null) return ['home: none (capture skipped)', 'capture: off'];
+  if (result.action === 'list') {
+    const out = [`capture ${result.capture}: ${result.entries.length} entr${result.entries.length === 1 ? 'y' : 'ies'} listed (new ${result.counts.new}, regressed ${result.counts.regressed}, noise ${result.counts.noise}, fixed ${result.counts.fixed}, imported ${result.counts.imported})`];
+    for (const e of result.entries) out.push(`${e.fp}  ${e.status}  x${e.count}  ${e.command} ${e.kind}${e.message ? `: ${e.message}` : ''}  (last seen ${e.lastSeen}, ${e.lastVersion})`);
+    if (result.unreadable.length) out.push(`unreadable failure files (not read): ${result.unreadable.join(', ')}`);
+    if (result.skippedLines) out.push(`${result.skippedLines} unreadable line${result.skippedLines === 1 ? '' : 's'} skipped`);
+    return [...out, ...result.next.map((n        ) => `next: ${n}`)];
+  }
+  if (result.action === 'settle') return [`${result.fp} settled as ${result.as}${result.followup ? `, follow-up ${result.followup.id}` : ''}`];
+  return [`capture ${result.effective}${result.sentinel ? ' (switched off on this machine)' : ''}${result.env ? ` (DOFLOW_FAILURE_CAPTURE=${result.env})` : ''}`];
+}
+
+/**
+ * @param {Object} options
+ * @param {string} [options.action] absent when --action was not given
+ * @param {string} [options.cwd] where `settle --as imported` looks for the DoFlow repository
+ * @param {boolean} [options.all] `list`: every status, not just new and regressed
+ * @param {Object} [options.flags] fp, as, reason, set
+ */
+function handleFailureCommand({ action, cwd, json = false, all = false, flags = {} }      = {})      {
+  let result     ;
+  try {
+    if (!ACTIONS.includes(action)) throw new FailureUsageError(`--action is required: one of ${ACTIONS.join(', ')}${action ? ` (got '${action}')` : ''}`);
+    if (action === 'list') result = listFailures({ all });
+    else if (action === 'settle') result = settleFailure({ fp: (flags       ).fp, as: (flags       ).as, reason: (flags       ).reason, cwd });
+    else result = captureState({ set: (flags       ).set });
+  } catch (error) {
+    if (error instanceof FailureUsageError || error instanceof StoreUnsafeError) return usageError('failure', (error         ).message, json);
+    if (!(error instanceof StoreLockedError)) throw error;
+    result = refusal(action, 'store-locked', (error         ).message);
+  }
+  if (json) console.log(JSON.stringify(result, null, 2));
+  else if (result.ok === false) console.log(printSafe(`${result.finding}: ${result.message}`));
+  else for (const line of lines(result)) console.log(printSafe(line));
+  return finishRuntime(result.ok === false ? 1 : 0);
+}
+
+module.exports = { handleFailureCommand, listFailures, settleFailure, captureState, importedStatement, ACTIONS };

package/src/runtime/failure/home.js

@@ -0,0 +1,64 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * Where DoFlow's own failures are kept on this machine, and whether capture is on (IC-011, IC-014).
+ * One folder per machine, shared by every project (DEC-007). Node and the bash writers resolve the
+ * home the same way, so a failure captured by either lands in the one list: `XDG_CONFIG_HOME` when it
+ * is set, non-empty and absolute, else `$HOME/.config` when `HOME` is set and absolute. Node reads the
+ * `HOME` variable and not `os.homedir()`, so both sides agree. A relative or missing base means
+ * there is no home, and capture is skipped.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const OFF_VALUES = new Set(['off', '0', 'false', 'no']);
+
+/** @param {Object} [env] defaults to process.env
+ * @returns {string|null} the failure home, an absolute path, or null when none can be resolved */
+function failureHome(env      = process.env)                {
+  const xdg = env.XDG_CONFIG_HOME;
+  if (typeof xdg === 'string' && xdg !== '') {
+    return path.isAbsolute(xdg) ? path.join(xdg, 'doflow', 'failures') : null;
+  }
+  const home = env.HOME;
+  if (typeof home === 'string' && path.isAbsolute(home)) return path.join(home, '.config', 'doflow', 'failures');
+  return null;
+}
+
+const sentinelPath = (home        )         => path.join(home, 'off');
+const eventsPath = (home        )         => path.join(home, 'events.jsonl');
+
+/** The value of `DOFLOW_FAILURE_CAPTURE` when it is set to anything, else null. */
+function envSetting(env      = process.env)                {
+  const raw = env.DOFLOW_FAILURE_CAPTURE;
+  return typeof raw === 'string' && raw !== '' ? raw : null;
+}
+
+/**
+ * The capture switch (IC-014). The sentinel file wins over everything and the environment can only
+ * turn capture off, never on over a sentinel. One `stat`, no folder created.
+ * @param {string|null} home
+ * @param {Object} [env]
+ * @returns {{effective: 'on'|'off', sentinel: boolean, env: string|null}}
+ */
+function captureSwitch(home               , env      = process.env)                                                                     {
+  let sentinel = false;
+  if (home) {
+    try { sentinel = fs.statSync(sentinelPath(home)).isFile(); } catch { sentinel = false; }
+  }
+  const setting = envSetting(env);
+  const envOff = setting !== null && OFF_VALUES.has(setting.trim().toLowerCase());
+  return { effective: sentinel || envOff ? 'off' : 'on', sentinel, env: setting };
+}
+
+/** The hot-path check a writer makes: the environment first, then one `stat` of the sentinel. */
+function captureIsOff(home        , env      = process.env)          {
+  const setting = envSetting(env);
+  if (setting !== null && OFF_VALUES.has(setting.trim().toLowerCase())) return true;
+  try { return fs.statSync(sentinelPath(home)).isFile(); } catch { return false; }
+}
+
+module.exports = { failureHome, captureSwitch, captureIsOff, sentinelPath, eventsPath, envSetting };

package/src/runtime/failure/store.js

@@ -0,0 +1,226 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * The failure store reader and settlement writer (IC-013, IC-014, IC-015). The capture writers append
+ * IC-011 lines; this module folds them into entries when they are asked for, so a count is always
+ * derived from the retained events and only a settlement is stored separately (DEC-019).
+ *
+ *   - `fp` is computed here, never by a writer: the first 16 hex characters of SHA-256 over
+ *     `source \n command \n kind \n message \n frame` (an absent frame is the empty string). The
+ *     version is not part of it, so the same bug in two releases is one entry.
+ *   - The latest settlement per `fp` applies. A `fixed` entry that is seen again is `regressed`.
+ *   - A line that does not parse, or is not an IC-011 line, is skipped and counted.
+ *   - Reading never writes. Rotation is the `failure` verb's own step before it reads (see cli.js).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { failureHome, captureSwitch, eventsPath } = require('./home.js');
+const { printSafe } = require('../mask.js');
+
+const ROTATED = /^events-\d{8}T\d{6}Z-\d+\.jsonl$/;
+const SETTLEMENTS = 'settlements.jsonl';
+const SOURCES = new Set(['cli', 'dispatcher', 'hook']);
+const SETTLE_AS = ['noise', 'fixed', 'imported'];
+const STATUSES = ['new', 'regressed', 'noise', 'fixed', 'imported'];
+const SHOWN_BY_DEFAULT = new Set(['new', 'regressed']);
+const PROJECTS_KEPT = 5;
+
+const settlementsPath = (home        )         => path.join(home, SETTLEMENTS);
+
+/** @param {{source: string, command: string, kind: string, message: string, frame: string|null}} event */
+function fingerprint(event     )         {
+  const text = [event.source, event.command, event.kind, event.message, event.frame || ''].join('\n');
+  return crypto.createHash('sha256').update(text).digest('hex').slice(0, 16);
+}
+
+/** One IC-011 line, or null. Only the fields a fold reads are checked. */
+function asEvent(value     )      {
+  if (!value || typeof value !== 'object' || value.v !== 1) return null;
+  const text = (x     ) => typeof x === 'string';
+  if (!text(value.at) || !SOURCES.has(value.source) || !text(value.command) || !text(value.kind)) return null;
+  return {
+    at: value.at,
+    source: value.source,
+    command: value.command,
+    harness: text(value.harness) ? value.harness : 'none',
+    version: text(value.version) ? value.version : 'unknown',
+    project: text(value.project) ? value.project : '',
+    kind: value.kind,
+    message: text(value.message) ? value.message : '',
+    frame: text(value.frame) ? value.frame : null,
+    exit: Number.isInteger(value.exit) ? value.exit : null,
+  };
+}
+
+/**
+ * Parses a JSON-lines file into `{rows, skipped, unreadable}`. A missing file is empty. A file that is
+ * not a regular file (a FIFO would block the read, a device never ends, a symlink may leave the folder)
+ * or cannot be read is `unreadable`, and nothing is read from it.
+ */
+function readLines(file        , accept                 )                                                        {
+  const c = fs.constants;
+  let text        ;
+  let fd                    ;
+  try {
+    fd = fs.openSync(file, c.O_RDONLY | (c.O_NOFOLLOW || 0) | (c.O_NONBLOCK || 0));
+    if (!fs.fstatSync(fd).isFile()) return { rows: [], skipped: 0, unreadable: true };
+    text = fs.readFileSync(fd, 'utf8');
+  } catch (error     ) {
+    return { rows: [], skipped: 0, unreadable: error.code !== 'ENOENT' };
+  } finally {
+    if (fd !== undefined) { try { fs.closeSync(fd); } catch { /* read already done */ } }
+  }
+  const rows        = [];
+  let skipped = 0;
+  for (const line of text.split('\n')) {
+    if (line.trim() === '') continue;
+    let row = null;
+    try { row = accept(JSON.parse(line)); } catch { row = null; }
+    if (row) rows.push(row); else skipped += 1;
+  }
+  return { rows, skipped, unreadable: false };
+}
+
+/**
+ * Every retained event: rotated files oldest first, then the live file (IC-015).
+ * @param {string} home
+ * @returns {{events: Object[], skippedLines: number, unreadable: string[]}} `unreadable` names the files that were not read
+ */
+function readEvents(home        )                                                                {
+  let rotated           = [];
+  try { rotated = fs.readdirSync(home).filter((name        ) => ROTATED.test(name)).sort(); } catch { /* no folder yet */ }
+  const events        = [];
+  let skippedLines = 0;
+  const unreadable           = [];
+  for (const file of [...rotated.map((name        ) => path.join(home, name)), eventsPath(home)]) {
+    const read = readLines(file, asEvent);
+    events.push(...read.rows);
+    skippedLines += read.skipped;
+    if (read.unreadable) unreadable.push(path.basename(file));
+  }
+  return { events, skippedLines, unreadable };
+}
+
+function asSettlement(value     )      {
+  if (!value || typeof value !== 'object' || value.v !== 1) return null;
+  if (typeof value.at !== 'string' || !/^[0-9a-f]{16}$/.test(value.fp) || !SETTLE_AS.includes(value.as)) return null;
+  return { at: value.at, fp: value.fp, as: value.as, reason: typeof value.reason === 'string' ? value.reason : null, followup: typeof value.followup === 'string' ? value.followup : null };
+}
+
+/** @returns {{settlements: Object[], skippedLines: number, unreadable: string[]}} in file order, which is time order */
+function readSettlements(home        )                                                                     {
+  const read = readLines(settlementsPath(home), asSettlement);
+  return { settlements: read.rows, skippedLines: read.skipped, unreadable: read.unreadable ? [SETTLEMENTS] : [] };
+}
+
+/** The IC-013 status of an entry from its latest settlement and the events seen after it. */
+function statusOf(settlement     , sinceSettlement        )         {
+  if (!settlement) return 'new';
+  if (settlement.as === 'fixed') return sinceSettlement > 0 ? 'regressed' : 'fixed';
+  return settlement.as;
+}
+
+/**
+ * Folds events and settlements into IC-013 entries, newest `lastSeen` first.
+ * @param {Object[]} events
+ * @param {Object[]} settlements
+ * @returns {Object[]}
+ */
+function foldEntries(events       , settlements       )        {
+  const latest = new Map();
+  for (const s of settlements) latest.set(s.fp, s);
+  const groups = new Map();
+  for (const event of events) {
+    const fp = fingerprint(event);
+    if (!groups.has(fp)) groups.set(fp, []);
+    groups.get(fp).push(event);
+  }
+  const entries        = [];
+  for (const [fp, group] of groups) {
+    const ordered = (group         ).map((event     , index        ) => ({ event, index })).sort((a     , b     ) => (a.event.at < b.event.at ? -1 : a.event.at > b.event.at ? 1 : a.index - b.index)).map((x     ) => x.event);
+    const first = ordered[0];
+    const last = ordered[ordered.length - 1];
+    const settlement = latest.get(fp) || null;
+    const since = settlement ? ordered.filter((e     ) => e.at > settlement.at).length : ordered.length;
+    const projects           = [];
+    for (let i = ordered.length - 1; i >= 0 && projects.length < PROJECTS_KEPT; i--) {
+      if (ordered[i].project && !projects.includes(ordered[i].project)) projects.push(ordered[i].project);
+    }
+    // The file is machine-wide and may hold lines someone else wrote: the fingerprint is taken over the
+    // stored text, and every string an entry shows is made print-safe, so a listing and --json never carry
+    // a terminal escape.
+    entries.push(printSafe({
+      fp,
+      status: statusOf(settlement, since),
+      count: ordered.length,
+      sinceSettlement: since,
+      firstSeen: first.at,
+      lastSeen: last.at,
+      firstVersion: first.version,
+      lastVersion: last.version,
+      source: first.source,
+      command: first.command,
+      kind: first.kind,
+      message: first.message,
+      frame: first.frame,
+      projects,
+      harnesses: [...new Set(ordered.map((e     ) => e.harness))].sort(),
+      exitCodes: [...new Set(ordered.map((e     ) => e.exit).filter((x     ) => x !== null))].sort((a     , b     ) => a - b),
+      settlement: settlement && { as: settlement.as, at: settlement.at, reason: settlement.reason, followup: settlement.followup },
+    }));
+  }
+  return entries.sort((a     , b     ) => (a.lastSeen < b.lastSeen ? 1 : a.lastSeen > b.lastSeen ? -1 : a.fp < b.fp ? -1 : 1));
+}
+
+/** The shape a listing shows (IC-019). */
+function listedEntry(entry     )      {
+  return {
+    fp: entry.fp, status: entry.status, count: entry.count, command: entry.command, kind: entry.kind,
+    message: entry.message, lastSeen: entry.lastSeen, lastVersion: entry.lastVersion,
+  };
+}
+
+/**
+ * Reads the store and folds it. With no resolvable failure home nothing is read.
+ * @param {Object} [options]
+ * @param {Object} [options.env] defaults to process.env
+ * @returns {{home: string|null, capture: 'on'|'off', entries: Object[], counts: Object, skippedLines: number, unreadable: string[]}}
+ */
+function loadEntries({ env = process.env } = {})      {
+  const home = failureHome(env);
+  const counts = Object.fromEntries(STATUSES.map((status) => [status, 0]));
+  // With no failure home nothing is captured, whatever the switch says.
+  if (!home) return { home: null, capture: 'off', entries: [], counts, skippedLines: 0, unreadable: [] };
+  const { events, skippedLines: eventSkips, unreadable: eventFiles } = readEvents(home);
+  const { settlements, skippedLines: settlementSkips, unreadable: settlementFiles } = readSettlements(home);
+  const entries = foldEntries(events, settlements);
+  for (const entry of entries) counts[entry.status] += 1;
+  return { home, capture: captureSwitch(home, env).effective, entries, counts, skippedLines: eventSkips + settlementSkips, unreadable: [...eventFiles, ...settlementFiles] };
+}
+
+/**
+ * Appends one settlement line (IC-013). Only `failure --action settle` calls this.
+ * @param {string} home
+ * @param {{fp: string, as: string, reason?: string|null, followup?: string|null, now?: Date}} settlement
+ */
+function appendSettlement(home        , { fp, as, reason = null, followup = null, now = new Date() }     )       {
+  fs.mkdirSync(home, { recursive: true, mode: 0o700 });
+  const line = JSON.stringify({ v: 1, at: now.toISOString(), fp, as, reason, followup });
+  fs.appendFileSync(settlementsPath(home), `${line}\n`, { flag: 'a', mode: 0o600 });
+}
+
+const DOFLOW_PACKAGE = '@khoavu882/doflow';
+
+/** Whether `root` is the DoFlow repository itself: its `package.json` is named `@khoavu882/doflow`. */
+function isDoflowRepo(root        )          {
+  try { return JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).name === DOFLOW_PACKAGE; } catch { return false; }
+}
+
+module.exports = {
+  isDoflowRepo, fingerprint, readEvents, readSettlements, foldEntries, listedEntry, loadEntries, appendSettlement,
+  settlementsPath, SETTLE_AS, STATUSES, SHOWN_BY_DEFAULT,
+};

package/src/runtime/feature-resolve.js

@@ -0,0 +1,79 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { resolveBashHelper } = require('../helper/bash-helper.js');
+
+// `resolveActiveFeature` was moved here from `scaffold/generate.js` (which had it from
+// bin/doflow.js) so the scaffold and the decision register ask the same resolver. The root comes
+// from src/helper/repo-root.js rather than from counting this file's own depth: this code has
+// already moved twice, and a miscounted expression would keep resolving, to the wrong directory.
+
+/** The one resolver: beside this module in a checkout, a project `node_modules/` and a global npm install,
+ *  else the copy projected next to an installed runtime (an installed runtime carries no `core/shared`). */
+const PATHS_HELPER = resolveBashHelper('do-paths.sh');
+
+/**
+ * Which feature is active, answered by `do-paths.sh` rather than by walking `agent-docs/` here.
+ *
+ * Every other consumer of "the active feature" — every chain skill, the prerequisite gate, the
+ * artifact validator — asks this script. A second implementation would disagree with them the
+ * first time branch naming, the non-git directory-scan fallback or `--slug` disambiguation came
+ * up, and it would disagree silently, because a scaffold generated for the wrong feature still
+ * looks like a scaffold.
+ *
+ * @param {Object} options
+ * @param {string} options.projectRoot working directory the resolution is relative to
+ * @param {string|null} [options.slug] explicit feature override, passed straight through
+ * @returns {{repoRoot:string, featureDir:string, paths:Object}|{error:string, message:string}}
+ *   `paths` is the resolver's own parsed JSON (repo-root-relative artifact paths and has_* flags),
+ *   so a caller needs no second resolver call.
+ */
+function resolveActiveFeature({ projectRoot, slug = null }                                               )      {
+  const helper = resolveBashHelper('do-paths.sh');
+  if (!helper) {
+    return { error: 'resolver-missing', message: 'the feature resolver (do-paths.sh) is missing from this install' };
+  }
+  const args           = [helper, '--json', '--require', 'feature'];
+  if (slug) args.push(`--slug=${slug}`);
+
+  let stdout        ;
+  try {
+    stdout = execFileSync('bash', args, { cwd: projectRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  } catch (error     ) {
+    // Exit 2 is the resolver's one non-zero path (no active feature, or an ambiguous one) and it
+    // still prints its error object on stdout — that object carries the hint the user needs, so
+    // it is read rather than replaced with a generic message. Anything else (no bash, NFR-003)
+    // has no stdout to read and reports the spawn failure instead.
+    stdout = typeof error.stdout === 'string' ? error.stdout : '';
+    if (!stdout.trim()) {
+      const detail = error.code === 'ENOENT'
+        ? 'bash is required to resolve the active feature and was not found on PATH'
+        : (error.stderr || error.message || '').toString().trim();
+      return { error: 'resolver-failed', message: `could not run the feature resolver: ${detail}` };
+    }
+  }
+
+  let paths     ;
+  try {
+    paths = JSON.parse(stdout);
+  } catch {
+    return { error: 'resolver-unparseable', message: `the feature resolver returned output that is not JSON: ${stdout.trim().slice(0, 200)}` };
+  }
+
+  if (paths.error) {
+    const hint = paths.hint ? ` — ${paths.hint}` : '';
+    const candidates = Array.isArray(paths.candidate_slugs) && paths.candidate_slugs.length
+      ? ` (candidates: ${paths.candidate_slugs.join(', ')})`
+      : '';
+    return { error: paths.error, message: `${paths.error}${candidates}${hint}` };
+  }
+  if (!paths.repo_root || !paths.feature_dir) {
+    return { error: 'no-active-feature', message: 'the resolver named no active feature directory to scaffold' };
+  }
+  return { repoRoot: paths.repo_root, featureDir: path.resolve(paths.repo_root, paths.feature_dir), paths };
+}
+
+module.exports = { resolveActiveFeature, PATHS_HELPER };