forge-workflow 0.0.10 → 0.1.0-beta.2

package/lib/upgrade-safety.js

@@ -0,0 +1,199 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { lintRuntimeGraphConfig } = require('./core/runtime-graph');
+const { resolvePatchIntentRecords } = require('./patch-intent');
+const { verifyForgeLock, readForgeLock } = require('./forge-lock');
+
+function checkStatus(ok) {
+  return ok ? 'pass' : 'fail';
+}
+
+function countUntrustedOptIns(lock) {
+  return lock.extensions.filter(entry => entry.trust?.allowUntrusted === true).length;
+}
+
+function buildPatchIntentSummary(projectRoot) {
+  try {
+    const status = resolvePatchIntentRecords(projectRoot);
+    return {
+      ok: status.orphans.length === 0,
+      path: status.path,
+      records: status.records.length,
+      orphans: status.orphans.length,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      path: '.forge/patch.md',
+      records: 0,
+      orphans: 0,
+      error: error.message,
+    };
+  }
+}
+
+function buildSelfHealCandidates(projectRoot) {
+  const forgeDir = path.join(projectRoot, '.forge');
+  const logPath = path.join(forgeDir, 'log.jsonl');
+  const candidates = [];
+  if (!fs.existsSync(forgeDir)) {
+    candidates.push({
+      id: 'forge-dir',
+      path: '.forge/',
+      description: 'Create missing Forge metadata directory',
+    });
+  }
+  if (!fs.existsSync(logPath)) {
+    candidates.push({
+      id: 'audit-log',
+      path: '.forge/log.jsonl',
+      description: 'Create missing Forge audit log file',
+    });
+  }
+  return candidates;
+}
+
+function buildUpgradeDryRunReport(projectRoot = process.cwd()) {
+  const root = path.resolve(projectRoot);
+  const runtime = lintRuntimeGraphConfig({ projectRoot: root });
+  const patchIntent = buildPatchIntentSummary(root);
+  const lockReport = verifyForgeLock(root);
+  const lock = readForgeLock(root);
+  const selfHealCandidates = buildSelfHealCandidates(root);
+  const failedLockEntries = lockReport.results.filter(result => result.status === 'fail');
+  const untrustedOptIns = countUntrustedOptIns(lock);
+  const lockTrustOk = lockReport.ok && untrustedOptIns === 0;
+
+  return {
+    ok: runtime.ok && patchIntent.ok && lockTrustOk,
+    projectRoot: root,
+    runtime,
+    patchIntent,
+    lock,
+    lockReport,
+    lockTrustOk,
+    selfHealCandidates,
+    failedLockEntries,
+  };
+}
+
+function formatCheck(status, label, detail) {
+  return `[${status.toUpperCase()}] ${label}: ${detail}`;
+}
+
+function runtimeDetail(runtime) {
+  return runtime.ok
+    ? 'resolved runtime graph config'
+    : runtime.errors.map(error => error.message).join('; ');
+}
+
+function patchIntentDetail(patchIntent) {
+  return patchIntent.error
+    ? patchIntent.error
+    : `${patchIntent.records} record(s), ${patchIntent.orphans} orphan(s)`;
+}
+
+function readinessLines(report) {
+  const untrustedOptIns = countUntrustedOptIns(report.lock);
+  const lockStatus = report.lockTrustOk ? 'pass' : 'fail';
+  return [
+    formatCheck(checkStatus(report.runtime.ok), 'Runtime config', runtimeDetail(report.runtime)),
+    formatCheck(checkStatus(report.patchIntent.ok), 'Patch intent', patchIntentDetail(report.patchIntent)),
+    formatCheck(
+      lockStatus,
+      'Lock trust',
+      `${report.lock.extensions.length} extension(s), ${untrustedOptIns} untrusted opt-in${untrustedOptIns === 1 ? '' : 's'}`
+    ),
+    ...report.lockReport.results.map(result => formatCheck(result.status, result.name, result.reason)),
+  ];
+}
+
+function appendPlannedSelfHeal(lines, candidates) {
+  lines.push('', 'Planned self-heal');
+  if (candidates.length === 0) {
+    lines.push('No self-heal actions needed.');
+    return;
+  }
+  for (const candidate of candidates) {
+    lines.push(`- ${candidate.path}: ${candidate.description}`);
+  }
+}
+
+function appendSelfHealResult(lines, selfHealResult) {
+  if (!selfHealResult) return;
+  lines.push('', 'Self-heal result');
+  if (selfHealResult.refused) {
+    lines.push('Self-heal refused unrecoverable lock integrity failure.');
+    return;
+  }
+  if (selfHealResult.applied.length === 0) {
+    lines.push('No self-heal actions needed.');
+    return;
+  }
+  lines.push(`Self-heal applied ${selfHealResult.applied.length} action(s).`);
+  for (const action of selfHealResult.applied) {
+    lines.push(`- ${action.path}`);
+  }
+}
+
+function renderUpgradeDryRunReport(report, selfHealResult = null) {
+  const lines = [
+    'Forge upgrade dry-run',
+    `Target: ${report.projectRoot}`,
+    `Result: ${report.ok ? 'PASS' : 'FAIL'}`,
+    '',
+    'Readiness',
+    ...readinessLines(report),
+  ];
+
+  appendPlannedSelfHeal(lines, report.selfHealCandidates);
+  appendSelfHealResult(lines, selfHealResult);
+
+  lines.push(
+    '',
+    'Limitations',
+    'Non-scope: rollback snapshots and full restore are not implemented in this PR.',
+    'Remote/package source integrity is recorded as explicit trust policy only until a resolver can materialize bytes for SRI verification.'
+  );
+
+  return `${lines.join('\n')}\n`;
+}
+
+function applySelfHeal(projectRoot, report) {
+  if (report.failedLockEntries.length > 0) {
+    return {
+      refused: true,
+      applied: [],
+      reason: 'unrecoverable lock integrity failure',
+    };
+  }
+
+  const applied = [];
+  const forgeDir = path.join(projectRoot, '.forge');
+  const logPath = path.join(forgeDir, 'log.jsonl');
+
+  if (!fs.existsSync(forgeDir)) {
+    fs.mkdirSync(forgeDir, { recursive: true });
+    applied.push({ path: '.forge/' });
+  }
+
+  if (!fs.existsSync(logPath)) {
+    fs.writeFileSync(logPath, '', 'utf8');
+    applied.push({ path: '.forge/log.jsonl' });
+  }
+
+  return {
+    refused: false,
+    applied,
+  };
+}
+
+module.exports = {
+  applySelfHeal,
+  buildUpgradeDryRunReport,
+  buildSelfHealCandidates,
+  renderUpgradeDryRunReport,
+};

