@izkac/forgekit 0.3.6 → 0.3.8

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.6",
+  "version": "0.3.8",
   "description": "Forgekit CLIs — forgekit (install), forge (workflow), review (code review)",
   "type": "module",
   "bin": {

package/src/brief-cli.mjs

@@ -3,9 +3,9 @@
  * Operator-brief CLI (core in brief.mjs).
  *
  * Usage:
- *   forge brief stamp [--session <id>] [--no-open]   stamp freshness hash + open in browser
- *   forge brief check [--session <id>]               exit 1 when missing/stale/unstamped
- *   forge brief open  [--session <id>]               open in default browser
+ *   forge brief stamp [--session <id>]   stamp freshness hash (never auto-opens)
+ *   forge brief check [--session <id>]   exit 1 when missing/stale/unstamped
+ *   forge brief open  [--session <id>]   open in default browser (explicit only)
  */
 
 import fs from 'node:fs';
@@ -16,7 +16,7 @@ import { BRIEF_FILE, briefPath, checkBrief, openInBrowser, stampBrief } from './
 const [cmd, ...rest] = process.argv.slice(2);
 if (!cmd || !['stamp', 'check', 'open'].includes(cmd)) {
   process.stderr.write(
-    'Usage: forge brief stamp [--session <id>] [--no-open] | check [--session <id>] | open [--session <id>]\n',
+    'Usage: forge brief stamp [--session <id>] | check [--session <id>] | open [--session <id>]\n',
   );
   process.exit(1);
 }
@@ -45,12 +45,13 @@ if (!changeDir) {
 }
 
 if (cmd === 'stamp') {
+  // Never auto-open: re-stamps happen several times a session and each open
+  // stole the operator's focus. `forge brief open` is the explicit opt-in.
   const hash = stampBrief(changeDir);
   process.stdout.write(`Stamped ${briefPath(changeDir)} (specs hash ${hash})\n`);
-  if (!rest.includes('--no-open')) {
-    openInBrowser(briefPath(changeDir));
-    process.stdout.write('Opened in default browser.\n');
-  }
+  process.stdout.write(
+    `Operator: review the brief at ${briefPath(changeDir)} — open it with \`forge brief open\`.\n`,
+  );
 } else {
   const file = briefPath(changeDir);
   if (!fs.existsSync(file)) {

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/phases/plan-openspec.md

@@ -37,7 +37,7 @@ Thin wrapper around the project **`openspec-propose`** skill (or `/opsx:propose`
    where helpful), then:
 
    ```bash
-   forge brief stamp    # records specs hash + opens it in the operator's browser
+   forge brief stamp    # records specs hash (does NOT auto-open)
    ```
 
    `forge phase implement` hard-refuses while the brief is missing or stale
@@ -51,7 +51,8 @@ Thin wrapper around the project **`openspec-propose`** skill (or `/opsx:propose`
    Count tasks from `tasks.md` checkboxes.
 
 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.
+   The brief is what the operator reviews — tell them its path and that
+   `forge brief open` launches it; never open it for them.
 
 ## Session tracking
 

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

@@ -85,7 +85,7 @@ OpenSpec propose flow without the vendor CLI. Change lives under
    where helpful), then:
 
    ```bash
-   forge brief stamp    # records specs hash + opens it in the operator's browser
+   forge brief stamp    # records specs hash (does NOT auto-open)
    ```
 
    `forge phase implement` hard-refuses while the brief is missing or stale
@@ -102,7 +102,8 @@ OpenSpec propose flow without the vendor CLI. Change lives under
    name for both engines.)
 
 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.
+   The brief is what the operator reviews — tell them its path and that
+   `forge brief open` launches it; never open it for them.
 
 ## Compatibility
 

package/vendor/skills/forge/references/operator-brief.md

@@ -21,7 +21,8 @@ freshness and opens the file.
 ```bash
 # 1. specs are final (proposal.md / design.md / tasks.md)
 # 2. write <changeDir>/brief.html   (structure below)
-forge brief stamp        # records specs hash + opens it in the operator's browser
+forge brief stamp        # records specs hash — tell the operator where the brief is
+                         # (it is NOT auto-opened; they can run `forge brief open`)
 forge phase implement --tasks-total <N>   # hard-gated on a fresh stamped brief
 ```
 

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`