@izkac/forgekit 0.3.14 → 0.3.16

package/src/health.test.mjs

@@ -0,0 +1,138 @@
+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 { DEFAULT_IDLE_HOURS, sessionHealth } from './health.mjs';
+import { e2eStepsHash } from './integrity.mjs';
+
+function tmp(prefix) {
+  return fs.realpathSync(fs.mkdtempSync(path.join(tmpdir(), prefix)));
+}
+
+const HOUR = 3600 * 1000;
+const NOW = new Date('2026-07-25T12:00:00.000Z').getTime();
+const ago = (hours) => new Date(NOW - hours * HOUR).toISOString();
+
+/** Project + session dir; session.json is passed separately. */
+function makeProject(overrides = {}) {
+  const cwd = tmp('forge-health-');
+  const sessionDir = path.join(cwd, '.forge', 'sessions', 's1');
+  fs.mkdirSync(sessionDir, { recursive: true });
+  const session = {
+    id: 's1',
+    slug: 'phase-1',
+    phase: 'implement',
+    planType: 'specs',
+    openspecChange: 'phase-1',
+    tasksTotal: 32,
+    tasksComplete: 27,
+    createdAt: ago(30),
+    updatedAt: ago(1),
+    ...overrides,
+  };
+  return { cwd, sessionDir, session };
+}
+
+/** e2e.json in the change dir + a results file in the session dir. */
+function writeE2e({ cwd, sessionDir }, { ok, stale = false, ranAt = ago(2) } = {}) {
+  const changeDir = path.join(cwd, 'specs', 'changes', 'phase-1');
+  fs.mkdirSync(changeDir, { recursive: true });
+  const steps = [{ name: 'bench-check-enforces-the-budget-gate', cmd: 'true' }];
+  fs.writeFileSync(path.join(changeDir, 'e2e.json'), `${JSON.stringify({ steps })}\n`, 'utf8');
+  // stepsHash is computed by integrity.e2eStepsHash; a wrong hash is what a
+  // post-run edit of e2e.json looks like.
+  const results = {
+    ok,
+    ranAt,
+    stepsHash: stale ? 'deadbeef' : e2eStepsHash(steps),
+    steps: [{ name: 'bench-check-enforces-the-budget-gate', ok, exitCode: ok ? 0 : 1 }],
+  };
+  fs.writeFileSync(
+    path.join(sessionDir, 'e2e-results.json'),
+    `${JSON.stringify(results)}\n`,
+    'utf8',
+  );
+  return changeDir;
+}
+
+test('a session that ran recently and has no failing proof is healthy', () => {
+  const p = makeProject();
+  const health = sessionHealth({ ...p, now: NOW });
+  assert.equal(health.state, 'healthy');
+  assert.deepEqual(health.reasons, []);
+  assert.match(health.line, /^HEALTHY/);
+});
+
+test('a failing e2e run is RED and names the failing step', () => {
+  // helm phase-1: 27/32 with e2e red on the bench budget gate, and nothing
+  // anywhere said so.
+  const p = makeProject();
+  writeE2e(p, { ok: false });
+  const health = sessionHealth({ ...p, now: NOW });
+
+  assert.equal(health.state, 'red');
+  assert.equal(health.reasons.length, 1);
+  assert.match(health.reasons[0], /e2e failing/);
+  assert.match(health.reasons[0], /bench-check-enforces-the-budget-gate/);
+  assert.match(health.line, /^RED —/);
+});
+
+test('e2e results that no longer match e2e.json are stale, not green', () => {
+  const p = makeProject();
+  writeE2e(p, { ok: true, stale: true });
+  const health = sessionHealth({ ...p, now: NOW });
+
+  assert.equal(health.state, 'stale');
+  assert.match(health.reasons.join(' '), /e2e results.*stale|stale.*e2e/i);
+});
+
+test('a green current e2e run keeps the session healthy', () => {
+  const p = makeProject();
+  writeE2e(p, { ok: true });
+  assert.equal(sessionHealth({ ...p, now: NOW }).state, 'healthy');
+});
+
+test('an idle session is STALE and says where it stopped', () => {
+  const p = makeProject({ updatedAt: ago(14) });
+  const health = sessionHealth({ ...p, now: NOW });
+
+  assert.equal(health.state, 'stale');
+  assert.match(health.reasons[0], /idle 14h/);
+  assert.match(health.reasons[0], /implement 27\/32/);
+});
+
+test('idle threshold is configurable and defaults to DEFAULT_IDLE_HOURS', () => {
+  const p = makeProject({ updatedAt: ago(DEFAULT_IDLE_HOURS + 1) });
+  assert.equal(sessionHealth({ ...p, now: NOW }).state, 'stale');
+  assert.equal(sessionHealth({ ...p, now: NOW, idleHours: 48 }).state, 'healthy');
+});
+
+test('BLOCKED verify evidence is RED', () => {
+  const p = makeProject({ phase: 'verify' });
+  fs.writeFileSync(
+    path.join(p.sessionDir, 'verify-evidence.md'),
+    '# Verify\n\n## Product loop\n\nBLOCKED — the queue worker has no runtime owner yet.\n',
+    'utf8',
+  );
+  const health = sessionHealth({ ...p, now: NOW });
+  assert.equal(health.state, 'red');
+  assert.match(health.reasons.join(' '), /BLOCKED/);
+});
+
+test('a finished session is neither stale nor red', () => {
+  // Idle for a month and carrying an old failing run: done is done.
+  const p = makeProject({ phase: 'done', updatedAt: ago(720), tasksComplete: 32 });
+  writeE2e(p, { ok: false });
+  const health = sessionHealth({ ...p, now: NOW });
+  assert.equal(health.state, 'done');
+  assert.match(health.line, /^DONE/);
+});
+
+test('red outranks stale when both fire', () => {
+  const p = makeProject({ updatedAt: ago(14) });
+  writeE2e(p, { ok: false });
+  const health = sessionHealth({ ...p, now: NOW });
+  assert.equal(health.state, 'red');
+  assert.equal(health.reasons.length, 2, 'both reasons are reported, severity picks the state');
+});

