@izkac/forgekit 0.3.13 → 0.3.15

package/src/lib.test.mjs

@@ -0,0 +1,128 @@
+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';
+import { findRepoRoot, sessionAgeDays } from './lib.mjs';
+
+const SESSION_STATUS = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  'session-status.mjs',
+);
+
+function tmp(prefix) {
+  return fs.realpathSync(fs.mkdtempSync(path.join(tmpdir(), prefix)));
+}
+
+test('sessionAgeDays reads createdAt, then startedAt, then updatedAt', () => {
+  const days = (n) => new Date(Date.now() - n * 86400000).toISOString();
+
+  assert.ok(Math.abs(sessionAgeDays({ createdAt: days(3) }) - 3) < 0.01);
+  // Hand-written / legacy records carry startedAt (a bare date) instead.
+  assert.ok(Math.abs(sessionAgeDays({ startedAt: days(5).slice(0, 10) }) - 5) < 1.01);
+  assert.ok(Math.abs(sessionAgeDays({ updatedAt: days(2) }) - 2) < 0.01);
+  // createdAt wins when several are present.
+  assert.ok(
+    Math.abs(sessionAgeDays({ createdAt: days(9), startedAt: days(1), updatedAt: days(1) }) - 9) <
+      0.01,
+  );
+});
+
+test('sessionAgeDays treats an undatable session as infinitely old, not age 0', () => {
+  // Regression: `new Date(undefined)` → NaN, and `NaN > RETENTION_DAYS` is
+  // false, so a session record without a date was never "too old" and
+  // survived every cleanup run forever.
+  assert.equal(sessionAgeDays({ phase: 'implement' }), Infinity);
+  assert.equal(sessionAgeDays({ createdAt: 'not-a-date' }), Infinity);
+  assert.equal(sessionAgeDays({}), Infinity);
+});
+
+test('forge cleanup removes an undatable abandoned session', () => {
+  const root = tmp('forge-cleanup-');
+  const sessionDir = path.join(root, '.forge', 'sessions', 'legacy');
+  fs.mkdirSync(sessionDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(sessionDir, 'session.json'),
+    // No date of any kind — the shape that lingered in volo, minus the
+    // startedAt that now gives such records a real age.
+    `${JSON.stringify({ slug: 'legacy', phase: 'implement' })}\n`,
+    'utf8',
+  );
+
+  const cleanup = path.join(path.dirname(SESSION_STATUS), 'cleanup-sessions.mjs');
+  const out = execFileSync(process.execPath, [cleanup], {
+    cwd: root,
+    env: { ...process.env, FORGEKIT_FLEET_DIR: path.join(tmp('forge-cleanup-fleet-'), 's') },
+  }).toString();
+
+  assert.match(out, /"reason": "retention"/);
+  assert.equal(fs.existsSync(sessionDir), false);
+});
+
+test('findRepoRoot walks up to the nearest .forge, then .git, then falls back', () => {
+  const root = tmp('forge-root-');
+  const nested = path.join(root, 'crates', 'helm-vfs', 'src');
+  fs.mkdirSync(nested, { recursive: true });
+
+  // No markers anywhere: the start dir is the root.
+  assert.equal(findRepoRoot(nested), nested);
+
+  // .git alone marks the project.
+  fs.mkdirSync(path.join(root, '.git'), { recursive: true });
+  assert.equal(findRepoRoot(nested), root);
+
+  // .forge wins over .git when both are present but at different depths:
+  // a nested checkout with its own session is its own project.
+  const inner = path.join(root, 'crates');
+  fs.mkdirSync(path.join(inner, '.forge'), { recursive: true });
+  assert.equal(findRepoRoot(nested), inner);
+  assert.equal(findRepoRoot(root), root);
+});
+
+test('forge status finds the session from a subdirectory of the project', () => {
+  const root = tmp('forge-subdir-');
+  const sessionDir = path.join(root, '.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: 'fixture',
+      createdAt: now,
+      updatedAt: now,
+      phase: 'implement',
+      planType: 'specs',
+      openspecChange: 'my-change',
+      tasksTotal: 3,
+      tasksComplete: 1,
+    })}\n`,
+    'utf8',
+  );
+  fs.writeFileSync(
+    path.join(root, '.forge', 'active.json'),
+    `${JSON.stringify({ sessionId: 's1' })}\n`,
+    'utf8',
+  );
+  const nested = path.join(root, 'crates', 'helm-vfs');
+  fs.mkdirSync(nested, { recursive: true });
+
+  const env = { ...process.env, FORGEKIT_FLEET_DIR: path.join(tmp('forge-subdir-fleet-'), 's') };
+  const out = execFileSync(process.execPath, [SESSION_STATUS], { cwd: nested, env }).toString();
+  const status = JSON.parse(out);
+
+  assert.equal(status.status, 'ok');
+  assert.equal(status.sessionId, 's1');
+  // Paths stay relative to the project root, not to the working directory.
+  assert.equal(status.sessionPath, '.forge/sessions/s1');
+
+  // ...and through the bin, which re-roots the child process, so writes land
+  // in the project's .forge rather than creating a second tree in the subdir.
+  const FORGE_BIN = path.join(path.dirname(SESSION_STATUS), '..', 'bin', 'forge.mjs');
+  execFileSync(process.execPath, [FORGE_BIN, 'phase', 'brainstorm'], { cwd: nested, env });
+  const saved = JSON.parse(fs.readFileSync(path.join(sessionDir, 'session.json'), 'utf8'));
+  assert.equal(saved.phase, 'brainstorm');
+  assert.equal(fs.existsSync(path.join(nested, '.forge')), false);
+});

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/repo-root.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/**
+ * Project-root resolution.
+ *
+ * Standalone (node builtins only) so the `forge` bin can re-root itself
+ * without importing session machinery.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Nearest enclosing project root: the closest ancestor holding `.forge/`,
+ * else the closest holding `.git/` (a repo boundary — a nested checkout must
+ * not adopt the enclosing project's sessions), else the start dir.
+ *
+ * Without this, forge was bound to the exact cwd: `cd crates && forge status`
+ * reported "no session" in a repo that had one, and `forge new` there would
+ * have created a second `.forge` tree inside the workspace.
+ *
+ * @param {string} [start]
+ * @returns {string}
+ */
+export function findRepoRoot(start = process.cwd()) {
+  let dir = path.resolve(start);
+  for (;;) {
+    if (fs.existsSync(path.join(dir, '.forge'))) return dir;
+    if (fs.existsSync(path.join(dir, '.git'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return path.resolve(start);
+    dir = parent;
+  }
+}

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/src/specs-sync.mjs

@@ -115,10 +115,8 @@ export function applyDeltaToMain(capability, mainBody, deltaBody) {
   const reqHeaderEnd = reqMatch ? reqMatch.index + reqMatch[0].length : main.length;
   const before = main.slice(0, reqHeaderEnd);
   const afterReq = main.slice(reqHeaderEnd);
-  // Stop at next ## section if any
-  const nextSection = /^##\s+/m.exec(afterReq.replace(/^\n/, ''));
-  // Simpler: treat everything after ## Requirements as the requirements body
-  // until EOF (OpenSpec main specs usually end there).
+  // Treat everything after ## Requirements as the requirements body until the
+  // next non-Requirements ## heading (OpenSpec main specs usually end there).
   let reqBody = afterReq.replace(/^\n+/, '');
   const trailingMatch = /\n##\s+(?!Requirements).*$/m.exec(`\n${reqBody}`);
   let trailing = '';

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.