@izkac/forgekit 0.1.7 → 0.3.0

package/src/lib/fleet.mjs

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+/**
+ * Machine-level fleet registry: one JSON file per forge session under
+ * `~/.forgekit/fleet/sessions/`, mirrored on every `saveSession` so any
+ * project's sessions are visible from a single control terminal
+ * (`forge fleet list|watch|view|send`).
+ *
+ * Standalone on purpose — no import of ../lib.mjs (which binds cwd at import
+ * time); everything here takes explicit paths. `FORGEKIT_FLEET_DIR` overrides
+ * the registry location (tests point it at a tmp dir).
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const PHASE_ORDER = [
+  'triage',
+  'brainstorm',
+  'plan',
+  'implement',
+  'verify',
+  'review',
+  'finish',
+  'done',
+];
+
+export function fleetDir() {
+  return (
+    process.env.FORGEKIT_FLEET_DIR ||
+    path.join(os.homedir(), '.forgekit', 'fleet', 'sessions')
+  );
+}
+
+/** Same sanitisation Claude Code uses for ~/.claude/projects dir names. */
+export function sanitizePath(p) {
+  return String(p).replace(/[^a-zA-Z0-9]/g, '-');
+}
+
+export function entryFile(projectRoot, sessionId) {
+  return path.join(fleetDir(), `${sanitizePath(projectRoot)}--${sessionId}.json`);
+}
+
+/**
+ * Best-effort engine detection from env vars set by agent harnesses.
+ * ponytail: claude + cursor only; other engines show as null until they
+ * grow a detectable env marker.
+ */
+export function detectEngine(env = process.env) {
+  if (env.CLAUDECODE) return 'claude';
+  if (env.CURSOR_TRACE_ID || env.CURSOR_AGENT) return 'cursor';
+  return null;
+}
+
+/**
+ * Mirror a session into the registry. Never throws — a broken registry must
+ * not break session saves.
+ *
+ * @param {string} projectRoot absolute project path
+ * @param {Record<string, any>} session forge session.json contents
+ */
+export function registerSession(projectRoot, session) {
+  try {
+    const file = entryFile(projectRoot, session.id);
+    let prev = {};
+    try {
+      prev = JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch {
+      /* first registration */
+    }
+    const entry = {
+      project: projectRoot,
+      projectName: path.basename(projectRoot),
+      sessionId: session.id,
+      slug: session.slug,
+      phase: session.phase,
+      planType: session.planType ?? null,
+      openspecChange: session.openspecChange ?? null,
+      tasksTotal: session.tasksTotal ?? 0,
+      tasksComplete: session.tasksComplete ?? 0,
+      pace: session.resolvedPace ?? session.pace ?? null,
+      engine: detectEngine() ?? prev.engine ?? null,
+      createdAt: session.createdAt,
+      updatedAt: session.updatedAt,
+    };
+    fs.mkdirSync(fleetDir(), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(entry, null, 2)}\n`, 'utf8');
+  } catch {
+    /* registry is advisory */
+  }
+}
+
+export function unregisterSession(projectRoot, sessionId) {
+  try {
+    fs.rmSync(entryFile(projectRoot, sessionId), { force: true });
+  } catch {
+    /* advisory */
+  }
+}
+
+/**
+ * All registry entries, newest first. Self-heals: entries whose session dir
+ * vanished (cleanup ran without unregister, project deleted the .forge dir)
+ * are removed; entries whose whole project path is unreachable (unplugged
+ * drive) are kept and marked `missing`.
+ *
+ * @returns {Array<Record<string, any>>}
+ */
+export function listFleet() {
+  const dir = fleetDir();
+  if (!fs.existsSync(dir)) return [];
+  const entries = [];
+  for (const name of fs.readdirSync(dir)) {
+    if (!name.endsWith('.json')) continue;
+    const file = path.join(dir, name);
+    let entry;
+    try {
+      entry = JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch {
+      continue;
+    }
+    const sessionDir = path.join(entry.project, '.forge', 'sessions', entry.sessionId);
+    if (fs.existsSync(sessionDir)) {
+      entry.missing = false;
+    } else if (fs.existsSync(entry.project)) {
+      fs.rmSync(file, { force: true });
+      continue;
+    } else {
+      entry.missing = true;
+    }
+    entries.push(entry);
+  }
+  entries.sort((a, b) => String(b.updatedAt).localeCompare(String(a.updatedAt)));
+  return entries;
+}
+
+export function sessionDirFor(entry) {
+  return path.join(entry.project, '.forge', 'sessions', entry.sessionId);
+}
+
+/**
+ * Queue a fleet message for a session; delivered into the agent's context by
+ * `forge reminder` (hook) on its next turn.
+ */
+export function queueMessage(sessionDir, message, from = 'fleet') {
+  const inbox = path.join(sessionDir, 'inbox');
+  fs.mkdirSync(inbox, { recursive: true });
+  const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
+  const file = path.join(inbox, `${stamp}-${from}.md`);
+  fs.writeFileSync(file, `${message}\n`, 'utf8');
+  return file;
+}
+
+/**
+ * Read-and-consume pending fleet messages (moved to inbox/delivered/ so each
+ * is injected exactly once).
+ *
+ * @returns {Array<{ file: string, text: string }>}
+ */
+export function drainInbox(sessionDir) {
+  const inbox = path.join(sessionDir, 'inbox');
+  if (!fs.existsSync(inbox)) return [];
+  const delivered = path.join(inbox, 'delivered');
+  const out = [];
+  for (const name of fs.readdirSync(inbox).sort()) {
+    const file = path.join(inbox, name);
+    if (!fs.statSync(file).isFile()) continue;
+    const text = fs.readFileSync(file, 'utf8').trim();
+    fs.mkdirSync(delivered, { recursive: true });
+    fs.renameSync(file, path.join(delivered, name));
+    out.push({ file: name, text });
+  }
+  return out;
+}
+
+/** Pending (undelivered) fleet messages, without consuming them. */
+export function peekInbox(sessionDir) {
+  const inbox = path.join(sessionDir, 'inbox');
+  if (!fs.existsSync(inbox)) return [];
+  return fs
+    .readdirSync(inbox)
+    .sort()
+    .filter((name) => fs.statSync(path.join(inbox, name)).isFile())
+    .map((name) => ({
+      file: name,
+      text: fs.readFileSync(path.join(inbox, name), 'utf8').trim(),
+    }));
+}
+
+/**
+ * Claude Code transcript dir for a project (`~/.claude/projects/<sanitized>`),
+ * or null when absent.
+ */
+export function claudeTranscriptDir(projectRoot, home = os.homedir()) {
+  const dir = path.join(home, '.claude', 'projects', sanitizePath(projectRoot));
+  return fs.existsSync(dir) ? dir : null;
+}
+
+/** Newest transcript jsonl in a project's Claude dir, or null. */
+export function newestTranscript(projectRoot, home = os.homedir()) {
+  const dir = claudeTranscriptDir(projectRoot, home);
+  if (!dir) return null;
+  const files = fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith('.jsonl'))
+    .map((f) => {
+      const full = path.join(dir, f);
+      return { full, mtime: fs.statSync(full).mtimeMs };
+    })
+    .sort((a, b) => b.mtime - a.mtime);
+  return files[0]?.full ?? null;
+}

package/src/lib.mjs

@@ -6,6 +6,7 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
+import { registerSession } from './lib/fleet.mjs';
 
 export const REPO_ROOT = process.cwd();
 export const FORGE_DIR = path.join(REPO_ROOT, '.forge');
@@ -130,6 +131,10 @@ export function saveSession(dir, session) {
   session.updatedAt = new Date().toISOString();
   writeJson(path.join(dir, 'session.json'), session);
   writeJson(path.join(dir, 'status.json'), defaultStatus(session));
+  // Mirror into ~/.forgekit/fleet so `forge fleet` sees every project's
+  // sessions. Project root derived from dir (<root>/.forge/sessions/<id>),
+  // not REPO_ROOT, so callers with explicit dirs mirror correctly too.
+  registerSession(path.resolve(dir, '..', '..', '..'), session);
 }
 
 export function sessionAgeDays(session) {

package/src/session-reminder.mjs

@@ -9,6 +9,7 @@
  */
 
 import { FORGE_DIR, loadSession, readActive } from './lib.mjs';
+import { drainInbox } from './lib/fleet.mjs';
 import { resolveEffectivePreferences } from './preferences.mjs';
 
 function getActiveSessionInfo() {
@@ -148,10 +149,20 @@ if (!info) {
   process.exit(0);
 }
 
-const message = prompt
+let message = prompt
   ? buildForgePromptMessage(info, prompt)
   : buildForgeMessage(info);
 
+// Deliver queued `forge fleet send` messages exactly once (drain moves them
+// to inbox/delivered/). This is the fleet command bus: control terminal →
+// inbox file → injected into the agent's next turn via this hook.
+const fleetMessages = drainInbox(info.dir);
+if (fleetMessages.length > 0) {
+  message += `\n\nFleet messages from the control terminal — acknowledge and act on these first:\n${fleetMessages
+    .map((m) => `- ${m.text}`)
+    .join('\n')}`;
+}
+
 switch (format) {
   case 'cursor':
     emitCursor(message);

package/src/set-phase.mjs

@@ -15,6 +15,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { loadSession, readActive, saveSession } from './lib.mjs';
+import { briefProblem, checkBrief } from './brief.mjs';
 import { runIntegrityChecks } from './integrity.mjs';
 import { writeSessionScorecard } from './score.mjs';
 
@@ -116,6 +117,33 @@ function maybeEscalatePaceForTaskCount() {
 
 maybeEscalatePaceForTaskCount();
 
+/**
+ * Hard gate: implementation may not start until the operator brief exists and
+ * matches the current specs — the plan-approval checkpoint is only as strong
+ * as the human's comprehension of it. `--allow-incomplete "<reason>"` records
+ * an honest skip.
+ */
+function enforceBriefGate() {
+  if (phase !== 'implement') return;
+  const result = checkBrief({ session });
+  if (result.ok) {
+    delete session.briefSkipped;
+    return;
+  }
+  if (allowIncomplete) {
+    session.briefSkipped = allowIncomplete;
+    return;
+  }
+  process.stderr.write(
+    `Cannot enter phase "implement":\n  - ${briefProblem(result)}\n` +
+      'Write the brief (see forge references/operator-brief.md), forge brief stamp, ' +
+      'or pass --allow-incomplete "<reason>".\n',
+  );
+  process.exit(1);
+}
+
+enforceBriefGate();
+
 /**
  * Refuse finish/done without verify evidence, full task completion, and a
  * clean integrity check (spine matrix, deferrals, product-loop evidence) —

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,23 +16,42 @@ 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. **Operator brief (mandatory)** — see [../references/operator-brief.md](../references/operator-brief.md):
+   write `openspec/changes/<change-name>/brief.html` — a plain-language,
+   self-contained HTML explanation of what will be built (mermaid diagrams
+   where helpful), then:
+
+   ```bash
+   forge brief stamp    # records specs hash + opens it in the operator's browser
+   ```
+
+   `forge phase implement` hard-refuses while the brief is missing or stale
+   (specs edited after stamping → rewrite affected sections and re-stamp).
 
-5. Update session:
+6. Update session:
    ```bash
    forge phase plan --plan-type openspec --openspec <change-name>
    forge phase implement --tasks-total <N>
    ```
    Count tasks from `tasks.md` checkboxes.
 
-6. Get user approval to proceed to implement (unless they already said "go").
+7. Get user approval to proceed to implement (unless they already said "go").
+   The brief (opened by `forge brief stamp`) is what the operator reviews.
 
 ## Session tracking
 

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

@@ -64,16 +64,34 @@ 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. **Operator brief (mandatory)** — see [../references/operator-brief.md](../references/operator-brief.md):
+   write `<specsDir>/changes/<change-name>/brief.html` — a plain-language,
+   self-contained HTML explanation of what will be built (mermaid diagrams
+   where helpful), then:
+
+   ```bash
+   forge brief stamp    # records specs hash + opens it in the operator's browser
+   ```
+
+   `forge phase implement` hard-refuses while the brief is missing or stale
+   (specs edited after stamping → rewrite affected sections and re-stamp).
 
-5. Update session:
+6. Update session:
 
    ```bash
    forge phase plan --plan-type specs --openspec <change-name>
@@ -83,7 +101,8 @@ OpenSpec propose flow without the vendor CLI. Change lives under
    Count tasks from `tasks.md` checkboxes. (`--openspec` carries the change
    name for both engines.)
 
-6. Get user approval on the artefacts before implementing (unless they already said "go").
+7. Get user approval on the artefacts before implementing (unless they already said "go").
+   The brief (opened by `forge brief stamp`) is what the operator reviews.
 
 ## Compatibility
 

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