@izkac/forgekit 0.3.15 → 0.3.16

package/bin/forge.mjs

@@ -39,6 +39,7 @@ const COMMANDS = {
   score: { script: 'score-cli.mjs', aliases: ['scorecard'] },
   fleet: { script: 'fleet.mjs' },
   brief: { script: 'brief-cli.mjs' },
+  finding: { script: 'findings-cli.mjs', aliases: ['findings'] },
 };
 
 function printHelp() {
@@ -72,6 +73,7 @@ Commands:
   score [--write]         L2 session scorecard (auto-written at phase done)
   fleet list|watch|view|send  Cross-project session control terminal
   brief stamp|check|open  Operator brief (plain-language HTML, gates implement)
+  finding add|list|resolve    Findings ledger — give an observation a home
 
 Prefer \`forgekit install\` to pick multiple skills + agents at once.
 

package/package.json

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

package/src/findings-cli.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+/**
+ * `forge finding` — file, list and close findings (see findings.mjs).
+ *
+ * Usage:
+ *   forge finding add "<text>" [--change <slug>] [--severity blocker|major|minor|note]
+ *   forge finding list [--json] [--all]
+ *   forge finding resolve <id> [--note "<text>"]
+ */
+
+import { FORGE_DIR, loadSession, readActive } from './lib.mjs';
+import { addFinding, readFindings, resolveFinding } from './findings.mjs';
+
+function usage() {
+  process.stderr.write(
+    `Usage:
+  forge finding add "<text>" [--change <slug>] [--severity blocker|major|minor|note]
+  forge finding list [--json] [--all]
+  forge finding resolve <id> [--note "<text>"]
+`,
+  );
+}
+
+function fail(message) {
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+}
+
+function emit(payload) {
+  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+
+/** Active session, or nulls — findings are often filed between sessions. */
+function activeSessionInfo() {
+  try {
+    const active = readActive();
+    if (!active?.sessionId) return { sessionId: null, slug: null };
+    const { session } = loadSession(active.sessionId);
+    return { sessionId: session.id ?? null, slug: session.slug ?? null };
+  } catch {
+    return { sessionId: null, slug: null };
+  }
+}
+
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+if (!cmd || cmd === '--help' || cmd === '-h') {
+  usage();
+  process.exit(cmd ? 0 : 1);
+}
+
+if (cmd === 'add') {
+  const text = argv[1] ?? '';
+  if (!text.trim() || text.startsWith('--')) {
+    fail('A finding needs text: forge finding add "<text>"');
+  }
+  let change = null;
+  let severity = 'major';
+  for (let i = 2; i < argv.length; i += 1) {
+    if (argv[i] === '--change' && argv[i + 1]) change = argv[(i += 1)];
+    else if (argv[i] === '--severity' && argv[i + 1]) severity = argv[(i += 1)];
+    else fail(`Unknown argument: ${argv[i]}`);
+  }
+  try {
+    const entry = addFinding({
+      forgeDir: FORGE_DIR,
+      text,
+      severity,
+      change,
+      session: activeSessionInfo(),
+    });
+    emit({
+      ok: true,
+      ...entry,
+      next: change
+        ? `Open its home: forge change new ${change}`
+        : 'Give it a home: forge change new <slug>, forge defer add, or fix it now — otherwise label it a note (--severity note).',
+    });
+  } catch (err) {
+    fail(err instanceof Error ? err.message : String(err));
+  }
+  process.exit(0);
+}
+
+if (cmd === 'list') {
+  const all = argv.includes('--all');
+  const entries = readFindings(FORGE_DIR);
+  const open = entries.filter((e) => e.status === 'open');
+  const resolved = entries.filter((e) => e.status !== 'open');
+  if (argv.includes('--json')) {
+    emit({ open, resolved: all ? resolved : resolved.slice(-10), total: entries.length });
+    process.exit(0);
+  }
+  if (entries.length === 0) {
+    process.stdout.write('No findings recorded. File one: forge finding add "<text>"\n');
+    process.exit(0);
+  }
+  const rows = (all ? entries : open).map(
+    (e) =>
+      `${e.id}  ${String(e.severity ?? 'major').padEnd(7)} ${e.status === 'open' ? ' ' : '✓'} ${e.text}${
+        e.change ? `  → ${e.change}` : ''
+      }`,
+  );
+  process.stdout.write(
+    `${rows.join('\n')}\n\n${open.length} open, ${resolved.length} resolved${
+      all ? '' : ' (--all to see resolved)'
+    }\n`,
+  );
+  process.exit(0);
+}
+
+if (cmd === 'resolve') {
+  const id = argv[1];
+  if (!id) fail('Usage: forge finding resolve <id> [--note "<text>"]');
+  let note = null;
+  for (let i = 2; i < argv.length; i += 1) {
+    if (argv[i] === '--note' && argv[i + 1]) note = argv[(i += 1)];
+    else fail(`Unknown argument: ${argv[i]}`);
+  }
+  try {
+    emit({ ok: true, ...resolveFinding({ forgeDir: FORGE_DIR, id, note }) });
+  } catch (err) {
+    fail(err instanceof Error ? err.message : String(err));
+  }
+  process.exit(0);
+}
+
+usage();
+fail(`Unknown subcommand: ${cmd}`);

package/src/findings.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+/**
+ * Findings ledger — give an observation a home the day it is written.
+ *
+ * Analysis reports kept re-listing the same unactioned items ("untick 6.2",
+ * "the e2e parallel race", "grouping.ts D1 extraction") because nothing turned
+ * a report line into tracked work: prose in a gitignored report is not a
+ * queue. A finding either becomes a change, a deferral, or an edit made on the
+ * spot — or it is a note, and should be labelled one.
+ *
+ * Library half (`findings-cli.mjs` is the command). Ledger:
+ * `.forge/findings.jsonl`, durable across session cleanup.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { readLedger } from './ledger.mjs';
+
+export const SEVERITIES = ['blocker', 'major', 'minor', 'note'];
+
+/** @param {string} forgeDir */
+export function findingsPath(forgeDir) {
+  return path.join(forgeDir, 'findings.jsonl');
+}
+
+/** @param {string} forgeDir */
+export function readFindings(forgeDir) {
+  return readLedger(findingsPath(forgeDir));
+}
+
+/** @param {string} forgeDir */
+export function openFindings(forgeDir) {
+  return readFindings(forgeDir).filter((f) => f && f.status === 'open');
+}
+
+/**
+ * Next id: F1, F2, … Stable across resolves so a report can cite one.
+ * @param {Record<string, any>[]} entries
+ */
+export function nextFindingId(entries) {
+  let max = 0;
+  for (const e of entries) {
+    const m = /^F(\d+)$/.exec(String(e?.id ?? ''));
+    if (m) max = Math.max(max, Number(m[1]));
+  }
+  return `F${max + 1}`;
+}
+
+/**
+ * @param {string} forgeDir
+ * @param {Record<string, any>[]} entries
+ */
+function writeAll(forgeDir, entries) {
+  const file = findingsPath(forgeDir);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${entries.map((e) => JSON.stringify(e)).join('\n')}\n`, 'utf8');
+}
+
+/**
+ * @param {{ forgeDir: string, text: string, severity?: string, change?: string | null,
+ *           session?: { sessionId?: string | null, slug?: string | null }, now?: () => Date }} opts
+ */
+export function addFinding(opts) {
+  const text = String(opts.text ?? '').trim();
+  if (!text) throw new Error('A finding needs text: forge finding add "<text>"');
+  const severity = opts.severity ?? 'major';
+  if (!SEVERITIES.includes(severity)) {
+    throw new Error(`Unknown severity "${severity}" (expected ${SEVERITIES.join(' | ')}).`);
+  }
+  const entries = readFindings(opts.forgeDir);
+  const entry = {
+    id: nextFindingId(entries),
+    text,
+    severity,
+    status: 'open',
+    change: opts.change ?? null,
+    sessionId: opts.session?.sessionId ?? null,
+    slug: opts.session?.slug ?? null,
+    createdAt: (opts.now?.() ?? new Date()).toISOString(),
+  };
+  writeAll(opts.forgeDir, [...entries, entry]);
+  return entry;
+}
+
+/**
+ * @param {{ forgeDir: string, id: string, note?: string | null, now?: () => Date }} opts
+ */
+export function resolveFinding(opts) {
+  const entries = readFindings(opts.forgeDir);
+  const idx = entries.findIndex((e) => e.id === opts.id);
+  if (idx < 0) throw new Error(`No finding with id ${opts.id}. See: forge finding list --all`);
+  if (entries[idx].status !== 'open') {
+    throw new Error(`Finding ${opts.id} is already ${entries[idx].status}.`);
+  }
+  entries[idx] = {
+    ...entries[idx],
+    status: 'resolved',
+    note: opts.note ?? entries[idx].note ?? null,
+    resolvedAt: (opts.now?.() ?? new Date()).toISOString(),
+  };
+  writeAll(opts.forgeDir, entries);
+  return entries[idx];
+}

