@izkac/forgekit 0.2.0 → 0.3.0

package/bin/forge.mjs

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 /**
  * Forge CLI — session orchestration, prefs, models, project init.
  *
@@ -35,6 +35,8 @@ const COMMANDS = {
   defer: { script: 'defer.mjs' },
   'integrity-check': { script: 'integrity-check.mjs', aliases: ['integrity'] },
   score: { script: 'score-cli.mjs', aliases: ['scorecard'] },
+  fleet: { script: 'fleet.mjs' },
+  brief: { script: 'brief-cli.mjs' },
 };
 
 function printHelp() {
@@ -64,6 +66,8 @@ Commands:
   defer add|resolve|list  Deferral registry (deferred wiring = tracked debt)
   integrity-check         Mechanical integrity gate (runs at phase done)
   score [--write]         L2 session scorecard (auto-written at phase done)
+  fleet list|watch|view|send  Cross-project session control terminal
+  brief stamp|check|open  Operator brief (plain-language HTML, gates implement)
 
 Prefer \`forgekit install\` to pick multiple skills + agents at once.
 

package/package.json

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

package/scripts/run-tests.mjs

@@ -7,6 +7,7 @@
  */
 
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
@@ -39,5 +40,11 @@ if (files.length === 0) {
 const result = spawnSync(process.execPath, ['--test', ...files], {
   cwd: cliRoot,
   stdio: 'inherit',
+  env: {
+    ...process.env,
+    // Keep saveSession's fleet-registry mirroring away from ~/.forgekit
+    // when tests exercise session saves with scratch projects.
+    FORGEKIT_FLEET_DIR: fs.mkdtempSync(path.join(os.tmpdir(), 'forgekit-test-fleet-')),
+  },
 });
 process.exit(result.status ?? 1);

package/src/brief-cli.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * Operator-brief CLI (core in brief.mjs).
+ *
+ * Usage:
+ *   forge brief stamp [--session <id>] [--no-open]   stamp freshness hash + open in browser
+ *   forge brief check [--session <id>]               exit 1 when missing/stale/unstamped
+ *   forge brief open  [--session <id>]               open in default browser
+ */
+
+import fs from 'node:fs';
+import { loadSession, readActive } from './lib.mjs';
+import { resolveChangeDir } from './integrity.mjs';
+import { BRIEF_FILE, briefPath, checkBrief, openInBrowser, stampBrief } from './brief.mjs';
+
+const [cmd, ...rest] = process.argv.slice(2);
+if (!cmd || !['stamp', 'check', 'open'].includes(cmd)) {
+  process.stderr.write(
+    'Usage: forge brief stamp [--session <id>] [--no-open] | check [--session <id>] | open [--session <id>]\n',
+  );
+  process.exit(1);
+}
+
+let sessionId = null;
+const si = rest.indexOf('--session');
+if (si >= 0 && rest[si + 1]) sessionId = rest[si + 1];
+if (!sessionId) sessionId = readActive()?.sessionId ?? null;
+if (!sessionId) {
+  process.stderr.write('No active session. Run forge new first.\n');
+  process.exit(1);
+}
+
+const { session } = loadSession(sessionId);
+const changeDir = resolveChangeDir({ session });
+
+if (cmd === 'check') {
+  const result = checkBrief({ session });
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  process.exit(result.ok ? 0 : 1);
+}
+
+if (!changeDir) {
+  process.stderr.write('Session has no tracked change — nothing to brief.\n');
+  process.exit(1);
+}
+
+if (cmd === 'stamp') {
+  const hash = stampBrief(changeDir);
+  process.stdout.write(`Stamped ${briefPath(changeDir)} (specs hash ${hash})\n`);
+  if (!rest.includes('--no-open')) {
+    openInBrowser(briefPath(changeDir));
+    process.stdout.write('Opened in default browser.\n');
+  }
+} else {
+  const file = briefPath(changeDir);
+  if (!fs.existsSync(file)) {
+    process.stderr.write(`No ${BRIEF_FILE} in ${changeDir}.\n`);
+    process.exit(1);
+  }
+  openInBrowser(file);
+  process.stdout.write(`Opened ${file}\n`);
+}

package/src/brief.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+/**
+ * Operator brief core — a plain-language, self-contained HTML explanation of
+ * what will be built, written by the agent at the end of the plan phase into
+ * `<changeDir>/brief.html`. CLI in brief-cli.mjs (`forge brief`).
+ *
+ * Freshness: `stampBrief` records a hash of proposal.md/design.md/tasks.md
+ * inside brief.html. When the specs change afterwards the brief goes stale and
+ * the hard gate in `forge phase implement` refuses until it is rewritten and
+ * re-stamped — same executed-evidence philosophy as the e2e gate.
+ */
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { resolveChangeDir } from './integrity.mjs';
+
+export const BRIEF_FILE = 'brief.html';
+const HASH_MARKER = /<!--\s*forge-brief-specs-hash:([a-f0-9]+)\s*-->/;
+const SPEC_FILES = ['proposal.md', 'design.md', 'tasks.md'];
+
+/** Hash of the spec sources a brief must reflect (missing files hash as absent). */
+export function specsHash(changeDir) {
+  const h = crypto.createHash('sha256');
+  for (const name of SPEC_FILES) {
+    const file = path.join(changeDir, name);
+    h.update(name);
+    h.update(fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '<absent>');
+  }
+  return h.digest('hex').slice(0, 16);
+}
+
+export function briefPath(changeDir) {
+  return path.join(changeDir, BRIEF_FILE);
+}
+
+export function readBriefHash(file) {
+  if (!fs.existsSync(file)) return null;
+  const match = fs.readFileSync(file, 'utf8').match(HASH_MARKER);
+  return match ? match[1] : null;
+}
+
+/** Write/replace the freshness marker in brief.html. Returns the stamped hash. */
+export function stampBrief(changeDir) {
+  const file = briefPath(changeDir);
+  if (!fs.existsSync(file)) {
+    throw new Error(`No ${BRIEF_FILE} in ${changeDir} — write the operator brief first.`);
+  }
+  const hash = specsHash(changeDir);
+  let html = fs.readFileSync(file, 'utf8');
+  const marker = `<!-- forge-brief-specs-hash:${hash} -->`;
+  html = HASH_MARKER.test(html) ? html.replace(HASH_MARKER, marker) : `${marker}\n${html}`;
+  fs.writeFileSync(file, html, 'utf8');
+  return hash;
+}
+
+/**
+ * Brief status for a session.
+ *
+ * @param {{ cwd?: string, session: Record<string, any> }} opts
+ * @returns {{ ok: boolean, reason: 'not-applicable'|'fresh'|'missing'|'unstamped'|'stale', path: string | null }}
+ */
+export function checkBrief(opts) {
+  const { session } = opts;
+  const changeDir = resolveChangeDir(opts);
+  // Brief only applies to tracked-change plans; direct/throwaway have no specs
+  // for an operator to review.
+  if (!changeDir || session.planType === 'direct' || session.planType === 'throwaway') {
+    return { ok: true, reason: 'not-applicable', path: null };
+  }
+  const file = briefPath(changeDir);
+  if (!fs.existsSync(file)) return { ok: false, reason: 'missing', path: file };
+  const stamped = readBriefHash(file);
+  if (!stamped) return { ok: false, reason: 'unstamped', path: file };
+  if (stamped !== specsHash(changeDir)) return { ok: false, reason: 'stale', path: file };
+  return { ok: true, reason: 'fresh', path: file };
+}
+
+/** Human-readable problem line for a failed check, null when ok. */
+export function briefProblem(result) {
+  switch (result.reason) {
+    case 'missing':
+      return `operator brief missing — write ${result.path} (plain-language HTML, see forge references/operator-brief.md), then run forge brief stamp`;
+    case 'unstamped':
+      return 'operator brief not stamped — run forge brief stamp (records specs hash + opens it for the operator)';
+    case 'stale':
+      return `operator brief is stale — specs changed after it was written; update ${result.path} and re-run forge brief stamp`;
+    default:
+      return null;
+  }
+}
+
+/** Open a file with the OS default handler (fire-and-forget). */
+export function openInBrowser(file) {
+  const target = path.resolve(file);
+  const [cmd, args] =
+    process.platform === 'win32'
+      ? ['cmd', ['/c', 'start', '', target]]
+      : process.platform === 'darwin'
+        ? ['open', [target]]
+        : ['xdg-open', [target]];
+  spawn(cmd, args, { detached: true, stdio: 'ignore' }).unref();
+}

package/src/brief.test.mjs

@@ -0,0 +1,186 @@
+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 {
+  briefPath,
+  checkBrief,
+  readBriefHash,
+  specsHash,
+  stampBrief,
+} from './brief.mjs';
+
+const SET_PHASE = path.join(path.dirname(fileURLToPath(import.meta.url)), 'set-phase.mjs');
+
+function tmp(prefix) {
+  return fs.mkdtempSync(path.join(tmpdir(), prefix));
+}
+
+/** Project with a specs-engine change dir containing proposal + tasks. */
+function makeChange(root, change) {
+  const changeDir = path.join(root, 'specs', 'changes', change);
+  fs.mkdirSync(changeDir, { recursive: true });
+  fs.writeFileSync(path.join(changeDir, 'proposal.md'), '# Why\nBecause.\n', 'utf8');
+  fs.writeFileSync(path.join(changeDir, 'tasks.md'), '# Tasks\n- [ ] 1.1 do it\n', 'utf8');
+  return changeDir;
+}
+
+function writeBrief(changeDir) {
+  fs.writeFileSync(
+    briefPath(changeDir),
+    '<html><head><title>Brief</title></head><body><h1>TL;DR</h1></body></html>\n',
+    'utf8',
+  );
+}
+
+function makeSession(overrides = {}) {
+  return {
+    id: 's1',
+    slug: 'fixture',
+    planType: 'specs',
+    openspecChange: 'my-change',
+    ...overrides,
+  };
+}
+
+test('specsHash changes when a spec file changes', () => {
+  const changeDir = makeChange(tmp('brief-'), 'my-change');
+  const before = specsHash(changeDir);
+  fs.appendFileSync(path.join(changeDir, 'proposal.md'), 'More.\n');
+  assert.notEqual(specsHash(changeDir), before);
+});
+
+test('stampBrief injects the marker once and restamp replaces it', () => {
+  const changeDir = makeChange(tmp('brief-'), 'my-change');
+  writeBrief(changeDir);
+  const hash = stampBrief(changeDir);
+  assert.equal(readBriefHash(briefPath(changeDir)), hash);
+
+  fs.appendFileSync(path.join(changeDir, 'tasks.md'), '- [ ] 1.2 more\n');
+  const hash2 = stampBrief(changeDir);
+  assert.notEqual(hash2, hash);
+  const html = fs.readFileSync(briefPath(changeDir), 'utf8');
+  assert.equal(html.match(/forge-brief-specs-hash/g).length, 1);
+});
+
+test('stampBrief throws when brief.html is missing', () => {
+  const changeDir = makeChange(tmp('brief-'), 'my-change');
+  assert.throws(() => stampBrief(changeDir), /write the operator brief first/);
+});
+
+test('checkBrief lifecycle: missing → unstamped → fresh → stale', () => {
+  const root = tmp('brief-');
+  const changeDir = makeChange(root, 'my-change');
+  const session = makeSession();
+
+  assert.equal(checkBrief({ cwd: root, session }).reason, 'missing');
+
+  writeBrief(changeDir);
+  assert.equal(checkBrief({ cwd: root, session }).reason, 'unstamped');
+
+  stampBrief(changeDir);
+  const fresh = checkBrief({ cwd: root, session });
+  assert.equal(fresh.reason, 'fresh');
+  assert.equal(fresh.ok, true);
+
+  fs.appendFileSync(path.join(changeDir, 'proposal.md'), 'Edited after stamp.\n');
+  const stale = checkBrief({ cwd: root, session });
+  assert.equal(stale.reason, 'stale');
+  assert.equal(stale.ok, false);
+});
+
+test('checkBrief not-applicable without a change or for direct/throwaway plans', () => {
+  const root = tmp('brief-');
+  assert.equal(
+    checkBrief({ cwd: root, session: makeSession({ openspecChange: null }) }).reason,
+    'not-applicable',
+  );
+  makeChange(root, 'my-change');
+  assert.equal(
+    checkBrief({ cwd: root, session: makeSession({ planType: 'direct' }) }).reason,
+    'not-applicable',
+  );
+});
+
+/** Full .forge fixture so set-phase.mjs can run as a child in `root`. */
+function makePhaseFixture(root, overrides = {}) {
+  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: 'plan',
+      planType: 'specs',
+      openspecChange: 'my-change',
+      forgeSkipped: false,
+      tasksTotal: 0,
+      tasksComplete: 0,
+      ...overrides,
+    })}\n`,
+    'utf8',
+  );
+  fs.writeFileSync(
+    path.join(root, '.forge', 'active.json'),
+    `${JSON.stringify({ sessionId: 's1' })}\n`,
+    'utf8',
+  );
+  return sessionDir;
+}
+
+function runSetPhase(cwd, args) {
+  try {
+    const stdout = execFileSync(process.execPath, [SET_PHASE, ...args], {
+      cwd,
+      env: { ...process.env, FORGEKIT_FLEET_DIR: path.join(tmp('brief-fleet-'), 's') },
+    });
+    return { status: 0, stdout: stdout.toString(), stderr: '' };
+  } catch (err) {
+    return { status: err.status, stdout: String(err.stdout), stderr: String(err.stderr) };
+  }
+}
+
+test('phase implement hard-refuses without a fresh brief, passes with one', () => {
+  const root = tmp('brief-gate-');
+  const changeDir = makeChange(root, 'my-change');
+  makePhaseFixture(root);
+
+  const refused = runSetPhase(root, ['implement', '--tasks-total', '3']);
+  assert.notEqual(refused.status, 0);
+  assert.match(refused.stderr, /operator brief missing/);
+
+  writeBrief(changeDir);
+  stampBrief(changeDir);
+  const ok = runSetPhase(root, ['implement', '--tasks-total', '3']);
+  assert.equal(ok.status, 0);
+
+  fs.appendFileSync(path.join(changeDir, 'tasks.md'), '- [ ] 1.9 late edit\n');
+  const stale = runSetPhase(root, ['implement']);
+  assert.notEqual(stale.status, 0);
+  assert.match(stale.stderr, /stale/);
+});
+
+test('phase implement --allow-incomplete records briefSkipped', () => {
+  const root = tmp('brief-gate-');
+  makeChange(root, 'my-change');
+  const sessionDir = makePhaseFixture(root);
+
+  const ok = runSetPhase(root, ['implement', '--allow-incomplete', 'operator waived brief']);
+  assert.equal(ok.status, 0);
+  const session = JSON.parse(fs.readFileSync(path.join(sessionDir, 'session.json'), 'utf8'));
+  assert.equal(session.briefSkipped, 'operator waived brief');
+});
+
+test('phase implement unaffected for sessions without a tracked change', () => {
+  const root = tmp('brief-gate-');
+  makePhaseFixture(root, { planType: null, openspecChange: null });
+  const ok = runSetPhase(root, ['implement', '--tasks-total', '2']);
+  assert.equal(ok.status, 0);
+});

package/src/cleanup-sessions.mjs

@@ -18,6 +18,7 @@ import {
   SESSIONS_DIR,
   sessionAgeDays,
 } from './lib.mjs';
+import { unregisterSession } from './lib/fleet.mjs';
 
 const args = new Set(process.argv.slice(2));
 const dryRun = args.has('--dry-run');
@@ -59,6 +60,7 @@ for (const entry of fs.readdirSync(SESSIONS_DIR, { withFileTypes: true })) {
     if (!dryRun) {
       fs.rmSync(dir, { recursive: true, force: true });
       if (isActive) clearActive();
+      unregisterSession(process.cwd(), sessionId);
     }
     removed.push({ sessionId, reason: tooOld ? 'retention' : 'finished' });
   } else {

package/src/fleet.mjs

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+/**
+ * Fleet control terminal — see and command every forge session on this
+ * machine, across projects and engines.
+ *
+ * Usage:
+ *   forge fleet list [--json]
+ *   forge fleet watch [--interval <sec>]
+ *   forge fleet view <session> [--transcript [N]]
+ *   forge fleet send <session>|--all <message...>
+ *
+ * <session> matches by sessionId, slug, or project name; must be unique.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  PHASE_ORDER,
+  listFleet,
+  newestTranscript,
+  peekInbox,
+  queueMessage,
+  sessionDirFor,
+} from './lib/fleet.mjs';
+
+function usage() {
+  process.stderr.write(
+    `Usage:
+  forge fleet list [--json]
+  forge fleet watch [--interval <sec>]
+  forge fleet view <session> [--transcript [N]]
+  forge fleet send <session>|--all <message...>
+`,
+  );
+  process.exit(1);
+}
+
+function relTime(iso) {
+  const ms = Date.now() - new Date(iso).getTime();
+  if (Number.isNaN(ms)) return '?';
+  const min = Math.floor(ms / 60000);
+  if (min < 1) return 'now';
+  if (min < 60) return `${min}m`;
+  const h = Math.floor(min / 60);
+  if (h < 24) return `${h}h`;
+  return `${Math.floor(h / 24)}d`;
+}
+
+function phaseBar(phase) {
+  const idx = PHASE_ORDER.indexOf(phase);
+  if (phase === 'skipped') return 'skipped';
+  if (idx < 0) return phase;
+  const total = PHASE_ORDER.length - 1; // done = full bar
+  return `${'█'.repeat(idx)}${'░'.repeat(total - idx)} ${phase}`;
+}
+
+function tasksCell(entry) {
+  const total = Number(entry.tasksTotal) || 0;
+  if (total === 0) return '—';
+  const complete = Number(entry.tasksComplete) || 0;
+  const width = 8;
+  const filled = Math.round((complete / total) * width);
+  return `${'█'.repeat(filled)}${'░'.repeat(width - filled)} ${complete}/${total}`;
+}
+
+function pad(str, len) {
+  const s = String(str ?? '');
+  return s.length >= len ? s.slice(0, len) : s + ' '.repeat(len - s.length);
+}
+
+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', 13)} ${pad('PACE', 9)} ${pad('AGE', 4)} MSGS`;
+  const lines = [header, '-'.repeat(header.length)];
+  for (const e of entries) {
+    const pending = e.missing ? 0 : peekInbox(sessionDirFor(e)).length;
+    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), 13)} ${pad(e.pace ?? '—', 9)} ${pad(relTime(e.updatedAt), 4)} ${
+        pending > 0 ? `✉ ${pending}` : ''
+      }`,
+    );
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+/** Resolve a user-supplied needle to exactly one fleet entry. */
+function findEntry(needle) {
+  const entries = listFleet();
+  const matches = entries.filter(
+    (e) =>
+      e.sessionId === needle ||
+      e.sessionId.includes(needle) ||
+      e.slug === needle ||
+      e.projectName === needle,
+  );
+  if (matches.length === 1) return matches[0];
+  if (matches.length === 0) {
+    process.stderr.write(`No fleet session matches "${needle}". Try: forge fleet list\n`);
+  } else {
+    process.stderr.write(
+      `Ambiguous "${needle}" — matches:\n${matches
+        .map((m) => `  ${m.sessionId} (${m.projectName})`)
+        .join('\n')}\n`,
+    );
+  }
+  process.exit(1);
+}
+
+function cmdList(args) {
+  const entries = listFleet();
+  if (args.includes('--json')) {
+    process.stdout.write(`${JSON.stringify(entries, null, 2)}\n`);
+  } else {
+    process.stdout.write(renderTable(entries));
+  }
+}
+
+function cmdWatch(args) {
+  const i = args.indexOf('--interval');
+  const interval = Math.max(1, Number(i >= 0 ? args[i + 1] : 3) || 3) * 1000;
+  const render = () => {
+    process.stdout.write('\x1b[2J\x1b[H');
+    process.stdout.write(`forge fleet — ${new Date().toLocaleTimeString()} (Ctrl+C to exit)\n\n`);
+    process.stdout.write(renderTable(listFleet()));
+  };
+  render();
+  setInterval(render, interval);
+}
+
+/**
+ * ponytail: transcript view is best-effort — newest jsonl in the project's
+ * Claude dir, not a verified session link. Upgrade path: SessionStart hook
+ * records claudeSessionId in the registry entry.
+ */
+function tailTranscript(entry, count) {
+  const file = newestTranscript(entry.project);
+  if (!file) {
+    process.stdout.write('No Claude Code transcript found for this project.\n');
+    return;
+  }
+  process.stdout.write(`Transcript (newest in project): ${file}\n\n`);
+  const lines = fs.readFileSync(file, 'utf8').trim().split('\n');
+  const turns = [];
+  for (const line of lines) {
+    let rec;
+    try {
+      rec = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (rec.type !== 'user' && rec.type !== 'assistant') continue;
+    const content = rec.message?.content;
+    let text = '';
+    if (typeof content === 'string') text = content;
+    else if (Array.isArray(content)) {
+      text = content
+        .map((c) => (c.type === 'text' ? c.text : c.type === 'tool_use' ? `[tool: ${c.name}]` : ''))
+        .filter(Boolean)
+        .join(' ');
+    }
+    text = text.replace(/\s+/g, ' ').trim();
+    if (text) turns.push(`${rec.type === 'user' ? '>' : '<'} ${text.slice(0, 300)}`);
+  }
+  process.stdout.write(`${turns.slice(-count).join('\n\n')}\n`);
+}
+
+function cmdView(args) {
+  if (!args[0]) usage();
+  const entry = findEntry(args[0]);
+  const ti = args.indexOf('--transcript');
+  const sessionDir = sessionDirFor(entry);
+
+  process.stdout.write(`${entry.projectName} · ${entry.slug}\n`);
+  process.stdout.write(`  Session:  ${entry.sessionId}\n`);
+  process.stdout.write(`  Project:  ${entry.project}\n`);
+  process.stdout.write(`  Engine:   ${entry.engine ?? 'unknown'}\n`);
+  process.stdout.write(`  Phase:    ${phaseBar(entry.phase)}\n`);
+  process.stdout.write(`  Tasks:    ${tasksCell(entry)}\n`);
+  process.stdout.write(`  Pace:     ${entry.pace ?? '—'}\n`);
+  process.stdout.write(`  Change:   ${entry.openspecChange ?? '—'} (${entry.planType ?? 'pending'})\n`);
+  const rel = relTime(entry.updatedAt);
+  process.stdout.write(`  Updated:  ${entry.updatedAt}${rel === 'now' ? '' : ` (${rel} ago)`}\n`);
+
+  const pending = entry.missing ? [] : peekInbox(sessionDir);
+  if (pending.length > 0) {
+    process.stdout.write(`\n  Pending fleet messages (${pending.length}):\n`);
+    for (const m of pending) process.stdout.write(`    • ${m.text.split('\n')[0]}\n`);
+  }
+  const evidence = path.join(sessionDir, 'verify-evidence.md');
+  if (fs.existsSync(evidence)) process.stdout.write(`  Evidence: ${evidence}\n`);
+
+  if (ti >= 0) {
+    const count = Number(args[ti + 1]) || 20;
+    process.stdout.write('\n');
+    tailTranscript(entry, count);
+  }
+}
+
+function cmdSend(args) {
+  const all = args[0] === '--all';
+  const message = (all ? args.slice(1) : args.slice(1)).join(' ').trim();
+  if (!args[0] || !message) usage();
+
+  const targets = all ? listFleet().filter((e) => !e.missing) : [findEntry(args[0])];
+  for (const entry of targets) {
+    const file = queueMessage(sessionDirFor(entry), message);
+    process.stdout.write(
+      `Queued for ${entry.projectName}/${entry.slug} → delivered on its next turn (${file})\n`,
+    );
+  }
+  if (targets.length === 0) process.stdout.write('No reachable fleet sessions.\n');
+}
+
+const [cmd, ...rest] = process.argv.slice(2);
+switch (cmd) {
+  case 'list':
+    cmdList(rest);
+    break;
+  case 'watch':
+    cmdWatch(rest);
+    break;
+  case 'view':
+    cmdView(rest);
+    break;
+  case 'send':
+    cmdSend(rest);
+    break;
+  default:
+    usage();
+}

package/src/fleet.test.mjs

@@ -0,0 +1,137 @@
+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 {
+  drainInbox,
+  entryFile,
+  listFleet,
+  peekInbox,
+  queueMessage,
+  registerSession,
+  sanitizePath,
+  unregisterSession,
+} from './lib/fleet.mjs';
+import { saveSession } from './lib.mjs';
+
+const FLEET_SCRIPT = path.join(path.dirname(fileURLToPath(import.meta.url)), 'fleet.mjs');
+
+function tmp(prefix) {
+  return fs.mkdtempSync(path.join(tmpdir(), prefix));
+}
+
+function makeSession(id, extra = {}) {
+  const now = new Date().toISOString();
+  return {
+    id,
+    slug: 'fixture',
+    createdAt: now,
+    updatedAt: now,
+    phase: 'implement',
+    planType: 'specs',
+    openspecChange: 'my-change',
+    tasksTotal: 10,
+    tasksComplete: 4,
+    pace: 'auto',
+    resolvedPace: 'standard',
+    ...extra,
+  };
+}
+
+/** Scratch project with a session dir so listFleet keeps the entry. */
+function makeProject(root, sessionId) {
+  const sessionDir = path.join(root, '.forge', 'sessions', sessionId);
+  fs.mkdirSync(sessionDir, { recursive: true });
+  return sessionDir;
+}
+
+test('register / list / unregister roundtrip', () => {
+  process.env.FORGEKIT_FLEET_DIR = path.join(tmp('fleet-reg-'), 'sessions');
+  const project = tmp('fleet-proj-');
+  makeProject(project, 's1');
+
+  registerSession(project, makeSession('s1'));
+  const entries = listFleet();
+  assert.equal(entries.length, 1);
+  assert.equal(entries[0].sessionId, 's1');
+  assert.equal(entries[0].project, project);
+  assert.equal(entries[0].projectName, path.basename(project));
+  assert.equal(entries[0].phase, 'implement');
+  assert.equal(entries[0].tasksTotal, 10);
+  assert.equal(entries[0].tasksComplete, 4);
+  assert.equal(entries[0].pace, 'standard');
+  assert.equal(entries[0].missing, false);
+
+  unregisterSession(project, 's1');
+  assert.equal(listFleet().length, 0);
+});
+
+test('listFleet self-heals entries whose session dir is gone', () => {
+  process.env.FORGEKIT_FLEET_DIR = path.join(tmp('fleet-heal-'), 'sessions');
+  const project = tmp('fleet-proj-');
+  registerSession(project, makeSession('gone')); // no session dir created
+  assert.equal(listFleet().length, 0);
+  assert.equal(fs.existsSync(entryFile(project, 'gone')), false);
+});
+
+test('saveSession mirrors into the fleet registry', () => {
+  process.env.FORGEKIT_FLEET_DIR = path.join(tmp('fleet-mirror-'), 'sessions');
+  const project = tmp('fleet-proj-');
+  const sessionDir = makeProject(project, 's2');
+
+  saveSession(sessionDir, makeSession('s2', { phase: 'review' }));
+  const entries = listFleet();
+  assert.equal(entries.length, 1);
+  assert.equal(entries[0].sessionId, 's2');
+  assert.equal(entries[0].phase, 'review');
+});
+
+test('queue → peek → drain delivers each message exactly once', () => {
+  const sessionDir = makeProject(tmp('fleet-proj-'), 's3');
+  queueMessage(sessionDir, 'pause and report status');
+  assert.equal(peekInbox(sessionDir).length, 1);
+
+  const drained = drainInbox(sessionDir);
+  assert.equal(drained.length, 1);
+  assert.equal(drained[0].text, 'pause and report status');
+  assert.equal(drainInbox(sessionDir).length, 0);
+  assert.equal(peekInbox(sessionDir).length, 0);
+});
+
+test('fleet CLI: send queues, list --json reports pending-capable entries', () => {
+  const fleetDir = path.join(tmp('fleet-cli-'), 'sessions');
+  const project = tmp('fleet-proj-');
+  const sessionDir = makeProject(project, 's4');
+  const env = { ...process.env, FORGEKIT_FLEET_DIR: fleetDir };
+
+  registerSessionIn(fleetDir, project, makeSession('s4'));
+
+  const listOut = execFileSync(process.execPath, [FLEET_SCRIPT, 'list', '--json'], { env });
+  const parsed = JSON.parse(listOut.toString());
+  assert.equal(parsed.length, 1);
+  assert.equal(parsed[0].sessionId, 's4');
+
+  execFileSync(process.execPath, [FLEET_SCRIPT, 'send', 's4', 'ship', 'it'], { env });
+  const pending = peekInbox(sessionDir);
+  assert.equal(pending.length, 1);
+  assert.equal(pending[0].text, 'ship it');
+});
+
+/** register via a temp override without clobbering this process's env-based dir */
+function registerSessionIn(fleetDir, project, session) {
+  const prev = process.env.FORGEKIT_FLEET_DIR;
+  process.env.FORGEKIT_FLEET_DIR = fleetDir;
+  try {
+    registerSession(project, session);
+  } finally {
+    if (prev === undefined) delete process.env.FORGEKIT_FLEET_DIR;
+    else process.env.FORGEKIT_FLEET_DIR = prev;
+  }
+}
+
+test('sanitizePath matches Claude Code project-dir naming', () => {
+  assert.equal(sanitizePath('S:\\Projects\\forgekit'), 'S--Projects-forgekit');
+});

package/src/lib/fleet.mjs

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+/**
+ * Machine-level fleet registry: one JSON file per forge session under
+ * `~/.forgekit/fleet/sessions/`, mirrored on every `saveSession` so any
+ * project's sessions are visible from a single control terminal
+ * (`forge fleet list|watch|view|send`).
+ *
+ * Standalone on purpose — no import of ../lib.mjs (which binds cwd at import
+ * time); everything here takes explicit paths. `FORGEKIT_FLEET_DIR` overrides
+ * the registry location (tests point it at a tmp dir).
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const PHASE_ORDER = [
+  'triage',
+  'brainstorm',
+  'plan',
+  'implement',
+  'verify',
+  'review',
+  'finish',
+  'done',
+];
+
+export function fleetDir() {
+  return (
+    process.env.FORGEKIT_FLEET_DIR ||
+    path.join(os.homedir(), '.forgekit', 'fleet', 'sessions')
+  );
+}
+
+/** Same sanitisation Claude Code uses for ~/.claude/projects dir names. */
+export function sanitizePath(p) {
+  return String(p).replace(/[^a-zA-Z0-9]/g, '-');
+}
+
+export function entryFile(projectRoot, sessionId) {
+  return path.join(fleetDir(), `${sanitizePath(projectRoot)}--${sessionId}.json`);
+}
+
+/**
+ * Best-effort engine detection from env vars set by agent harnesses.
+ * ponytail: claude + cursor only; other engines show as null until they
+ * grow a detectable env marker.
+ */
+export function detectEngine(env = process.env) {
+  if (env.CLAUDECODE) return 'claude';
+  if (env.CURSOR_TRACE_ID || env.CURSOR_AGENT) return 'cursor';
+  return null;
+}
+
+/**
+ * Mirror a session into the registry. Never throws — a broken registry must
+ * not break session saves.
+ *
+ * @param {string} projectRoot absolute project path
+ * @param {Record<string, any>} session forge session.json contents
+ */
+export function registerSession(projectRoot, session) {
+  try {
+    const file = entryFile(projectRoot, session.id);
+    let prev = {};
+    try {
+      prev = JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch {
+      /* first registration */
+    }
+    const entry = {
+      project: projectRoot,
+      projectName: path.basename(projectRoot),
+      sessionId: session.id,
+      slug: session.slug,
+      phase: session.phase,
+      planType: session.planType ?? null,
+      openspecChange: session.openspecChange ?? null,
+      tasksTotal: session.tasksTotal ?? 0,
+      tasksComplete: session.tasksComplete ?? 0,
+      pace: session.resolvedPace ?? session.pace ?? null,
+      engine: detectEngine() ?? prev.engine ?? null,
+      createdAt: session.createdAt,
+      updatedAt: session.updatedAt,
+    };
+    fs.mkdirSync(fleetDir(), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(entry, null, 2)}\n`, 'utf8');
+  } catch {
+    /* registry is advisory */
+  }
+}
+
+export function unregisterSession(projectRoot, sessionId) {
+  try {
+    fs.rmSync(entryFile(projectRoot, sessionId), { force: true });
+  } catch {
+    /* advisory */
+  }
+}
+
+/**
+ * All registry entries, newest first. Self-heals: entries whose session dir
+ * vanished (cleanup ran without unregister, project deleted the .forge dir)
+ * are removed; entries whose whole project path is unreachable (unplugged
+ * drive) are kept and marked `missing`.
+ *
+ * @returns {Array<Record<string, any>>}
+ */
+export function listFleet() {
+  const dir = fleetDir();
+  if (!fs.existsSync(dir)) return [];
+  const entries = [];
+  for (const name of fs.readdirSync(dir)) {
+    if (!name.endsWith('.json')) continue;
+    const file = path.join(dir, name);
+    let entry;
+    try {
+      entry = JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch {
+      continue;
+    }
+    const sessionDir = path.join(entry.project, '.forge', 'sessions', entry.sessionId);
+    if (fs.existsSync(sessionDir)) {
+      entry.missing = false;
+    } else if (fs.existsSync(entry.project)) {
+      fs.rmSync(file, { force: true });
+      continue;
+    } else {
+      entry.missing = true;
+    }
+    entries.push(entry);
+  }
+  entries.sort((a, b) => String(b.updatedAt).localeCompare(String(a.updatedAt)));
+  return entries;
+}
+
+export function sessionDirFor(entry) {
+  return path.join(entry.project, '.forge', 'sessions', entry.sessionId);
+}
+
+/**
+ * Queue a fleet message for a session; delivered into the agent's context by
+ * `forge reminder` (hook) on its next turn.
+ */
+export function queueMessage(sessionDir, message, from = 'fleet') {
+  const inbox = path.join(sessionDir, 'inbox');
+  fs.mkdirSync(inbox, { recursive: true });
+  const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
+  const file = path.join(inbox, `${stamp}-${from}.md`);
+  fs.writeFileSync(file, `${message}\n`, 'utf8');
+  return file;
+}
+
+/**
+ * Read-and-consume pending fleet messages (moved to inbox/delivered/ so each
+ * is injected exactly once).
+ *
+ * @returns {Array<{ file: string, text: string }>}
+ */
+export function drainInbox(sessionDir) {
+  const inbox = path.join(sessionDir, 'inbox');
+  if (!fs.existsSync(inbox)) return [];
+  const delivered = path.join(inbox, 'delivered');
+  const out = [];
+  for (const name of fs.readdirSync(inbox).sort()) {
+    const file = path.join(inbox, name);
+    if (!fs.statSync(file).isFile()) continue;
+    const text = fs.readFileSync(file, 'utf8').trim();
+    fs.mkdirSync(delivered, { recursive: true });
+    fs.renameSync(file, path.join(delivered, name));
+    out.push({ file: name, text });
+  }
+  return out;
+}
+
+/** Pending (undelivered) fleet messages, without consuming them. */
+export function peekInbox(sessionDir) {
+  const inbox = path.join(sessionDir, 'inbox');
+  if (!fs.existsSync(inbox)) return [];
+  return fs
+    .readdirSync(inbox)
+    .sort()
+    .filter((name) => fs.statSync(path.join(inbox, name)).isFile())
+    .map((name) => ({
+      file: name,
+      text: fs.readFileSync(path.join(inbox, name), 'utf8').trim(),
+    }));
+}
+
+/**
+ * Claude Code transcript dir for a project (`~/.claude/projects/<sanitized>`),
+ * or null when absent.
+ */
+export function claudeTranscriptDir(projectRoot, home = os.homedir()) {
+  const dir = path.join(home, '.claude', 'projects', sanitizePath(projectRoot));
+  return fs.existsSync(dir) ? dir : null;
+}
+
+/** Newest transcript jsonl in a project's Claude dir, or null. */
+export function newestTranscript(projectRoot, home = os.homedir()) {
+  const dir = claudeTranscriptDir(projectRoot, home);
+  if (!dir) return null;
+  const files = fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith('.jsonl'))
+    .map((f) => {
+      const full = path.join(dir, f);
+      return { full, mtime: fs.statSync(full).mtimeMs };
+    })
+    .sort((a, b) => b.mtime - a.mtime);
+  return files[0]?.full ?? null;
+}

