@izkac/forgekit 0.2.0 → 0.3.1

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) —