@izkac/forgekit 0.3.5 → 0.3.7

package/README.md

@@ -32,7 +32,7 @@ Running agents across three IDEs and two terminals? `forge fleet` is a single co
 
 ```bash
 forge fleet list       # every session: phase, task progress, engine, activity
-forge fleet watch      # live-refreshing dashboard
+forge fleet watch      # live-refreshing dashboard (active sessions only; --all shows everything)
 forge fleet view <s>   # detail + live transcript tail (Claude Code)
 forge fleet send <s> "pause and report"   # message any session; --all broadcasts
 ```

package/package.json

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

package/src/e2e-cli.test.mjs

@@ -0,0 +1,75 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const E2E = path.join(path.dirname(fileURLToPath(import.meta.url)), 'e2e.mjs');
+
+function tmp(prefix) {
+  return fs.mkdtempSync(path.join(tmpdir(), prefix));
+}
+
+function run(cwd, args) {
+  return execFileSync(process.execPath, [E2E, ...args], {
+    cwd,
+    env: { ...process.env, FORGEKIT_FLEET_DIR: path.join(tmp('e2e-fleet-'), 's') },
+  }).toString();
+}
+
+/** .forge fixture with an active session tracking a specs change. */
+function makeFixture(root) {
+  const sessionDir = path.join(root, '.forge', 'sessions', 's1');
+  fs.mkdirSync(sessionDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(sessionDir, 'session.json'),
+    `${JSON.stringify({ id: 's1', slug: 'fixture', planType: 'specs', openspecChange: 'my-change' })}\n`,
+    'utf8',
+  );
+  fs.writeFileSync(
+    path.join(root, '.forge', 'active.json'),
+    `${JSON.stringify({ sessionId: 's1' })}\n`,
+    'utf8',
+  );
+  fs.mkdirSync(path.join(root, 'specs', 'changes', 'my-change'), { recursive: true });
+}
+
+test('e2e harness: record → show → surfaced by init; config keys preserved', () => {
+  const root = tmp('e2e-harness-');
+  makeFixture(root);
+  // Pre-existing config keys must survive the harness merge-write.
+  fs.writeFileSync(
+    path.join(root, '.forge', 'config.json'),
+    `${JSON.stringify({ plan: { engine: 'specs', dir: 'specs' } }, null, 2)}\n`,
+    'utf8',
+  );
+
+  assert.match(run(root, ['harness']), /No harness recorded/);
+
+  run(root, [
+    'harness',
+    '--set',
+    'compose test stack: server + scratch mongo on isolated ports',
+    '--start',
+    'npm run e2e:stack',
+    '--dir',
+    'scripts/e2e',
+  ]);
+
+  const cfg = JSON.parse(fs.readFileSync(path.join(root, '.forge', 'config.json'), 'utf8'));
+  assert.equal(cfg.plan.engine, 'specs');
+  assert.equal(cfg.e2e.harness.start, 'npm run e2e:stack');
+  assert.match(cfg.e2e.harness.description, /compose test stack/);
+
+  assert.match(run(root, ['harness']), /REUSE it — do not build/);
+  assert.match(run(root, ['init']), /REUSE it — do not build/);
+  assert.equal(JSON.parse(run(root, ['status'])).harness.dir, 'scripts/e2e');
+});
+
+test('e2e harness --set requires a description', () => {
+  const root = tmp('e2e-harness-req-');
+  makeFixture(root);
+  assert.throws(() => run(root, ['harness', '--set']), /Usage: forge e2e harness --set/);
+});

package/src/e2e.mjs

@@ -7,6 +7,8 @@
  *   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
+ *   forge e2e harness                 # show recorded project harness (reuse it!)
+ *   forge e2e harness --set "<desc>" [--start "<cmd>"] [--dir <path>]
  *   [--session <id>]
  *
  * e2e.json lives next to spine.json (change dir, falling back to the session
@@ -17,6 +19,7 @@
 
 import fs from 'node:fs';
 import { loadSession, readActive, readJson } from './lib.mjs';
+import { loadProjectConfig, saveProjectConfig } from './config.mjs';
 import {
   checkE2eGate,
   e2ePath,
@@ -34,11 +37,57 @@ 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',
+    'Usage: forge e2e [init [--force] | run | check | status | harness [--set <desc> --start <cmd> --dir <path>]] [--session <id>]\n',
   );
   process.exit(0);
 }
 