package/src/lib.mjs

@@ -6,6 +6,7 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
+import { registerSession } from './lib/fleet.mjs';
 
 export const REPO_ROOT = process.cwd();
 export const FORGE_DIR = path.join(REPO_ROOT, '.forge');
@@ -130,6 +131,10 @@ export function saveSession(dir, session) {
   session.updatedAt = new Date().toISOString();
   writeJson(path.join(dir, 'session.json'), session);
   writeJson(path.join(dir, 'status.json'), defaultStatus(session));
+  // Mirror into ~/.forgekit/fleet so `forge fleet` sees every project's
+  // sessions. Project root derived from dir (<root>/.forge/sessions/<id>),
+  // not REPO_ROOT, so callers with explicit dirs mirror correctly too.
+  registerSession(path.resolve(dir, '..', '..', '..'), session);
 }
 
 export function sessionAgeDays(session) {

package/src/session-reminder.mjs

@@ -9,6 +9,7 @@
  */
 
 import { FORGE_DIR, loadSession, readActive } from './lib.mjs';
+import { drainInbox } from './lib/fleet.mjs';
 import { resolveEffectivePreferences } from './preferences.mjs';
 
 function getActiveSessionInfo() {
@@ -148,10 +149,20 @@ if (!info) {
   process.exit(0);
 }
 
-const message = prompt
+let message = prompt
   ? buildForgePromptMessage(info, prompt)
   : buildForgeMessage(info);
 
+// Deliver queued `forge fleet send` messages exactly once (drain moves them
+// to inbox/delivered/). This is the fleet command bus: control terminal →
+// inbox file → injected into the agent's next turn via this hook.
+const fleetMessages = drainInbox(info.dir);
+if (fleetMessages.length > 0) {
+  message += `\n\nFleet messages from the control terminal — acknowledge and act on these first:\n${fleetMessages
+    .map((m) => `- ${m.text}`)
+    .join('\n')}`;
+}
+
 switch (format) {
   case 'cursor':
     emitCursor(message);

package/src/set-phase.mjs

@@ -15,6 +15,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { loadSession, readActive, saveSession } from './lib.mjs';
+import { briefProblem, checkBrief } from './brief.mjs';
 import { runIntegrityChecks } from './integrity.mjs';
 import { writeSessionScorecard } from './score.mjs';
 
@@ -116,6 +117,33 @@ function maybeEscalatePaceForTaskCount() {
 
 maybeEscalatePaceForTaskCount();
 
+/**
+ * Hard gate: implementation may not start until the operator brief exists and
+ * matches the current specs — the plan-approval checkpoint is only as strong
+ * as the human's comprehension of it. `--allow-incomplete "<reason>"` records
+ * an honest skip.
+ */
+function enforceBriefGate() {
+  if (phase !== 'implement') return;
+  const result = checkBrief({ session });
+  if (result.ok) {
+    delete session.briefSkipped;
+    return;
+  }
+  if (allowIncomplete) {
+    session.briefSkipped = allowIncomplete;
+    return;
+  }
+  process.stderr.write(
+    `Cannot enter phase "implement":\n  - ${briefProblem(result)}\n` +
+      'Write the brief (see forge references/operator-brief.md), forge brief stamp, ' +
+      'or pass --allow-incomplete "<reason>".\n',
+  );
+  process.exit(1);
+}
+
+enforceBriefGate();
+
 /**
  * Refuse finish/done without verify evidence, full task completion, and a
  * clean integrity check (spine matrix, deferrals, product-loop evidence) —

package/vendor/skills/forge/phases/plan-openspec.md

@@ -31,14 +31,27 @@ Thin wrapper around the project **`openspec-propose`** skill (or `/opsx:propose`
    valid spine and, when the spine has rows, a green current e2e run —
    keyword sniffing does not decide.)
 
-5. Update session:
+5. **Operator brief (mandatory)** — see [../references/operator-brief.md](../references/operator-brief.md):
+   write `openspec/changes/<change-name>/brief.html` — a plain-language,
+   self-contained HTML explanation of what will be built (mermaid diagrams
+   where helpful), then:
+
+   ```bash
+   forge brief stamp    # records specs hash + opens it in the operator's browser
+   ```
+
+   `forge phase implement` hard-refuses while the brief is missing or stale
+   (specs edited after stamping → rewrite affected sections and re-stamp).
+
+6. Update session:
    ```bash
    forge phase plan --plan-type openspec --openspec <change-name>
    forge phase implement --tasks-total <N>
    ```
    Count tasks from `tasks.md` checkboxes.
 
-6. Get user approval to proceed to implement (unless they already said "go").
+7. Get user approval to proceed to implement (unless they already said "go").
+   The brief (opened by `forge brief stamp`) is what the operator reviews.
 
 ## Session tracking
 

package/vendor/skills/forge/phases/plan-specs.md

@@ -79,7 +79,19 @@ OpenSpec propose flow without the vendor CLI. Change lives under
    valid spine and, when the spine has rows, a green current e2e run —
    keyword sniffing does not decide.)
 
-5. Update session:
+5. **Operator brief (mandatory)** — see [../references/operator-brief.md](../references/operator-brief.md):
+   write `<specsDir>/changes/<change-name>/brief.html` — a plain-language,
+   self-contained HTML explanation of what will be built (mermaid diagrams
+   where helpful), then:
+
+   ```bash
+   forge brief stamp    # records specs hash + opens it in the operator's browser
+   ```
+
+   `forge phase implement` hard-refuses while the brief is missing or stale
+   (specs edited after stamping → rewrite affected sections and re-stamp).
+
+6. Update session:
 
    ```bash
    forge phase plan --plan-type specs --openspec <change-name>
@@ -89,7 +101,8 @@ OpenSpec propose flow without the vendor CLI. Change lives under
    Count tasks from `tasks.md` checkboxes. (`--openspec` carries the change
    name for both engines.)
 
-6. Get user approval on the artefacts before implementing (unless they already said "go").
+7. Get user approval on the artefacts before implementing (unless they already said "go").
+   The brief (opened by `forge brief stamp`) is what the operator reviews.
 
 ## Compatibility
 

package/vendor/skills/forge/references/operator-brief.md

@@ -0,0 +1,74 @@
+# Operator brief — `brief.html`
+
+Every tracked change (openspec or specs engine) ends its plan phase with an
+**operator brief**: one self-contained HTML file at
+`<changeDir>/brief.html` that a human can read in two minutes and understand
+*what will be built* — without reading proposal.md, design.md, or tasks.md.
+
+The plan-approval checkpoint is only as strong as the operator's comprehension.
+The specs are written for agents; the brief is the translation for the human
+who approves them. `forge phase implement` **refuses** while the brief is
+missing, unstamped, or stale.
+
+## Who writes it
+
+You (the agent), at the end of the plan phase — after the specs are final,
+before `forge phase implement`. The CLI never generates prose; it only stamps
+freshness and opens the file.
+
+## Workflow
+
+```bash
+# 1. specs are final (proposal.md / design.md / tasks.md)
+# 2. write <changeDir>/brief.html   (structure below)
+forge brief stamp        # records specs hash + opens it in the operator's browser
+forge phase implement --tasks-total <N>   # hard-gated on a fresh stamped brief
+```
+
+If any spec file changes later, the brief goes **stale** — update the affected
+sections and `forge brief stamp` again. `forge brief check` reports status.
+Genuine edge case (operator explicitly waives it):
+`forge phase implement --allow-incomplete "<reason>"`.
+
+## Writing rules
+
+Audience: a smart human who has NOT read the specs and doesn't want to.
+Plain language. No spec-speak, no requirement IDs, no file paths in headings.
+If a sentence would not make sense to a project stakeholder outside this
+session, rewrite it.
+
+Structure (sections, in order — skip a section only when truly empty):
+
+1. **TL;DR** — 2-3 sentences: what will exist after this change that doesn't
+   today, and why it's worth doing.
+2. **What you'll get** — the observable outcomes, bulleted. Behavior, not
+   implementation ("you can send a message to any session from one terminal",
+   not "a registry module under lib/").
+3. **How it works** — the shape of the solution in one short narrative plus a
+   **mermaid diagram** where a picture beats prose (flow, sequence, or state —
+   whichever fits; skip the diagram for trivial changes rather than forcing one).
+4. **What changes for you** — new commands/screens/steps the operator will
+   use; anything that behaves differently than before.
+5. **Risks and open questions** — honest, short. What could go wrong, what was
+   deliberately deferred, what the operator should keep an eye on.
+6. **Out of scope** — what this change deliberately does NOT do.
+7. **Work overview** — task groups from tasks.md compressed to one line each,
+   with rough size (n tasks). Not the full task list.
+
+## File rules
+
+- One file, self-contained: inline CSS, no build step, no local assets.
+- Mermaid via CDN is fine (`<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js">`
+  + `mermaid.initialize({ startOnLoad: true })`; diagrams in `<pre class="mermaid">` blocks).
+  Trade-off accepted: diagrams need internet to render; the text must stand on
+  its own without them.
+- Readable defaults: max-width ~48rem/prose, system font stack, dark-on-light.
+  Keep styling minimal — this is a memo, not a product page.
+- Do not remove the `<!-- forge-brief-specs-hash:… -->` comment `forge brief
+  stamp` inserts; re-stamping updates it.
+
+## Archive
+
+`brief.html` lives in the change dir, so it archives with the change
+(`changes/archive/…`) and remains the human-readable record of what was
+approved — useful input for archive→ADR.