@izkac/forgekit 0.3.7 → 0.3.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@izkac/forgekit",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "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/cleanup-sessions.mjs

@@ -19,6 +19,7 @@ import {
   sessionAgeDays,
 } from './lib.mjs';
 import { unregisterSession } from './lib/fleet.mjs';
+import { appendScorecardLedger } from './score.mjs';
 
 const args = new Set(process.argv.slice(2));
 const dryRun = args.has('--dry-run');
@@ -58,6 +59,17 @@ for (const entry of fs.readdirSync(SESSIONS_DIR, { withFileTypes: true })) {
 
   if (shouldRemove) {
     if (!dryRun) {
+      // Harvest the scorecard into the durable ledger before the session dir
+      // (and its scoring history) is erased. Covers sessions scored before
+      // the ledger existed; a no-op when the ledger already has the line.
+      try {
+        const cardFile = path.join(dir, 'scorecard.json');
+        if (fs.existsSync(cardFile)) {
+          appendScorecardLedger(dir, JSON.parse(fs.readFileSync(cardFile, 'utf8')), session);
+        }
+      } catch {
+        /* ledger is advisory — never block cleanup */
+      }
       fs.rmSync(dir, { recursive: true, force: true });
       if (isActive) clearActive();
       unregisterSession(process.cwd(), sessionId);

package/src/score.mjs

@@ -11,6 +11,8 @@ import path from 'node:path';
 import { readJson, writeJson } from './lib.mjs';
 import {
   JOBS_SIGNAL_RE,
+  checkE2eGate,
+  e2ePath,
   loadDeferrals,
   openDeferrals,
   resolveChangeDir,
@@ -110,10 +112,29 @@ function reviewSelfCheckCount(sessionDir) {
   return n;
 }
 
+/**
+ * True when a green e2e run was executed against the current e2e.json — the
+ * primary product-loop signal: score what ran, not what was written. A phrase
+ * match in verify-evidence is only the fallback (a session that titled its
+ * section differently but ran the loop green must not score 0).
+ *
+ * @param {{ cwd?: string, session?: Record<string, unknown> | null, sessionDir: string }} opts
+ */
+function e2eRunGreen(opts) {
+  try {
+    const e2eFile = e2ePath(opts);
+    const gate = checkE2eGate({ e2eFile, sessionDir: opts.sessionDir });
+    return gate.problems.length === 0 && !gate.notApplicable;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * @param {string} body
+ * @param {boolean} executedGreen
  */
-function scoreProductLoopBody(body) {
+function scoreProductLoopBody(body, executedGreen = false) {
   /** @type {string[]} */
   const notes = [];
   let pts = 0;
@@ -122,12 +143,16 @@ function scoreProductLoopBody(body) {
     notes.push('verify-evidence contains BLOCKED — product-loop not proven');
     return { points: 0, max, notes };
   }
-  if (!/product[- ]loop/i.test(body)) {
-    notes.push('no ## Product loop section');
+  if (executedGreen) {
+    pts += 8;
+    notes.push('green e2e run executed against current e2e.json — loop proven by execution');
+  } else if (/product[- ]loop/i.test(body)) {
+    pts += 8;
+    notes.push('product-loop section present (phrase-based — no executed green e2e run)');
+  } else {
+    notes.push('no executed green e2e run and no product-loop section in verify-evidence');
     return { points: 0, max, notes };
   }
-  pts += 8;
-  notes.push('product-loop section present');
   if (/\b(fixture|OP\d+|testdata|sample)\b/i.test(body)) {
     pts += 4;
     notes.push('names a fixture / corpus');
@@ -237,14 +262,15 @@ export function scoreSession(opts) {
     loopNotes = ['verify-evidence.md missing'];
   } else {
     const body = fs.readFileSync(evidenceFile, 'utf8');
+    const executedGreen = e2eRunGreen({ cwd, session, sessionDir });
     if (spineHasRows || JOBS_SIGNAL_RE.test(sessionJobsSignalText(session))) {
-      const scored = scoreProductLoopBody(body);
+      const scored = scoreProductLoopBody(body, executedGreen);
       loopPts = scored.points;
       loopNotes = scored.notes;
     } else {
       // Rows expected but maybe empty invalid spine — still look for loop
-      if (/product[- ]loop/i.test(body)) {
-        const scored = scoreProductLoopBody(body);
+      if (executedGreen || /product[- ]loop/i.test(body)) {
+        const scored = scoreProductLoopBody(body, executedGreen);
         loopPts = scored.points;
         loopNotes = scored.notes;
       } else {

package/src/score.test.mjs

@@ -11,9 +11,11 @@ import {
   scoreSession,
   writeSessionScorecard,
 } from './score.mjs';
+import { e2eStepsHash } from './integrity.mjs';
 
 const PHASE_SCRIPT = path.join(path.dirname(fileURLToPath(import.meta.url)), 'set-phase.mjs');
 const SCORE_SCRIPT = path.join(path.dirname(fileURLToPath(import.meta.url)), 'score-cli.mjs');
+const CLEANUP_SCRIPT = path.join(path.dirname(fileURLToPath(import.meta.url)), 'cleanup-sessions.mjs');
 
 function tmp(prefix) {
   return fs.mkdtempSync(path.join(tmpdir(), prefix));
@@ -177,6 +179,80 @@ Fixture: OP1086
   }
 });
 
+test('scoreSession: green e2e run proves the loop even without the phrase', () => {
+  const root = tmp('forge-score-e2e-');
+  try {
+    const { sessionDir, session } = makeSession(root, { slug: 'jobs-loop' });
+    fs.writeFileSync(
+      path.join(sessionDir, 'spine.json'),
+      `${JSON.stringify(validSpine([validRow()]), null, 2)}\n`,
+      'utf8',
+    );
+    // Evidence deliberately avoids the words "product loop" — before the fix
+    // this session scored 0/20 despite an executed green run.
+    fs.writeFileSync(
+      path.join(sessionDir, 'verify-evidence.md'),
+      '# Verify\n\n## What the evidence actually proves\n\nReverted the fix, reproduced the broken row, re-applied, ran the loop green.\n',
+      'utf8',
+    );
+    const steps = [{ name: 'probe', cmd: 'node -e "console.log(1)"' }];
+    fs.writeFileSync(
+      path.join(sessionDir, 'e2e.json'),
+      `${JSON.stringify({ change: null, notApplicable: null, steps }, null, 2)}\n`,
+      'utf8',
+    );
+    fs.writeFileSync(
+      path.join(sessionDir, 'e2e-results.json'),
+      `${JSON.stringify({ ok: true, stepsHash: e2eStepsHash(steps), steps: [{ name: 'probe', ok: true, exitCode: 0 }] }, null, 2)}\n`,
+      'utf8',
+    );
+    const card = scoreSession({ cwd: root, sessionDir, session });
+    const loop = card.checks.find((c) => c.id === 'product_loop');
+    assert.ok(loop.points >= 8, `expected >= 8 loop points, got ${loop.points}`);
+    assert.match(loop.notes.join('\n'), /proven by execution/);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('forge cleanup harvests scorecard.json into the ledger before pruning', () => {
+  const root = tmp('forge-cleanup-harvest-');
+  try {
+    const { sessionDir, session } = makeSession(root, { phase: 'done' });
+    // A scorecard as an older (pre-ledger) forgekit would have written it.
+    fs.writeFileSync(
+      path.join(sessionDir, 'scorecard.json'),
+      `${JSON.stringify({
+        scoredAt: '2026-06-01T00:00:00.000Z',
+        sessionId: session.id,
+        slug: session.slug,
+        openspecChange: null,
+        score: 83,
+        maxScore: 100,
+        grade: 'B',
+        integrityOk: true,
+        caps: [],
+        checks: [{ id: 'spine', label: 'Spine matrix quality', points: 20, max: 25, notes: ['one row thin'] }],
+      }, null, 2)}\n`,
+      'utf8',
+    );
+    execFileSync(process.execPath, [CLEANUP_SCRIPT, '--include-active'], {
+      cwd: root,
+      env: { ...process.env, FORGEKIT_FLEET_DIR: path.join(root, 'fleet') },
+    });
+    assert.equal(fs.existsSync(sessionDir), false);
+    const ledger = path.join(root, '.forge', 'scorecards.jsonl');
+    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, 'B');
+    assert.equal(entry.deductions[0].id, 'spine');
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
 test('writeSessionScorecard writes json and md', () => {
   const root = tmp('forge-score-write-');
   try {

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