@izkac/forgekit 0.1.0

package/src/score.test.mjs

@@ -0,0 +1,253 @@
+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 {
+  formatScorecardMarkdown,
+  gradeForScore,
+  scoreSession,
+  writeSessionScorecard,
+} from './score.mjs';
+
+const PHASE_SCRIPT = path.join(path.dirname(fileURLToPath(import.meta.url)), 'set-phase.mjs');
+const SCORE_SCRIPT = path.join(path.dirname(fileURLToPath(import.meta.url)), 'score-cli.mjs');
+
+function tmp(prefix) {
+  return fs.mkdtempSync(path.join(tmpdir(), prefix));
+}
+
+function makeSession(root, overrides = {}) {
+  const sessionDir = path.join(root, '.forge', 'sessions', 'sess-score');
+  fs.mkdirSync(sessionDir, { recursive: true });
+  const now = new Date().toISOString();
+  const session = {
+    id: 'sess-score',
+    slug: 'fixture',
+    createdAt: now,
+    updatedAt: now,
+    phase: 'verify',
+    planType: null,
+    openspecChange: null,
+    tasksTotal: 2,
+    tasksComplete: 2,
+    pace: 'auto',
+    resolvedPace: 'standard',
+    pacePinned: false,
+    ...overrides,
+  };
+  fs.writeFileSync(path.join(sessionDir, 'session.json'), `${JSON.stringify(session, null, 2)}\n`, 'utf8');
+  fs.writeFileSync(
+    path.join(root, '.forge', 'active.json'),
+    `${JSON.stringify({ sessionId: 'sess-score' }, null, 2)}\n`,
+    'utf8',
+  );
+  return { sessionDir, session };
+}
+
+function validSpine(rows) {
+  return {
+    change: null,
+    notApplicable: null,
+    rows,
+  };
+}
+
+function validRow() {
+  return {
+    capability: 'REQ-GOV-01 matching',
+    library: 'etl_core/matcher.py',
+    runtimeOwner: 'worker job analyze_study',
+    writes: 'study_proposals',
+    reads: 'N/A',
+    uiConsumer: 'Proposals',
+    evidence: 'tasks/12/test-evidence.md',
+  };
+}
+
+test('gradeForScore bands', () => {
+  assert.equal(gradeForScore(95), 'A');
+  assert.equal(gradeForScore(80), 'B');
+  assert.equal(gradeForScore(60), 'C');
+  assert.equal(gradeForScore(40), 'D');
+  assert.equal(gradeForScore(10), 'F');
+});
+
+test('scoreSession: strong sync-only session scores high', () => {
+  const root = tmp('forge-score-strong-');
+  try {
+    const { sessionDir, session } = makeSession(root, { slug: 'add-health' });
+    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-health');
+    fs.mkdirSync(taskDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(taskDir, 'test-evidence.md'),
+      '# Test evidence\n\n- **Exit code:** 0\n- **Summary:** assert response.ok === true\n',
+      'utf8',
+    );
+
+    const card = scoreSession({ cwd: root, sessionDir, session });
+    assert.ok(card.score >= 80, `expected >=80, got ${card.score}`);
+    assert.ok(['A', 'B'].includes(card.grade));
+    assert.equal(card.integrityOk, true);
+    assert.match(formatScorecardMarkdown(card), /Grade: [AB]/);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('scoreSession: missing spine scores poorly', () => {
+  const root = tmp('forge-score-weak-');
+  try {
+    const { sessionDir, session } = makeSession(root);
+    fs.writeFileSync(path.join(sessionDir, 'verify-evidence.md'), '# ok\n', 'utf8');
+    const card = scoreSession({ cwd: root, sessionDir, session });
+    assert.ok(card.score < 60, `expected weak score, got ${card.score}`);
+    assert.equal(card.integrityOk, false);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('scoreSession: incompleteReason caps score at 59', () => {
+  const root = tmp('forge-score-cap-');
+  try {
+    const { sessionDir, session } = makeSession(root, {
+      incompleteReason: 'E2E blocked',
+      slug: 'add-health',
+    });
+    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'), '# ok\n', 'utf8');
+    const card = scoreSession({ cwd: root, sessionDir, session });
+    assert.ok(card.score <= 59);
+    assert.ok(card.caps.some((c) => /incompleteReason/.test(c)));
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('scoreSession: product-loop with baseline-diff scores higher than bare section', () => {
+  const root = tmp('forge-score-loop-');
+  try {
+    const { sessionDir, session } = makeSession(root, { slug: 'wire-worker-jobs' });
+    fs.writeFileSync(
+      path.join(sessionDir, 'spine.json'),
+      `${JSON.stringify(validSpine([validRow()]), null, 2)}\n`,
+      'utf8',
+    );
+    fs.writeFileSync(
+      path.join(sessionDir, 'verify-evidence.md'),
+      '# Verify\n\n## Product loop\n\nJust a heading\n',
+      'utf8',
+    );
+    const weak = scoreSession({ cwd: root, sessionDir, session });
+
+    fs.writeFileSync(
+      path.join(sessionDir, 'verify-evidence.md'),
+      `# Verify
+
+## Product loop
+
+Fixture: OP1086
+
+1. ingest
+2. analyze
+3. ratify
+4. run @R — output differs from baseline
+`,
+      'utf8',
+    );
+    const strong = scoreSession({ cwd: root, sessionDir, session });
+    assert.ok(strong.score > weak.score, `${strong.score} should beat ${weak.score}`);
+    const loop = strong.checks.find((c) => c.id === 'product_loop');
+    assert.ok(loop.points >= 15);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('writeSessionScorecard writes json and md', () => {
+  const root = tmp('forge-score-write-');
+  try {
+    const { sessionDir, session } = makeSession(root, { slug: 'docs-only' });
+    fs.writeFileSync(
+      path.join(sessionDir, 'spine.json'),
+      `${JSON.stringify({ rows: [], notApplicable: 'docs-only' }, null, 2)}\n`,
+      'utf8',
+    );
+    fs.writeFileSync(path.join(sessionDir, 'verify-evidence.md'), '# ok\n', 'utf8');
+    const { jsonPath, mdPath, card } = writeSessionScorecard({ cwd: root, sessionDir, session });
+    assert.equal(fs.existsSync(jsonPath), true);
+    assert.equal(fs.existsSync(mdPath), true);
+    assert.equal(JSON.parse(fs.readFileSync(jsonPath, 'utf8')).grade, card.grade);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('forge phase done writes scorecard and stamps session.scoreGrade', () => {
+  const root = tmp('forge-score-phase-');
+  try {
+    const { sessionDir } = makeSession(root, {
+      slug: 'add-health',
+      phase: 'verify',
+      tasksTotal: 1,
+      tasksComplete: 1,
+    });
+    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'), '# ok\n', 'utf8');
+
+    execFileSync(process.execPath, [PHASE_SCRIPT, 'done'], {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    assert.equal(fs.existsSync(path.join(sessionDir, 'scorecard.md')), true);
+    assert.equal(fs.existsSync(path.join(sessionDir, 'scorecard.json')), true);
+    const session = JSON.parse(fs.readFileSync(path.join(sessionDir, 'session.json'), 'utf8'));
+    assert.equal(session.phase, 'done');
+    assert.ok(typeof session.score === 'number');
+    assert.ok(['A', 'B', 'C', 'D', 'F'].includes(session.scoreGrade));
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('forge score CLI prints JSON', () => {
+  const root = tmp('forge-score-cli-');
+  try {
+    const { sessionDir } = makeSession(root, { slug: 'add-health' });
+    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'), '# ok\n', 'utf8');
+    const out = execFileSync(process.execPath, [SCORE_SCRIPT], {
+      cwd: root,
+      encoding: 'utf8',
+    });
+    const card = JSON.parse(out);
+    assert.ok(card.grade);
+    assert.ok(Array.isArray(card.humanPrompts));
+    assert.equal(card.humanPrompts.length, 4);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});

package/src/session-reminder.mjs

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+/**
+ * Build Forge session reminders for agent hooks.
+ *
+ * Usage:
+ *   forge reminder --format cursor
+ *   forge reminder --format claude-session-start
+ *   forge reminder --format plain
+ */
+
+import { FORGE_DIR, loadSession, readActive } from './lib.mjs';
+import { resolveEffectivePreferences } from './preferences.mjs';
+
+function getActiveSessionInfo() {
+  const active = readActive();
+  if (!active?.sessionId) return null;
+  try {
+    const { dir, session } = loadSession(active.sessionId);
+    return { active, dir, session };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {Record<string, unknown>} session
+ */
+export function formatPaceLine(session) {
+  try {
+    const eff = resolveEffectivePreferences({
+      forgeDir: FORGE_DIR,
+      session,
+      signalText:
+        (typeof session.paceSignal === 'string' && session.paceSignal) ||
+        (typeof session.slug === 'string' && session.slug) ||
+        '',
+    });
+    const requested = eff.requestedPace;
+    const resolved = eff.resolvedPace;
+    if (requested === 'auto') {
+      return `Pace: auto → ${resolved} (${eff.paceReason})`;
+    }
+    return `Pace: ${resolved}`;
+  } catch {
+    const requested = session.pace ?? 'auto';
+    const resolved = session.resolvedPace;
+    if (resolved) return `Pace: ${requested} → ${resolved}`;
+    return `Pace: ${requested}`;
+  }
+}
+
+export const OPENSPEC_PLAN_REMINDER =
+  'Planning: Forge always uses OpenSpec. After brainstorm approval, run /opsx:propose (openspec-propose). Do not ask for a plan mode. See forge references/plan-routing.md.';
+
+/** @deprecated use OPENSPEC_PLAN_REMINDER */
+export const PLAN_MODE_PROMPT_REMINDER = OPENSPEC_PLAN_REMINDER;
+
+export function needsOpenSpecPlan(session) {
+  return (
+    !session.planType &&
+    (session.phase === 'brainstorm' || session.phase === 'plan')
+  );
+}
+
+/** @deprecated use needsOpenSpecPlan */
+export const needsPlanModePrompt = needsOpenSpecPlan;
+
+export const RUNTIME_INTEGRITY_REMINDER =
+  'Integrity: spine.json mandatory every change (rows or notApplicable); no stubs/false success; specs beat task wording; product-loop when spine has rows; defer wiring only via `forge defer` — `forge phase done` runs `forge integrity-check` (forge references/runtime-integrity.md).';
+
+export function buildForgeMessage(info) {
+  const { session } = info;
+  const lines = [];
+  lines.push(`[forge] Active Forge session: ${session.id}`);
+  lines.push(
+    `Phase: ${session.phase} | Plan: ${session.planType ?? 'pending'}${
+      session.openspecChange ? ` (${session.openspecChange})` : ''
+    }`,
+  );
+  lines.push(formatPaceLine(session));
+  if (session.tasksTotal > 0) {
+    lines.push(`Tasks: ${session.tasksComplete}/${session.tasksTotal}`);
+  }
+  if (needsOpenSpecPlan(session)) {
+    lines.push(OPENSPEC_PLAN_REMINDER);
+  }
+  lines.push(RUNTIME_INTEGRITY_REMINDER);
+  lines.push('Resume: invoke the forge skill for the current phase.');
+  lines.push('Honor pace: see forge references/pace.md (`forge prefs`).');
+  lines.push('Skip Forge for this task only: /forge:skip');
+  lines.push('Guide: Forge skill + forgekit docs/forge.md');
+  return lines.join('\n');
+}
+
+export function buildForgePromptMessage(info, prompt) {
+  const base = buildForgeMessage(info);
+  const trimmed = (prompt || '').trim();
+  if (/^\/forge:skip\b/i.test(trimmed)) {
+    return `${base}\n\nUser invoked /forge:skip — execute directly; do not start brainstorm/plan.`;
+  }
+  if (/^\/forge:status\b/i.test(trimmed)) {
+    return `${base}\n\nRun: forge status — then summarize for the user.`;
+  }
+  if (/^\/forge:plan\b/i.test(trimmed)) {
+    return `${base}\n\nPlan phase: ${OPENSPEC_PLAN_REMINDER}`;
+  }
+  if (/^\/forge:brainstorm\b/i.test(trimmed)) {
+    return `${base}\n\nBrainstorm terminal state: proceed to OpenSpec propose — do not implement until artefacts are approved.`;
+  }
+  return `${base}\n\nUser invoked Forge — follow forge skill from phase "${info.session.phase}".`;
+}
+
+function emitCursor(message) {
+  const payload = JSON.stringify({ agent_message: message });
+  process.stdout.write(`${payload}\n`);
+}
+
+function emitClaudeSessionStart(message) {
+  const payload = {
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart',
+      additionalContext: `<system-reminder>\n${message}\n</system-reminder>`,
+    },
+  };
+  process.stdout.write(`${JSON.stringify(payload)}\n`);
+}
+
+function emitPlain(message) {
+  process.stdout.write(`${message}\n`);
+}
+
+const args = process.argv.slice(2);
+let format = 'plain';
+let prompt = '';
+
+for (let i = 0; i < args.length; i += 1) {
+  if (args[i] === '--format' && args[i + 1]) {
+    format = args[i + 1];
+    i += 1;
+  } else if (args[i] === '--prompt' && args[i + 1]) {
+    prompt = args[i + 1];
+    i += 1;
+  }
+}
+
+const info = getActiveSessionInfo();
+if (!info) {
+  process.exit(0);
+}
+
+const message = prompt
+  ? buildForgePromptMessage(info, prompt)
+  : buildForgeMessage(info);
+
+switch (format) {
+  case 'cursor':
+    emitCursor(message);
+    break;
+  case 'claude-session-start':
+    emitClaudeSessionStart(message);
+    break;
+  case 'plain':
+    emitPlain(message);
+    break;
+  default:
+    process.stderr.write(`Unknown format: ${format}\n`);
+    process.exit(1);
+}

package/src/session-status.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * Print the active Forge session or a specific session by id.
+ *
+ * Usage:
+ *   forge status
+ *   forge status [--session <id>]
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  FORGE_DIR,
+  loadSession,
+  readActive,
+  REPO_ROOT,
+} from './lib.mjs';
+import { resolveEffectivePreferences } from './preferences.mjs';
+
+const args = process.argv.slice(2);
+let sessionId = null;
+for (let i = 0; i < args.length; i += 1) {
+  if (args[i] === '--session' && args[i + 1]) {
+    sessionId = args[i + 1];
+    i += 1;
+  }
+}
+
+if (!sessionId) {
+  const active = readActive();
+  if (!active?.sessionId) {
+    process.stdout.write(JSON.stringify({ status: 'none', message: 'No active Forge session.' }, null, 2));
+    process.stdout.write('\n');
+    process.exit(0);
+  }
+  sessionId = active.sessionId;
+}
+
+const { dir, session } = loadSession(sessionId);
+const statusPath = path.join(dir, 'status.json');
+const status = fs.existsSync(statusPath) ? JSON.parse(fs.readFileSync(statusPath, 'utf8')) : null;
+
+const pace = resolveEffectivePreferences({
+  forgeDir: FORGE_DIR,
+  session,
+  signalText: session.paceSignal || session.slug || '',
+});
+
+process.stdout.write(
+  JSON.stringify(
+    {
+      status: 'ok',
+      sessionId,
+      sessionPath: path.relative(REPO_ROOT, dir).replace(/\\/g, '/'),
+      session,
+      progress: status,
+      pace: {
+        requested: pace.requestedPace,
+        resolved: pace.resolvedPace,
+        reason: pace.paceReason,
+        source: pace.source,
+        effective: pace.effective,
+      },
+      integrity: pace.integrity,
+    },
+    null,
+    2,
+  ),
+);
+process.stdout.write('\n');

package/src/set-models.mjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+/**
+ * Get or set the checkout-local Forge subagent billing preference.
+ *
+ * Usage:
+ *   forge set-models              # print effective billing
+ *   forge set-models included     # set local billing
+ *   forge set-models metered
+ *
+ * Options:
+ *   --forge-dir <path>  Forge root (default: .forge under cwd)
+ *   --defaults <path>   Defaults JSON path
+ *   --json              Machine-readable stdout for get
+ *   --help
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import {
+  BILLING_LANES,
+  DEFAULTS_PATH,
+  loadJsonFile,
+  loadMergedConfig,
+} from './resolve-model.mjs';
+
+/**
+ * @param {string[]} argv
+ */
+export function parseArgs(argv) {
+  const opts = {
+    billing: null,
+    forgeDir: null,
+    defaults: null,
+    json: false,
+    help: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--forge-dir') opts.forgeDir = argv[++i];
+    else if (arg === '--defaults') opts.defaults = argv[++i];
+    else if (arg === '--json') opts.json = true;
+    else if (arg === '--help' || arg === '-h') opts.help = true;
+    else if (arg === '--') continue;
+    else if (!arg.startsWith('-') && opts.billing === null) opts.billing = arg;
+    else throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  return opts;
+}
+
+/**
+ * @param {{ forgeDir: string, billing: string }} opts
+ */
+export function writeLocalBilling(opts) {
+  if (!BILLING_LANES.includes(opts.billing)) {
+    throw new Error(`Unknown billing "${opts.billing}". Expected one of: ${BILLING_LANES.join(', ')}`);
+  }
+
+  fs.mkdirSync(opts.forgeDir, { recursive: true });
+  const localPath = path.join(opts.forgeDir, 'models.local.json');
+
+  /** @type {Record<string, unknown>} */
+  let existing = {};
+  if (fs.existsSync(localPath)) {
+    existing = loadJsonFile(localPath);
+  }
+
+  const next = { ...existing, billing: opts.billing };
+  fs.writeFileSync(localPath, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+  return { localPath, billing: opts.billing };
+}
+
+/**
+ * @param {{ forgeDir?: string, defaultsPath?: string, cwd?: string }} [paths]
+ */
+export function getEffectiveBilling(paths = {}) {
+  const { config, sources, localPath } = loadMergedConfig({
+    defaultsPath: paths.defaultsPath,
+    forgeDir: paths.forgeDir,
+    cwd: paths.cwd,
+  });
+  const billing =
+    typeof config.billing === 'string' && BILLING_LANES.includes(config.billing)
+      ? config.billing
+      : 'included';
+  return {
+    billing,
+    localPath,
+    localExists: fs.existsSync(localPath),
+    source: sources,
+  };
+}
+
+function printHelp() {
+  process.stdout.write(`Usage: forge set-models [included|metered] [options]
+
+Get or set checkout-local Forge subagent billing lane.
+
+  forge models
+      Print effective lane only — does NOT create .forge/models.local.json.
+      Without a local file, this prints the committed default (usually "included").
+
+  forge models included|metered
+      Write/update .forge/models.local.json (gitignored, per-checkout).
+
+  forge models -- --json
+      Same get, with paths and localExists.
+
+Defaults: models.defaults.json
+Local overlay: .forge/models.local.json (appears only after a set)
+
+Options:
+  --forge-dir <path>  Forge directory (default: .forge)
+  --defaults <path>   Defaults JSON path
+  --json              JSON stdout when getting
+  --help              Show help
+`);
+}
+
+/**
+ * @param {string[]} argv
+ * @param {{ cwd?: string, stdout?: NodeJS.WritableStream, stderr?: NodeJS.WritableStream }} [io]
+ */
+export function runSetModels(argv, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  const stderr = io.stderr ?? process.stderr;
+  const cwd = io.cwd ?? process.cwd();
+
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    stderr.write(`${msg}\n`);
+    return 2;
+  }
+
+  if (opts.help) {
+    printHelp();
+    return 0;
+  }
+
+  const forgeDir = opts.forgeDir ?? path.join(cwd, '.forge');
+  const defaultsPath = opts.defaults ?? DEFAULTS_PATH;
+
+  try {
+    if (opts.billing) {
+      const written = writeLocalBilling({ forgeDir, billing: opts.billing });
+      stdout.write(`billing=${written.billing}\n`);
+      stdout.write(`wrote ${written.localPath}\n`);
+      return 0;
+    }
+
+    const effective = getEffectiveBilling({
+      forgeDir,
+      defaultsPath,
+      cwd,
+    });
+    if (opts.json) {
+      stdout.write(`${JSON.stringify(effective, null, 2)}\n`);
+    } else {
+      stdout.write(`billing=${effective.billing}\n`);
+      if (effective.localExists) {
+        stdout.write(`local=${effective.localPath}\n`);
+      } else {
+        stdout.write(`local=(none — using models.defaults.json)\n`);
+        stdout.write(`hint: forge models included|metered  # writes .forge/models.local.json\n`);
+      }
+    }
+    return 0;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    stderr.write(`${msg}\n`);
+    return 1;
+  }
+}
+
+const isMain =
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href;
+
+if (isMain) {
+  process.exitCode = runSetModels(process.argv.slice(2));
+}