package/src/ledger.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+/**
+ * Durable session ledgers.
+ *
+ * `cleanup-sessions` deletes the whole session dir at done, so reviews,
+ * deferrals, fix-round briefs and test evidence all disappear — 5 of 6 scored
+ * sessions in one project were already gone, and what the reviews actually
+ * caught survived nowhere. `scorecards.jsonl` solved exactly this problem for
+ * scores; these are the same trick for the rest:
+ *
+ *   .forge/sessions.jsonl    one digest line per finished session
+ *   .forge/deferrals.jsonl   unresolved deferrals, with the session that owed them
+ *
+ * Both are append-with-replace (keyed by sessionId), tolerant of corrupt
+ * lines, and never throw — a ledger must not block a phase transition.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadDeferrals } from './integrity.mjs';
+import { reviewCensus } from './review-census.mjs';
+import { sessionHealth } from './health.mjs';
+
+/**
+ * @param {string} file
+ * @returns {Record<string, any>[]}
+ */
+export function readLedger(file) {
+  if (!fs.existsSync(file)) return [];
+  /** @type {Record<string, any>[]} */
+  const out = [];
+  for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      out.push(JSON.parse(line));
+    } catch {
+      // A half-written line from a killed process must not hide the rest.
+    }
+  }
+  return out;
+}
+
+/**
+ * @param {string} file
+ * @param {Record<string, any>[]} lines
+ * @param {(entry: Record<string, any>) => boolean} [replaceWhen] existing entries matching this are dropped
+ */
+function appendLines(file, lines, replaceWhen) {
+  if (lines.length === 0) return 0;
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const kept = replaceWhen ? readLedger(file).filter((e) => !replaceWhen(e)) : readLedger(file);
+    const all = [...kept, ...lines].map((e) => JSON.stringify(e));
+    fs.writeFileSync(file, `${all.join('\n')}\n`, 'utf8');
+    return lines.length;
+  } catch {
+    return 0; // advisory
+  }
+}
+
+/** @param {{ cwd?: string }} opts */
+function forgeDirOf(opts, sessionDir) {
+  return opts.cwd ? path.join(opts.cwd, '.forge') : path.resolve(sessionDir, '..', '..');
+}
+
+/**
+ * One line summarising how a session actually went — the fields a later
+ * analysis would otherwise have to reconstruct from deleted directories.
+ *
+ * @param {{ cwd?: string, sessionDir: string, session: Record<string, any>, card?: Record<string, any> | null }} opts
+ */
+export function appendSessionDigest(opts) {
+  const { sessionDir, session } = opts;
+  try {
+    const census = reviewCensus(sessionDir);
+    const health = sessionHealth({ cwd: opts.cwd, sessionDir, session });
+    const started = new Date(session.createdAt ?? NaN).getTime();
+    const ended = new Date(session.updatedAt ?? NaN).getTime();
+    const durationHours =
+      Number.isNaN(started) || Number.isNaN(ended)
+        ? null
+        : Math.round(((ended - started) / 3600000) * 100) / 100;
+
+    const entry = {
+      sessionId: session.id ?? null,
+      slug: session.slug ?? null,
+      change: session.openspecChange ?? null,
+      phase: session.phase ?? null,
+      planType: session.planType ?? null,
+      pace: session.resolvedPace ?? session.pace ?? null,
+      tasks: `${session.tasksComplete ?? 0}/${session.tasksTotal ?? 0}`,
+      subagentsDispatched: session.subagentsDispatched ?? null,
+      reviews: {
+        total: census.total,
+        independent: census.independent,
+        selfChecks: census.selfChecks,
+        rejections: census.rejections,
+        final: census.finalReview,
+      },
+      checkpoints: Array.isArray(session.checkpoints) ? session.checkpoints.length : 0,
+      health: health.state,
+      healthReasons: health.reasons,
+      score: opts.card?.score ?? session.score ?? null,
+      grade: opts.card?.grade ?? session.scoreGrade ?? null,
+      incompleteReason: session.incompleteReason ?? null,
+      durationHours,
+      startedAt: session.createdAt ?? null,
+      endedAt: session.updatedAt ?? null,
+    };
+    return appendLines(
+      path.join(forgeDirOf(opts, sessionDir), 'sessions.jsonl'),
+      [entry],
+      (e) => e.sessionId === entry.sessionId,
+    );
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Unresolved deferrals, promoted out of the session before it is deleted.
+ * Resolved ones are not debt and are left behind.
+ *
+ * @param {{ cwd?: string, sessionDir: string, session: Record<string, any> }} opts
+ */
+export function appendDeferralLedger(opts) {
+  const { sessionDir, session } = opts;
+  try {
+    const doc = loadDeferrals(sessionDir);
+    const open = (doc?.deferrals ?? []).filter((d) => d && !d.resolvedAt);
+    const lines = open.map((d) => ({
+      sessionId: session.id ?? null,
+      slug: session.slug ?? null,
+      change: session.openspecChange ?? null,
+      task: d.task ?? null,
+      reason: d.reason ?? null,
+      createdAt: d.createdAt ?? null,
+      carriedAt: new Date().toISOString(),
+    }));
+    return appendLines(
+      path.join(forgeDirOf(opts, sessionDir), 'deferrals.jsonl'),
+      lines,
+      (e) => e.sessionId === (session.id ?? null),
+    );
+  } catch {
+    return 0;
+  }
+}

package/src/ledger.test.mjs

@@ -0,0 +1,132 @@
+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 { appendDeferralLedger, appendSessionDigest, readLedger } from './ledger.mjs';
+
+function tmp(prefix) {
+  return fs.realpathSync(fs.mkdtempSync(path.join(tmpdir(), prefix)));
+}
+
+function makeSession(root, id = 's1', overrides = {}) {
+  const sessionDir = path.join(root, '.forge', 'sessions', id);
+  fs.mkdirSync(path.join(sessionDir, 'tasks', '01-model'), { recursive: true });
+  const session = {
+    id,
+    slug: 'add-billing',
+    openspecChange: 'add-billing',
+    phase: 'done',
+    planType: 'specs',
+    tasksTotal: 20,
+    tasksComplete: 20,
+    subagentsDispatched: 12,
+    createdAt: '2026-07-25T08:00:00.000Z',
+    updatedAt: '2026-07-25T14:30:00.000Z',
+    checkpoints: [{ sha: 'abc123', group: '01', tasks: '1.1-1.4', at: '2026-07-25T09:00:00.000Z' }],
+    ...overrides,
+  };
+  fs.writeFileSync(
+    path.join(sessionDir, 'session.json'),
+    `${JSON.stringify(session, null, 2)}\n`,
+    'utf8',
+  );
+  return { sessionDir, session };
+}
+
+test('a session digest survives the deletion of its session dir', () => {
+  // cleanup-sessions removes the whole session dir at done, taking reviews,
+  // deferrals and evidence with it — 5 of volo's 6 scored sessions were
+  // already gone, so what review actually caught existed nowhere.
+  const root = tmp('forge-ledger-');
+  const { sessionDir, session } = makeSession(root);
+  fs.writeFileSync(
+    path.join(sessionDir, 'tasks', '01-model', 'group-review.md'),
+    '# Group review\n\n**Verdict: APPROVED** (opus reviewer 9f2)\n\n## Round 1 — REJECTED\n',
+    'utf8',
+  );
+
+  appendSessionDigest({ cwd: root, sessionDir, session, card: { score: 88, grade: 'B' } });
+
+  fs.rmSync(sessionDir, { recursive: true, force: true });
+  const [entry] = readLedger(path.join(root, '.forge', 'sessions.jsonl'));
+
+  assert.equal(entry.sessionId, 's1');
+  assert.equal(entry.slug, 'add-billing');
+  assert.equal(entry.score, 88);
+  assert.equal(entry.tasks, '20/20');
+  assert.equal(entry.subagentsDispatched, 12);
+  assert.equal(entry.reviews.independent, 1);
+  assert.equal(entry.reviews.rejections, 1);
+  assert.equal(entry.checkpoints, 1);
+  assert.equal(entry.durationHours, 6.5);
+});
+
+test('the digest records the health verdict, not just the score', () => {
+  const root = tmp('forge-ledger-health-');
+  const { sessionDir, session } = makeSession(root, 's2', { phase: 'implement' });
+  fs.writeFileSync(
+    path.join(sessionDir, 'verify-evidence.md'),
+    '# Verify\n\nBLOCKED — no runtime owner for the queue worker.\n',
+    'utf8',
+  );
+
+  appendSessionDigest({ cwd: root, sessionDir, session, card: { score: 40, grade: 'D' } });
+  const [entry] = readLedger(path.join(root, '.forge', 'sessions.jsonl'));
+
+  assert.equal(entry.health, 'red');
+  assert.match(entry.healthReasons.join(' '), /BLOCKED/);
+});
+
+test('re-running a digest replaces that session line instead of duplicating it', () => {
+  const root = tmp('forge-ledger-dupe-');
+  const { sessionDir, session } = makeSession(root);
+  appendSessionDigest({ cwd: root, sessionDir, session, card: { score: 70, grade: 'C' } });
+  appendSessionDigest({ cwd: root, sessionDir, session, card: { score: 88, grade: 'B' } });
+
+  const entries = readLedger(path.join(root, '.forge', 'sessions.jsonl'));
+  assert.equal(entries.length, 1);
+  assert.equal(entries[0].score, 88);
+});
+
+test('unresolved deferrals outlive the session that raised them', () => {
+  // volo carried four standing deferrals that lived only in analysis reports:
+  // per-session deferrals.json is deleted with the session dir.
+  const root = tmp('forge-ledger-defer-');
+  const { sessionDir, session } = makeSession(root);
+  fs.writeFileSync(
+    path.join(sessionDir, 'deferrals.json'),
+    `${JSON.stringify({
+      deferrals: [
+        { task: '5.4', reason: 'gating tests land in group 6', createdAt: '2026-07-25T10:00:00.000Z', resolvedAt: '2026-07-25T11:00:00.000Z' },
+        { task: '7.1', reason: 'grouping.ts D1 extraction — three duplicated pipelines', createdAt: '2026-07-25T12:00:00.000Z' },
+      ],
+    })}\n`,
+    'utf8',
+  );
+
+  const written = appendDeferralLedger({ cwd: root, sessionDir, session });
+  assert.equal(written, 1, 'only the unresolved one is debt worth carrying');
+
+  fs.rmSync(sessionDir, { recursive: true, force: true });
+  const entries = readLedger(path.join(root, '.forge', 'deferrals.jsonl'));
+  assert.equal(entries.length, 1);
+  assert.equal(entries[0].task, '7.1');
+  assert.equal(entries[0].sessionId, 's1');
+  assert.equal(entries[0].change, 'add-billing');
+  assert.match(entries[0].reason, /grouping\.ts/);
+});
+
+test('a session with no deferrals writes no ledger noise', () => {
+  const root = tmp('forge-ledger-empty-');
+  const { sessionDir, session } = makeSession(root);
+  assert.equal(appendDeferralLedger({ cwd: root, sessionDir, session }), 0);
+  assert.equal(fs.existsSync(path.join(root, '.forge', 'deferrals.jsonl')), false);
+});
+
+test('readLedger tolerates a truncated or corrupt line', () => {
+  const root = tmp('forge-ledger-corrupt-');
+  const file = path.join(root, 'x.jsonl');
+  fs.writeFileSync(file, '{"a":1}\n{ broken\n{"a":2}\n', 'utf8');
+  assert.deepEqual(readLedger(file), [{ a: 1 }, { a: 2 }]);
+});

package/src/new-session.mjs

@@ -7,12 +7,14 @@
  *   forge new <slug> [--chat-id <id>] [--signal <text>]
  */
 
+import { spawnSync } from 'node:child_process';
 import {
   defaultSession,
   defaultStatus,
   ensureForgeLayout,
   FORGE_DIR,
   makeSessionId,
+  REPO_ROOT,
   saveSession,
   scaffoldSessionDirs,
   sessionPath,
@@ -55,6 +57,19 @@ scaffoldSessionDirs(dir);
 const session = defaultSession(sessionId, slug);
 if (cursorChatId) session.cursorChatId = cursorChatId;
 
+// Where this session started, so reviewers have a diff range even when the
+// project never enables checkpoints (and `forge checkpoint --range` has a
+// base from commit one).
+const head = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: REPO_ROOT, encoding: 'utf8' });
+if (head.status === 0) {
+  session.baseCommit = head.stdout.trim();
+  const branch = spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+    cwd: REPO_ROOT,
+    encoding: 'utf8',
+  });
+  if (branch.status === 0) session.branch = branch.stdout.trim();
+}
+
 const paceFields = resolveSessionPaceFields({
   forgeDir: FORGE_DIR,
   slug: session.slug,

package/src/review-census.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * Census of a session's review artifacts.
+ *
+ * Its own module because both the scorer and the durable ledger need it, and
+ * a scorer↔ledger import cycle would force one of them into a lazy import.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** A review the coordinator wrote about its own work — a weaker signal. */
+const SELF_REVIEW_RE = /pace self-check|APPROVED \(pace|self-review|reviewed by the coordinator/i;
+/** A round that sent work back: proof the review was not a rubber stamp. */
+const REJECTION_RE = /\bREJECT(ED)?\b/;
+
+/**
+ * Census of the review artifacts on disk.
+ *
+ * Counts what was *dispatched*, not what is absent: the previous version
+ * started at full marks and only ever subtracted, so a session with no
+ * reviewer of any kind scored 5/5 — which is how a 38-task, high-risk,
+ * self-reviewed session reached 100/100.
+ *
+ * @param {string} sessionDir
+ */
+export function reviewCensus(sessionDir) {
+  const census = { total: 0, independent: 0, selfChecks: 0, rejections: 0, finalReview: null };
+  /** @param {string} file */
+  const read = (file) => {
+    if (!fs.existsSync(file)) return null;
+    try {
+      return fs.readFileSync(file, 'utf8');
+    } catch {
+      return null;
+    }
+  };
+
+  const tasksDir = path.join(sessionDir, 'tasks');
+  if (fs.existsSync(tasksDir)) {
+    for (const e of fs.readdirSync(tasksDir, { withFileTypes: true })) {
+      if (!e.isDirectory()) continue;
+      for (const name of ['task-review.md', 'group-review.md']) {
+        const body = read(path.join(tasksDir, e.name, name));
+        if (body === null) continue;
+        census.total += 1;
+        if (SELF_REVIEW_RE.test(body)) census.selfChecks += 1;
+        else census.independent += 1;
+        if (REJECTION_RE.test(body)) census.rejections += 1;
+      }
+    }
+  }
+
+  for (const name of ['final-review.md', 'final-review-outcome.md']) {
+    const body = read(path.join(sessionDir, 'reviews', name));
+    if (body === null) continue;
+    census.finalReview = SELF_REVIEW_RE.test(body) ? 'self' : 'independent';
+    if (REJECTION_RE.test(body)) census.rejections += 1;
+    break;
+  }
+  return census;
+}