@izkac/forgekit 0.3.14 → 0.3.15

package/bin/forge.mjs

@@ -20,6 +20,7 @@ const COMMANDS = {
   status: { script: 'session-status.mjs' },
   cleanup: { script: 'cleanup-sessions.mjs' },
   phase: { script: 'set-phase.mjs', aliases: ['set-phase'] },
+  checkpoint: { script: 'checkpoint.mjs', aliases: ['ckpt'] },
   prefs: { script: 'set-prefs.mjs' },
   models: { script: 'set-models.mjs' },
   'resolve-model': { script: 'resolve-model.mjs' },
@@ -50,6 +51,7 @@ Commands:
   new <slug>              Create a Forge session under .forge/
   status                  Show active session
   phase <phase>           Update session phase
+  checkpoint              Commit the group's work (opt-in; never pushes)
   cleanup                 Prune old/finished sessions
   prefs [pace]            Get/set pace preferences
   models [lane]           Get/set subagent billing (included|metered)

package/package.json

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

package/src/checkpoint.mjs

@@ -0,0 +1,357 @@
+#!/usr/bin/env node
+/**
+ * `forge checkpoint` — an authorized, boring commit at a task-group boundary.
+ *
+ * Forge forbids autonomous commits, which is right, but the missing half was
+ * an *explicit* one: a 32-task session accumulated 6k lines across 37 files
+ * and 18 untracked ones in a single working tree, so a stray `git checkout`
+ * could erase a day of work and every reviewer after task 1 saw a diff
+ * containing all previous tasks.
+ *
+ * Checkpoints are opt-in per project (`.forge/config.json` → `git.checkpoint`),
+ * never push, never run on the default branch unless explicitly allowed, and
+ * record the resulting sha on the session so reviewers get a real diff range.
+ *
+ * Usage:
+ *   forge checkpoint --group <name> [--tasks <ids>] [--message <subject>]
+ *   forge checkpoint --dry-run
+ *   forge checkpoint --range [--last]
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { loadSession, readActive, REPO_ROOT, saveSession } from './lib.mjs';
+import { loadProjectConfig } from './config.mjs';
+
+const MODES = ['off', 'per-group', 'per-task'];
+const DEFAULT_BRANCHES = new Set(['main', 'master']);
+
+function usage() {
+  process.stderr.write(
+    `Usage:
+  forge checkpoint --group <name> [--tasks <ids>] [--message <subject>]
+  forge checkpoint --dry-run                 what would be committed
+  forge checkpoint --range [--last]          diff range for a reviewer brief
+
+Enable per project in .forge/config.json:
+  { "git": { "checkpoint": "per-group" } }   # or "per-task", "off" (default)
+`,
+  );
+}
+
+/**
+ * @param {string} cwd
+ * @param {string[]} args
+ */
+function git(cwd, args) {
+  return spawnSync('git', args, { cwd, encoding: 'utf8' });
+}
+
+/**
+ * @param {string} cwd
+ * @param {string[]} args
+ */
+function gitOut(cwd, args) {
+  return gitOutRaw(cwd, args).trim();
+}
+
+/**
+ * Untrimmed stdout. `git status --porcelain` encodes the unstaged marker as a
+ * leading space, so trimming shifts every path in the first line by one.
+ *
+ * @param {string} cwd
+ * @param {string[]} args
+ */
+function gitOutRaw(cwd, args) {
+  const r = git(cwd, args);
+  if (r.status !== 0) throw new Error(`git ${args.join(' ')} failed: ${r.stderr.trim()}`);
+  return r.stdout;
+}
+
+function fail(message, payload = null) {
+  process.stderr.write(`${message}\n`);
+  if (payload) process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+  process.exit(1);
+}
+
+function emit(payload) {
+  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+
+/**
+ * Session bookkeeping is not product work: `.forge/` churns on every phase
+ * write (including this command's own), so committing it would make every
+ * checkpoint dirty the tree again and bury the real diff in scratch.
+ */
+const EXCLUDE_SCRATCH = ['--', '.', ':(exclude).forge'];
+
+/**
+ * Working-tree entries with their porcelain status, including untracked ones —
+ * agent work is mostly new files, so a tracked-only view would miss most of it.
+ *
+ * @param {string} cwd
+ * @returns {{ path: string, status: string, untracked: boolean }[]}
+ */
+export function pendingEntries(cwd) {
+  const porcelain = gitOutRaw(cwd, [
+    'status',
+    '--porcelain',
+    '--untracked-files=all',
+    ...EXCLUDE_SCRATCH,
+  ]);
+  if (!porcelain) return [];
+  return porcelain
+    .split('\n')
+    .filter((line) => line.length > 3)
+    .map((line) => {
+      const status = line.slice(0, 2);
+      let file = line.slice(3);
+      // Renames read `old -> new`; the new path is what landed.
+      if (file.includes(' -> ')) file = file.split(' -> ')[1];
+      return { path: file.replace(/^"|"$/g, '').trim(), status, untracked: status === '??' };
+    })
+    .filter((e) => e.path)
+    .sort((a, b) => a.path.localeCompare(b.path));
+}
+
+/**
+ * @param {string} cwd
+ * @returns {string[]}
+ */
+export function pendingFiles(cwd) {
+  return pendingEntries(cwd).map((e) => e.path);
+}
+
+/**
+ * What a reviewer should actually read.
+ *
+ * A group review runs *before* that group's checkpoint, so HEAD is still the
+ * previous checkpoint and `<base>..HEAD` is empty — the reviewer would be
+ * handed a range containing nothing. While the tree is dirty the target is the
+ * working tree instead, and untracked files are named because `git diff` never
+ * shows them.
+ *
+ * @param {string} base
+ * @param {{ path: string, untracked: boolean }[]} pending
+ * @returns {string}
+ */
+export function reviewTargetFor(base, pending) {
+  if (pending.length === 0) return `${base}..HEAD`;
+  const untracked = pending.filter((e) => e.untracked).map((e) => e.path);
+  const target = `git diff ${base} (working tree vs the last checkpoint)`;
+  if (untracked.length === 0) return target;
+  return `${target} — plus ${untracked.length} untracked file(s) that no diff shows, read them in full: ${untracked.join(', ')}`;
+}
+
+/**
+ * Git operations that must finish before anything else touches the index.
+ * @param {string} cwd
+ */
+function inProgressOperation(cwd) {
+  const gitDir = path.join(cwd, '.git');
+  for (const [file, label] of [
+    ['MERGE_HEAD', 'merge'],
+    ['CHERRY_PICK_HEAD', 'cherry-pick'],
+    ['REVERT_HEAD', 'revert'],
+    ['rebase-merge', 'rebase'],
+    ['rebase-apply', 'rebase'],
+    ['BISECT_LOG', 'bisect'],
+  ]) {
+    if (fs.existsSync(path.join(gitDir, file))) return label;
+  }
+  return null;
+}
+
+/**
+ * @param {{ slug?: string, openspecChange?: string }} session
+ * @param {{ group?: string, tasks?: string, message?: string }} opts
+ */
+export function checkpointSubject(session, opts) {
+  if (opts.message) return opts.message;
+  const scope = session.openspecChange || session.slug || 'session';
+  const label = [opts.group, opts.tasks && `tasks ${opts.tasks}`].filter(Boolean).join(' ');
+  return `forge(${scope}): checkpoint${label ? ` — ${label}` : ''}`;
+}
+
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+  usage();
+  process.exit(0);
+}
+
+/** @type {{ group?: string, tasks?: string, message?: string }} */
+const opts = {};
+let dryRun = false;
+let rangeOnly = false;
+let sinceLast = false;
+let allowDefaultBranch = false;
+let sessionId = null;
+for (let i = 0; i < args.length; i += 1) {
+  const a = args[i];
+  if (a === '--group' && args[i + 1]) opts.group = args[(i += 1)];
+  else if (a === '--tasks' && args[i + 1]) opts.tasks = args[(i += 1)];
+  else if ((a === '--message' || a === '-m') && args[i + 1]) opts.message = args[(i += 1)];
+  else if (a === '--session' && args[i + 1]) sessionId = args[(i += 1)];
+  else if (a === '--dry-run') dryRun = true;
+  else if (a === '--range') rangeOnly = true;
+  else if (a === '--last') sinceLast = true;
+  else if (a === '--allow-default-branch') allowDefaultBranch = true;
+  else {
+    usage();
+    fail(`Unknown argument: ${a}`);
+  }
+}
+
+const cwd = REPO_ROOT;
+
+if (!sessionId) {
+  const active = readActive();
+  if (!active?.sessionId) fail('No active Forge session — run forge new <slug> first.');
+  sessionId = active.sessionId;
+}
+const { dir: sessionDir, session } = loadSession(sessionId);
+
+const checkpoints = Array.isArray(session.checkpoints) ? session.checkpoints : [];
+
+// --- `--range`: what a reviewer should read, no repo mutation ---
+if (rangeOnly) {
+  const base = sinceLast && checkpoints.length ? checkpoints[checkpoints.length - 1].sha : session.baseCommit;
+  if (!base) {
+    emit({
+      ok: false,
+      range: null,
+      base: null,
+      checkpoints: checkpoints.length,
+      note: 'No base commit recorded — this session started before checkpoints, so reviewers read the working tree (git diff).',
+    });
+    process.exit(1);
+  }
+  let pending = [];
+  try {
+    pending = pendingEntries(cwd);
+  } catch {
+    /* not a git repo / unreadable — fall back to the bare commit range */
+  }
+  emit({
+    ok: true,
+    base,
+    range: `${base}..HEAD`,
+    dirty: pending.length > 0,
+    pending: pending.map((e) => e.path),
+    untracked: pending.filter((e) => e.untracked).map((e) => e.path),
+    reviewTarget: reviewTargetFor(base, pending),
+    checkpoints: checkpoints.length,
+    note: 'Pass reviewTarget as {DIFF_RANGE}. `range` is the commit range only — it is empty while the group under review is still uncommitted.',
+  });
+  process.exit(0);
+}
+
+// --- gates ---
+const config = loadProjectConfig(cwd);
+const mode = config?.git?.checkpoint ?? 'off';
+if (!MODES.includes(mode)) {
+  fail(`Unknown git.checkpoint mode "${mode}" in .forge/config.json (expected ${MODES.join(' | ')}).`);
+}
+if (mode === 'off') {
+  fail(
+    'Checkpoints are off for this project. Enable with .forge/config.json → { "git": { "checkpoint": "per-group" } }.',
+    { ok: false, reason: 'git.checkpoint is "off" — checkpoints disabled for this project' },
+  );
+}
+
+if (!fs.existsSync(path.join(cwd, '.git'))) {
+  fail(`Not a git repository: ${cwd} — nothing to checkpoint.`, { ok: false, reason: 'not a git repo' });
+}
+
+const busy = inProgressOperation(cwd);
+if (busy) {
+  fail(`A ${busy} is in progress — finish it before checkpointing.`, { ok: false, reason: `${busy} in progress` });
+}
+
+let branch;
+try {
+  branch = gitOut(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']);
+} catch (err) {
+  fail(`Could not read the current branch: ${err instanceof Error ? err.message : err}`);
+}
+if (DEFAULT_BRANCHES.has(branch) && !allowDefaultBranch && config?.git?.allowDefaultBranch !== true) {
+  fail(
+    `Refusing to checkpoint on the default branch "${branch}". Forge work belongs on a branch — create one, or pass --allow-default-branch (or set git.allowDefaultBranch: true) if this project really commits to ${branch}.`,
+    { ok: false, reason: `default branch "${branch}"` },
+  );
+}
+
+// --- what would land ---
+let files;
+try {
+  files = pendingFiles(cwd);
+} catch (err) {
+  fail(`Could not read the working tree: ${err instanceof Error ? err.message : err}`);
+}
+
+const subject = checkpointSubject(session, opts);
+
+if (files.length === 0) {
+  emit({
+    ok: true,
+    committed: false,
+    reason: 'nothing to checkpoint — working tree is clean',
+    branch,
+    range: session.baseCommit ? `${session.baseCommit}..HEAD` : null,
+  });
+  process.exit(0);
+}
+
+if (dryRun) {
+  emit({ ok: true, committed: false, dryRun: true, branch, subject, files });
+  process.exit(0);
+}
+
+// --- commit (never push) ---
+const prev = checkpoints.length ? checkpoints[checkpoints.length - 1].sha : null;
+try {
+  gitOut(cwd, ['add', '-A', ...EXCLUDE_SCRATCH]);
+} catch (err) {
+  fail(`git add failed: ${err instanceof Error ? err.message : err}`);
+}
+const commit = git(cwd, ['commit', '-m', subject, '--no-verify']);
+if (commit.status !== 0) {
+  fail(`git commit failed: ${commit.stderr.trim() || commit.stdout.trim()}`);
+}
+const sha = gitOut(cwd, ['rev-parse', 'HEAD']);
+
+// A session created before checkpoints existed has no base; this commit's
+// parent is the closest honest answer.
+if (!session.baseCommit) {
+  try {
+    session.baseCommit = gitOut(cwd, ['rev-parse', `${sha}^`]);
+  } catch {
+    session.baseCommit = sha; // root commit — nothing before it
+  }
+}
+if (!session.branch) session.branch = branch;
+
+checkpoints.push({
+  sha,
+  subject,
+  group: opts.group ?? null,
+  tasks: opts.tasks ?? null,
+  files: files.length,
+  at: new Date().toISOString(),
+});
+session.checkpoints = checkpoints;
+saveSession(sessionDir, session);
+
+emit({
+  ok: true,
+  committed: true,
+  sha,
+  subject,
+  branch,
+  files,
+  range: `${session.baseCommit}..HEAD`,
+  groupRange: prev ? `${prev}..${sha}` : `${session.baseCommit}..${sha}`,
+  pushed: false,
+  note: 'Checkpoints never push. Pass groupRange as {DIFF_RANGE} to the group reviewer.',
+});

package/src/checkpoint.test.mjs

@@ -0,0 +1,252 @@
+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, spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const SRC = path.dirname(fileURLToPath(import.meta.url));
+const CHECKPOINT = path.join(SRC, 'checkpoint.mjs');
+
+function tmp(prefix) {
+  return fs.realpathSync(fs.mkdtempSync(path.join(tmpdir(), prefix)));
+}
+
+function git(cwd, ...args) {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  if (r.status !== 0) throw new Error(`git ${args.join(' ')}: ${r.stderr}`);
+  return r.stdout.trim();
+}
+
+/**
+ * Git project on a feature branch with one commit, a Forge session, and
+ * uncommitted work — the shape of an implement phase at a group boundary.
+ */
+function makeProject({ branch = 'feature-x', config = { git: { checkpoint: 'per-group' } } } = {}) {
+  const cwd = tmp('forge-ckpt-');
+  git(cwd, 'init', '-q', '-b', 'main');
+  git(cwd, 'config', 'user.email', 'test@example.com');
+  git(cwd, 'config', 'user.name', 'Test');
+  fs.writeFileSync(path.join(cwd, 'README.md'), '# base\n', 'utf8');
+  git(cwd, 'add', '-A');
+  git(cwd, 'commit', '-q', '-m', 'base');
+  const baseSha = git(cwd, 'rev-parse', 'HEAD');
+  if (branch !== 'main') git(cwd, 'checkout', '-q', '-b', branch);
+
+  const sessionDir = path.join(cwd, '.forge', 'sessions', 's1');
+  fs.mkdirSync(sessionDir, { recursive: true });
+  const now = new Date().toISOString();
+  fs.writeFileSync(
+    path.join(sessionDir, 'session.json'),
+    `${JSON.stringify({
+      id: 's1',
+      slug: 'phase-1',
+      createdAt: now,
+      updatedAt: now,
+      phase: 'implement',
+      planType: 'specs',
+      openspecChange: 'phase-1',
+      tasksTotal: 8,
+      tasksComplete: 4,
+      baseCommit: baseSha,
+      branch,
+    })}\n`,
+    'utf8',
+  );
+  fs.writeFileSync(
+    path.join(cwd, '.forge', 'active.json'),
+    `${JSON.stringify({ sessionId: 's1' })}\n`,
+    'utf8',
+  );
+  if (config) {
+    fs.writeFileSync(
+      path.join(cwd, '.forge', 'config.json'),
+      `${JSON.stringify(config)}\n`,
+      'utf8',
+    );
+  }
+  // Agent work: one edit, one new file.
+  fs.appendFileSync(path.join(cwd, 'README.md'), 'edited by task 1.1\n');
+  fs.writeFileSync(path.join(cwd, 'new-module.mjs'), 'export const x = 1;\n', 'utf8');
+  return { cwd, sessionDir, baseSha };
+}
+
+function run(cwd, args = []) {
+  const env = { ...process.env, FORGEKIT_FLEET_DIR: path.join(tmp('ckpt-fleet-'), 's') };
+  try {
+    const stdout = execFileSync(process.execPath, [CHECKPOINT, ...args], { cwd, env });
+    return { status: 0, out: JSON.parse(stdout.toString()), stderr: '' };
+  } catch (err) {
+    let out = null;
+    try {
+      out = JSON.parse(String(err.stdout));
+    } catch {
+      /* non-JSON failure */
+    }
+    return { status: err.status, out, stderr: String(err.stderr) };
+  }
+}
+
+function readSession(sessionDir) {
+  return JSON.parse(fs.readFileSync(path.join(sessionDir, 'session.json'), 'utf8'));
+}
+
+test('checkpoint commits the working tree and records the commit on the session', () => {
+  const { cwd, sessionDir, baseSha } = makeProject();
+
+  const { status, out } = run(cwd, ['--group', 'group-02-testkit', '--tasks', '2.1-2.4']);
+  assert.equal(status, 0);
+  assert.equal(out.ok, true);
+  assert.equal(out.committed, true);
+  assert.match(out.subject, /phase-1/);
+  assert.match(out.subject, /group-02-testkit/);
+  // Both the edit and the untracked file are in — agent work is mostly new files.
+  assert.deepEqual(out.files.sort(), ['README.md', 'new-module.mjs']);
+
+  // Product files are all in; session scratch is deliberately left out, so a
+  // checkpoint cannot bury the diff under .forge churn (or dirty the tree
+  // again with its own session write).
+  assert.equal(
+    git(cwd, 'status', '--porcelain', '--', '.', ':(exclude).forge'),
+    '',
+    'no product file is left uncommitted',
+  );
+  assert.equal(
+    git(cwd, 'show', '--name-only', '--format=', 'HEAD').split('\n').some((f) => f.startsWith('.forge')),
+    false,
+    'session scratch is never committed by a checkpoint',
+  );
+  const session = readSession(sessionDir);
+  assert.equal(session.checkpoints.length, 1);
+  assert.equal(session.checkpoints[0].sha, git(cwd, 'rev-parse', 'HEAD'));
+  assert.equal(session.checkpoints[0].group, 'group-02-testkit');
+  assert.equal(session.checkpoints[0].tasks, '2.1-2.4');
+  // The range a reviewer needs: everything this session has produced.
+  assert.equal(out.range, `${baseSha}..HEAD`);
+});
+
+test('a second checkpoint reports the range covering only the new group', () => {
+  const { cwd, sessionDir } = makeProject();
+  const first = run(cwd, ['--group', 'group-01']);
+  assert.equal(first.status, 0);
+
+  fs.writeFileSync(path.join(cwd, 'second.mjs'), 'export const y = 2;\n', 'utf8');
+  const second = run(cwd, ['--group', 'group-02']);
+
+  assert.equal(second.status, 0);
+  assert.equal(second.out.groupRange, `${first.out.sha}..${second.out.sha}`);
+  assert.deepEqual(second.out.files, ['second.mjs']);
+  assert.equal(readSession(sessionDir).checkpoints.length, 2);
+});
+
+test('a clean tree is not an error and creates no empty commit', () => {
+  const { cwd } = makeProject();
+  run(cwd, ['--group', 'group-01']);
+  const head = git(cwd, 'rev-parse', 'HEAD');
+
+  const { status, out } = run(cwd, ['--group', 'group-02']);
+  assert.equal(status, 0);
+  assert.equal(out.ok, true);
+  assert.equal(out.committed, false);
+  assert.match(out.reason, /nothing to checkpoint/i);
+  assert.equal(git(cwd, 'rev-parse', 'HEAD'), head, 'no empty commit');
+});
+
+test('--dry-run reports what would be committed and commits nothing', () => {
+  const { cwd, sessionDir } = makeProject();
+  const head = git(cwd, 'rev-parse', 'HEAD');
+
+  const { status, out } = run(cwd, ['--group', 'group-01', '--dry-run']);
+  assert.equal(status, 0);
+  assert.equal(out.committed, false);
+  assert.deepEqual(out.files.sort(), ['README.md', 'new-module.mjs']);
+  assert.equal(git(cwd, 'rev-parse', 'HEAD'), head);
+  assert.equal(readSession(sessionDir).checkpoints, undefined);
+});
+
+test('checkpoints are refused on the default branch unless explicitly allowed', () => {
+  // Forge work belongs on a branch; committing straight to main is the one
+  // mistake an automated commit must never make on its own.
+  const { cwd } = makeProject({ branch: 'main' });
+
+  const refused = run(cwd, ['--group', 'group-01']);
+  assert.equal(refused.status, 1);
+  assert.match(refused.stderr, /default branch/i);
+  assert.equal(git(cwd, 'status', '--porcelain') === '', false, 'work is left untouched');
+
+  const allowed = run(cwd, ['--group', 'group-01', '--allow-default-branch']);
+  assert.equal(allowed.status, 0);
+  assert.equal(allowed.out.committed, true);
+});
+
+test('checkpoints are off unless the project opts in', () => {
+  const { cwd } = makeProject({ config: {} });
+  const { status, out, stderr } = run(cwd, ['--group', 'group-01']);
+  assert.equal(status, 1);
+  assert.equal(out?.ok, false);
+  assert.match(`${stderr}${out?.reason ?? ''}`, /checkpoint/i);
+  assert.match(`${stderr}${out?.reason ?? ''}`, /git\.checkpoint/);
+});
+
+test('an in-progress merge blocks a checkpoint', () => {
+  const { cwd } = makeProject();
+  fs.writeFileSync(path.join(cwd, '.git', 'MERGE_HEAD'), `${'0'.repeat(40)}\n`, 'utf8');
+
+  const { status, stderr } = run(cwd, ['--group', 'group-01']);
+  assert.equal(status, 1);
+  assert.match(stderr, /merge|rebase|in progress/i);
+});
+
+test('--range --last targets the working tree while the group is still uncommitted', () => {
+  // The group review runs BEFORE its checkpoint, so at review time the group's
+  // work is uncommitted and HEAD is still the previous checkpoint: a
+  // `<sha>..HEAD` range would be empty and the reviewer would read nothing.
+  const { cwd } = makeProject();
+  const first = run(cwd, ['--group', 'group-01']);
+  fs.writeFileSync(path.join(cwd, 'second.mjs'), 'export const y = 2;\n', 'utf8');
+  fs.appendFileSync(path.join(cwd, 'README.md'), 'more\n');
+
+  const { status, out } = run(cwd, ['--range', '--last']);
+  assert.equal(status, 0);
+  assert.equal(out.base, first.out.sha);
+  assert.equal(out.dirty, true);
+  // Untracked files are most of what an agent writes and never appear in a
+  // plain `git diff`, so they must be called out by name.
+  assert.deepEqual(out.untracked, ['second.mjs']);
+  assert.match(out.reviewTarget, new RegExp(`git diff ${first.out.sha}`));
+  assert.match(out.reviewTarget, /second\.mjs/);
+});
+
+test('--range --last is a plain commit range once the group is checkpointed', () => {
+  const { cwd } = makeProject();
+  run(cwd, ['--group', 'group-01']);
+  fs.writeFileSync(path.join(cwd, 'second.mjs'), 'export const y = 2;\n', 'utf8');
+  const second = run(cwd, ['--group', 'group-02']);
+
+  const { out } = run(cwd, ['--range', '--last']);
+  assert.equal(out.dirty, false);
+  assert.deepEqual(out.untracked, []);
+  assert.equal(out.base, second.out.sha);
+  assert.equal(out.reviewTarget, `${second.out.sha}..HEAD`);
+});
+
+test('--range without --last spans the whole session from its base commit', () => {
+  const { cwd, baseSha } = makeProject();
+  run(cwd, ['--group', 'group-01']);
+
+  const { out } = run(cwd, ['--range']);
+  assert.equal(out.base, baseSha);
+  assert.equal(out.range, `${baseSha}..HEAD`);
+  assert.equal(out.dirty, false);
+});
+
+test('checkpoint never pushes', () => {
+  const { cwd } = makeProject();
+  // A remote that would fail loudly if anything tried to reach it.
+  git(cwd, 'remote', 'add', 'origin', 'file:///nonexistent-remote.git');
+  const { status, out } = run(cwd, ['--group', 'group-01']);
+  assert.equal(status, 0);
+  assert.equal(out.committed, true);
+  assert.equal(git(cwd, 'log', '--oneline', '-1', '--format=%s').includes('phase-1'), true);
+});

package/src/fleet.mjs

@@ -24,6 +24,7 @@ import {
   queueMessage,
   sessionDirFor,
 } from './lib/fleet.mjs';
+import { healthCell, sessionHealth } from './health.mjs';
 
 function usage() {
   process.stderr.write(
@@ -70,21 +71,45 @@ function pad(str, len) {
   return s.length >= len ? s.slice(0, len) : s + ' '.repeat(len - s.length);
 }
 
+/**
+ * Health per entry, read from that project's session dir. A row showing a
+ * healthy-looking `27/32` while its e2e run is red and nobody has touched it
+ * for 14 hours is the failure this column exists to prevent.
+ */
+function healthFor(entry) {
+  if (entry.missing) return { state: 'unknown', line: 'missing' };
+  try {
+    const sessionDir = sessionDirFor(entry);
+    const session = JSON.parse(fs.readFileSync(path.join(sessionDir, 'session.json'), 'utf8'));
+    return sessionHealth({ cwd: entry.project, sessionDir, session });
+  } catch {
+    return { state: 'unknown', line: 'unknown' };
+  }
+}
+
 function renderTable(entries) {
   if (entries.length === 0) return 'No fleet sessions. Start one with `forge new <slug>`.\n';
-  const header = `${pad('PROJECT', 18)} ${pad('SESSION', 26)} ${pad('ENGINE', 7)} ${pad('PHASE', 18)} ${pad('TASKS', 16)} ${pad('PACE', 9)} ${pad('AGE', 4)} MSGS`;
+  const header = `${pad('PROJECT', 18)} ${pad('SESSION', 26)} ${pad('ENGINE', 7)} ${pad('PHASE', 18)} ${pad('TASKS', 16)} ${pad('HEALTH', 6)} ${pad('PACE', 9)} ${pad('AGE', 4)} MSGS`;
   const lines = [header, '-'.repeat(header.length)];
+  /** @type {string[]} */
+  const notes = [];
   for (const e of entries) {
     const pending = e.missing ? 0 : peekInbox(sessionDirFor(e)).length;
+    const health = healthFor(e);
+    if (health.state === 'red' || health.state === 'stale') {
+      notes.push(`${e.projectName}/${e.slug}: ${health.line}`);
+    }
     lines.push(
       `${pad(e.projectName, 18)} ${pad(e.slug, 26)} ${pad(e.engine ?? '—', 7)} ${pad(
         e.missing ? 'missing' : phaseBar(e.phase),
         18,
-      )} ${pad(tasksCell(e), 16)} ${pad(e.pace ?? '—', 9)} ${pad(relTime(e.lastSeen ?? e.updatedAt), 4)} ${
+      )} ${pad(tasksCell(e), 16)} ${pad(healthCell(health.state), 6)} ${pad(e.pace ?? '—', 9)} ${pad(relTime(e.lastSeen ?? e.updatedAt), 4)} ${
         pending > 0 ? `✉ ${pending}` : ''
       }`,
     );
   }
+  // The column says which row; the notes say why, without a second command.
+  if (notes.length) lines.push('', ...notes.map((n) => `  ! ${n}`));
   return `${lines.join('\n')}\n`;
 }
 

package/src/health.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+/**
+ * Session health — a verdict, not a data dump.
+ *
+ * `forge status` printed every field a session had and said nothing about
+ * whether the session was in trouble, so a session could sit at
+ * `implement 27/32` with a red e2e run for 14 hours and look exactly like one
+ * that was mid-stride. Health answers the one question the operator actually
+ * asks: is this session fine, stopped, or broken?
+ *
+ * Cheap on purpose — file reads only, no subprocesses — because it runs on
+ * every `forge status`, every reminder hook, and once per row in
+ * `forge fleet list`.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { e2ePath, e2eStepsHash, loadE2eResults } from './integrity.mjs';
+import { readJson } from './lib.mjs';
+
+/** Hours of no session write after which an unfinished session reads as stopped. */
+export const DEFAULT_IDLE_HOURS = 4;
+
+const SEVERITY = { done: 0, healthy: 1, stale: 2, red: 3 };
+
+/**
+ * @param {number} ms
+ * @returns {string}
+ */
+function humanDuration(ms) {
+  const min = Math.floor(ms / 60000);
+  if (min < 60) return `${Math.max(min, 1)}m`;
+  const hours = Math.floor(min / 60);
+  if (hours < 48) return `${hours}h`;
+  return `${Math.floor(hours / 24)}d`;
+}
+
+/**
+ * The failing step of a red run, for a reason line that names the problem
+ * instead of pointing at a file.
+ *
+ * @param {Record<string, any> | null} results
+ */
+function failedStepName(results) {
+  if (!results || !Array.isArray(results.steps)) return null;
+  const failed = results.steps.find((s) => s && s.ok === false);
+  return failed?.name ?? null;
+}
+
+/**
+ * @param {{ cwd?: string, sessionDir: string, session: Record<string, any>, now?: number, idleHours?: number }} opts
+ * @returns {{ state: 'healthy'|'stale'|'red'|'done', reasons: string[], line: string }}
+ */
+export function sessionHealth(opts) {
+  const cwd = opts.cwd ?? process.cwd();
+  const { sessionDir, session } = opts;
+  const now = opts.now ?? Date.now();
+  const idleHours = Number.isFinite(opts.idleHours) ? Number(opts.idleHours) : DEFAULT_IDLE_HOURS;
+
+  /** @type {string[]} */
+  const reasons = [];
+  let state = 'healthy';
+  const escalate = (next) => {
+    if (SEVERITY[next] > SEVERITY[state]) state = next;
+  };
+
+  if (session.phase === 'done' || session.phase === 'skipped') {
+    return {
+      state: 'done',
+      reasons: [],
+      line: `DONE — ${session.slug ?? session.id} (${session.phase})`,
+    };
+  }
+
+  // --- executed product loop: the strongest signal we have on disk ---
+  try {
+    const results = loadE2eResults(sessionDir);
+    if (results) {
+      let currentHash = null;
+      try {
+        const doc = readJson(e2ePath({ cwd, session, sessionDir }));
+        currentHash = e2eStepsHash(doc.steps);
+      } catch {
+        currentHash = null;
+      }
+      // A failed run outranks a stale one: staleness asks "does this proof
+      // still describe the current steps", a failure says the loop is broken
+      // either way.
+      if (results.ok === false) {
+        const step = failedStepName(results);
+        const since = results.ranAt ? ` since ${results.ranAt}` : '';
+        reasons.push(`e2e failing${since}${step ? ` at step "${step}"` : ''}`);
+        escalate('red');
+      } else if (currentHash && results.stepsHash !== currentHash) {
+        reasons.push('e2e results are stale — e2e.json changed since the last run');
+        escalate('stale');
+      }
+    }
+  } catch {
+    /* health must never throw — a broken artifact is the caller's problem */
+  }
+
+  // --- an explicit BLOCKED beats any inference we could make ---
+  try {
+    const verify = path.join(sessionDir, 'verify-evidence.md');
+    if (fs.existsSync(verify) && /\bBLOCKED\b/.test(fs.readFileSync(verify, 'utf8'))) {
+      reasons.push('verify-evidence records BLOCKED — product loop not proven');
+      escalate('red');
+    }
+  } catch {
+    /* ignore */
+  }
+
+  // --- idle: nobody is driving this session ---
+  const updatedAt = new Date(session.updatedAt ?? session.createdAt ?? NaN).getTime();
+  if (!Number.isNaN(updatedAt)) {
+    const idleMs = now - updatedAt;
+    if (idleMs > idleHours * 3600 * 1000) {
+      const where = `${session.phase ?? 'unknown'}${
+        Number(session.tasksTotal) > 0 ? ` ${session.tasksComplete ?? 0}/${session.tasksTotal}` : ''
+      }`;
+      reasons.push(`idle ${humanDuration(idleMs)} at ${where}`);
+      escalate('stale');
+    }
+  }
+
+  const label = state.toUpperCase();
+  const line = reasons.length ? `${label} — ${reasons.join('; ')}` : `${label} — ${session.phase}`;
+  return { state, reasons, line };
+}
+
+/** Short cell for table renderers (`forge fleet list`). */
+export function healthCell(state) {
+  switch (state) {
+    case 'red':
+      return 'RED';
+    case 'stale':
+      return 'STALE';
+    case 'done':
+      return 'done';
+    default:
+      return 'ok';
+  }
+}

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/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/session-reminder.mjs

@@ -17,6 +17,7 @@ import {
   touchSession,
 } from './lib/fleet.mjs';
 import { resolveEffectivePreferences } from './preferences.mjs';
+import { sessionHealth } from './health.mjs';
 
 function getActiveSessionInfo() {
   const active = readActive();
@@ -88,6 +89,15 @@ export function buildForgeMessage(info) {
   if (session.tasksTotal > 0) {
     lines.push(`Tasks: ${session.tasksComplete}/${session.tasksTotal}`);
   }
+  // Only when something is wrong: a resumed session that is red or was
+  // abandoned mid-implement should say so before the agent picks up where it
+  // thinks it left off.
+  if (info.dir) {
+    const health = sessionHealth({ cwd: REPO_ROOT, sessionDir: info.dir, session });
+    if (health.state === 'red' || health.state === 'stale') {
+      lines.push(`Health: ${health.line}`);
+    }
+  }
   if (needsOpenSpecPlan(session)) {
     lines.push(OPENSPEC_PLAN_REMINDER);
   }

package/src/session-status.mjs

@@ -16,6 +16,7 @@ import {
   REPO_ROOT,
 } from './lib.mjs';
 import { resolveEffectivePreferences } from './preferences.mjs';
+import { sessionHealth } from './health.mjs';
 
 const args = process.argv.slice(2);
 let sessionId = null;
@@ -46,12 +47,17 @@ const pace = resolveEffectivePreferences({
   signalText: session.paceSignal || session.slug || '',
 });
 
+const health = sessionHealth({ cwd: REPO_ROOT, sessionDir: dir, session });
+
 process.stdout.write(
   JSON.stringify(
     {
       status: 'ok',
       sessionId,
       sessionPath: path.relative(REPO_ROOT, dir).replace(/\\/g, '/'),
+      // 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,
       session,
       progress: status,
       pace: {

package/vendor/skills/forge/SKILL.md

@@ -113,7 +113,8 @@ Testing: [references/test-strategy.md](./references/test-strategy.md) — tier 1
 
 ## Guardrails (every phase)
 
-- No autonomous `git commit` / push unless the user explicitly asks
+- 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
 - 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

@@ -268,8 +268,12 @@ OpenSpec commands remain available standalone (OpenSpec-engine projects):
 
 ```bash
 forge new <slug> [--signal "…"]   # new session + set active (resolves pace; warn-only doctor)
-forge status                      # active session JSON (+ effective pace)
+forge status                      # active session JSON (+ effective pace + health verdict)
 forge phase <phase> […]           # update phase / openspec / task counters
+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 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
@@ -572,7 +576,7 @@ forge models metered                  # WRITE .forge/models.local.json
 
 Guardrails in every subagent brief (honor the **project’s** agent docs too):
 
-- No autonomous `git commit` / push unless the user asks
+- No autonomous `git commit` / push unless the user asks — subagents never commit at all
 - Implementer runs tier 1 (scoped) + tier 2 (narrow) tests; coordinator saves `tasks/<nn>-<slug>/test-evidence.md` before marking task done
 - Trace downstream consumers when contracts change
 
@@ -580,6 +584,79 @@ Prompt templates: [subagents/](../subagents/)
 
 ---
 
+## Checkpoints (opt-in commits)
+
+Off by default. Enable per project in `.forge/config.json`:
+
+```json
+{ "git": { "checkpoint": "per-group" } }
+```
+
+| Mode | When the coordinator runs `forge checkpoint` |
+| ---- | -------------------------------------------- |
+| `off` (default) | never — nothing is committed, reviewers read the working tree |
+| `per-group` | at each `tasks.md` group boundary |
+| `per-task` | after each task |
+
+Why: a long session otherwise accumulates the whole change as one uncommitted
+working tree — one bad `git checkout` from losing a day of agent work, with
+every reviewer after task 1 reading a diff that contains all previous tasks.
+
+Guarantees — the reason this is safe to automate:
+
+- **Never pushes.** Nothing leaves the machine.
+- **Refuses on the default branch** (`main` / `master`) unless
+  `--allow-default-branch` or `git.allowDefaultBranch: true`.
+- **Refuses mid-merge / rebase / cherry-pick / revert / bisect.**
+- **Excludes `.forge/`** — session scratch never lands in project history.
+- Nothing to commit is success, not an error, and never makes an empty commit.
+- Records `{ sha, group, tasks, at }` on the session, so reviewers get a real
+  range: `groupRange` (this group) and `range` (whole session, from
+  `session.baseCommit`, which `forge new` records even when checkpoints are off).
+
+```bash
+forge checkpoint --group 06-helm-cli --tasks 6.1-6.4
+forge checkpoint --dry-run          # list what would be committed
+forge checkpoint --range --last     # {DIFF_RANGE} for the group reviewer
+```
+
+**Reviewer scope.** A group review happens *before* that group's checkpoint,
+so HEAD is still the previous one and a `<base>..HEAD` range would be empty.
+Use the `reviewTarget` field from `forge checkpoint --range --last`:
+
+| Tree state | `reviewTarget` |
+| ---------- | -------------- |
+| group still uncommitted | `git diff <last checkpoint>` **plus** the untracked files listed by name — `git diff` never shows them, and new files are most of what an implementer writes |
+| group checkpointed | `<last checkpoint>..HEAD` |
+
+`range` in the same output is the commit range only; it is empty mid-group by
+design. `--last` scopes to the current group, without it the base is
+`session.baseCommit` (the whole session).
+
+Caveat: a checkpoint stages **everything outside `.forge/`**, including
+unrelated edits sitting in the tree. Check `--dry-run` when the working tree
+was not clean before the session started.
+
+---
+
+## Session health
+
+`forge status` returns a verdict next to the data, and the reminder hook
+surfaces it on resume when it is not healthy:
+
+| State | Meaning |
+| ----- | ------- |
+| `red` | e2e run failing (named step), or `verify-evidence.md` records BLOCKED |
+| `stale` | no session write for `health.idleHours` (default 4), or e2e results no longer match `e2e.json` |
+| `healthy` | none of the above |
+| `done` | phase `done` / `skipped` |
+
+`forge fleet list` renders the same verdict as a HEALTH column plus a reason
+line per unhealthy session, so a red or abandoned session is visible without
+opening the project.
+
+---
+
 ## Bundled skills (self-contained)
 
 Forge vendors adapted Superpowers skills (MIT) under `skills/forge/skills/`.

package/vendor/skills/forge/phases/implement.md

@@ -56,7 +56,24 @@ Honor [../references/runtime-integrity.md](../references/runtime-integrity.md) i
    ```
    (Refuses non-zero exit without `--allow-fail`; template + rules in [../references/test-evidence.md](../references/test-evidence.md).)
 7. Mark task complete (`tasks.md` `- [x]` or update `tasksComplete`). Detect group boundary: next line in `tasks.md` is a new `##` heading, or no remaining tasks under the current heading.
-8. Repeat.
+8. **Checkpoint** — when the project opts in (`.forge/config.json` → `git.checkpoint`):
+   ```bash
+   forge checkpoint --group <nn>-<slug> --tasks <ids>   # per-group: at the boundary; per-task: after each task
+   ```
+   Commits the group's work and records the sha on the session. Never pushes,
+   refuses on the default branch, and leaves `.forge/` scratch out of the
+   commit. Default is `off`: nothing is committed and reviewers read the
+   working tree, as before.
+
+   **Reviewer scope (step 4).** The group review runs *before* this
+   checkpoint, so fill `{DIFF_RANGE}` from `forge checkpoint --range --last` →
+   its **`reviewTarget`** field. While the group is uncommitted that is
+   `git diff <last checkpoint>` plus the untracked files named explicitly (a
+   diff never shows them); once checkpointed it collapses to a plain commit
+   range. Do **not** paste `range` during a pre-checkpoint review — it is
+   empty until the group lands. Without checkpoints, every reviewer after task
+   1 re-reads all previous tasks' diffs.
+9. Repeat.
 
 **Batching:** consecutive small same-area tasks (docs, config, wording) may share one implementer brief + one review — see the batching rules in [subagent-driven-development](../skills/subagent-driven-development/SKILL.md). Never batch money/auth/contract/migration tasks.
 
@@ -66,7 +83,7 @@ forge phase implement --tasks-complete <N> --subagents <total dispatched so far>
 
 ## Forge constraints (include in every brief)
 
-- **No** autonomous `git commit` or `git push`
+- **No** autonomous `git commit` or `git push` — implementer subagents never commit. Checkpoints are the coordinator's job and only when `git.checkpoint` is enabled (`forge checkpoint`, which still never pushes)
 - **Tier 2 tests only** before claiming task done — narrowest command for this task ([test-strategy.md](../references/test-strategy.md)); **not** the full workspace suite unless the task requires it
 - Trace ecosystem consumers when contracts change
 - Minimal diff — surgical changes only

package/vendor/skills/forge/subagents/task-reviewer-prompt.md

@@ -21,7 +21,7 @@ Capability specs beat narrow task wording when they conflict. See
 
 {FILE_LIST}
 
-Diff range: {DIFF_RANGE}   <!-- e.g. `git diff` (uncommitted) or BASE..HEAD -->
+Diff range: {DIFF_RANGE}   <!-- `forge checkpoint --range --last` → paste its `reviewTarget` (scopes to this group; names untracked files a diff hides). No checkpoints: `git diff` + the untracked files in `git status`. -->
 
 **Read the actual code.** The summary above was written by the party under review — it is a map, not evidence. Read the changed files (or the diff range) before any verdict; verify each spec requirement against what the code does, not what the summary says it does.