+/** Recorded project harness (committed in .forge/config.json → e2e.harness). */
+function loadHarness() {
+  const cfg = loadProjectConfig(process.cwd());
+  const h = cfg?.e2e?.harness;
+  return h && typeof h === 'object' ? h : null;
+}
+
+function harnessLines(h) {
+  const lines = [`Existing e2e harness (REUSE it — do not build or ask for a new one):`];
+  lines.push(`  ${h.description}`);
+  if (h.start) lines.push(`  Start: ${h.start}`);
+  if (h.dir) lines.push(`  Location: ${h.dir}`);
+  return lines.join('\n');
+}
+
+// Project-level, no session needed.
+if (sub === 'harness') {
+  const si = args.indexOf('--set');
+  if (si >= 0) {
+    const description = args[si + 1];
+    if (!description || description.startsWith('--')) {
+      process.stderr.write('Usage: forge e2e harness --set "<description>" [--start "<cmd>"] [--dir <path>]\n');
+      process.exit(1);
+    }
+    const harness = { description, recordedAt: new Date().toISOString() };
+    const st = args.indexOf('--start');
+    if (st >= 0 && args[st + 1]) harness.start = args[st + 1];
+    const di = args.indexOf('--dir');
+    if (di >= 0 && args[di + 1]) harness.dir = args[di + 1];
+    saveProjectConfig(process.cwd(), { e2e: { harness } }, { mergeKeys: ['adr', 'plan', 'e2e'] });
+    process.stdout.write(
+      `Recorded harness in .forge/config.json (commit it). Future sessions will see it on forge e2e init.\n`,
+    );
+    process.exit(0);
+  }
+  const h = loadHarness();
+  if (!h) {
+    process.stdout.write(
+      'No harness recorded. After building one (with operator approval), record it:\n  forge e2e harness --set "<what/where>" --start "<command>" [--dir <path>]\n',
+    );
+    process.exit(0);
+  }
+  process.stdout.write(`${harnessLines(h)}\n`);
+  process.exit(0);
+}
+
 let sessionId = null;
 let force = false;
 for (let i = 0; i < args.length; i += 1) {
@@ -74,6 +123,8 @@ if (sub === 'init') {
   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`,
   );
+  const harness = loadHarness();
+  if (harness) process.stdout.write(`\n${harnessLines(harness)}\n`);
   process.exit(0);
 }
 
@@ -133,7 +184,7 @@ if (sub === 'check') {
 
 if (sub === 'status') {
   if (!fs.existsSync(file)) {
-    process.stdout.write(JSON.stringify({ file, exists: false }, null, 2));
+    process.stdout.write(JSON.stringify({ file, exists: false, harness: loadHarness() }, null, 2));
     process.stdout.write('\n');
     process.exit(0);
   }
@@ -153,6 +204,7 @@ if (sub === 'status') {
         exists: true,
         ok: valid.ok,
         problems: valid.problems,
+        harness: loadHarness(),
         results: results
           ? {
               file: e2eResultsPath(dir),

package/src/fleet.mjs

@@ -5,11 +5,13 @@
  *
  * Usage:
  *   forge fleet list [--json]
- *   forge fleet watch [--interval <sec>]
+ *   forge fleet watch [--interval <sec>] [--all]
  *   forge fleet view <session> [--transcript [N]]
  *   forge fleet send <session>|--all <message...>
  *
  * <session> matches by sessionId, slug, or project name; must be unique.
+ * watch shows only active sessions (not done, session dir present); --all
+ * includes done/missing ones. list always shows everything.
  */
 
 import fs from 'node:fs';
@@ -27,7 +29,7 @@ function usage() {
   process.stderr.write(
     `Usage:
   forge fleet list [--json]
-  forge fleet watch [--interval <sec>]
+  forge fleet watch [--interval <sec>] [--all]
   forge fleet view <session> [--transcript [N]]
   forge fleet send <session>|--all <message...>
 `,
@@ -78,7 +80,7 @@ function renderTable(entries) {
       `${pad(e.projectName, 18)} ${pad(e.slug, 26)} ${pad(e.engine ?? '—', 7)} ${pad(
         e.missing ? 'missing' : phaseBar(e.phase),
         18,
-      )} ${pad(tasksCell(e), 13)} ${pad(e.pace ?? '—', 9)} ${pad(relTime(e.updatedAt), 4)} ${
+      )} ${pad(tasksCell(e), 13)} ${pad(e.pace ?? '—', 9)} ${pad(relTime(e.lastSeen ?? e.updatedAt), 4)} ${
         pending > 0 ? `✉ ${pending}` : ''
       }`,
     );
@@ -121,10 +123,14 @@ function cmdList(args) {
 function cmdWatch(args) {
   const i = args.indexOf('--interval');
   const interval = Math.max(1, Number(i >= 0 ? args[i + 1] : 3) || 3) * 1000;
+  const all = args.includes('--all');
   const render = () => {
+    const entries = listFleet().filter((e) => all || (!e.missing && e.phase !== 'done'));
     process.stdout.write('\x1b[2J\x1b[H');
-    process.stdout.write(`forge fleet — ${new Date().toLocaleTimeString()} (Ctrl+C to exit)\n\n`);
-    process.stdout.write(renderTable(listFleet()));
+    process.stdout.write(
+      `forge fleet — ${new Date().toLocaleTimeString()} (Ctrl+C to exit${all ? '' : ', --all for done/missing'})\n\n`,
+    );
+    process.stdout.write(renderTable(entries));
   };
   render();
   setInterval(render, interval);

package/src/fleet.test.mjs

@@ -9,10 +9,13 @@ import {
   drainInbox,
   entryFile,
   listFleet,
+  LIVE_WINDOW_MS,
+  liveOverlaps,
   peekInbox,
   queueMessage,
   registerSession,
   sanitizePath,
+  touchSession,
   unregisterSession,
 } from './lib/fleet.mjs';
 import { saveSession } from './lib.mjs';
@@ -132,6 +135,47 @@ function registerSessionIn(fleetDir, project, session) {
   }
 }
 
+test('registerSession stamps lastSeen; touchSession refreshes it', () => {
+  process.env.FORGEKIT_FLEET_DIR = path.join(tmp('fleet-hb-'), 'sessions');
+  const project = tmp('fleet-proj-');
+  makeProject(project, 's5');
+
+  registerSession(project, makeSession('s5'));
+  const before = listFleet()[0].lastSeen;
+  assert.ok(before);
+
+  const file = entryFile(project, 's5');
+  const entry = JSON.parse(fs.readFileSync(file, 'utf8'));
+  entry.lastSeen = '2000-01-01T00:00:00.000Z';
+  fs.writeFileSync(file, JSON.stringify(entry));
+
+  touchSession(project, 's5');
+  const after = listFleet()[0].lastSeen;
+  assert.ok(after > '2000-01-01T00:00:00.000Z');
+});
+
+test('liveOverlaps flags only live sessions in the same project', () => {
+  process.env.FORGEKIT_FLEET_DIR = path.join(tmp('fleet-ovl-'), 'sessions');
+  const project = tmp('fleet-proj-');
+  const other = tmp('fleet-proj2-');
+  for (const id of ['me', 'peer', 'finished']) makeProject(project, id);
+  makeProject(other, 'elsewhere');
+
+  registerSession(project, makeSession('me'));
+  registerSession(project, makeSession('peer'));
+  registerSession(project, makeSession('finished', { phase: 'done' }));
+  registerSession(other, makeSession('elsewhere'));
+
+  const overlaps = liveOverlaps(project, 'me');
+  assert.deepEqual(
+    overlaps.map((e) => e.sessionId),
+    ['peer'],
+  );
+
+  // Stale heartbeat falls outside the liveness window.
+  assert.equal(liveOverlaps(project, 'me', Date.now() + LIVE_WINDOW_MS + 1000).length, 0);
+});
+
 test('sanitizePath matches Claude Code project-dir naming', () => {
   assert.equal(sanitizePath('S:\\Projects\\forgekit'), 'S--Projects-forgekit');
 });

package/src/lib/fleet.mjs

@@ -82,6 +82,7 @@ export function registerSession(projectRoot, session) {
       engine: detectEngine() ?? prev.engine ?? null,
       createdAt: session.createdAt,
       updatedAt: session.updatedAt,
+      lastSeen: new Date().toISOString(),
     };
     fs.mkdirSync(fleetDir(), { recursive: true });
     fs.writeFileSync(file, `${JSON.stringify(entry, null, 2)}\n`, 'utf8');
@@ -90,6 +91,40 @@ export function registerSession(projectRoot, session) {
   }
 }
 
+/**
+ * Heartbeat: refresh lastSeen on an existing registry entry. Called from the
+ * reminder hook, which fires on every agent turn — so lastSeen ≈ "agent is
+ * actually running", unlike updatedAt which only moves on saveSession.
+ */
+export function touchSession(projectRoot, sessionId) {
+  try {
+    const file = entryFile(projectRoot, sessionId);
+    const entry = JSON.parse(fs.readFileSync(file, 'utf8'));
+    entry.lastSeen = new Date().toISOString();
+    fs.writeFileSync(file, `${JSON.stringify(entry, null, 2)}\n`, 'utf8');
+  } catch {
+    /* advisory */
+  }
+}
+
+// ponytail: fixed 30-min liveness window; make configurable if hooks ever fire slower.
+export const LIVE_WINDOW_MS = 30 * 60 * 1000;
+
+/**
+ * Other live sessions in the same project — the overlap signal for "two
+ * agents editing one working tree". Live = not done, session dir present,
+ * heartbeat (lastSeen, falling back to updatedAt) within LIVE_WINDOW_MS.
+ */
+export function liveOverlaps(projectRoot, sessionId, now = Date.now()) {
+  const root = path.resolve(projectRoot);
+  return listFleet().filter((e) => {
+    if (e.sessionId === sessionId || e.missing || e.phase === 'done') return false;
+    if (path.resolve(e.project) !== root) return false;
+    const seen = new Date(e.lastSeen ?? e.updatedAt).getTime();
+    return !Number.isNaN(seen) && now - seen < LIVE_WINDOW_MS;
+  });
+}
+
 export function unregisterSession(projectRoot, sessionId) {
   try {
     fs.rmSync(entryFile(projectRoot, sessionId), { force: true });

package/src/new-session.mjs

@@ -20,6 +20,7 @@ import {
 } from './lib.mjs';
 import { resolveSessionPaceFields } from './preferences.mjs';
 import { warnIfDoctorFails } from './doctor.mjs';
+import { liveOverlaps, queueMessage, sessionDirFor } from './lib/fleet.mjs';
 
 function usage() {
   process.stderr.write(
@@ -64,19 +65,35 @@ Object.assign(session, paceFields);
 saveSession(dir, session);
 writeActive(sessionId);
 
-process.stdout.write(
-  `${JSON.stringify(
-    {
-      sessionId,
-      dir,
-      session: defaultStatus(session),
-      pace: {
-        requested: session.pace,
-        resolved: session.resolvedPace,
-        reason: session.paceReason,
-      },
-    },
-    null,
-    2,
-  )}\n`,
-);
+// Fleet coordination: another live session in this working tree risks
+// conflicting edits — surface it here and notify the other sessions' inboxes.
+const overlaps = liveOverlaps(process.cwd(), sessionId);
+for (const o of overlaps) {
+  queueMessage(
+    sessionDirFor(o),
+    `Fleet overlap: session "${session.slug}" (${sessionId}) just started in this project. Coordinate with the user to avoid conflicting edits.`,
+  );
+}
+
+const out = {
+  sessionId,
+  dir,
+  session: defaultStatus(session),
+  pace: {
+    requested: session.pace,
+    resolved: session.resolvedPace,
+    reason: session.paceReason,
+  },
+};
+if (overlaps.length > 0) {
+  out.overlaps = overlaps.map((o) => ({
+    sessionId: o.sessionId,
+    slug: o.slug,
+    phase: o.phase,
+    engine: o.engine,
+    lastSeen: o.lastSeen ?? o.updatedAt,
+  }));
+  out.overlapAdvice =
+    'Other live sessions are working in this project. Tell the user and ask: continue anyway, use a git worktree, or pause one session.';
+}
+process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);

package/src/score.mjs

@@ -475,7 +475,52 @@ export function formatScorecardMarkdown(card) {
 }
 
 /**
- * Write scorecard.json + scorecard.md into the session dir.
+ * Durable one-line-per-session ledger at `.forge/scorecards.jsonl`. Sessions
+ * are pruned after RETENTION_DAYS and scorecards die with them; the ledger
+ * survives — it is the history `/forge:analyze` reads for trends. Re-scoring
+ * a session replaces its line (latest score wins). Never throws.
+ *
+ * @param {string} sessionDir
+ * @param {ReturnType<typeof scoreSession>} card
+ * @param {Record<string, unknown>} session
+ */
+export function appendScorecardLedger(sessionDir, card, session = {}) {
+  try {
+    const file = path.join(path.resolve(sessionDir, '..', '..'), 'scorecards.jsonl');
+    const line = {
+      scoredAt: card.scoredAt,
+      sessionId: card.sessionId,
+      slug: card.slug,
+      change: card.openspecChange,
+      score: card.score,
+      grade: card.grade,
+      integrityOk: card.integrityOk,
+      pace: session.resolvedPace ?? null,
+      incompleteReason: session.incompleteReason ?? null,
+      caps: card.caps,
+      deductions: card.checks
+        .filter((c) => c.points < c.max)
+        .map((c) => ({ id: c.id, points: c.points, max: c.max, notes: c.notes })),
+    };
+    const kept = (fs.existsSync(file) ? fs.readFileSync(file, 'utf8').split('\n') : [])
+      .filter(Boolean)
+      .filter((l) => {
+        try {
+          return JSON.parse(l).sessionId !== card.sessionId;
+        } catch {
+          return false;
+        }
+      });
+    kept.push(JSON.stringify(line));
+    fs.writeFileSync(file, `${kept.join('\n')}\n`, 'utf8');
+  } catch {
+    /* ledger is advisory — never block a scorecard write */
+  }
+}
+
+/**
+ * Write scorecard.json + scorecard.md into the session dir, and mirror a
+ * summary line into the durable `.forge/scorecards.jsonl` ledger.
  *
  * @param {{ cwd?: string, sessionDir: string, session: Record<string, unknown> }} opts
  */
@@ -485,5 +530,6 @@ export function writeSessionScorecard(opts) {
   const mdPath = path.join(opts.sessionDir, 'scorecard.md');
   writeJson(jsonPath, card);
   fs.writeFileSync(mdPath, formatScorecardMarkdown(card), 'utf8');
+  appendScorecardLedger(opts.sessionDir, card, opts.session);
   return { card, jsonPath, mdPath };
 }

package/src/score.test.mjs

@@ -191,6 +191,17 @@ test('writeSessionScorecard writes json and md', () => {
     assert.equal(fs.existsSync(jsonPath), true);
     assert.equal(fs.existsSync(mdPath), true);
     assert.equal(JSON.parse(fs.readFileSync(jsonPath, 'utf8')).grade, card.grade);
+
+    // Durable ledger: one line per session, re-scoring replaces (not appends).
+    const ledger = path.join(root, '.forge', 'scorecards.jsonl');
+    assert.equal(fs.existsSync(ledger), true);
+    writeSessionScorecard({ cwd: root, sessionDir, session });
+    const lines = fs.readFileSync(ledger, 'utf8').split('\n').filter(Boolean);
+    assert.equal(lines.length, 1);
+    const entry = JSON.parse(lines[0]);
+    assert.equal(entry.sessionId, session.id);
+    assert.equal(entry.grade, card.grade);
+    assert.ok(Array.isArray(entry.deductions));
   } finally {
     fs.rmSync(root, { recursive: true, force: true });
   }

package/src/session-reminder.mjs

@@ -8,8 +8,14 @@
  *   forge reminder --format plain
  */
 
-import { FORGE_DIR, loadSession, readActive } from './lib.mjs';
-import { drainInbox } from './lib/fleet.mjs';
+import { FORGE_DIR, loadSession, readActive, REPO_ROOT } from './lib.mjs';
+import {
+  drainInbox,
+  liveOverlaps,
+  queueMessage,
+  sessionDirFor,
+  touchSession,
+} from './lib/fleet.mjs';
 import { resolveEffectivePreferences } from './preferences.mjs';
 
 function getActiveSessionInfo() {
@@ -149,10 +155,32 @@ if (!info) {
   process.exit(0);
 }
 
+// Fleet heartbeat: this hook fires on every agent turn, so lastSeen in the
+// registry tracks "agent actually running", not just the last saveSession.
+touchSession(REPO_ROOT, info.session.id);
+
 let message = prompt
   ? buildForgePromptMessage(info, prompt)
   : buildForgeMessage(info);
 
+// Overlap check on resume: another live session in this same working tree
+// means potentially conflicting edits. Warn this agent and drop a note in the
+// other sessions' inboxes. Session-start only — per-turn would spam.
+if (format === 'claude-session-start') {
+  const overlaps = liveOverlaps(REPO_ROOT, info.session.id);
+  if (overlaps.length > 0) {
+    message += `\n\nFleet overlap — other live session(s) in this project:\n${overlaps
+      .map((o) => `- ${o.slug} (${o.sessionId}) · ${o.engine ?? 'unknown'} · phase ${o.phase}`)
+      .join('\n')}\nTell the user and ask how to proceed: continue anyway, move this work to a git worktree, or pause one session.`;
+    for (const o of overlaps) {
+      queueMessage(
+        sessionDirFor(o),
+        `Fleet overlap: session "${info.session.slug}" (${info.session.id}) just resumed in this project. Coordinate with the user to avoid conflicting edits.`,
+      );
+    }
+  }
+}
+
 // 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.

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

@@ -246,6 +246,8 @@ required for correctness.
 | `/forge:apply` | **Tracked-change implement** — subagent TDD + verify + review (preferred over `/opsx:apply`) |
 | `/forge:build` | Implement phase (`tasks.md` from either engine) |
 | `/forge:status` | Show active session progress |
+| `/forge:harness` | Ensure a working, recorded project e2e harness (build proactively) |
+| `/forge:analyze` | Agent-written improvement report over recent sessions |
 | `/forge:skip` | **Explicit** opt-out of Forge for this task |
 
 OpenSpec commands remain available standalone (OpenSpec-engine projects):
@@ -624,6 +626,8 @@ per machine with `forgekit install`; wire project commands/hooks with `forge ini
 | `/forge:apply` | Tracked-change implement + verify + review (preferred) |
 | `/forge:build` | Implement phase (`tasks.md` from either engine) |
 | `/forge:status` | Session progress |
+| `/forge:harness` | Ensure a working, recorded project e2e harness |
+| `/forge:analyze` | Improvement report over recent sessions |
 | `/forge:skip` | Explicit skip for this task |
 
 ### Codex CLI

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

@@ -98,6 +98,18 @@ cost instead:
   fixture-level work is over-asking; skipping the loop because the rig is
   missing is under-testing — the ask is exactly the moment the operator can
   say "build it once" and make every future loop on the project cheap.
+- **A built harness is permanent project infrastructure — record it, reuse
+  it.** When the operator approves building one: build it as committed
+  project code (never session scratch), then record it:
+
+  ```bash
+  forge e2e harness --set "<what it is / where>" --start "<start command>" [--dir <path>]
+  ```
+
+  This lands in `.forge/config.json` (committed), and every later session
+  sees it — `forge e2e init` and `forge e2e status` print the recorded
+  harness. Check `forge e2e harness` before proposing to build or asking the
+  operator; proposing a new rig while one is recorded is a REJECT.
 - **One executed loop per capability, not per assertion.** Push edge cases
   into unit tests; e2e proves the wiring exists.
 - **Set `timeoutMs` from the step count up front.** A 10-step loop is never a

package/vendor/templates/project/claude/commands/forge-analyze.md

@@ -0,0 +1,42 @@
+---
+name: /forge:analyze
+description: Forge — analyze recent sessions and write an improvement report
+category: Workflow
+tags: [workflow, forge, retrospective]
+---
+
+**Forge-owned command.** Read the evidence recent Forge sessions left behind and write an honest improvement report — what went well, what keeps going wrong, and what to change. The analysis is yours: look for patterns, not single events.
+
+## 1. Gather
+
+- `.forge/scorecards.jsonl` — durable one-line-per-session ledger (score, grade, deductions, caps, pace, incomplete reasons). Survives session cleanup; this is your history.
+- `.forge/sessions/*/` for sessions still on disk: `scorecard.md`, `verify-evidence.md`, `reviews/final-review.md`, `deferrals.json`, `session.json`.
+
+If both are empty, tell the user there is nothing to analyze yet and stop.
+
+## 2. Analyze
+
+Patterns worth hunting (not a checklist — follow what the data shows):
+
+- **Recurring deductions** — the same check losing points across sessions is a process problem, not a session problem.
+- **`--allow-incomplete` usage** — legitimate deferrals, or the gate being routinely dodged? Read the reasons.
+- **Pace vs outcome** — do brisk/lite sessions score worse here? Are task-count escalations firing when they should?
+- **Evidence honesty** — ceremony-only tests, evidence with non-zero exits, verify phases that re-ran nothing.
+- **Deferrals** — raised vs resolved; anything raised repeatedly for the same area?
+- **Grade trend** — improving, flat, or decaying over time?
+
+For each pattern found: name the root cause and one concrete fix — a pace pref, a missing harness, a rule, a habit. No generic advice.
+
+## 3. Report
+
+Write `.forge/reports/analysis-<YYYY-MM-DD>.md`:
+
+- **TL;DR** — 3 bullets max
+- **Trend table** — session · date · grade · top deduction
+- **What's working** — keep doing
+- **What's broken** — each item with its concrete fix
+- **Next actions** — ranked, smallest-effective first
+
+Then summarize the TL;DR to the user in chat.
+
+Reference: `~/.claude/skills/forge/docs/forge.md`

package/vendor/templates/project/claude/commands/forge-harness.md

@@ -0,0 +1,41 @@
+---
+name: /forge:harness
+description: Forge — ensure the project has a working, recorded e2e harness
+category: Workflow
+tags: [workflow, forge, e2e]
+---
+
+**Forge-owned command.** Ensure this project has a working, recorded e2e harness — the environment `forge e2e run` steps execute against, and the base for the project's own end-to-end testing. Building it proactively here means later sessions never stall at the integrity gate waiting for one.
+
+## 1. Check what's recorded
+
+```bash
+forge e2e harness
+```
+
+- **Harness shown** → verify it still works: run its start command, then one real probe against it. Working → report to the user and stop. Broken → continue to step 2, treating the existing harness as the starting point (fix, don't rebuild).
+- **"No harness recorded"** → step 2.
+
+## 2. Design it with the operator
+
+Explore the project first: how the app starts, what backing services it needs, and what a real user-visible probe looks like (HTTP endpoint, CLI invocation, UI route). Then propose to the user:
+
+- what the harness starts (app + backing services, isolated ports/data so it can't touch dev state)
+- how a test asserts *through the product* (the probe `forge e2e` steps will use — not internal function calls)
+- where it lives (e.g. `scripts/e2e/`, a compose file, a test config)
+
+**Get explicit approval before building.** A harness is committed project infrastructure, not session scratch.
+
+## 3. Build and prove
+
+Build the approved harness. Prove it end-to-end: start it, run one real probe, show the user the output. A harness that has never gone green is not done.
+
+## 4. Record it
+
+```bash
+forge e2e harness --set "<what/where>" --start "<command>" [--dir <path>]
+```
+
+Then commit `.forge/config.json`. Every future session sees the harness on `forge e2e init` and reuses it instead of rebuilding or asking again.
+
+Reference: `~/.claude/skills/forge/docs/forge.md`

package/vendor/templates/project/claude/commands/forge.md

@@ -13,4 +13,4 @@ Read and follow the Forge skill (`~/.claude/skills/forge/SKILL.md`) and `~/.clau
 2. Resume from `.forge/active.json` or `forge new <slug>`
 3. Continue from current `phase` in `session.json`
 
-Subcommands: `/forge:brainstorm`, `/forge:plan`, `/forge:apply`, `/forge:build`, `/forge:status`, `/forge:skip`
+Subcommands: `/forge:brainstorm`, `/forge:plan`, `/forge:apply`, `/forge:build`, `/forge:status`, `/forge:harness`, `/forge:analyze`, `/forge:skip`

package/vendor/templates/project/cursor/commands/forge-analyze.md

@@ -0,0 +1,42 @@
+---
+name: /forge:analyze
+id: forge-analyze
+category: Workflow
+description: Forge — analyze recent sessions and write an improvement report
+---
+
+**Forge-owned command.** Read the evidence recent Forge sessions left behind and write an honest improvement report — what went well, what keeps going wrong, and what to change. The analysis is yours: look for patterns, not single events.
+
+## 1. Gather
+
+- `.forge/scorecards.jsonl` — durable one-line-per-session ledger (score, grade, deductions, caps, pace, incomplete reasons). Survives session cleanup; this is your history.
+- `.forge/sessions/*/` for sessions still on disk: `scorecard.md`, `verify-evidence.md`, `reviews/final-review.md`, `deferrals.json`, `session.json`.
+
+If both are empty, tell the user there is nothing to analyze yet and stop.
+
+## 2. Analyze
+
+Patterns worth hunting (not a checklist — follow what the data shows):
+
+- **Recurring deductions** — the same check losing points across sessions is a process problem, not a session problem.
+- **`--allow-incomplete` usage** — legitimate deferrals, or the gate being routinely dodged? Read the reasons.
+- **Pace vs outcome** — do brisk/lite sessions score worse here? Are task-count escalations firing when they should?
+- **Evidence honesty** — ceremony-only tests, evidence with non-zero exits, verify phases that re-ran nothing.
+- **Deferrals** — raised vs resolved; anything raised repeatedly for the same area?
+- **Grade trend** — improving, flat, or decaying over time?
+
+For each pattern found: name the root cause and one concrete fix — a pace pref, a missing harness, a rule, a habit. No generic advice.
+
+## 3. Report
+
+Write `.forge/reports/analysis-<YYYY-MM-DD>.md`:
+
+- **TL;DR** — 3 bullets max
+- **Trend table** — session · date · grade · top deduction
+- **What's working** — keep doing
+- **What's broken** — each item with its concrete fix
+- **Next actions** — ranked, smallest-effective first
+
+Then summarize the TL;DR to the user in chat.
+
+Reference: `~/.cursor/skills/forge/docs/forge.md`

package/vendor/templates/project/cursor/commands/forge-harness.md

@@ -0,0 +1,41 @@
+---
+name: /forge:harness
+id: forge-harness
+category: Workflow
+description: Forge — ensure the project has a working, recorded e2e harness
+---
+
+**Forge-owned command.** Ensure this project has a working, recorded e2e harness — the environment `forge e2e run` steps execute against, and the base for the project's own end-to-end testing. Building it proactively here means later sessions never stall at the integrity gate waiting for one.
+
+## 1. Check what's recorded
+
+```bash
+forge e2e harness
+```
+
+- **Harness shown** → verify it still works: run its start command, then one real probe against it. Working → report to the user and stop. Broken → continue to step 2, treating the existing harness as the starting point (fix, don't rebuild).
+- **"No harness recorded"** → step 2.
+
+## 2. Design it with the operator
+
+Explore the project first: how the app starts, what backing services it needs, and what a real user-visible probe looks like (HTTP endpoint, CLI invocation, UI route). Then propose to the user:
+
+- what the harness starts (app + backing services, isolated ports/data so it can't touch dev state)
+- how a test asserts *through the product* (the probe `forge e2e` steps will use — not internal function calls)
+- where it lives (e.g. `scripts/e2e/`, a compose file, a test config)
+
+**Get explicit approval before building.** A harness is committed project infrastructure, not session scratch.
+
+## 3. Build and prove
+
+Build the approved harness. Prove it end-to-end: start it, run one real probe, show the user the output. A harness that has never gone green is not done.
+
+## 4. Record it
+
+```bash
+forge e2e harness --set "<what/where>" --start "<command>" [--dir <path>]
+```
+
+Then commit `.forge/config.json`. Every future session sees the harness on `forge e2e init` and reuses it instead of rebuilding or asking again.
+
+Reference: `~/.cursor/skills/forge/docs/forge.md`

package/vendor/templates/project/cursor/commands/forge.md

@@ -13,4 +13,4 @@ Read and follow the Forge skill (`~/.cursor/skills/forge/SKILL.md`) and `~/.curs
 2. Resume from `.forge/active.json` or `forge new <slug>`
 3. Continue from current `phase` in `session.json`
 
-Subcommands: `/forge:brainstorm`, `/forge:plan`, `/forge:apply`, `/forge:build`, `/forge:status`, `/forge:skip`
+Subcommands: `/forge:brainstorm`, `/forge:plan`, `/forge:apply`, `/forge:build`, `/forge:status`, `/forge:harness`, `/forge:analyze`, `/forge:skip`