@izkac/forgekit 0.1.6 → 0.2.0

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`**