package/lib/workflow/enforce-stage.js

@@ -2,6 +2,7 @@
 
 const { repairWorkflowRuntimeAssets } = require('../commands/setup');
 const { checkRuntimeHealth } = require('../runtime-health');
+const { resolveIssueBackend } = require('../issue-backend');
 const { normalizeStageId } = require('./stages');
 const {
   getAllowedTransitionsForWorkflowState,
@@ -12,6 +13,171 @@ const { loadState, WORKFLOW_STATE_FILENAME } = require('./state-manager');
 
 const STATELESS_ENTRY_STAGES = new Set(['plan', 'dev', 'validate', 'verify']);
 
+const UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+
+// Canonical full-ladder path (critical superset). Used to derive a stage's
+// immediate predecessor for the kernel completion gate.
+const STAGE_PATH = Object.freeze(['plan', 'dev', 'validate', 'ship', 'review', 'verify']);
+
+function stagePredecessor(stageId) {
+  const index = STAGE_PATH.indexOf(stageId);
+  return index > 0 ? STAGE_PATH[index - 1] : null;
+}
+
+// Emit a warning to stderr. Writes even under FORGE_JSON=1 on purpose: stderr
+// never pollutes machine-readable stdout, and a dropped kernel write must always
+// leave a trace ("never silent") so a JSON-mode agent can see it.
+function defaultStageWarn(message) {
+  process.stderr.write(`${message}\n`);
+}
+
+// Best-effort kernel write (action 'start' | 'complete') at the stage
+// chokepoint. Idempotent per (issue_id, stage). A failure warns to stderr but
+// never throws — ship's gate stays tolerant of whatever IS durably recorded.
+function recordStageRunSafe(driver, issueId, stageId, action, warn = defaultStageWarn) {
+  if (!driver || !issueId || !stageId || typeof driver.recordStageRun !== 'function') {
+    return false;
+  }
+
+  try {
+    driver.recordStageRun({ issue_id: issueId, stage: stageId, action }, {});
+    return true;
+  } catch (error) {
+    warn(`[forge] could not record stage '${stageId}' (${action}) for ${issueId} in the kernel: ${error.message}`);
+    return false;
+  }
+}
+
+// Latest stage-run row for a specific (issue, stage), or null.
+function findLatestStageRun(driver, issueId, stage) {
+  if (!driver || typeof driver.listStageRuns !== 'function') {
+    return null;
+  }
+
+  try {
+    const runs = driver.listStageRuns({ issue_id: issueId }, {}) || [];
+    let latest = null;
+    for (const run of runs) {
+      if (run?.stage === stage) {
+        latest = run;
+      }
+    }
+    return latest;
+  } catch {
+    return null;
+  }
+}
+
+// Decide whether entering stageId is allowed given ONLY the kernel's recorded
+// stage history (used when no inline/file workflow state exists):
+//   - Stateless stages (plan/dev/validate/verify) are always re-entrant, so the
+//     dev<->validate rework loop never dead-ends.
+//   - A gated stage (ship/review) requires its immediate predecessor to be
+//     COMPLETED (status 'done'); merely ENTERING validate does not unlock ship.
+//   - When nothing is recorded for the predecessor, returns { kernelEmpty } so
+//     the caller falls through to the fail-closed hard block.
+function evaluateKernelStageGate(driver, issueId, stageId) {
+  if (STATELESS_ENTRY_STAGES.has(stageId)) {
+    return { allowed: true };
+  }
+
+  const predecessor = stagePredecessor(stageId);
+  const predecessorRun = predecessor ? findLatestStageRun(driver, issueId, predecessor) : null;
+  if (predecessorRun?.status === 'done') {
+    return { allowed: true };
+  }
+  if (predecessorRun) {
+    return {
+      allowed: false,
+      reason: `Stage ${stageId} requires ${predecessor} to be completed first (currently ${predecessorRun.status}).`,
+    };
+  }
+  return { allowed: false, kernelEmpty: true };
+}
+
+// Verify a kernel issue exists before binding stage state to it (F4a: a UUID
+// parsed from a branch name must not bind to a phantom issue).
+async function kernelIssueExists(driver, issueId) {
+  if (!driver || typeof driver.findIssueIdsByPrefix !== 'function') {
+    return false;
+  }
+
+  try {
+    // findIssueIdsByPrefix returns rows ({ id, title }); tolerate plain-id shapes too.
+    const matches = await driver.findIssueIdsByPrefix(issueId, 6, {}, {});
+    return Array.isArray(matches) && matches.some(row => (row?.id ?? row) === issueId);
+  } catch {
+    return false;
+  }
+}
+
+// Resolve the kernel issue that THIS worktree/branch is working on, so stage
+// state can be read and written without an explicit issue argument on `forge
+// ship`. Prefers the branch->issue linkage registry (authoritative); falls back
+// to a UUID encoded in the branch name, but ONLY after verifying it exists.
+async function resolveActiveIssueId(driver, branch) {
+  if (!driver || !branch) {
+    return null;
+  }
+
+  try {
+    if (typeof driver.listWorktrees === 'function') {
+      const rows = driver.listWorktrees() || [];
+      const match = rows.find(row => row && row.branch === branch && row.issue_id);
+      if (match) {
+        return match.issue_id;
+      }
+    }
+  } catch {
+    // Fall through to branch-name parsing.
+  }
+
+  const encoded = UUID_RE.exec(String(branch));
+  if (encoded && await kernelIssueExists(driver, encoded[0])) {
+    return encoded[0];
+  }
+  return null;
+}
+
+// Lazily build a kernel driver from the project root (the real CLI path).
+// Best-effort: returns null when the kernel is unavailable so the caller
+// degrades to legacy file/beads state instead of crashing a stage command.
+async function buildKernelDriver(projectRoot) {
+  if (!projectRoot) {
+    return null;
+  }
+
+  try {
+    const { buildMigratedKernelIssueDeps } = require('../kernel/cli-broker-factory');
+    const deps = await buildMigratedKernelIssueDeps({ projectRoot });
+    return deps.kernelDriver || null;
+  } catch {
+    return null;
+  }
+}
+
+function detectBranchName(projectRoot) {
+  try {
+    const { detectWorktree } = require('../detect-worktree');
+    const info = detectWorktree(projectRoot || process.cwd());
+    return info?.branch || null;
+  } catch {
+    return null;
+  }
+}
+
+// Resolve { driver, issueId } for kernel stage-state: build the driver from the
+// project root and resolve the active issue from the branch when not explicitly
+// injected. Best-effort — returns nulls when the kernel is absent.
+async function resolveKernelContext({ kernelDriver, activeIssueId, branch, projectRoot }) {
+  const driver = kernelDriver || await buildKernelDriver(projectRoot);
+  let issueId = activeIssueId || null;
+  if (driver && !issueId) {
+    issueId = await resolveActiveIssueId(driver, branch || detectBranchName(projectRoot));
+  }
+  return { driver, issueId };
+}
+
 function getOverrideInput(flags = {}) {
   if (Object.hasOwn(flags, 'overrideStage')) {
     return flags.overrideStage;
@@ -103,55 +269,18 @@ function formatDiagnostics(diagnostics = []) {
     .join('; ');
 }
 
-async function enforceStageEntry({ commandName, args = [], flags = {}, projectRoot, workflowState, health, repairRuntime } = {}) {
-  const stageId = normalizeStageId(commandName);
-  if (!stageId) {
-    return { allowed: true };
-  }
-
-  if (projectRoot) {
-    repairWorkflowRuntimeAssets(projectRoot);
-  }
-
-  let runtimeHealth = health || checkRuntimeHealth(projectRoot);
-  if (runtimeHealth.hardStop && typeof repairRuntime === 'function') {
-    const repairedHealth = await repairRuntime({
-      commandName,
-      flags,
-      projectRoot,
-      workflowState,
-      health: runtimeHealth,
-    });
-    if (repairedHealth) {
-      runtimeHealth = repairedHealth;
-    }
-  }
-  if (runtimeHealth.hardStop) {
-    throw new Error(`Stage ${stageId} blocked by runtime prerequisites: ${formatDiagnostics(runtimeHealth.diagnostics)}`);
-  }
-
-  const stateInput = resolveWorkflowStateInput(workflowState, flags, args, projectRoot);
-  const currentState = readWorkflowStateInput(stateInput);
-  if (!currentState) {
-    if (STATELESS_ENTRY_STAGES.has(stageId)) {
-      return { allowed: true, stage: stageId, workflowState: null };
-    }
-
-    throw new Error(
-      `Stage ${stageId} requires authoritative workflow state. ` +
-      `Provide --workflow-state or restore ${WORKFLOW_STATE_FILENAME} before continuing.`
-    );
-  }
-
+// Enforce a stage entry against authoritative FILE/inline workflow state
+// (unchanged legacy behavior: normal path-transition + override rules).
+function enforceWithFileState(currentState, stageId, flags, args, finish) {
   const currentStage = currentState.currentStage;
   const classification = currentState.workflowDecisions?.classification;
   if (!currentStage || !classification || stageId === currentStage) {
-    return { allowed: true, stage: stageId, workflowState: currentState };
+    return finish({ allowed: true, stage: stageId, workflowState: currentState });
   }
 
   const allowedTransitions = getAllowedTransitionsForWorkflowState(currentState);
   if (allowedTransitions.includes(stageId)) {
-    return { allowed: true, stage: stageId, workflowState: currentState };
+    return finish({ allowed: true, stage: stageId, workflowState: currentState });
   }
 
   const override = parseOverride(flags, args);
@@ -168,12 +297,128 @@ async function enforceStageEntry({ commandName, args = [], flags = {}, projectRo
     );
   }
 
-  return {
-    allowed: true,
-    stage: stageId,
-    workflowState: currentState,
-    override,
+  return finish({ allowed: true, stage: stageId, workflowState: currentState, override });
+}
+
+function isInlineStateProvided(workflowState, flags, args) {
+  return Boolean(
+    workflowState || flags.workflowState || flags['--workflow-state'] || getCliFlagValue('--workflow-state', args)
+  );
+}
+
+// Enforce a stage entry against kernel-recorded stage state (completion gate).
+// Returns a decided enforcement result, or null to fall through to the
+// stateless / hard-block rules.
+function enforceWithKernelState(driver, issueId, stageId, finish) {
+  const gate = evaluateKernelStageGate(driver, issueId, stageId);
+  if (gate.allowed) {
+    return finish({ allowed: true, stage: stageId, workflowState: null });
+  }
+  if (!gate.kernelEmpty) {
+    throw new Error(gate.reason);
+  }
+  return null;
+}
+
+async function resolveStageRuntimeHealth({ health, checkHealth, projectRoot, issueBackend, commandName, flags, workflowState, repairRuntime }) {
+  const runHealthCheck = checkHealth || checkRuntimeHealth;
+  let runtimeHealth = health || runHealthCheck(projectRoot, { issueBackend });
+  if (runtimeHealth.hardStop && typeof repairRuntime === 'function') {
+    const repaired = await repairRuntime({ commandName, flags, projectRoot, workflowState, health: runtimeHealth });
+    if (repaired) {
+      runtimeHealth = repaired;
+    }
+  }
+  return runtimeHealth;
+}
+
+async function enforceStageEntry({
+  commandName,
+  args = [],
+  flags = {},
+  projectRoot,
+  workflowState,
+  health,
+  repairRuntime,
+  checkHealth,
+  // B1 — kernel stage-state authority. Injectable for tests; the real CLI sets
+  // autoResolveKernel:true so the driver + active issue are resolved from the
+  // worktree. When neither a driver nor autoResolveKernel is provided, the
+  // kernel path is inert and behavior matches the legacy file/beads state.
+  kernelDriver,
+  activeIssueId,
+  branch,
+  autoResolveKernel = false,
+  warn = defaultStageWarn,
+} = {}) {
+  const stageId = normalizeStageId(commandName);
+  if (!stageId) {
+    return { allowed: true };
+  }
+
+  if (projectRoot) {
+    repairWorkflowRuntimeAssets(projectRoot);
+  }
+
+  // Resolve the active issue backend (env > .forge/config.yaml > default 'kernel') so
+  // the runtime gate only treats bd as a hard prerequisite for the beads backend. The
+  // kernel default needs no bd, so stages must run without it.
+  const issueBackend = resolveIssueBackend({ deps: {}, env: process.env, projectRoot, warn: () => {} });
+  const runtimeHealth = await resolveStageRuntimeHealth({
+    health, checkHealth, projectRoot, issueBackend, commandName, flags, workflowState, repairRuntime,
+  });
+  if (runtimeHealth.hardStop) {
+    throw new Error(`Stage ${stageId} blocked by runtime prerequisites: ${formatDiagnostics(runtimeHealth.diagnostics)}`);
+  }
+
+  const stateInput = resolveWorkflowStateInput(workflowState, flags, args, projectRoot);
+
+  // Kernel stage-state authority is active when a driver is injected (tests) or
+  // the caller opts in (real CLI via autoResolveKernel). Inline/flag state
+  // disables it: the caller is explicitly driving state, so no kernel side
+  // effects should occur.
+  const kernelEnabled = !isInlineStateProvided(workflowState, flags, args)
+    && (Boolean(kernelDriver) || autoResolveKernel === true);
+  const { driver, issueId } = kernelEnabled
+    ? await resolveKernelContext({ kernelDriver, activeIssueId, branch, projectRoot })
+    : { driver: null, issueId: null };
+  const kernelActive = Boolean(kernelEnabled && driver && issueId);
+
+  // On an allowed entry, record the stage as started (active) AND return a
+  // recordCompletion() the command runner calls after the handler SUCCEEDS — so
+  // a stage only counts as 'done' when its command actually passed (the ship
+  // gate below requires the predecessor to be done, not merely entered).
+  const finish = (result) => {
+    if (kernelActive) {
+      recordStageRunSafe(driver, issueId, stageId, 'start', warn);
+      result.recordCompletion = () => recordStageRunSafe(driver, issueId, stageId, 'complete', warn);
+    }
+    return result;
   };
+
+  const currentState = readWorkflowStateInput(stateInput);
+  if (currentState) {
+    return enforceWithFileState(currentState, stageId, flags, args, finish);
+  }
+
+  // No inline/file state: the kernel is authoritative. Gate on recorded stage
+  // completions (tolerant read) so `ship` is reachable from a pure-CLI
+  // plan->dev->validate progression with no .forge-state.json.
+  if (kernelActive) {
+    const decided = enforceWithKernelState(driver, issueId, stageId, finish);
+    if (decided) {
+      return decided;
+    }
+  }
+
+  if (STATELESS_ENTRY_STAGES.has(stageId)) {
+    return finish({ allowed: true, stage: stageId, workflowState: null });
+  }
+
+  throw new Error(
+    `Stage ${stageId} requires authoritative workflow state. ` +
+    `Provide --workflow-state or restore ${WORKFLOW_STATE_FILENAME} before continuing.`
+  );
 }
 
 module.exports = {
@@ -182,4 +427,8 @@ module.exports = {
   parseOverride,
   resolveWorkflowStateInput,
   readWorkflowStateFile,
+  resolveActiveIssueId,
+  evaluateKernelStageGate,
+  recordStageRunSafe,
+  stagePredecessor,
 };

package/lib/workflow/stage-transition.js

@@ -0,0 +1,115 @@
+'use strict';
+
+/**
+ * Stage-transition auto-recording (5a5ba3a6).
+ *
+ * PR #348 (f61601ab) added the stage_runs record/read capability but nothing
+ * populated it automatically — `current_stage` stayed unknown. The Descriptive
+ * Context Convention (AGENTS.md) already has agents record each stage boundary as
+ * a kernel issue comment shaped:
+ *
+ *     stage: <from> -> <to>
+ *     summary: ...
+ *
+ * This module turns that existing, already-followed convention into a structured
+ * stage_run WITHOUT any new manual verb call: parse the `stage:` line and, best
+ * effort, complete the from-stage and start the to-stage. Recording is strictly
+ * non-blocking — a stage_run write failure must NEVER break the comment that
+ * triggered it.
+ *
+ * @module workflow/stage-transition
+ */
+
+const { normalizeStageId } = require('./stages');
+
+// `stage: <from> -> <to>` on its own line, case-insensitive, arrow spacing optional.
+const STAGE_LINE = /^\s*stage:\s*([a-z]+)\s*->\s*([a-z]+)\s*$/im;
+
+/**
+ * Parse a stage-transition line out of a comment body.
+ *
+ * @param {string} body - Comment body (may be multi-line).
+ * @returns {{from: string, to: string}|null} Normalized stages, or null when the
+ *   body has no valid `stage: X -> Y` line (both tokens must be canonical stages).
+ */
+function parseStageTransition(body) {
+  if (typeof body !== 'string' || body.length === 0) {
+    return null;
+  }
+  const match = body.match(STAGE_LINE);
+  if (!match) {
+    return null;
+  }
+  // STAGE_LINE is case-insensitive, so an uppercase token (e.g. `stage: DEV ->
+  // VALIDATE`) matches. normalizeStageId only knows lowercase canonical ids, so
+  // lowercase both captures first or an uppercase-but-valid stage is wrongly rejected.
+  const from = normalizeStageId(match[1].toLowerCase());
+  const to = normalizeStageId(match[2].toLowerCase());
+  if (!from || !to) {
+    return null;
+  }
+  return { from, to };
+}
+
+/**
+ * Best-effort record of a stage transition into stage_runs. Parses the comment
+ * body; on a valid transition it completes the from-stage and starts the to-stage.
+ *
+ * The write must be ATOMIC: completing `from` and starting `to` are one logical
+ * transition, so a failure partway through must leave neither persisted (otherwise
+ * `current_stage` reflects a half-transition — from marked done, to never started).
+ * The preferred path is a single transactional `driver.recordStageTransition` that
+ * wraps both writes in one transaction; a driver that only exposes `recordStageRun`
+ * falls back to two sequential writes (non-atomic, tolerated only because the whole
+ * operation is non-blocking).
+ *
+ * ANY failure (parse miss, missing driver, DB error) is swallowed and reported as
+ * `{ recorded: false }` — this function never throws.
+ *
+ * @param {object} params
+ * @param {object} [params.driver] - Kernel driver exposing recordStageTransition
+ *   (preferred) and/or recordStageRun(input, config).
+ * @param {string} params.issueId - Full kernel issue id the comment targets.
+ * @param {string} params.body - The comment body just written.
+ * @param {object} [params.config] - Driver config (e.g. { databasePath }).
+ * @returns {{recorded: boolean, from?: string, to?: string}}
+ */
+function recordStageTransition({ driver, issueId, body, config = {} } = {}) {
+  try {
+    const transition = parseStageTransition(body);
+    if (!transition || !issueId || !driver) {
+      return { recorded: false };
+    }
+    // Preferred: one atomic driver op — complete(from) + start(to) inside a single
+    // transaction, so a mid-transition failure rolls back and never persists a
+    // wrong `current_stage`.
+    if (typeof driver.recordStageTransition === 'function') {
+      driver.recordStageTransition(
+        { issue_id: issueId, from: transition.from, to: transition.to },
+        config,
+      );
+      return { from: transition.from, to: transition.to, recorded: true };
+    }
+    // Fallback for a minimal driver without the atomic op: two sequential writes.
+    if (typeof driver.recordStageRun === 'function') {
+      driver.recordStageRun(
+        { issue_id: issueId, stage: transition.from, action: 'complete' },
+        config,
+      );
+      driver.recordStageRun(
+        { issue_id: issueId, stage: transition.to, action: 'start' },
+        config,
+      );
+      return { from: transition.from, to: transition.to, recorded: true };
+    }
+    return { recorded: false };
+  } catch {
+    // Non-blocking by contract: never let a stage_run write break the comment.
+    return { recorded: false };
+  }
+}
+
+module.exports = {
+  parseStageTransition,
+  recordStageTransition,
+};