package/src/findings.test.mjs

@@ -0,0 +1,140 @@
+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 FINDINGS = path.join(path.dirname(fileURLToPath(import.meta.url)), 'findings-cli.mjs');
+
+function tmp(prefix) {
+  return fs.realpathSync(fs.mkdtempSync(path.join(tmpdir(), prefix)));
+}
+
+function makeProject() {
+  const cwd = tmp('forge-finding-');
+  const sessionDir = path.join(cwd, '.forge', 'sessions', 's1');
+  fs.mkdirSync(sessionDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(sessionDir, 'session.json'),
+    `${JSON.stringify({
+      id: 's1',
+      slug: 'phase-1',
+      openspecChange: 'phase-1',
+      phase: 'verify',
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    })}\n`,
+    'utf8',
+  );
+  fs.writeFileSync(
+    path.join(cwd, '.forge', 'active.json'),
+    `${JSON.stringify({ sessionId: 's1' })}\n`,
+    'utf8',
+  );
+  return cwd;
+}
+
+function run(cwd, args) {
+  const env = { ...process.env, FORGEKIT_FLEET_DIR: path.join(tmp('finding-fleet-'), 's') };
+  try {
+    const stdout = execFileSync(process.execPath, [FINDINGS, ...args], { cwd, env });
+    const text = stdout.toString();
+    try {
+      return { status: 0, out: JSON.parse(text), text };
+    } catch {
+      return { status: 0, out: null, text };
+    }
+  } catch (err) {
+    return { status: err.status, out: null, text: String(err.stdout), stderr: String(err.stderr) };
+  }
+}
+
+test('a finding lands in a durable ledger with the session that raised it', () => {
+  // "A finding either gets a home the day it is written, or it is not a
+  // finding — it is a note." Three analysis reports in a row carried the same
+  // unactioned items because nothing converted a line into tracked work.
+  const cwd = makeProject();
+  const { status, out } = run(cwd, [
+    'add',
+    'smoke suite pinned --workers=1 in 6/6 changes; the shared-state race is never fixed',
+  ]);
+
+  assert.equal(status, 0);
+  assert.equal(out.ok, true);
+  assert.match(out.id, /^F\d+$/);
+
+  const ledger = path.join(cwd, '.forge', 'findings.jsonl');
+  const [entry] = fs
+    .readFileSync(ledger, 'utf8')
+    .split('\n')
+    .filter(Boolean)
+    .map((l) => JSON.parse(l));
+  assert.equal(entry.status, 'open');
+  assert.equal(entry.sessionId, 's1');
+  assert.match(entry.text, /workers=1/);
+});
+
+test('a finding can name the change that will carry it', () => {
+  const cwd = makeProject();
+  const { out } = run(cwd, ['add', 'grouping.ts D1 extraction', '--change', 'fix-grouping-d1']);
+  assert.equal(out.change, 'fix-grouping-d1');
+  // The command tells you how to open that change rather than creating it
+  // behind your back.
+  assert.match(out.next, /forge change new fix-grouping-d1/);
+});
+
+test('list shows open findings and resolve closes one by id', () => {
+  const cwd = makeProject();
+  const first = run(cwd, ['add', 'server suite baseline is 1-4 varying failures']);
+  run(cwd, ['add', 'untick 6.2 in the archived tasks.md']);
+
+  const open = run(cwd, ['list', '--json']);
+  assert.equal(open.out.open.length, 2);
+
+  const resolved = run(cwd, ['resolve', first.out.id, '--note', 'quarantined the flaky names']);
+  assert.equal(resolved.status, 0);
+  assert.equal(resolved.out.status, 'resolved');
+
+  const after = run(cwd, ['list', '--json']);
+  assert.equal(after.out.open.length, 1);
+  assert.equal(after.out.resolved.length, 1);
+  assert.match(after.out.resolved[0].note, /quarantined/);
+});
+
+test('resolving an unknown id fails loudly instead of silently succeeding', () => {
+  const cwd = makeProject();
+  const { status, stderr } = run(cwd, ['resolve', 'F999']);
+  assert.equal(status, 1);
+  assert.match(stderr, /F999/);
+});
+
+test('add refuses an empty finding', () => {
+  const cwd = makeProject();
+  const { status, stderr } = run(cwd, ['add', '   ']);
+  assert.equal(status, 1);
+  assert.match(stderr, /text/i);
+});
+
+test('findings work without an active session', () => {
+  // Reports are often written between sessions; that must not block filing.
+  const cwd = tmp('forge-finding-nosession-');
+  fs.mkdirSync(path.join(cwd, '.forge'), { recursive: true });
+  const { status, out } = run(cwd, ['add', 'pace auto never selects brisk or lite']);
+  assert.equal(status, 0);
+  assert.equal(out.sessionId, null);
+});
+
+test('forge status reports open findings so they cannot be forgotten', () => {
+  const cwd = makeProject();
+  run(cwd, ['add', 'e2e parallel race unfixed']);
+  const statusScript = path.join(path.dirname(FINDINGS), 'session-status.mjs');
+  const stdout = execFileSync(process.execPath, [statusScript], {
+    cwd,
+    env: { ...process.env, FORGEKIT_FLEET_DIR: path.join(tmp('finding-fleet-'), 's') },
+  }).toString();
+  const status = JSON.parse(stdout);
+  assert.equal(status.openFindings.count, 1);
+  assert.match(status.openFindings.latest[0].text, /parallel race/);
+});

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/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;
+}

