@izkac/forgekit 0.1.7 → 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.7",
+  "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/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 };
 }

package/src/integrity.test.mjs

@@ -6,16 +6,24 @@ import { tmpdir } from 'node:os';
 import {
   JOBS_SIGNAL_RE,
   addDeferral,
+  checkE2eGate,
+  e2ePath,
+  e2eStepsHash,
+  e2eTemplate,
+  initE2e,
   initSpine,
   loadDeferrals,
   openDeferrals,
   resolveChangeDir,
   resolveDeferral,
+  runE2eSteps,
   runIntegrityChecks,
   sessionJobsSignalText,
   spinePath,
   spineTemplate,
+  validateE2e,
   validateSpine,
+  writeE2eResults,
 } from './integrity.mjs';
 
 function tmp(prefix) {
@@ -215,40 +223,184 @@ test('runIntegrityChecks: empty slug without spine still fails', () => {
   }
 });
 
-test('runIntegrityChecks: spine rows demand product-loop evidence', () => {
+function greenStep(overrides = {}) {
+  return {
+    name: 'produce',
+    cmd: 'node -e "console.log(\'proposals: 3\')"',
+    ...overrides,
+  };
+}
+
+function writeSpineWithRows(sessionDir) {
+  fs.writeFileSync(
+    path.join(sessionDir, 'spine.json'),
+    `${JSON.stringify({ change: null, notApplicable: null, rows: [validRow()] }, null, 2)}\n`,
+    'utf8',
+  );
+}
+
+function writeE2eDoc(sessionDir, doc) {
+  fs.writeFileSync(path.join(sessionDir, 'e2e.json'), `${JSON.stringify(doc, null, 2)}\n`, 'utf8');
+}
+
+test('validateE2e: filled steps pass; template placeholders rejected', () => {
+  assert.equal(validateE2e({ notApplicable: null, steps: [greenStep()] }).ok, true);
+  const scaffold = validateE2e(e2eTemplate({ change: 'x' }));
+  assert.equal(scaffold.ok, false);
+  assert.match(scaffold.problems.join('\n'), /scaffold placeholder/);
+});
+
+test('validateE2e: missing cmd, bad regex, bad timeout, empty steps', () => {
+  assert.match(
+    validateE2e({ steps: [{ name: 'x', cmd: '' }] }).problems.join('\n'),
+    /missing cmd/,
+  );
+  assert.match(
+    validateE2e({ steps: [greenStep({ expect: '(' })] }).problems.join('\n'),
+    /not a valid regex/,
+  );
+  assert.match(
+    validateE2e({ steps: [greenStep({ timeoutMs: -5 })] }).problems.join('\n'),
+    /timeoutMs/,
+  );
+  assert.match(validateE2e({ steps: [] }).problems.join('\n'), /steps is empty/);
+  assert.equal(validateE2e({ steps: [], notApplicable: 'no headless env — manual device loop' }).ok, true);
+});
+
+test('e2e init writes template and refuses overwrite without force', () => {
+  const dir = tmp('forge-e2e-init-');
+  try {
+    const file = path.join(dir, 'e2e.json');
+    initE2e({ file, change: 'my-change' });
+    assert.equal(JSON.parse(fs.readFileSync(file, 'utf8')).change, 'my-change');
+    assert.throws(() => initE2e({ file, change: 'my-change' }), /already exists/);
+    initE2e({ file, change: 'other', force: true });
+    assert.equal(JSON.parse(fs.readFileSync(file, 'utf8')).change, 'other');
+    assert.equal(
+      e2ePath({ cwd: dir, session: { openspecChange: null }, sessionDir: dir }),
+      file,
+    );
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('runE2eSteps: green run with expect match', () => {
+  const results = runE2eSteps({ steps: [greenStep({ expect: 'proposals: \\d+' })] });
+  assert.equal(results.ok, true);
+  assert.equal(results.steps[0].exitCode, 0);
+  assert.equal(results.steps[0].expectMatched, true);
+  assert.equal(results.stepsHash, e2eStepsHash([greenStep({ expect: 'proposals: \\d+' })]));
+});
+
+test('runE2eSteps: non-zero exit fails and skips later steps', () => {
+  const results = runE2eSteps({
+    steps: [
+      { name: 'boom', cmd: 'node -e "process.exit(3)"' },
+      greenStep({ name: 'never' }),
+    ],
+  });
+  assert.equal(results.ok, false);
+  assert.equal(results.steps[0].exitCode, 3);
+  assert.equal(results.steps[1].skipped, true);
+});
+
+test('runE2eSteps: exit 0 but expect mismatch fails', () => {
+  const results = runE2eSteps({ steps: [greenStep({ expect: 'ratified: \\d+' })] });
+  assert.equal(results.ok, false);
+  assert.equal(results.steps[0].expectMatched, false);
+});
+
+test('checkE2eGate: missing file, missing results, stale hash, failed run, green, notApplicable', () => {
+  const dir = tmp('forge-e2e-gate-');
+  try {
+    const e2eFile = path.join(dir, 'e2e.json');
+
+    let gate = checkE2eGate({ e2eFile, sessionDir: dir });
+    assert.match(gate.problems.join('\n'), /e2e\.json required/);
+
+    writeE2eDoc(dir, { notApplicable: null, steps: [greenStep()] });
+    gate = checkE2eGate({ e2eFile, sessionDir: dir });
+    assert.match(gate.problems.join('\n'), /e2e-results\.json missing/);
+
+    const results = runE2eSteps({ steps: [greenStep()] });
+    writeE2eResults(dir, results);
+    gate = checkE2eGate({ e2eFile, sessionDir: dir });
+    assert.deepEqual(gate.problems, []);
+
+    writeE2eDoc(dir, { notApplicable: null, steps: [greenStep({ name: 'edited' })] });
+    gate = checkE2eGate({ e2eFile, sessionDir: dir });
+    assert.match(gate.problems.join('\n'), /stale/);
+
+    writeE2eDoc(dir, { notApplicable: null, steps: [{ name: 'boom', cmd: 'node -e "process.exit(1)"' }] });
+    writeE2eResults(dir, runE2eSteps({ steps: [{ name: 'boom', cmd: 'node -e "process.exit(1)"' }] }));
+    gate = checkE2eGate({ e2eFile, sessionDir: dir });
+    assert.match(gate.problems.join('\n'), /failed at step "boom"/);
+
+    writeE2eDoc(dir, { notApplicable: 'loop needs a physical device', steps: [] });
+    gate = checkE2eGate({ e2eFile, sessionDir: dir });
+    assert.deepEqual(gate.problems, []);
+    assert.equal(gate.notApplicable, true);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('runIntegrityChecks: spine rows demand an executed green e2e run', () => {
   const cwd = tmp('forge-int-loop-');
   try {
     const sessionDir = makeSessionDir(cwd);
-    const spineFile = path.join(sessionDir, 'spine.json');
-    fs.writeFileSync(
-      spineFile,
-      `${JSON.stringify({ change: null, notApplicable: null, rows: [validRow()] }, null, 2)}\n`,
-      'utf8',
-    );
+    writeSpineWithRows(sessionDir);
     const session = { slug: 'wire-worker-jobs', openspecChange: null };
 
     let result = runIntegrityChecks({ cwd, sessionDir, session });
     assert.equal(result.ok, false);
-    assert.match(result.problems.join('\n'), /verify-evidence\.md missing/);
+    assert.match(result.problems.join('\n'), /e2e\.json required/);
 
-    const evidenceFile = path.join(sessionDir, 'verify-evidence.md');
-    fs.writeFileSync(evidenceFile, '# Verify\n\ntier 3 green\n', 'utf8');
+    writeE2eDoc(sessionDir, { notApplicable: null, steps: [greenStep()] });
     result = runIntegrityChecks({ cwd, sessionDir, session });
     assert.equal(result.ok, false);
-    assert.match(result.problems.join('\n'), /no "Product loop" section/);
+    assert.match(result.problems.join('\n'), /e2e-results\.json missing/);
 
-    fs.writeFileSync(evidenceFile, '# Verify\n\n## Product loop\n\nBLOCKED: no compose here\n', 'utf8');
+    writeE2eResults(sessionDir, runE2eSteps({ steps: [greenStep()] }));
     result = runIntegrityChecks({ cwd, sessionDir, session });
-    assert.equal(result.ok, false);
-    assert.match(result.problems.join('\n'), /BLOCKED/);
+    assert.equal(result.ok, true);
+    assert.equal(result.e2eFile, path.join(sessionDir, 'e2e.json'));
 
+    // prose "## Product loop" alone no longer satisfies the gate
+    fs.rmSync(path.join(sessionDir, 'e2e-results.json'));
     fs.writeFileSync(
-      evidenceFile,
-      '# Verify\n\n## Product loop\n\ningest x3 -> analyze -> ratify -> run@R: output differs from baseline\n',
+      path.join(sessionDir, 'verify-evidence.md'),
+      '# Verify\n\n## Product loop\n\ningest -> analyze -> ratify: output differs\n',
       'utf8',
     );
     result = runIntegrityChecks({ cwd, sessionDir, session });
-    assert.equal(result.ok, true);
+    assert.equal(result.ok, false);
+    assert.match(result.problems.join('\n'), /e2e-results\.json missing/);
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('runIntegrityChecks: BLOCKED in verify-evidence blocks even with green e2e', () => {
+  const cwd = tmp('forge-int-blocked-');
+  try {
+    const sessionDir = makeSessionDir(cwd);
+    writeSpineWithRows(sessionDir);
+    writeE2eDoc(sessionDir, { notApplicable: null, steps: [greenStep()] });
+    writeE2eResults(sessionDir, runE2eSteps({ steps: [greenStep()] }));
+    fs.writeFileSync(
+      path.join(sessionDir, 'verify-evidence.md'),
+      '# Verify\n\nBLOCKED: ratify UI unreachable in CI\n',
+      'utf8',
+    );
+    const result = runIntegrityChecks({
+      cwd,
+      sessionDir,
+      session: { slug: 'wire-worker-jobs', openspecChange: null },
+    });
+    assert.equal(result.ok, false);
+    assert.match(result.problems.join('\n'), /BLOCKED/);
   } finally {
     fs.rmSync(cwd, { recursive: true, force: true });
   }

package/src/set-phase.test.mjs

@@ -5,6 +5,7 @@ import path from 'node:path';
 import { tmpdir } from 'node:os';
 import { execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import { runE2eSteps, writeE2eResults } from './integrity.mjs';
 
 const SCRIPT = path.join(path.dirname(fileURLToPath(import.meta.url)), 'set-phase.mjs');
 
@@ -253,7 +254,7 @@ test('phase done refuses any session without spine.json', () => {
   }
 });
 
-test('phase done accepts jobs-scoped session with wired spine + product-loop evidence', () => {
+test('phase done accepts jobs-scoped session with wired spine + green e2e run', () => {
   const dir = tmp('forge-set-phase-spine-ok-');
   try {
     const sessionFile = makeForgeFixture(dir, 'sess-spine-ok');
@@ -289,6 +290,13 @@ test('phase done accepts jobs-scoped session with wired spine + product-loop evi
       '# Verify\n\n## Product loop\n\ningest -> analyze -> ratify -> run: output differs\n',
       'utf8',
     );
+    const e2eSteps = [{ name: 'loop', cmd: 'node -e "console.log(\'ratified: 1\')"' }];
+    fs.writeFileSync(
+      path.join(sessionDir, 'e2e.json'),
+      `${JSON.stringify({ change: null, notApplicable: null, steps: e2eSteps }, null, 2)}\n`,
+      'utf8',
+    );
+    writeE2eResults(sessionDir, runE2eSteps({ steps: e2eSteps }));
 
     runSetPhase(dir, ['done']);
     const session = JSON.parse(fs.readFileSync(sessionFile, 'utf8'));

package/vendor/skills/forge/SKILL.md

@@ -117,7 +117,7 @@ Testing: [references/test-strategy.md](./references/test-strategy.md) — tier 1
 - Tests required for behavior changes
 - Trace ecosystem consumers when contracts change
 - Honor `openspec/config.yaml` prefixes when the project uses them (OpenSpec engine)
-- **Runtime integrity** — [references/runtime-integrity.md](./references/runtime-integrity.md): **spine.json mandatory every change** (rows or `notApplicable` — not keyword-gated); no stubs / false success; capability specs beat narrow task wording; every claimed capability needs a named production caller; product-loop when spine has rows (or BLOCKED); deferred wiring only via `forge defer` — `forge phase done` mechanically refuses on `forge integrity-check` failures
+- **Runtime integrity** — [references/runtime-integrity.md](./references/runtime-integrity.md): **spine.json mandatory every change** (rows or `notApplicable` — not keyword-gated); no stubs / false success; capability specs beat narrow task wording; every claimed capability needs a named production caller; when spine has rows the product loop must be **executed** — `e2e.json` steps + green `forge e2e run` (or BLOCKED), prose does not satisfy the gate; deferred wiring only via `forge defer` — `forge phase done` mechanically refuses on `forge integrity-check` failures
 
 ## Agent surfaces
 

package/vendor/skills/forge/docs/forge.md

@@ -115,7 +115,7 @@ User request
             └─────────────┬─────────────┘
                           ▼
          Verify: audit tier 2 + tier 3 (scope from pace)
-                  + ## Product loop (or BLOCKED)
+                  + forge e2e run (green, or BLOCKED)
                   + forge integrity-check
                           │
                           ▼
@@ -130,8 +130,9 @@ User request
 ```
 
 **Jobs / workers / queues:** spine is mandatory for *every* change (`forge spine
-init` — rows or `notApplicable`). Async work also needs wiring + product-loop
-tasks. See [Runtime integrity](#runtime-integrity).
+init` — rows or `notApplicable`). Spine rows also require executable acceptance
+steps (`forge e2e init` at plan, green `forge e2e run` before done). Async work
+also needs wiring + product-loop tasks. See [Runtime integrity](#runtime-integrity).
 
 ### Triage (top of tree)
 
@@ -178,10 +179,10 @@ See the Forge skill’s [references/plan-routing.md](../references/plan-routing.
 | ----- | ------------ | ----------------- |
 | **triage** | Substantial? Skip allowed? Bootstrap session | `forge` skill |
 | **brainstorm** | Explore intent, approaches, approval | `skills/brainstorming` |
-| **plan** | Tracked-change propose; **`forge spine init` every change** (rows or `notApplicable`); wiring + product-loop tasks when async | [plan-routing.md](../references/plan-routing.md) |
+| **plan** | Tracked-change propose; **`forge spine init` every change** (rows or `notApplicable`); rows → `forge e2e init` (steps are a plan deliverable); wiring + product-loop tasks when async | [plan-routing.md](../references/plan-routing.md) |
 | **implement** | Subagent per task, TDD, tier 2 evidence; update spine rows; `forge defer` for deferred wiring | **`/forge:apply`** (OpenSpec) or `/forge:build` + `skills/subagent-driven-development` + `skills/test-driven-development` + [test-strategy](../references/test-strategy.md) |
-| **verify** | Audit tier 2; tier 3; product-loop evidence; `forge integrity-check` | `skills/verification-before-completion` + `verify-evidence.md` |
-| **review** | Combined task reviewer (spec + quality) per task; final review (spine + product loop) | `skills/requesting-code-review` |
+| **verify** | Audit tier 2; tier 3; green `forge e2e run`; `forge integrity-check` | `skills/verification-before-completion` + `verify-evidence.md` |
+| **review** | Combined task reviewer (spec + quality) per task; final review (spine + executed e2e) | `skills/requesting-code-review` |
 | **finish** | Archive (+ ADR if the project uses that); `forge phase done` (integrity gate); cleanup | `/opsx:archive`, `forge cleanup` |
 
 **Standalone deep review (outside Forge):** for pre-merge audits with adversarial false-positive filtering, use the **thorough code review** skill — see [thorough-code-review.md](https://github.com/izkac/forgekit/blob/main/docs/thorough-code-review.md). Forge's `requesting-code-review` stays the per-task checkpoint during `/forge:build`.
@@ -206,9 +207,11 @@ Cursor, Claude Code, and Codex without requiring a chat ID.
         notes.md
         decisions.md
       plan.md                         ← legacy throwaway plans only (deprecated)
-      verify-evidence.md              ← tier 3 + ## Product loop (or BLOCKED)
+      verify-evidence.md              ← tier 3 + loop narrative (or BLOCKED)
+      e2e-results.json                ← forge e2e run results (steps hash + per-step outcomes)
       deferrals.json                  ← forge defer registry (when used)
       spine.json                      ← fallback if no tracked change dir
+      e2e.json                        ← fallback if no tracked change dir
       scorecard.md / scorecard.json   ← L2 session score (written at done/finish)
       tasks/
         01-first-task/
@@ -219,8 +222,9 @@ Cursor, Claude Code, and Codex without requiring a chat ID.
         final-review.md
 ```
 
-For OpenSpec / specs-engine changes, the canonical **spine matrix** lives next to
-the plan: `openspec/changes/<name>/spine.json` (or `<specsDir>/changes/<name>/spine.json`).
+For OpenSpec / specs-engine changes, the canonical **spine matrix** and **e2e
+steps** live next to the plan: `openspec/changes/<name>/spine.json` + `e2e.json`
+(or `<specsDir>/changes/<name>/…`).
 
 **Session ID:** `<UTC-compact>-<kebab-slug>-<6-hex>`
 
@@ -275,8 +279,9 @@ forge prefs --session-set lite    # pin active session only
 forge doctor                      # plan-engine readiness (OpenSpec or specs layout)
 forge doctor --install            # attempt npm install -g @fission-ai/openspec
 forge spine init|check            # capability→runtime spine matrix (spine.json in change dir)
+forge e2e init|run|check          # executable product-loop acceptance (e2e.json + e2e-results.json)
 forge defer add|resolve|list      # deferral registry — deferred wiring is tracked debt
-forge integrity-check             # mechanical gate: spine + deferrals + product-loop evidence
+forge integrity-check             # mechanical gate: spine + deferrals + executed e2e
 forge score [--write] [--md]      # L2 session scorecard (also auto-written at phase done)
 forge overlay                     # re-apply OpenSpec vendor overlays in this project
 forge init […]                    # wire project commands / hooks / rules
@@ -399,7 +404,7 @@ Integrity upgrades Forge from “no false job success” to **product-loop accep
 2. **Runtime owner required** — a library alone does not satisfy a capability; name the production caller (job, endpoint, CLI).
 3. **Tests must fail on a no-op** — asserting “job status became succeeded” is not enough.
 4. **Specs beat narrow tasks** — capability specs win when they conflict with a thin task reading.
-5. **E2E = product loop** — produce → consume → decision changes output. A single job slice (ingest → Parquet) is **not** platform E2E.
+5. **E2E = executed product loop** — produce → consume → decision changes output, run as `e2e.json` steps via `forge e2e run` (prose does not count). A single job slice (ingest → Parquet) is **not** platform E2E.
 6. **Job-kind closure** — every product-surface job kind is wired end-to-end **or deleted** before complete. “Fail closed” is only a temporary `BLOCKED` state.
 7. **Consumer–producer** — if UI/API reads it, production must write it (proven in evidence).
 8. **Deferrals are tracked** — “wiring later” only via `forge defer`; unresolved deferrals block `done`.
@@ -409,6 +414,7 @@ Integrity upgrades Forge from “no false job success” to **product-loop accep
 | Tool | Purpose |
 |------|---------|
 | `forge spine init\|check` | **Mandatory every change.** `spine.json`: rows **or** `notApplicable`. Not keyword-gated. |
+| `forge e2e init\|run\|check` | **Mandatory when the spine has rows.** `e2e.json` step list executed by `forge e2e run`; results (`e2e-results.json`) carry a steps hash, so edits after a green run go stale |
 | `forge defer add\|resolve\|list` | Deferred wiring as tracked debt in the session |
 | `forge integrity-check` | Combined gate — also run automatically by `forge phase done\|finish` |
 
@@ -425,9 +431,9 @@ You do **not** paste a long definition-of-done prompt. After
 
 | Automatic (CLI / hooks) | Agent-driven (skill phases — required) |
 | ----------------------- | -------------------------------------- |
-| Integrity reminder on every session/prompt hook | Plan: **`forge spine init` every change** — fill rows or `notApplicable` |
+| Integrity reminder on every session/prompt hook | Plan: **`forge spine init` every change** — fill rows or `notApplicable`; rows → also `forge e2e init` |
 | Pace `auto` fail-closed to **standard**; task-count escalation at ≥15 | Implement: update spine rows; `forge defer add` if wiring is deferred |
-| `forge phase done\|finish` requires valid spine + writes L2 scorecard | Verify: `## Product loop` when spine has rows (sync-only → prefer `notApplicable`) |
+| `forge phase done\|finish` requires valid spine + green current e2e run + writes L2 scorecard | Verify: green `forge e2e run` when spine has rows (sync-only → prefer `notApplicable`) |
 | `forge status` surfaces `integrity.*` defaults | After done: answer L3 ship-check in `scorecard.md` |
 
 **Gates are automatic. Filling evidence is part of the normal phase flow.**
@@ -471,35 +477,51 @@ forge spine init
 
 Docs-only / no-runtime changes may set `"notApplicable": "docs-only change"` instead of rows.
 
-**If wiring must wait for a later task**
+Spine rows → also author the executable acceptance steps:
 
 ```bash
-forge defer add --task 9.7 --reason "analyze_study handler lands in 9.7"
-# … when 9.7 is done:
-forge defer resolve --task 9.7
+forge e2e init
+# edit openspec/changes/<name>/e2e.json — the closed loop as commands
 ```
 
-**Verify evidence** (required when spine has rows):
+```json
+{
+  "change": "etl-surveydb-pipeline-closure",
+  "notApplicable": null,
+  "steps": [
+    { "name": "ingest", "cmd": "node scripts/e2e/ingest-fixture.mjs OP1086" },
+    { "name": "analyze", "cmd": "node scripts/e2e/run-analyze.mjs", "expect": "proposals: [1-9]" },
+    { "name": "ratify", "cmd": "node scripts/e2e/ratify-subset.mjs" },
+    { "name": "run-assert", "cmd": "node scripts/e2e/assert-output-differs.mjs", "timeoutMs": 600000 }
+  ]
+}
+```
 
-```markdown
-# Verify evidence — tier 3
+Steps must assert domain side effects — a list that would pass against a
+stubbed handler is invalid. `"notApplicable": "<reason>"` only when no command
+can drive the loop.
 
-- **Command:** `pytest …` / `npm test …`
-- **Exit code:** 0
+**If wiring must wait for a later task**
 
-## Product loop
+```bash
+forge defer add --task 9.7 --reason "analyze_study handler lands in 9.7"
+# … when 9.7 is done:
+forge defer resolve --task 9.7
+```
 
-Fixture: OP1086 three sources
+**Verify** (required when spine has rows):
 
-1. ingest_source ×3 → study_sources + Parquet
-2. analyze_study → study_proposals (match / loop)
-3. ratify subset via API → decisions tip at revision R
-4. harmonization_run @R → .sav + Master QML + BI
-5. Assert: output at R differs from unratified baseline
+```bash
+forge e2e run    # executes the steps, writes e2e-results.json (session dir)
 ```
 
-Or an explicit `BLOCKED: …` line — then `forge phase done` refuses until unblocked
-or the user passes `--allow-incomplete`.
+Green run required; results go stale if `e2e.json` changes afterwards (steps
+hash). Keep a short loop narrative under `## Product loop` in
+`verify-evidence.md` as reviewer context — the gate checks the executed
+results, not the heading.
+
+Or an explicit `BLOCKED: …` line in `verify-evidence.md` — then `forge phase
+done` refuses until unblocked or the user passes `--allow-incomplete`.
 
 **Finish**
 

package/vendor/skills/forge/phases/finish.md

@@ -3,7 +3,7 @@
 Before marking done, integrity must pass (or the user must approve an incomplete finish):
 
 ```bash
-forge integrity-check    # spine + deferrals + product-loop / BLOCKED
+forge integrity-check    # spine + deferrals + executed e2e (green, current) / BLOCKED
 forge score              # preview L2 scorecard (optional)
 forge phase done         # runs integrity checks + writes scorecard.md/json
 # escape hatch only with an honest reason:

package/vendor/skills/forge/phases/implement.md

@@ -38,6 +38,7 @@ Honor [../references/runtime-integrity.md](../references/runtime-integrity.md) i
 - Do not mark a section complete if libraries exist but nothing in the production path calls them.
 - **Deferrals:** if wiring genuinely lands in a later task, register it — `forge defer add --task <id> --reason "…"` — and resolve it when that task lands. Unregistered "later" is a REJECT; unresolved deferrals block `forge phase done`.
 - **Spine:** when a task wires a capability into production, update its `spine.json` row (runtimeOwner / writes / evidence). `forge spine check` must pass before verify ends.
+- **E2E:** the product-loop acceptance task (last implement task) delivers working `e2e.json` steps and a green `forge e2e run` — steps that would pass against a stubbed handler are invalid.
 
 ## Per-task loop
 

package/vendor/skills/forge/phases/plan-openspec.md

@@ -16,14 +16,20 @@ Thin wrapper around the project **`openspec-propose`** skill (or `/opsx:propose`
    Sync-only / docs-only: `"notApplicable": "<reason>"`. Capability work: one row
    per REQ cluster (library → runtime owner → writes → evidence).
 
+   When the spine has real rows, also `forge e2e init` — the executable
+   product-loop steps (`e2e.json`) are a **plan deliverable**: author them (or
+   task out their authoring) so verify can `forge e2e run` them.
+
    If the change also involves workers, job queues, handlers, or cross-runtime
    calls, `tasks.md` MUST include:
 
    - Explicit **wiring** tasks per job kind / entry point → domain pipeline
-   - One **product-loop acceptance** task (last implement task, before verify)
+   - One **product-loop acceptance** task (last implement task, before
+     verify) — its output is a green `forge e2e run`
 
    Missing spine = plan **not** ready. (`forge phase done` refuses without a
-   valid spine — keyword sniffing does not decide.)
+   valid spine and, when the spine has rows, a green current e2e run —
+   keyword sniffing does not decide.)
 
 5. Update session:
    ```bash

package/vendor/skills/forge/phases/plan-specs.md

@@ -64,14 +64,20 @@ OpenSpec propose flow without the vendor CLI. Change lives under
    Sync-only / docs-only: `"notApplicable": "<reason>"`. Capability work: one row
    per REQ cluster (library → runtime owner → writes → evidence).
 
+   When the spine has real rows, also `forge e2e init` — the executable
+   product-loop steps (`e2e.json`) are a **plan deliverable**: author them (or
+   task out their authoring) so verify can `forge e2e run` them.
+
    If the change also involves workers, job queues, handlers, or cross-runtime
    calls, `tasks.md` MUST include:
 
    - Explicit **wiring** tasks per job kind / entry point → domain pipeline
-   - One **product-loop acceptance** task (last implement task, before verify)
+   - One **product-loop acceptance** task (last implement task, before
+     verify) — its output is a green `forge e2e run`
 
    Missing spine = plan **not** ready. (`forge phase done` refuses without a
-   valid spine — keyword sniffing does not decide.)
+   valid spine and, when the spine has rows, a green current e2e run —
+   keyword sniffing does not decide.)
 
 5. Update session:
 

package/vendor/skills/forge/phases/verify.md

@@ -73,12 +73,15 @@ For each requirement in the change's **capability specs** (not only `tasks.md`):
 
 Record the trace in `verify-evidence.md` (a short REQ → caller table is enough).
 
-### 4. Product-loop E2E or BLOCKED
+### 4. Product-loop E2E — executed, or BLOCKED
 
 Before leaving verify / claiming the change complete:
 
-1. Run (or document exact commands for) the **closed product loop** — not a single job slice. When the design has a producer/consumer split (analyze vs execute, proposals vs ratify), the loop is: produce artifact → consumer reads it → decision/state change → **next run's output differs from baseline**. Record it under a `## Product loop` heading in `verify-evidence.md` (the done gate greps for it). **Or**
-2. Leave an explicit **`BLOCKED`** list in `verify-evidence.md` explaining why E2E cannot run here — the done gate then refuses `done` until unblocked or the user signs `--allow-incomplete`.
+1. Confirm `e2e.json` (scaffolded at plan time via `forge e2e init`) drives the **closed product loop** — not a single job slice. When the design has a producer/consumer split (analyze vs execute, proposals vs ratify), the loop is: produce artifact → consumer reads it → decision/state change → **next run's output differs from baseline**. Steps must assert domain side effects; a step list that would pass against a stubbed handler is invalid.
+2. `forge e2e run` — executes the steps sequentially and writes `e2e-results.json` (per-step exit codes, output tails, steps hash) into the session dir. A **green run** is required; results go stale if `e2e.json` changes afterwards (re-run). Prose in `verify-evidence.md` no longer satisfies the done gate. **Or**
+3. Leave an explicit **`BLOCKED`** list in `verify-evidence.md` explaining why E2E cannot run here — the done gate then refuses `done` until unblocked or the user signs `--allow-incomplete`. (`e2e.json` `notApplicable` is only for loops no command can drive — reviewers police the reason.)
+
+Keep a short loop narrative under `## Product loop` in `verify-evidence.md` as reviewer context — the gate checks the executed results, not the heading.
 
 Also enforce **job-kind closure**: every product-surface job kind is wired end-to-end or deleted from enums/API/UI before complete. And the **consumer–producer rule**: anything the UI/API reads must be proven written by the production path.
 
@@ -88,6 +91,7 @@ Do **not** mark the change complete or advance to `done` while a critical path i
 
 ```bash
 forge spine check        # every capability row wired (library → runtime owner → writes → evidence)
+forge e2e check          # green, current e2e-results.json (steps hash matches e2e.json)
 forge defer list         # no unresolved deferrals
 forge integrity-check    # combined; forge phase done runs the same checks
 ```

package/vendor/skills/forge/references/runtime-integrity.md

@@ -45,12 +45,13 @@ task.
 - To shrink scope: stop and ask the user. Do not silently checkbox around gaps.
 - Prefer `DONE_WITH_CONCERNS` / incomplete tasks over green checkboxes.
 
-## 5. E2E means product loop, not job slice
+## 5. E2E means an executed product loop, not prose
 
 Before claiming the change complete:
 
-1. Run (or document exact commands for) the **closed product loop** through the
-   live entry points, **or**
+1. Author the **closed product loop** as executable steps in `e2e.json`
+   (`forge e2e init`), run it against the live entry points
+   (`forge e2e run`), and get a **green run** — **or**
 2. Leave an explicit **`BLOCKED`** list in `verify-evidence.md` — and do **not**
    mark the change complete / advance to `done`.
 
@@ -65,8 +66,19 @@ next run's OUTPUT DIFFERS from the baseline
 
 Example: ingest→Parquet plus a thin run→`.sav` does **not** verify a
 governance loop; analyze→proposals→ratify→run-applies-decisions does.
-Record it under a `## Product loop` heading in `verify-evidence.md` —
-the mechanical gate looks for it.
+
+The mechanical gate requires a green, **current** `e2e-results.json` (its
+steps hash must match `e2e.json`) whenever the spine has real rows.
+Describing the loop in `verify-evidence.md` no longer satisfies the gate —
+prose cannot prove wiring. Each step is `{ name, cmd, expect?, timeoutMs? }`:
+exit code 0 required, `expect` (regex) matched against the output. Steps must
+assert **domain side effects** — a step list that would pass against a
+stubbed handler is invalid (rule 3 applies to e2e steps too).
+
+`e2e.json` may set `"notApplicable": "<reason>"` only when the loop cannot be
+driven by any command (e.g. requires a physical device). Reviewers police the
+reason; "no time" or "covered by unit tests" is a REJECT. Keep a short loop
+narrative under `## Product loop` in `verify-evidence.md` as reviewer context.
 
 ## 6. Job-kind closure
 
@@ -126,9 +138,9 @@ Then either:
    (e.g. `"sync HTTP only — no async producer/consumer"`). That is the honest
    opt-out; missing `spine.json` is not.
 
-Product-loop evidence in `verify-evidence.md` is required when the spine has
-real rows. Prefer `notApplicable` for sync-only changes instead of inventing a
-fake loop.
+An executed product loop (`forge e2e run`, green + current results) is
+required when the spine has real rows. Prefer `notApplicable` for sync-only
+changes instead of inventing a fake loop.
 
 ## Reviewer REJECT checklist (mandatory)
 
@@ -141,6 +153,8 @@ REJECT the task (or final review → `NOT READY`) if any of:
 - Spec requirement has a library but no named runtime owner
 - Deferred wiring without a registered open deferral (`forge defer list`)
 - Spine row for this capability missing or library-only
+- E2E steps would pass against a stubbed handler (no domain side-effect
+  assertions), or `e2e.json` opts out via `notApplicable` without a real reason
 
 ## Plan seam (every change)
 
@@ -148,10 +162,14 @@ Before apply-ready:
 
 1. `forge spine init` — **always**. Fill rows for each capability, or set
    `notApplicable` with a reason (sync-only / docs-only).
-2. If the change involves workers, job queues, handlers, or cross-runtime
+2. When the spine has real rows, `forge e2e init` — the acceptance **steps are
+   a plan deliverable**: author (or task out) the `e2e.json` step list that
+   drives the loop and asserts its side effects.
+3. If the change involves workers, job queues, handlers, or cross-runtime
    calls, `tasks.md` MUST also include:
    - Explicit **wiring** tasks per job kind / entry point → domain pipeline
-   - One **product-loop acceptance** task (last implement task, before verify)
+   - One **product-loop acceptance** task (last implement task, before
+     verify) — its output is a green `forge e2e run`
 
 Missing spine = plan not ready. Keyword guesses about “jobs in scope” are not
 an excuse to skip the spine.

package/vendor/skills/forge/subagents/final-reviewer-prompt.md

@@ -34,14 +34,17 @@ job, …) that invokes the implementing code. Cross-check against `spine.json`
 - UI/API reads a collection or artifact nothing in the production path writes → **`NOT READY`**
 - Missing E2E fixture path with no explicit `BLOCKED` in `verify-evidence.md` → **`NOT READY`**
 
-## Product-loop evidence (required)
+## Product-loop acceptance (required — executed, not described)
 
-`verify-evidence.md` must contain a `## Product loop` section proving the
-**closed loop** (produce → consume → decision changes output), or an explicit
-`BLOCKED` list. A single job slice (e.g. ingest→file) or a library-level E2E
-does **not** count as platform E2E.
+`forge e2e check` must be green: `e2e.json` steps drive the **closed loop**
+(produce → consume → decision changes output) and `e2e-results.json` records a
+green, current run (steps hash matches). A single job slice (e.g. ingest→file)
+or a library-level E2E does **not** count as platform E2E. Read the steps —
+would they pass against a stubbed handler? If yes, they prove nothing.
 
-- No product-loop section and no `BLOCKED` → **`NOT READY`**
+- No green, current e2e run and no `BLOCKED` in `verify-evidence.md` → **`NOT READY`**
+- E2E steps assert no domain side effects (would pass on a stub) → **`NOT READY`**
+- `e2e.json` `notApplicable` without a reason no command could overcome → **`NOT READY`**
 - `BLOCKED` present → **`NOT READY`** (honest, but not READY)
 - Unresolved deferrals in `forge defer list` → **`NOT READY`**
 

package/vendor/skills/forge/subagents/task-reviewer-prompt.md

@@ -43,6 +43,7 @@ Diff range: {DIFF_RANGE}   <!-- e.g. `git diff` (uncommitted) or BASE..HEAD -->
 - Brief authorized a stub / “wire later” for a path this change claims
 - Wiring is deferred **without a registered open deferral** — the packet must show `forge defer list` output naming this task's deferral; "wiring in §9" with no registry entry is a REJECT
 - The task claims a capability whose `spine.json` row is missing or library-only (empty runtimeOwner / writes / evidence)
+- The task authored or touched `e2e.json` steps that would pass against a stubbed handler (no domain side-effect assertions), or set `notApplicable` without a real reason
 
 **Code quality:**