@izkac/forgekit 0.1.6 → 0.2.0

package/bin/forge.mjs

@@ -31,6 +31,7 @@ const COMMANDS = {
   triage: { script: 'triage-prompt.mjs' },
   change: { script: 'change.mjs' },
   spine: { script: 'spine.mjs' },
+  e2e: { script: 'e2e.mjs' },
   defer: { script: 'defer.mjs' },
   'integrity-check': { script: 'integrity-check.mjs', aliases: ['integrity'] },
   score: { script: 'score-cli.mjs', aliases: ['scorecard'] },
@@ -59,6 +60,7 @@ Commands:
   triage                  Classify whether a prompt needs Forge triage
   change new|archive      Specs-engine change scaffold / archive
   spine init|check        Capability→runtime spine matrix (spine.json)
+  e2e init|run|check      Executable product-loop acceptance (e2e.json)
   defer add|resolve|list  Deferral registry (deferred wiring = tracked debt)
   integrity-check         Mechanical integrity gate (runs at phase done)
   score [--write]         L2 session scorecard (auto-written at phase done)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@izkac/forgekit",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "description": "Forgekit CLIs — forgekit (install), forge (workflow), review (code review)",
   "type": "module",
   "bin": {

package/src/e2e.mjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+/**
+ * Forge E2E acceptance — the closed product loop as an executable step list.
+ *
+ * Usage:
+ *   forge e2e                         # show status (file, validity, results freshness)
+ *   forge e2e init [--force]          # scaffold e2e.json for the active change
+ *   forge e2e run                     # execute steps, write e2e-results.json (session dir)
+ *   forge e2e check                   # gate check: green + current results; exit 1 with problems
+ *   [--session <id>]
+ *
+ * e2e.json lives next to spine.json (change dir, falling back to the session
+ * dir). Results carry a hash of the steps, so editing e2e.json after a green
+ * run invalidates the results. `forge integrity-check` / `forge phase done`
+ * run the same gate when the spine has real rows.
+ */
+
+import fs from 'node:fs';
+import { loadSession, readActive, readJson } from './lib.mjs';
+import {
+  checkE2eGate,
+  e2ePath,
+  e2eResultsPath,
+  e2eStepsHash,
+  initE2e,
+  loadE2eResults,
+  runE2eSteps,
+  validateE2e,
+  writeE2eResults,
+} from './integrity.mjs';
+
+const args = process.argv.slice(2);
+const sub = args[0] && !args[0].startsWith('--') ? args[0] : 'status';
+
+if (args[0] === '--help' || sub === 'help') {
+  process.stdout.write(
+    'Usage: forge e2e [init [--force] | run | check | status] [--session <id>]\n',
+  );
+  process.exit(0);
+}
+
+let sessionId = null;
+let force = false;
+for (let i = 0; i < args.length; i += 1) {
+  if (args[i] === '--session' && args[i + 1]) {
+    sessionId = args[i + 1];
+    i += 1;
+  } else if (args[i] === '--force') {
+    force = true;
+  }
+}
+
+if (!sessionId) {
+  const active = readActive();
+  sessionId = active?.sessionId;
+}
+if (!sessionId) {
+  process.stderr.write('No active session. Run forge new first.\n');
+  process.exit(1);
+}
+
+const { dir, session } = loadSession(sessionId);
+const file = e2ePath({ session, sessionDir: dir });
+
+if (sub === 'init') {
+  try {
+    initE2e({ file, change: session.openspecChange ?? null, force });
+  } catch (err) {
+    process.stderr.write(`${err instanceof Error ? err.message : err}\n`);
+    process.exit(1);
+  }
+  process.stdout.write(
+    `Scaffolded ${file}\nAuthor the product-loop steps (produce → consume → assert domain side effects).\nSteps that would pass against a stubbed handler are invalid.\nRun with: forge e2e run\n`,
+  );
+  process.exit(0);
+}
+
+if (sub === 'run') {
+  if (!fs.existsSync(file)) {
+    process.stderr.write(`e2e.json not found at ${file} — run forge e2e init\n`);
+    process.exit(1);
+  }
+  let doc;
+  try {
+    doc = readJson(file);
+  } catch (err) {
+    process.stderr.write(`e2e.json unreadable: ${err instanceof Error ? err.message : err}\n`);
+    process.exit(1);
+  }
+  const valid = validateE2e(doc);
+  if (!valid.ok) {
+    process.stderr.write(`e2e.json invalid:\n${valid.problems.map((p) => `  - ${p}`).join('\n')}\n`);
+    process.exit(1);
+  }
+  if (typeof doc.notApplicable === 'string' && doc.notApplicable.trim()) {
+    process.stdout.write(`e2e notApplicable: ${doc.notApplicable}\nNothing to run.\n`);
+    process.exit(0);
+  }
+  const results = runE2eSteps(doc, { cwd: process.cwd() });
+  const resultsFile = writeE2eResults(dir, results);
+  for (const step of results.steps) {
+    if (step.skipped) {
+      process.stdout.write(`  - ${step.name}: skipped (earlier step failed)\n`);
+    } else {
+      process.stdout.write(
+        `  ${step.ok ? '✓' : '✗'} ${step.name}: exit ${step.exitCode ?? 'n/a'}${
+          step.expectMatched === false ? ' (expect did not match)' : ''
+        }${step.error ? ` [${step.error}]` : ''} (${step.durationMs}ms)\n`,
+      );
+      if (!step.ok && step.outputTail) {
+        process.stdout.write(`${step.outputTail.replace(/^/gm, '    ')}\n`);
+      }
+    }
+  }
+  process.stdout.write(`${results.ok ? 'GREEN' : 'FAILED'} — results: ${resultsFile}\n`);
+  process.exit(results.ok ? 0 : 1);
+}
+
+if (sub === 'check') {
+  const gate = checkE2eGate({ e2eFile: file, sessionDir: dir });
+  process.stdout.write(
+    JSON.stringify(
+      { file, ok: gate.problems.length === 0, notApplicable: gate.notApplicable, problems: gate.problems },
+      null,
+      2,
+    ),
+  );
+  process.stdout.write('\n');
+  process.exit(gate.problems.length === 0 ? 0 : 1);
+}
+
+if (sub === 'status') {
+  if (!fs.existsSync(file)) {
+    process.stdout.write(JSON.stringify({ file, exists: false }, null, 2));
+    process.stdout.write('\n');
+    process.exit(0);
+  }
+  let doc = null;
+  let valid = { ok: false, problems: ['unreadable'] };
+  try {
+    doc = readJson(file);
+    valid = validateE2e(doc);
+  } catch (err) {
+    valid = { ok: false, problems: [`unreadable: ${err instanceof Error ? err.message : err}`] };
+  }
+  const results = loadE2eResults(dir);
+  process.stdout.write(
+    JSON.stringify(
+      {
+        file,
+        exists: true,
+        ok: valid.ok,
+        problems: valid.problems,
+        results: results
+          ? {
+              file: e2eResultsPath(dir),
+              ok: results.ok === true,
+              ranAt: results.ranAt ?? null,
+              stale: doc ? results.stepsHash !== e2eStepsHash(doc.steps) : null,
+            }
+          : null,
+      },
+      null,
+      2,
+    ),
+  );
+  process.stdout.write('\n');
+  process.exit(0);
+}
+
+process.stderr.write(`Unknown subcommand: ${sub}\n`);
+process.exit(1);

package/src/init.mjs

@@ -100,7 +100,8 @@ Options:
   --no-adr          Disable ADRs for this project
   --adr-dir <path>  ADR directory (default: ${DEFAULT_ADR_DIR} or ~/.forgekit preference)
   --overlay         Also run \`forge overlay\` (OpenSpec vendor patches)
-  --force, -f       Overwrite existing template files
+  --force, -f       Force re-scaffold of ADR/specs docs (managed command,
+                    rule, and hook files always refresh to the latest template)
   --cwd <path>      Project root (default: cwd)
   --help
 
@@ -124,16 +125,22 @@ export function resolveTemplatesRoot() {
 }
 
 /**
+ * Copy a forgekit-managed template file. These are regenerated pointers
+ * (forge-* commands/rules/hooks) with no user-owned content, so re-running
+ * `forge init` refreshes them in place — that's how template fixes propagate.
  * @param {string} src
  * @param {string} dest
- * @param {{ force?: boolean }} opts
+ * @param {{ force?: boolean }} _opts
  */
-function copyFile(src, dest, opts) {
+function copyFile(src, dest, _opts) {
   fs.mkdirSync(path.dirname(dest), { recursive: true });
-  if (fs.existsSync(dest) && !opts.force) {
-    return 'skipped';
+  const next = fs.readFileSync(src);
+  if (fs.existsSync(dest)) {
+    if (fs.readFileSync(dest).equals(next)) return 'unchanged';
+    fs.writeFileSync(dest, next);
+    return 'updated';
   }
-  fs.copyFileSync(src, dest);
+  fs.writeFileSync(dest, next);
   return 'written';
 }
 

package/src/init.test.mjs

@@ -3,7 +3,7 @@ import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { parseArgs, initProject, rememberedAgents } from './init.mjs';
+import { parseArgs, initProject, rememberedAgents, resolveTemplatesRoot } from './init.mjs';
 import { installSkillsToAgents } from './install.mjs';
 import { saveUserConfig } from './config.mjs';
 
@@ -35,6 +35,37 @@ test('rememberedAgents unions install config, installed skills, and project wiri
   }
 });
 
+test('re-running init refreshes stale managed rule files in place', () => {
+  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'forgekit-refresh-'));
+  try {
+    initProject(['claude'], { cwd, adr: false, planEngine: null });
+    const rule = path.join(cwd, '.claude', 'rules', 'forge.md');
+    // Simulate an older install with a stale reference.
+    fs.writeFileSync(rule, 'Full workflow: forgekit `docs/forge.md`\n', 'utf8');
+
+    const report = initProject(['claude'], { cwd, adr: false, planEngine: null });
+    const updated = fs.readFileSync(rule, 'utf8');
+    assert.ok(!updated.includes('forgekit `docs/forge.md`'), 'stale ref replaced');
+    assert.ok(updated.includes('~/.claude/skills/forge/docs/forge.md'), 'points to global skill doc');
+    assert.ok(
+      report.files.some((f) => f.file.includes('forge.md') && f.status === 'updated'),
+      'reports the refresh as updated',
+    );
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('thin-rule templates are engine-neutral (no hardcoded OpenSpec-only flow)', () => {
+  const root = resolveTemplatesRoot();
+  for (const rel of ['claude/rules/forge.md', 'cursor/rules/forge.mdc', 'codex/rules/forge.md']) {
+    const body = fs.readFileSync(path.join(root, ...rel.split('/')), 'utf8');
+    assert.ok(!/Forge = OpenSpec/.test(body), `${rel} still says "Forge = OpenSpec"`);
+    assert.ok(body.includes('forge change new'), `${rel} missing built-in specs command`);
+    assert.ok(body.includes('/opsx:propose'), `${rel} missing OpenSpec command`);
+  }
+});
+
 test('initProject wires templated envs and marks the rest skill-only', () => {
   const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'forgekit-init-'));
   try {

package/src/integrity-check.mjs

@@ -7,9 +7,10 @@
  *
  * Fails (exit 1) when:
  *   - deferrals are unresolved
- *   - spine.json is required (jobs/workers in scope) but missing or invalid
- *   - a spine with rows exists but verify-evidence.md lacks a product-loop
- *     section, or contains an explicit BLOCKED marker
+ *   - spine.json is missing or invalid
+ *   - a spine with rows exists but the executable E2E acceptance is missing,
+ *     failed, or stale (e2e.json + green, current e2e-results.json), or
+ *     verify-evidence.md contains an explicit BLOCKED marker
  */
 
 import { loadSession, readActive } from './lib.mjs';
@@ -49,6 +50,7 @@ process.stdout.write(
       problems: result.problems,
       spineFile: result.spineFile,
       spineExists: result.spineExists,
+      e2eFile: result.e2eFile,
     },
     null,
     2,

package/src/integrity.mjs

@@ -1,6 +1,7 @@
 /**
  * Forge runtime-integrity mechanics: spine matrix, deferral registry,
- * and the integrity checks that gate `forge phase done|finish`.
+ * executable E2E acceptance, and the integrity checks that gate
+ * `forge phase done|finish`.
  *
  * Spine matrix — `spine.json` in the change dir (or session dir when the
  * session has no tracked change). One row per capability/REQ cluster:
@@ -8,13 +9,21 @@
  * Library-only rows (missing runtime owner / writes / evidence) fail
  * validation, so "wire later" cannot be checkboxed past `forge phase done`.
  *
+ * E2E acceptance — `e2e.json` next to the spine: the closed product loop as
+ * an executable step list. `forge e2e run` executes it and records
+ * `e2e-results.json` (session dir) with a hash of the steps, so results go
+ * stale when steps change. When the spine has real rows, the gate requires a
+ * green, current run — prose in verify-evidence.md no longer satisfies it.
+ *
  * Deferral registry — `deferrals.json` in the session dir. Reviewers may only
  * accept "wiring deferred" when a registered deferral names the open task;
  * unresolved deferrals block done/finish.
  */
 
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
+import { spawnSync } from 'node:child_process';
 import { readJson, writeJson } from './lib.mjs';
 import { DEFAULT_SPECS_DIR, resolveProjectPlanEngine } from './plan-engine.mjs';
 
@@ -169,6 +178,292 @@ export function validateSpine(doc) {
   return { ok: problems.length === 0, problems };
 }
 
+/* ------------------------------------------------------------------ */
+/* E2E acceptance — executable product loop                            */
+/* ------------------------------------------------------------------ */
+
+const E2E_FILE = 'e2e.json';
+const E2E_RESULTS_FILE = 'e2e-results.json';
+export const E2E_DEFAULT_TIMEOUT_MS = 300_000;
+
+/**
+ * Path to e2e.json: change dir when available, else session dir.
+ *
+ * @param {{ cwd?: string, session?: Record<string, unknown> | null, sessionDir?: string }} opts
+ */
+export function e2ePath(opts = {}) {
+  const changeDir = resolveChangeDir(opts);
+  if (changeDir) return path.join(changeDir, E2E_FILE);
+  if (opts.sessionDir) return path.join(opts.sessionDir, E2E_FILE);
+  throw new Error('Cannot resolve e2e.json location: no change and no session dir');
+}
+
+/**
+ * @param {{ change?: string | null }} [opts]
+ */
+export function e2eTemplate(opts = {}) {
+  return {
+    change: opts.change ?? null,
+    notApplicable: null,
+    steps: [
+      {
+        name: '<boot>',
+        cmd: '<command that starts the system, e.g. docker compose up -d api worker>',
+      },
+      {
+        name: '<produce>',
+        cmd: '<command that drives the real production entry point, e.g. node scripts/e2e/enqueue-analyze.mjs>',
+        expect: '<regex the combined output must match — delete this field if exit code 0 is enough>',
+      },
+      {
+        name: '<consume-assert>',
+        cmd: '<command that proves the domain side effects exist, e.g. node scripts/e2e/assert-ratified.mjs>',
+      },
+    ],
+  };
+}
+
+/**
+ * Scaffold e2e.json (refuses to overwrite unless force).
+ *
+ * @param {{ file: string, change?: string | null, force?: boolean }} opts
+ */
+export function initE2e(opts) {
+  if (fs.existsSync(opts.file) && !opts.force) {
+    throw new Error(`e2e.json already exists: ${opts.file} (use --force to overwrite)`);
+  }
+  writeJson(opts.file, e2eTemplate({ change: opts.change }));
+  return opts.file;
+}
+
+/**
+ * Validate an e2e document.
+ *
+ * Valid when either:
+ *  - `notApplicable` is a non-empty string (loop cannot be driven by any
+ *    command — reviewers police the reason), or
+ *  - `steps` is a non-empty array where every step has a filled `name` and
+ *    `cmd` (no scaffold placeholders), `expect` (optional) is a valid regex,
+ *    and `timeoutMs` (optional) is a positive number.
+ *
+ * @param {unknown} doc
+ * @returns {{ ok: boolean, problems: string[] }}
+ */
+export function validateE2e(doc) {
+  /** @type {string[]} */
+  const problems = [];
+  if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
+    return { ok: false, problems: ['e2e.json is not an object'] };
+  }
+  const e2e = /** @type {Record<string, unknown>} */ (doc);
+
+  if (isNonEmptyString(e2e.notApplicable)) {
+    return { ok: true, problems: [] };
+  }
+
+  const steps = e2e.steps;
+  if (!Array.isArray(steps) || steps.length === 0) {
+    return {
+      ok: false,
+      problems: [
+        'e2e.steps is empty — add executable product-loop steps, or set notApplicable with a reason',
+      ],
+    };
+  }
+
+  steps.forEach((step, i) => {
+    if (!step || typeof step !== 'object' || Array.isArray(step)) {
+      problems.push(`step ${i + 1}: not an object`);
+      return;
+    }
+    const s = /** @type {Record<string, unknown>} */ (step);
+    for (const field of ['name', 'cmd']) {
+      const value = s[field];
+      if (!isNonEmptyString(value)) {
+        problems.push(`step ${i + 1} (${s.name ?? '?'}): missing ${field}`);
+      } else if (/^<.*>$/.test(value.trim())) {
+        problems.push(`step ${i + 1} (${s.name ?? '?'}): ${field} still has scaffold placeholder`);
+      }
+    }
+    if (s.expect !== undefined && s.expect !== null) {
+      if (!isNonEmptyString(s.expect)) {
+        problems.push(`step ${i + 1} (${s.name ?? '?'}): expect must be a non-empty regex string`);
+      } else if (/^<.*>$/.test(s.expect.trim())) {
+        problems.push(`step ${i + 1} (${s.name ?? '?'}): expect still has scaffold placeholder`);
+      } else {
+        try {
+          new RegExp(s.expect);
+        } catch {
+          problems.push(`step ${i + 1} (${s.name ?? '?'}): expect is not a valid regex`);
+        }
+      }
+    }
+    if (s.timeoutMs !== undefined && (typeof s.timeoutMs !== 'number' || s.timeoutMs <= 0)) {
+      problems.push(`step ${i + 1} (${s.name ?? '?'}): timeoutMs must be a positive number`);
+    }
+  });
+
+  return { ok: problems.length === 0, problems };
+}
+
+/**
+ * Hash of the step list — recorded in results so editing e2e.json after a
+ * green run invalidates the results.
+ *
+ * @param {unknown[]} steps
+ */
+export function e2eStepsHash(steps) {
+  return crypto.createHash('sha256').update(JSON.stringify(steps ?? [])).digest('hex');
+}
+
+/**
+ * @param {string} text
+ */
+function outputTail(text, lines = 30) {
+  if (!text) return '';
+  return text.split(/\r?\n/).slice(-lines).join('\n').trim();
+}
+
+/**
+ * Execute e2e steps sequentially (shell). Stops at the first failure —
+ * later steps depend on earlier ones. Exit code must be 0 and `expect`
+ * (when present) must match combined stdout+stderr.
+ *
+ * @param {{ steps?: unknown[] }} doc — a validated e2e document with steps
+ * @param {{ cwd?: string }} [opts]
+ */
+export function runE2eSteps(doc, opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const steps = Array.isArray(doc?.steps) ? doc.steps : [];
+  /** @type {Array<Record<string, unknown>>} */
+  const results = [];
+  let ok = true;
+
+  for (const step of steps) {
+    const s = /** @type {Record<string, any>} */ (step);
+    if (!ok) {
+      results.push({ name: s.name, cmd: s.cmd, skipped: true });
+      continue;
+    }
+    const started = Date.now();
+    const r = spawnSync(s.cmd, {
+      shell: true,
+      cwd,
+      encoding: 'utf8',
+      timeout: typeof s.timeoutMs === 'number' ? s.timeoutMs : E2E_DEFAULT_TIMEOUT_MS,
+      maxBuffer: 10 * 1024 * 1024,
+    });
+    const output = `${r.stdout ?? ''}${r.stderr ?? ''}`;
+    const exitCode = typeof r.status === 'number' ? r.status : null;
+    let expectMatched = null;
+    let stepOk = exitCode === 0;
+    if (stepOk && isNonEmptyString(s.expect)) {
+      expectMatched = new RegExp(s.expect).test(output);
+      stepOk = expectMatched;
+    }
+    results.push({
+      name: s.name,
+      cmd: s.cmd,
+      exitCode,
+      expectMatched,
+      ok: stepOk,
+      durationMs: Date.now() - started,
+      outputTail: outputTail(output),
+      error: r.error ? String(r.error.message ?? r.error) : null,
+    });
+    if (!stepOk) ok = false;
+  }
+
+  return {
+    ok,
+    ranAt: new Date().toISOString(),
+    stepsHash: e2eStepsHash(steps),
+    steps: results,
+  };
+}
+
+/**
+ * @param {string} sessionDir
+ */
+export function e2eResultsPath(sessionDir) {
+  return path.join(sessionDir, E2E_RESULTS_FILE);
+}
+
+/**
+ * @param {string} sessionDir
+ * @param {ReturnType<typeof runE2eSteps>} results
+ */
+export function writeE2eResults(sessionDir, results) {
+  writeJson(e2eResultsPath(sessionDir), results);
+  return e2eResultsPath(sessionDir);
+}
+
+/**
+ * @param {string} sessionDir
+ * @returns {Record<string, any> | null}
+ */
+export function loadE2eResults(sessionDir) {
+  const file = e2eResultsPath(sessionDir);
+  if (!fs.existsSync(file)) return null;
+  try {
+    return readJson(file);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Gate check for the executable E2E acceptance. Returns the problems that
+ * block `forge phase done` — empty when the loop was executed green (and the
+ * results are current), or when e2e.json honestly opts out via notApplicable.
+ *
+ * @param {{ e2eFile: string, sessionDir: string }} opts
+ * @returns {{ problems: string[], notApplicable: boolean }}
+ */
+export function checkE2eGate(opts) {
+  /** @type {string[]} */
+  const problems = [];
+
+  if (!fs.existsSync(opts.e2eFile)) {
+    problems.push(
+      `e2e.json required at ${opts.e2eFile} — run forge e2e init, author the product-loop steps, then forge e2e run. Spine rows mean an async loop exists; it must be executed, not described.`,
+    );
+    return { problems, notApplicable: false };
+  }
+
+  let doc;
+  try {
+    doc = readJson(opts.e2eFile);
+  } catch (err) {
+    problems.push(`e2e.json unreadable: ${err instanceof Error ? err.message : err}`);
+    return { problems, notApplicable: false };
+  }
+
+  const valid = validateE2e(doc);
+  if (!valid.ok) {
+    problems.push(...valid.problems.map((p) => `e2e: ${p}`));
+    return { problems, notApplicable: false };
+  }
+
+  if (isNonEmptyString(doc.notApplicable)) {
+    return { problems: [], notApplicable: true };
+  }
+
+  const results = loadE2eResults(opts.sessionDir);
+  if (!results) {
+    problems.push('e2e-results.json missing — run forge e2e run (a green run is required before done)');
+  } else if (results.stepsHash !== e2eStepsHash(doc.steps)) {
+    problems.push('e2e-results.json is stale — e2e.json changed since the last run; re-run forge e2e run');
+  } else if (!results.ok) {
+    const failed = Array.isArray(results.steps) ? results.steps.find((s) => s?.ok === false) : null;
+    problems.push(
+      `e2e run failed${failed ? ` at step "${failed.name}"` : ''} — fix and re-run forge e2e run`,
+    );
+  }
+
+  return { problems, notApplicable: false };
+}
+
 /**
  * @param {string} sessionDir
  */
@@ -245,13 +540,15 @@ export function sessionJobsSignalText(session) {
  *  2. spine.json — **always required** (filled rows, or `notApplicable` with a
  *     reason). Keyword sniffing is not enough to decide; missing spine is how
  *     library-only platforms checkbox past gaps.
- *  3. verify-evidence.md — when a spine has real rows (not notApplicable): must
- *     exist and contain a product-loop section; an explicit BLOCKED marker means
- *     the change cannot be done. Sync-only work should prefer `notApplicable`
- *     over inventing a fake loop.
+ *  3. E2E acceptance — when a spine has real rows (not notApplicable):
+ *     e2e.json must exist with filled steps (or its own notApplicable reason)
+ *     and e2e-results.json must record a green, current run (steps hash must
+ *     match). Prose in verify-evidence.md does not satisfy this; an explicit
+ *     BLOCKED marker there still means the change cannot be done. Sync-only
+ *     work should prefer spine `notApplicable` over inventing a fake loop.
  *
  * @param {{ cwd?: string, sessionDir: string, session: Record<string, unknown> }} opts
- * @returns {{ ok: boolean, problems: string[], spineFile: string, spineExists: boolean }}
+ * @returns {{ ok: boolean, problems: string[], spineFile: string, spineExists: boolean, e2eFile: string | null }}
  */
 export function runIntegrityChecks(opts) {
   /** @type {string[]} */
@@ -295,23 +592,16 @@ export function runIntegrityChecks(opts) {
     }
   }
 
+  let e2eFile = null;
   if (spineExists && spineHasRows) {
+    e2eFile = e2ePath({ cwd, session, sessionDir });
+    problems.push(...checkE2eGate({ e2eFile, sessionDir }).problems);
+
     const evidenceFile = path.join(sessionDir, 'verify-evidence.md');
-    if (!fs.existsSync(evidenceFile)) {
-      problems.push(
-        'verify-evidence.md missing — spine rows require product-loop evidence (or use notApplicable for sync-only work)',
-      );
-    } else {
-      const body = fs.readFileSync(evidenceFile, 'utf8');
-      if (/\bBLOCKED\b/.test(body)) {
-        problems.push('verify-evidence.md contains BLOCKED — change cannot be marked done while E2E is blocked');
-      } else if (!/product[- ]loop/i.test(body)) {
-        problems.push(
-          'verify-evidence.md has no "Product loop" section — record the closed producer→consumer loop (or BLOCKED). Sync-only changes should use spine notApplicable instead.',
-        );
-      }
+    if (fs.existsSync(evidenceFile) && /\bBLOCKED\b/.test(fs.readFileSync(evidenceFile, 'utf8'))) {
+      problems.push('verify-evidence.md contains BLOCKED — change cannot be marked done while E2E is blocked');
     }
   }
 
-  return { ok: problems.length === 0, problems, spineFile, spineExists };
+  return { ok: problems.length === 0, problems, spineFile, spineExists, e2eFile };
 }