package/src/score.mjs

@@ -22,10 +22,17 @@ import {
   spinePath,
   validateSpine,
 } from './integrity.mjs';
+import { sessionHealth } from './health.mjs';
+import { isHighRiskText } from './preferences.mjs';
+import { reviewCensus } from './review-census.mjs';
+import { appendDeferralLedger, appendSessionDigest } from './ledger.mjs';
 
 /** Keep in sync with set-phase.mjs TASK_COUNT_ESCALATION_THRESHOLD. */
 const TASK_COUNT_ESCALATION_THRESHOLD = 15;
 
+/** Ceiling (grade C) for sessions whose outcome is unproven or unreviewed. */
+const OUTCOME_CAP = 69;
+
 /**
  * @param {unknown} value
  */
@@ -94,25 +101,6 @@ function evidenceHonestyIssues(sessionDir) {
   return issues;
 }
 
-/**
- * @param {string} sessionDir
- */
-function reviewSelfCheckCount(sessionDir) {
-  const tasksDir = path.join(sessionDir, 'tasks');
-  if (!fs.existsSync(tasksDir)) return 0;
-  let n = 0;
-  for (const e of fs.readdirSync(tasksDir, { withFileTypes: true })) {
-    if (!e.isDirectory()) continue;
-    for (const name of ['task-review.md', 'group-review.md']) {
-      const file = path.join(tasksDir, e.name, name);
-      if (!fs.existsSync(file)) continue;
-      const body = fs.readFileSync(file, 'utf8');
-      if (/pace self-check|APPROVED \(pace/i.test(body)) n += 1;
-    }
-  }
-  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
@@ -207,11 +195,15 @@ export function scoreSession(opts) {
   /** @type {string[]} */
   const spineNotes = [];
   const spineFile = spinePath({ cwd, session, sessionDir });
+  // What the change actually touches, for risk detection below — a slug
+  // written at session start rarely says "auth" even when the change is one.
+  let spineText = '';
   if (!fs.existsSync(spineFile)) {
     spineNotes.push('spine.json missing');
   } else {
     try {
       const doc = readJson(spineFile);
+      spineText = JSON.stringify(doc);
       const v = validateSpine(doc);
       if (!v.ok) {
         spineNotes.push(...v.problems);
@@ -386,23 +378,56 @@ export function scoreSession(opts) {
   }
   checks.push({ id: 'pace', label: 'Pace sanity', points: pacePts, max: 5, notes: paceNotes });
 
-  // --- review depth soft signal (5) ---
-  const selfChecks = reviewSelfCheckCount(sessionDir);
-  let reviewPts = 5;
+  // --- review depth (5) — scored by what was dispatched ---
+  const census = reviewCensus(sessionDir);
+  let reviewPts = 0;
   /** @type {string[]} */
   const reviewNotes = [];
-  if (selfChecks > 0 && (resolved === 'thorough' || total >= TASK_COUNT_ESCALATION_THRESHOLD)) {
-    reviewPts = Math.max(0, 5 - Math.min(5, selfChecks));
-    reviewNotes.push(`${selfChecks} pace self-check review(s) on a large/thorough session`);
-  } else if (selfChecks > 0) {
-    reviewNotes.push(`${selfChecks} pace self-check(s) — ok under brisk/standard mid-group`);
+  if (census.total === 0 && !census.finalReview) {
+    reviewNotes.push('no review artifacts at all — nobody read this work but the author');
   } else {
-    reviewNotes.push('no pace self-check markers found');
+    // Coverage, not presence: one review across eight task groups is not the
+    // same signal as nine across nine.
+    const groups = Math.max(ev.taskDirs, census.total);
+    const coverage = groups > 0 ? census.independent / groups : 0;
+    if (census.independent > 0 && coverage >= 0.5) {
+      reviewPts += 2;
+      reviewNotes.push(`${census.independent} dispatched review(s) across ${groups} task group(s)`);
+    } else if (census.independent > 0) {
+      reviewPts += 1;
+      reviewNotes.push(
+        `${census.independent} dispatched review(s) across ${groups} task group(s) — thin coverage`,
+      );
+    } else {
+      reviewNotes.push(`${census.selfChecks} self-check(s), no dispatched reviewer`);
+    }
+    if (census.finalReview === 'independent') {
+      reviewPts += 2;
+      reviewNotes.push('independent final review');
+    } else if (census.finalReview === 'self') {
+      reviewPts += 1;
+      reviewNotes.push('final review is self-authored — weaker than an outside reader');
+    } else {
+      reviewNotes.push('no final review');
+    }
+    // A review that never rejected anything may still be a rubber stamp; one
+    // that sent work back demonstrably was not.
+    if (census.rejections > 0) {
+      reviewPts += 1;
+      reviewNotes.push(`${census.rejections} review round(s) rejected work before approving`);
+    }
+  }
+  if (
+    census.selfChecks > 0 &&
+    census.independent === 0 &&
+    (resolved === 'thorough' || total >= TASK_COUNT_ESCALATION_THRESHOLD)
+  ) {
+    reviewNotes.push('large/thorough session carried by self-checks only');
   }
   checks.push({
     id: 'reviews',
-    label: 'Review depth signal',
-    points: reviewPts,
+    label: 'Review depth (dispatched reviewers, not absence of markers)',
+    points: Math.min(5, reviewPts),
     max: 5,
     notes: reviewNotes,
   });
@@ -420,6 +445,45 @@ export function scoreSession(opts) {
     );
   }
 
+  // A failing product loop is an outcome, and outcomes outrank artifacts: no
+  // amount of spine/evidence polish should let a session with a red e2e run
+  // read as an A.
+  const health = sessionHealth({ cwd, sessionDir, session });
+  if (health.state === 'red') {
+    const before = score;
+    if (score > OUTCOME_CAP) {
+      score = OUTCOME_CAP;
+      caps.push(`${health.reasons.join('; ')} — score capped at ${OUTCOME_CAP} (was ${before})`);
+    }
+  }
+
+  // Money/auth/contracts/migrations have a hard floor: an independent
+  // reviewer. Prose saying dispatch was declined does not survive session
+  // cleanup; a cap does.
+  // Fails closed, like pace resolution: a *negated* mention ("carries
+  // consumption, never money") still counts as a money-shaped change, because
+  // the cost of being wrong is one dispatched reviewer.
+  const riskText = [session.paceSignal, session.slug, session.openspecChange, spineText]
+    .filter(isNonEmptyString)
+    .join(' ');
+  // The floor for a high-risk change is an independent reader of the *whole*
+  // change. Per-group reviews do not substitute: they each saw one slice.
+  if (isHighRiskText(riskText) && census.finalReview !== 'independent') {
+    const before = score;
+    const what =
+      census.finalReview === 'self'
+        ? 'high-risk session whose final review is self-authored'
+        : 'high-risk session with no independent final review';
+    if (score > OUTCOME_CAP) {
+      score = OUTCOME_CAP;
+      caps.push(
+        `${what} — score capped at ${OUTCOME_CAP} (was ${before}); dispatch a final reviewer, or record the refusal with forge defer so it survives cleanup`,
+      );
+    } else {
+      caps.push(what);
+    }
+  }
+
   const grade = gradeForScore(score);
   const changeDir = resolveChangeDir({ cwd, session });
 
@@ -564,5 +628,9 @@ export function writeSessionScorecard(opts) {
   writeJson(jsonPath, card);
   fs.writeFileSync(mdPath, formatScorecardMarkdown(card), 'utf8');
   appendScorecardLedger(opts.sessionDir, card, opts.session);
+  // Durable ledgers: the session dir is deleted at cleanup, so the digest and
+  // any unresolved deferrals have to leave the session while it still exists.
+  appendSessionDigest({ cwd: opts.cwd, sessionDir: opts.sessionDir, session: opts.session, card });
+  appendDeferralLedger({ cwd: opts.cwd, sessionDir: opts.sessionDir, session: opts.session });
   return { card, jsonPath, mdPath };
 }

package/src/score.test.mjs

@@ -105,6 +105,231 @@ test('scoreSession: strong sync-only session scores high', () => {
   }
 });
 
+/** Session with everything except reviews, so review depth is the only variable. */
+function makeReviewFixture(root, sessionOverrides = {}) {
+  const { sessionDir, session } = makeSession(root, {
+    slug: 'add-billing',
+    tasksTotal: 20,
+    tasksComplete: 20,
+    ...sessionOverrides,
+  });
+  fs.writeFileSync(
+    path.join(sessionDir, 'spine.json'),
+    `${JSON.stringify({ rows: [], notApplicable: 'sync HTTP only' }, null, 2)}\n`,
+    'utf8',
+  );
+  fs.writeFileSync(path.join(sessionDir, 'verify-evidence.md'), '# Verify\n\nExit 0\n', 'utf8');
+  const taskDir = path.join(sessionDir, 'tasks', '01-model');
+  fs.mkdirSync(taskDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(taskDir, 'test-evidence.md'),
+    '# Test evidence\n\n- **Exit code:** 0\n- **Summary:** asserts the row is written\n',
+    'utf8',
+  );
+  return { sessionDir, session, taskDir };
+}
+
+function reviewCheck(card) {
+  return card.checks.find((c) => c.id === 'reviews');
+}
+
+test('review depth: no reviewer artifacts at all scores zero, not full marks', () => {
+  // Regression: reviewPts started at 5 and was only ever *reduced* by finding
+  // self-check markers, so a session with no reviews of any kind scored 5/5.
+  // That is how a 38-task, high-risk, self-reviewed session reached 100/100.
+  const root = tmp('forge-score-noreview-');
+  try {
+    const { sessionDir, session } = makeReviewFixture(root);
+    const check = reviewCheck(scoreSession({ cwd: root, sessionDir, session }));
+    assert.equal(check.points, 0);
+    assert.match(check.notes.join(' '), /no review/i);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('review depth: a dispatched reviewer beats a self-check', () => {
+  const root = tmp('forge-score-dispatched-');
+  try {
+    const { sessionDir, session, taskDir } = makeReviewFixture(root);
+    fs.writeFileSync(
+      path.join(taskDir, 'task-review.md'),
+      '# Task review\n\nAPPROVED (pace self-check) — coordinator read the diff.\n',
+      'utf8',
+    );
+    const selfOnly = reviewCheck(scoreSession({ cwd: root, sessionDir, session }));
+
+    fs.writeFileSync(
+      path.join(taskDir, 'group-review.md'),
+      '# Group review\n\n**Verdict: APPROVED** (opus reviewer a3cbc561b60655bb8)\n',
+      'utf8',
+    );
+    const dispatched = reviewCheck(scoreSession({ cwd: root, sessionDir, session }));
+
+    assert.ok(
+      dispatched.points > selfOnly.points,
+      `dispatched (${dispatched.points}) should beat self-check-only (${selfOnly.points})`,
+    );
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('review depth: a recorded rejection round scores as evidence the review had teeth', () => {
+  // helm's group-6 REJECT→fix→APPROVE caught a flaky-green test about to
+  // become 3-OS CI evidence. It is the most valuable artifact in the corpus
+  // and used to score nothing.
+  const root = tmp('forge-score-reject-');
+  try {
+    const { sessionDir, session, taskDir } = makeReviewFixture(root);
+    fs.writeFileSync(
+      path.join(taskDir, 'group-review.md'),
+      '# Group 6 review\n\n**Verdict: APPROVED** (opus reviewer 9f2, after one fix round)\n\n## Round 1 — REJECTED\n\nOne blocker, four majors.\n',
+      'utf8',
+    );
+    const withReject = reviewCheck(scoreSession({ cwd: root, sessionDir, session }));
+
+    fs.writeFileSync(
+      path.join(taskDir, 'group-review.md'),
+      '# Group 6 review\n\n**Verdict: APPROVED** (opus reviewer 9f2)\n',
+      'utf8',
+    );
+    const cleanApprove = reviewCheck(scoreSession({ cwd: root, sessionDir, session }));
+
+    assert.ok(
+      withReject.points > cleanApprove.points,
+      `a rejection round (${withReject.points}) should outscore a first-pass approval (${cleanApprove.points})`,
+    );
+    assert.match(withReject.notes.join(' '), /reject/i);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('review depth scores coverage, not presence — 1 review across 8 groups is thin', () => {
+  const root = tmp('forge-score-coverage-');
+  try {
+    const { sessionDir, session } = makeReviewFixture(root);
+    const tasksDir = path.join(sessionDir, 'tasks');
+    for (const g of ['02-api', '03-mail', '04-client']) {
+      fs.mkdirSync(path.join(tasksDir, g), { recursive: true });
+      fs.writeFileSync(
+        path.join(tasksDir, g, 'test-evidence.md'),
+        '# Test evidence\n\n- **Exit code:** 0\n- **Summary:** asserts output\n',
+        'utf8',
+      );
+    }
+    fs.writeFileSync(
+      path.join(tasksDir, '01-model', 'group-review.md'),
+      '# Group review\n\n**Verdict: APPROVED** (opus reviewer 7c1)\n',
+      'utf8',
+    );
+    const thin = reviewCheck(scoreSession({ cwd: root, sessionDir, session }));
+    assert.match(thin.notes.join(' '), /thin coverage/);
+
+    for (const g of ['02-api', '03-mail', '04-client']) {
+      fs.writeFileSync(
+        path.join(tasksDir, g, 'group-review.md'),
+        '# Group review\n\n**Verdict: APPROVED** (opus reviewer 7c1)\n',
+        'utf8',
+      );
+    }
+    const full = reviewCheck(scoreSession({ cwd: root, sessionDir, session }));
+    assert.ok(full.points > thin.points, `full coverage (${full.points}) should beat thin (${thin.points})`);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('a high-risk session with no independent review is capped, however good its artifacts', () => {
+  const root = tmp('forge-score-riskcap-');
+  try {
+    // Money/auth signal: the hard floor says an independent reviewer is
+    // mandatory regardless of pace.
+    const { sessionDir, session } = makeReviewFixture(root, {
+      slug: 'add-stripe-refund-auth',
+      paceSignal: 'payment refunds behind an authorization gate',
+    });
+    const card = scoreSession({ cwd: root, sessionDir, session });
+
+    assert.ok(card.score <= 69, `expected a cap at C, got ${card.score}`);
+    assert.match(card.caps.join(' '), /independent final review/i);
+
+    // Per-group reviews do NOT lift the cap: each saw one slice, and the floor
+    // is an independent reader of the whole change.
+    const taskDir = path.join(sessionDir, 'tasks', '01-model');
+    fs.writeFileSync(
+      path.join(taskDir, 'group-review.md'),
+      '# Group review\n\n**Verdict: APPROVED** (opus reviewer 7c1)\n',
+      'utf8',
+    );
+    assert.ok(scoreSession({ cwd: root, sessionDir, session }).score <= 69);
+
+    // A self-authored final review is named as such, and still capped.
+    fs.mkdirSync(path.join(sessionDir, 'reviews'), { recursive: true });
+    fs.writeFileSync(
+      path.join(sessionDir, 'reviews', 'final-review.md'),
+      '# Final review\n\nReviewer: the coordinator — this is a self-review, dispatch was declined.\n',
+      'utf8',
+    );
+    const selfFinal = scoreSession({ cwd: root, sessionDir, session });
+    assert.ok(selfFinal.score <= 69);
+    assert.match(selfFinal.caps.join(' '), /self-authored/i);
+
+    // An independent final review lifts it.
+    fs.writeFileSync(
+      path.join(sessionDir, 'reviews', 'final-review.md'),
+      '# Final review\n\n**Verdict: APPROVED** — opus reviewer 4d2 read the whole diff.\n',
+      'utf8',
+    );
+    const reviewed = scoreSession({ cwd: root, sessionDir, session });
+    assert.equal(
+      reviewed.caps.some((c) => /final review/i.test(c)),
+      false,
+    );
+    assert.ok(reviewed.score > 69, `expected no cap, got ${reviewed.score}`);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('a red e2e run caps the score — artifacts cannot outvote a failing product loop', () => {
+  const root = tmp('forge-score-redcap-');
+  try {
+    const { sessionDir, session } = makeSession(root, {
+      slug: 'phase-1',
+      openspecChange: 'phase-1',
+      planType: 'specs',
+    });
+    const changeDir = path.join(root, 'specs', 'changes', 'phase-1');
+    fs.mkdirSync(changeDir, { recursive: true });
+    const steps = [{ name: 'bench-gate', cmd: 'true' }];
+    fs.writeFileSync(
+      path.join(changeDir, 'spine.json'),
+      `${JSON.stringify({ rows: [], notApplicable: 'sync only' }, null, 2)}\n`,
+      'utf8',
+    );
+    fs.writeFileSync(path.join(changeDir, 'e2e.json'), `${JSON.stringify({ steps })}\n`, 'utf8');
+    fs.writeFileSync(
+      path.join(sessionDir, 'e2e-results.json'),
+      `${JSON.stringify({
+        ok: false,
+        ranAt: new Date().toISOString(),
+        stepsHash: e2eStepsHash(steps),
+        steps: [{ name: 'bench-gate', ok: false, exitCode: 1 }],
+      })}\n`,
+      'utf8',
+    );
+    fs.writeFileSync(path.join(sessionDir, 'verify-evidence.md'), '# Verify\n\n## Product loop\n\n1. run it\n', 'utf8');
+
+    const card = scoreSession({ cwd: root, sessionDir, session });
+    assert.ok(card.score <= 69, `expected a cap at C, got ${card.score}`);
+    assert.match(card.caps.join(' '), /e2e|product loop/i);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
 test('scoreSession: missing spine scores poorly', () => {
   const root = tmp('forge-score-weak-');
   try {

package/src/session-status.mjs

@@ -17,6 +17,7 @@ import {
 } from './lib.mjs';
 import { resolveEffectivePreferences } from './preferences.mjs';
 import { sessionHealth } from './health.mjs';
+import { openFindings } from './findings.mjs';
 
 const args = process.argv.slice(2);
 let sessionId = null;
@@ -49,6 +50,10 @@ const pace = resolveEffectivePreferences({
 
 const health = sessionHealth({ cwd: REPO_ROOT, sessionDir: dir, session });
 
+// Open findings are project-level, not session-level: they outlive the session
+// that raised them, which is the entire point of the ledger.
+const findings = openFindings(FORGE_DIR);
+
 process.stdout.write(
   JSON.stringify(
     {
@@ -58,6 +63,10 @@ process.stdout.write(
       // Verdict first: a status dump that never says "this session is red and
       // nobody has touched it since yesterday" makes the operator derive it.
       health,
+      openFindings: {
+        count: findings.length,
+        latest: findings.slice(-5).map((f) => ({ id: f.id, severity: f.severity, text: f.text, change: f.change })),
+      },
       session,
       progress: status,
       pace: {

package/vendor/skills/forge/SKILL.md

@@ -115,6 +115,8 @@ Testing: [references/test-strategy.md](./references/test-strategy.md) — tier 1
 
 - No autonomous `git commit` / push unless the user explicitly asks. **Never push.** The one sanctioned commit is `forge checkpoint` at a task-group boundary, and only when the project set `.forge/config.json` → `git.checkpoint` (default `off`); it refuses on the default branch and excludes `.forge/` scratch
 - **Session health** — `forge status` returns a `health` verdict (`healthy` / `stale` / `red` / `done`). On resume, read it before continuing: a red e2e run or an idle session mid-implement is the first thing to tell the user about
+- **High-risk floor** — money/auth/contracts/migrations need an **independent final review** (a reviewer other than you reading the whole change). `forge score` caps the session at 69 without one. If the user declines dispatch, record it with `forge defer` — prose caveats do not survive session cleanup
+- **Findings** — anything you notice that deserves work but is out of scope goes to `forge finding add "<text>" [--change <slug>]`, not into a report the next session will not read
 - Tests required for behavior changes
 - Trace ecosystem consumers when contracts change
 - Honor `openspec/config.yaml` prefixes when the project uses them (OpenSpec engine)

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

@@ -274,6 +274,9 @@ forge checkpoint --group <name> [--tasks <ids>]
                                   # commit this group's work (opt-in; never pushes)
 forge checkpoint --dry-run        # what a checkpoint would commit
 forge checkpoint --range [--last] # diff range for a reviewer brief ({DIFF_RANGE})
+forge finding add "<text>" [--change <slug>] [--severity blocker|major|minor|note]
+                                  # findings ledger (.forge/findings.jsonl)
+forge finding list|resolve <id>   # open findings appear in forge status
 forge cleanup [--dry-run]         # prune sessions >14 days or finished
 forge evidence --task <nn>-<slug> --command "<cmd>" --exit 0 --summary "<text>"
                                   # stamp tier-2 test-evidence.md