@izkac/forgekit 0.3.14 → 0.3.16

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-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,8 @@ import {
   REPO_ROOT,
 } 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;
@@ -46,12 +48,25 @@ const pace = resolveEffectivePreferences({
   signalText: session.paceSignal || session.slug || '',
 });
 
+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(
     {
       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,
+      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

@@ -113,7 +113,10 @@ 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
+- **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

@@ -268,8 +268,15 @@ 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 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
@@ -572,7 +579,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 +587,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.