@izkac/forgekit 0.1.0

package/src/set-prefs.mjs

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+/**
+ * Get or set checkout-local Forge pace preferences.
+ *
+ * Usage:
+ *   forge set-prefs                         # print effective
+ *   forge set-prefs brisk                   # set pace
+ *   forge set-prefs --set review.perTask=always
+ *   forge set-prefs --session-set lite      # pin active session
+ *   forge set-prefs --resolve --signal "…"  # resolve auto now
+ *
+ * Options:
+ *   --forge-dir <path>
+ *   --defaults <path>
+ *   --json
+ *   --help
+ */
+
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import {
+  DEFAULTS_PATH,
+  PACES,
+  parseAssignment,
+  resolveEffectivePreferences,
+  resolveSessionPaceFields,
+  setDotted,
+  suggestPaceFromSignals,
+  writeLocalPreferences,
+} from './preferences.mjs';
+import {
+  loadSession,
+  readActive,
+  saveSession,
+} from './lib.mjs';
+
+/**
+ * @param {string[]} argv
+ */
+export function parseArgs(argv) {
+  const opts = {
+    pace: null,
+    sets: [],
+    sessionSet: null,
+    resolve: false,
+    signal: 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 === '--set') opts.sets.push(argv[++i]);
+    else if (arg === '--session-set') opts.sessionSet = argv[++i];
+    else if (arg === '--resolve') opts.resolve = true;
+    else if (arg === '--signal') opts.signal = 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.pace === null) opts.pace = arg;
+    else throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  return opts;
+}
+
+function printHelp() {
+  process.stdout.write(`Usage: forge set-prefs [pace] [options]
+
+Get or set Forge pace (thoroughness) preferences.
+
+Paces: ${PACES.join(', ')}  (default: auto)
+
+  forge prefs
+      Print effective pace + knobs — does NOT create .forge/preferences.local.json
+      unless you also pass a pace or --set. local=(none) means committed defaults.
+
+  forge prefs brisk
+      Write/update .forge/preferences.local.json (gitignored, per-checkout).
+
+  forge prefs --session-set lite
+      Pin pace on the active session only (no local file write).
+
+  forge prefs -- --set review.perTask=always
+  forge prefs -- --resolve --signal "add stripe refund"
+
+Defaults: preferences.defaults.json
+Local overlay: .forge/preferences.local.json (appears only after a set)
+Matrix: .cursor/skills/forge/references/pace.md
+
+Options:
+  --set path=value   Nested override (repeatable)
+  --session-set      Pin pace on active session only
+  --resolve          Re-resolve auto for active session
+  --signal <text>    Signals for auto / --resolve
+  --json             JSON stdout
+  --forge-dir <path>
+  --defaults <path>
+  --help
+`);
+}
+
+/**
+ * @param {string[]} argv
+ * @param {{ cwd?: string, stdout?: NodeJS.WritableStream, stderr?: NodeJS.WritableStream }} [io]
+ */
+export function runSetPrefs(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.sessionSet != null) {
+      if (!PACES.includes(opts.sessionSet)) {
+        throw new Error(`Unknown pace "${opts.sessionSet}". Expected one of: ${PACES.join(', ')}`);
+      }
+      const active = readActive();
+      if (!active?.sessionId) {
+        throw new Error('No active Forge session. Run forge:new first.');
+      }
+      const { dir, session } = loadSession(active.sessionId);
+      if (opts.sessionSet === 'auto') {
+        const fields = resolveSessionPaceFields({
+          forgeDir,
+          defaultsPath,
+          cwd,
+          slug: session.slug,
+          signalText: opts.signal || session.paceSignal || session.slug,
+          paceOverride: 'auto',
+        });
+        Object.assign(session, fields);
+      } else {
+        session.pace = opts.sessionSet;
+        session.resolvedPace = opts.sessionSet;
+        session.paceReason = 'session override';
+        session.pacePinned = true;
+        session.preferencesOverride = { pace: opts.sessionSet };
+      }
+      saveSession(dir, session);
+      if (opts.json) {
+        stdout.write(`${JSON.stringify({ sessionId: session.id, pace: session }, null, 2)}\n`);
+      } else {
+        stdout.write(`session ${session.id}: pace=${session.pace} resolved=${session.resolvedPace}\n`);
+      }
+      return 0;
+    }
+
+    if (opts.resolve) {
+      const active = readActive();
+      if (!active?.sessionId) {
+        throw new Error('No active Forge session. Run forge:new first.');
+      }
+      const { dir, session } = loadSession(active.sessionId);
+      const signal = opts.signal || session.paceSignal || session.slug || '';
+      const fields = resolveSessionPaceFields({
+        forgeDir,
+        defaultsPath,
+        cwd,
+        slug: session.slug,
+        signalText: signal,
+        paceOverride: typeof session.pace === 'string' ? session.pace : 'auto',
+      });
+      // Force re-resolve even if concrete: when --resolve with auto requested
+      if ((session.pace ?? 'auto') === 'auto' || fields.pace === 'auto') {
+        const suggested = suggestPaceFromSignals(signal);
+        session.pace = 'auto';
+        session.resolvedPace = suggested.pace;
+        session.paceReason = suggested.reason;
+        session.paceSignal = signal || null;
+        session.pacePinned = false;
+        session.preferencesOverride = null;
+      } else {
+        Object.assign(session, fields);
+      }
+      saveSession(dir, session);
+      if (opts.json) {
+        stdout.write(
+          `${JSON.stringify({
+            sessionId: session.id,
+            requestedPace: session.pace,
+            resolvedPace: session.resolvedPace,
+            paceReason: session.paceReason,
+          }, null, 2)}\n`,
+        );
+      } else {
+        stdout.write(
+          `resolved ${session.resolvedPace} (${session.paceReason})\n`,
+        );
+      }
+      return 0;
+    }
+
+    if (opts.pace != null || opts.sets.length > 0) {
+      /** @type {Record<string, unknown>} */
+      const patch = {};
+      if (opts.pace != null) {
+        if (!PACES.includes(opts.pace)) {
+          throw new Error(`Unknown pace "${opts.pace}". Expected one of: ${PACES.join(', ')}`);
+        }
+        patch.pace = opts.pace;
+      }
+      for (const assignment of opts.sets) {
+        if (!assignment) throw new Error('--set requires path=value');
+        const { key, value } = parseAssignment(assignment);
+        setDotted(patch, key, value);
+      }
+      const written = writeLocalPreferences({ forgeDir, patch });
+      if (opts.json) {
+        stdout.write(`${JSON.stringify(written, null, 2)}\n`);
+      } else {
+        stdout.write(`wrote ${written.localPath}\n`);
+        if (patch.pace) stdout.write(`pace=${patch.pace}\n`);
+        for (const a of opts.sets) stdout.write(`set ${a}\n`);
+      }
+      return 0;
+    }
+
+    let session = null;
+    const active = readActive();
+    if (active?.sessionId) {
+      try {
+        session = loadSession(active.sessionId).session;
+      } catch {
+        session = null;
+      }
+    }
+
+    const effective = resolveEffectivePreferences({
+      forgeDir,
+      defaultsPath,
+      cwd,
+      session,
+      signalText: opts.signal || undefined,
+    });
+
+    if (opts.json) {
+      stdout.write(`${JSON.stringify(effective, null, 2)}\n`);
+    } else {
+      stdout.write(`pace=${effective.requestedPace}\n`);
+      stdout.write(`resolved=${effective.resolvedPace}\n`);
+      stdout.write(`reason=${effective.paceReason}\n`);
+      stdout.write(`source=${effective.source}\n`);
+      stdout.write(`review.perTask=${effective.effective.review.perTask}\n`);
+      stdout.write(`review.final=${effective.effective.review.final}\n`);
+      stdout.write(`review.depth=${effective.effective.review.depth}\n`);
+      stdout.write(`review.maxRounds=${effective.effective.review.maxRounds}\n`);
+      stdout.write(`verify.tier3=${effective.effective.verify.tier3}\n`);
+      stdout.write(`models.bias=${effective.effective.models.bias}\n`);
+      stdout.write(`brainstorm.depth=${effective.effective.brainstorm.depth}\n`);
+      if (effective.localExists) {
+        stdout.write(`local=${effective.localPath}\n`);
+      } else {
+        stdout.write(`local=(none — using preferences.defaults.json)\n`);
+        stdout.write(
+          `hint: forge prefs -- auto|thorough|standard|brisk|lite  # writes .forge/preferences.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 = runSetPrefs(process.argv.slice(2));
+}

package/src/spine.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * Forge spine matrix — scaffold + validate the capability→runtime wiring map.
+ *
+ * Usage:
+ *   forge spine                       # show status (path, validity)
+ *   forge spine init [--force]        # scaffold spine.json for the active change
+ *   forge spine check                 # validate; exit 1 with problems
+ *   [--session <id>]
+ *
+ * spine.json lives in the change dir (openspec/changes/<name>/ or
+ * <specsDir>/changes/<name>/), falling back to the session dir when the
+ * session has no tracked change.
+ */
+
+import fs from 'node:fs';
+import { loadSession, readActive, readJson } from './lib.mjs';
+import { initSpine, spinePath, validateSpine } from './integrity.mjs';
+
+const args = process.argv.slice(2);
+const sub = args[0] && !args[0].startsWith('--') ? args[0] : 'status';
+
+if (args[0] === '--help' || sub === 'help') {
+  process.stdout.write(
+    'Usage: forge spine [init [--force] | check | status] [--session <id>]\n',
+  );
+  process.exit(0);
+}
+
+let sessionId = null;
+let force = false;
+for (let i = 0; i < args.length; i += 1) {
+  if (args[i] === '--session' && args[i + 1]) {
+    sessionId = args[i + 1];
+    i += 1;
+  } else if (args[i] === '--force') {
+    force = true;
+  }
+}
+
+if (!sessionId) {
+  const active = readActive();
+  sessionId = active?.sessionId;
+}
+if (!sessionId) {
+  process.stderr.write('No active session. Run forge new first.\n');
+  process.exit(1);
+}
+
+const { dir, session } = loadSession(sessionId);
+const file = spinePath({ session, sessionDir: dir });
+
+if (sub === 'init') {
+  try {
+    initSpine({ file, change: session.openspecChange ?? null, force });
+  } catch (err) {
+    process.stderr.write(`${err instanceof Error ? err.message : err}\n`);
+    process.exit(1);
+  }
+  process.stdout.write(
+    `Scaffolded ${file}\nFill every row (one per capability/REQ cluster); reads/uiConsumer may be "N/A".\nValidate with: forge spine check\n`,
+  );
+  process.exit(0);
+}
+
+if (sub === 'check' || sub === 'status') {
+  if (!fs.existsSync(file)) {
+    const msg = `spine.json not found at ${file} — run forge spine init\n`;
+    if (sub === 'check') {
+      process.stderr.write(msg);
+      process.exit(1);
+    }
+    process.stdout.write(JSON.stringify({ file, exists: false }, null, 2));
+    process.stdout.write('\n');
+    process.exit(0);
+  }
+  let result;
+  try {
+    result = validateSpine(readJson(file));
+  } catch (err) {
+    result = { ok: false, problems: [`unreadable: ${err instanceof Error ? err.message : err}`] };
+  }
+  process.stdout.write(
+    JSON.stringify({ file, exists: true, ok: result.ok, problems: result.problems }, null, 2),
+  );
+  process.stdout.write('\n');
+  process.exit(sub === 'check' && !result.ok ? 1 : 0);
+}
+
+process.stderr.write(`Unknown subcommand: ${sub}\n`);
+process.exit(1);

package/src/triage-prompt.mjs

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+/**
+ * Heuristics for Forge auto-triage on agent UserPromptSubmit hooks.
+ * Mirrors references/substantial-work.md — err toward Forge when unsure.
+ */
+
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export function isForgeSkip(prompt) {
+  return /^\s*\/forge:skip\b/i.test((prompt || '').trim());
+}
+
+export function isForgeInvocation(prompt) {
+  return /^\s*\/forge(?::|\s|$)/i.test((prompt || '').trim());
+}
+
+export function isTrivialEdit(prompt) {
+  const p = (prompt || '').trim();
+  if (!p) return true;
+  return (
+    /\b(typo|formatting only|whitespace only|comment only|rename only|no behavior change|zero behavior)\b/i.test(p)
+    || /^\s*fix(ed)?\s+(a|the)?\s*typo\b/i.test(p)
+  );
+}
+
+export function isReadOnlyQuestion(prompt) {
+  const p = (prompt || '').trim();
+  if (!p) return true;
+
+  const implementVerb =
+    /\b(add|build|implement|create|fix|update|wire|integrate|migrate|refactor|change|modify|delete|remove|make|enable|support|debug|investigate)\b/i;
+  const diagnosticFix =
+    /\b(doesn'?t|does not|isn'?t|not)\s+(seem to|work|fire|load|trigger|run)\b/i.test(p)
+    || /\b(wired correctly|not wired|broken wiring|misconfigured)\b/i.test(p);
+
+  if (diagnosticFix) return false;
+
+  const questionLead =
+    /^(what|how does|how do|why|where|when|who|explain|describe|tell me about|can you explain|is there|are there|does the|do we|show me|list|summarize)\b/i;
+  if (questionLead.test(p) && !implementVerb.test(p)) return true;
+
+  if (/\?\s*$/.test(p) && !implementVerb.test(p) && !/\b(check if|verify that|audit)\b/i.test(p)) {
+    return true;
+  }
+
+  return false;
+}
+
+export function isSubstantialWork(prompt) {
+  const p = (prompt || '').trim();
+  if (!p) return false;
+  if (isForgeSkip(p)) return false;
+  if (isForgeInvocation(p)) return true;
+  if (isTrivialEdit(p)) return false;
+  if (isReadOnlyQuestion(p)) return false;
+
+  const patterns = [
+    /^\s*(please\s+)?(add|build|create|implement|develop|wire|integrate|migrate|port|enable|support|make|change|modify|update|remove|delete|refactor|fix|debug|investigate|set up|setup)\b/i,
+    /\b(add|build|implement|create|wire up|hook up)\s+(a|an|the|new)\b/i,
+    /\b(doesn'?t|does not|isn'?t)\s+(seem to|work|fire|load|trigger|run)\b/i,
+    /\b(bug|regression|broken|misconfigured|not wired)\b/i,
+    /\bnew feature\b/i,
+    /\bcheck if\b.*\b(wired|configured|working|hook)\b/i,
+    /\b(ensure|make sure)\b.*\b(wired|configured|working|fires?)\b/i,
+  ];
+
+  return patterns.some((re) => re.test(p));
+}
+
+export function shouldForgeTriage(prompt) {
+  if (isForgeInvocation(prompt)) return false;
+  return isSubstantialWork(prompt);
+}
+
+export function buildForgeTriageMessage(options = {}) {
+  const {
+    hasActiveSession = false,
+    skillPath = 'forge skill (SKILL.md)',
+    sessionLines = [],
+  } = options;
+
+  const lines = [];
+  lines.push('[forge] Substantial work detected — triage before implementation.');
+  lines.push('');
+  lines.push(`1. Read the Forge skill (\`${skillPath}\`) and follow triage (references/substantial-work.md).`);
+  if (!hasActiveSession) {
+    lines.push('2. If entering Forge: `forge new <slug>` then continue the current phase.');
+  } else if (sessionLines.length > 0) {
+    lines.push('2. Active session:');
+    for (const line of sessionLines) lines.push(`   ${line}`);
+  }
+  lines.push('3. Skip Forge for this task only: `/forge:skip`');
+  lines.push('Guide: Forge skill + forgekit docs/forge.md');
+  return lines.join('\n');
+}
+
+/**
+ * CLI:
+ *   forge triage --check "<prompt>"     exit 0 if should triage, else 1
+ *   forge triage --message "<prompt>"   print triage reminder (always)
+ *   forge triage --message --has-session "<prompt>"
+ */
+function parseTriageArgs(argv) {
+  const opts = {
+    check: false,
+    message: false,
+    hasSession: false,
+    help: false,
+    prompt: '',
+  };
+  const rest = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--check') opts.check = true;
+    else if (arg === '--message') opts.message = true;
+    else if (arg === '--has-session') opts.hasSession = true;
+    else if (arg === '--help' || arg === '-h') opts.help = true;
+    else rest.push(arg);
+  }
+  opts.prompt = rest.join(' ').trim();
+  return opts;
+}
+
+function printTriageHelp() {
+  process.stdout.write(`Usage:
+  forge triage --check "<prompt>"
+  forge triage --message [--has-session] "<prompt>"
+`);
+}
+
+async function triageMain(argv = process.argv.slice(2)) {
+  const opts = parseTriageArgs(argv);
+  if (opts.help || (!opts.check && !opts.message)) {
+    printTriageHelp();
+    return opts.help ? 0 : 1;
+  }
+
+  let prompt = opts.prompt;
+  if (!prompt && !process.stdin.isTTY) {
+    prompt = await new Promise((resolve) => {
+      let data = '';
+      process.stdin.setEncoding('utf8');
+      process.stdin.on('data', (c) => {
+        data += c;
+      });
+      process.stdin.on('end', () => resolve(data.trim()));
+      setTimeout(() => resolve(data.trim()), 1000);
+    });
+  }
+
+  if (opts.check) {
+    return shouldForgeTriage(prompt) ? 0 : 1;
+  }
+
+  process.stdout.write(
+    `${buildForgeTriageMessage({
+      hasActiveSession: opts.hasSession,
+      sessionLines: [],
+    })}\n`,
+  );
+  return 0;
+}
+
+const isDirect =
+  process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url;
+
+if (isDirect) {
+  triageMain()
+    .then((code) => process.exit(code))
+    .catch((err) => {
+      process.stderr.write(`${err.message || err}\n`);
+      process.exit(1);
+    });
+}

package/src/triage-prompt.test.mjs

@@ -0,0 +1,50 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  isForgeSkip,
+  isForgeInvocation,
+  isReadOnlyQuestion,
+  isSubstantialWork,
+  shouldForgeTriage,
+} from './triage-prompt.mjs';
+
+test('isForgeSkip matches /forge:skip', () => {
+  assert.equal(isForgeSkip('/forge:skip fix typo'), true);
+  assert.equal(isForgeSkip('  /forge:skip'), true);
+});
+
+test('isForgeInvocation matches forge commands', () => {
+  assert.equal(isForgeInvocation('/forge'), true);
+  assert.equal(isForgeInvocation('/forge:brainstorm'), true);
+});
+
+test('read-only questions skip triage', () => {
+  assert.equal(isReadOnlyQuestion('How does auth work?'), true);
+  assert.equal(isReadOnlyQuestion('What is forge?'), true);
+});
+
+test('diagnostic fix requests are substantial', () => {
+  const prompt =
+    'Check if Claude is wired correctly. It does not seem to fire the forge flow automatically';
+  assert.equal(isReadOnlyQuestion(prompt), false);
+  assert.equal(isSubstantialWork(prompt), true);
+  assert.equal(shouldForgeTriage(prompt), true);
+});
+
+test('implementation prompts triage', () => {
+  assert.equal(shouldForgeTriage('Add login to mercury console'), true);
+  assert.equal(shouldForgeTriage('Fix the bug in callback verification'), true);
+});
+
+test('explicit /forge handled by prompt hook not triage hook', () => {
+  assert.equal(shouldForgeTriage('/forge:brainstorm'), false);
+  assert.equal(isSubstantialWork('/forge:brainstorm'), true);
+});
+
+test('/forge:skip is not substantial', () => {
+  assert.equal(isSubstantialWork('/forge:skip rename variable'), false);
+});
+
+test('trivial edits skip', () => {
+  assert.equal(isSubstantialWork('Fix the typo in README'), false);
+});