@izkac/forgekit 0.1.0

package/src/integrity.test.mjs

@@ -0,0 +1,296 @@
+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 {
+  JOBS_SIGNAL_RE,
+  addDeferral,
+  initSpine,
+  loadDeferrals,
+  openDeferrals,
+  resolveChangeDir,
+  resolveDeferral,
+  runIntegrityChecks,
+  sessionJobsSignalText,
+  spinePath,
+  spineTemplate,
+  validateSpine,
+} from './integrity.mjs';
+
+function tmp(prefix) {
+  return fs.mkdtempSync(path.join(tmpdir(), prefix));
+}
+
+function validRow(overrides = {}) {
+  return {
+    capability: 'REQ-GOV-01 matching',
+    library: 'services/etl-core/matcher.py',
+    runtimeOwner: 'worker job analyze_study',
+    writes: 'study_proposals',
+    reads: 'N/A',
+    uiConsumer: 'Proposals page',
+    evidence: 'tasks/12-analyze/test-evidence.md',
+    ...overrides,
+  };
+}
+
+test('validateSpine: filled rows pass', () => {
+  const result = validateSpine({ change: 'x', notApplicable: null, rows: [validRow()] });
+  assert.equal(result.ok, true);
+  assert.deepEqual(result.problems, []);
+});
+
+test('validateSpine: library-only row fails (missing runtimeOwner/writes/evidence)', () => {
+  const result = validateSpine({
+    rows: [validRow({ runtimeOwner: '', writes: '', evidence: '' })],
+  });
+  assert.equal(result.ok, false);
+  assert.equal(result.problems.length, 3);
+  assert.match(result.problems.join('\n'), /runtimeOwner/);
+  assert.match(result.problems.join('\n'), /writes/);
+  assert.match(result.problems.join('\n'), /evidence/);
+});
+
+test('validateSpine: scaffold placeholders are rejected', () => {
+  const result = validateSpine(spineTemplate({ change: 'x' }));
+  assert.equal(result.ok, false);
+  assert.match(result.problems.join('\n'), /scaffold placeholder/);
+});
+
+test('validateSpine: empty rows fail; notApplicable opt-out passes', () => {
+  assert.equal(validateSpine({ rows: [] }).ok, false);
+  assert.equal(validateSpine({ rows: [], notApplicable: 'docs-only change' }).ok, true);
+});
+
+test('spine init writes template and refuses overwrite without force', () => {
+  const dir = tmp('forge-spine-');
+  try {
+    const file = path.join(dir, 'spine.json');
+    initSpine({ file, change: 'my-change' });
+    const doc = JSON.parse(fs.readFileSync(file, 'utf8'));
+    assert.equal(doc.change, 'my-change');
+    assert.throws(() => initSpine({ file, change: 'my-change' }), /already exists/);
+    initSpine({ file, change: 'other', force: true });
+    assert.equal(JSON.parse(fs.readFileSync(file, 'utf8')).change, 'other');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('resolveChangeDir: openspec plan type and session-dir fallback', () => {
+  const cwd = tmp('forge-changedir-');
+  try {
+    const dir = resolveChangeDir({
+      cwd,
+      session: { planType: 'openspec', openspecChange: 'my-change' },
+    });
+    assert.equal(dir, path.join(cwd, 'openspec', 'changes', 'my-change'));
+    assert.equal(resolveChangeDir({ cwd, session: { openspecChange: null } }), null);
+    const sessionDir = path.join(cwd, '.forge', 'sessions', 's1');
+    assert.equal(
+      spinePath({ cwd, session: { openspecChange: null }, sessionDir }),
+      path.join(sessionDir, 'spine.json'),
+    );
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('deferrals: add, list, resolve lifecycle', () => {
+  const dir = tmp('forge-defer-');
+  try {
+    addDeferral(dir, { task: '9.2', reason: 'wiring lands in 9.7' });
+    assert.equal(openDeferrals(dir).length, 1);
+    assert.throws(() => addDeferral(dir, { task: '9.2', reason: 'dup' }), /already open/);
+    resolveDeferral(dir, '9.2');
+    assert.equal(openDeferrals(dir).length, 0);
+    assert.equal(loadDeferrals(dir).deferrals.length, 1);
+    assert.throws(() => resolveDeferral(dir, '9.2'), /No open deferral/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('deferrals: add requires task and reason', () => {
+  const dir = tmp('forge-defer-req-');
+  try {
+    assert.throws(() => addDeferral(dir, { task: '', reason: 'x' }), /--task/);
+    assert.throws(() => addDeferral(dir, { task: '1.1', reason: '' }), /--reason/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('JOBS_SIGNAL_RE + sessionJobsSignalText', () => {
+  assert.equal(JOBS_SIGNAL_RE.test('etl-surveydb-harmonization-platform worker'), true);
+  assert.equal(JOBS_SIGNAL_RE.test('fix toolbar padding'), false);
+  assert.equal(
+    sessionJobsSignalText({ paceSignal: null, slug: 'my-slug', openspecChange: 'chg' }),
+    'my-slug chg',
+  );
+});
+
+function makeSessionDir(root) {
+  const dir = path.join(root, '.forge', 'sessions', 's1');
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+test('runIntegrityChecks: missing spine always fails (not keyword-gated)', () => {
+  const cwd = tmp('forge-int-clean-');
+  try {
+    const sessionDir = makeSessionDir(cwd);
+    const result = runIntegrityChecks({
+      cwd,
+      sessionDir,
+      session: { slug: 'fix-toolbar', openspecChange: null },
+    });
+    assert.equal(result.ok, false);
+    assert.match(result.problems.join('\n'), /spine\.json required/);
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('runIntegrityChecks: notApplicable spine allows sync-only without product-loop', () => {
+  const cwd = tmp('forge-int-na-sync-');
+  try {
+    const sessionDir = makeSessionDir(cwd);
+    fs.writeFileSync(
+      path.join(sessionDir, 'spine.json'),
+      `${JSON.stringify(
+        { rows: [], notApplicable: 'sync HTTP only — no async producer/consumer' },
+        null,
+        2,
+      )}\n`,
+      'utf8',
+    );
+    const result = runIntegrityChecks({
+      cwd,
+      sessionDir,
+      session: { slug: 'fix-toolbar', openspecChange: null },
+    });
+    assert.equal(result.ok, true);
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('runIntegrityChecks: unresolved deferral fails', () => {
+  const cwd = tmp('forge-int-defer-');
+  try {
+    const sessionDir = makeSessionDir(cwd);
+    fs.writeFileSync(
+      path.join(sessionDir, 'spine.json'),
+      `${JSON.stringify({ rows: [], notApplicable: 'sync only' }, null, 2)}\n`,
+      'utf8',
+    );
+    addDeferral(sessionDir, { task: '9.2', reason: 'later' });
+    const result = runIntegrityChecks({
+      cwd,
+      sessionDir,
+      session: { slug: 'fix-toolbar', openspecChange: null },
+    });
+    assert.equal(result.ok, false);
+    assert.match(result.problems.join('\n'), /unresolved deferrals: 9\.2/);
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('runIntegrityChecks: empty slug without spine still fails', () => {
+  const cwd = tmp('forge-int-jobs-');
+  try {
+    const sessionDir = makeSessionDir(cwd);
+    const result = runIntegrityChecks({
+      cwd,
+      sessionDir,
+      session: { slug: 'add-harmonization-platform', openspecChange: null },
+    });
+    assert.equal(result.ok, false);
+    assert.match(result.problems.join('\n'), /spine\.json required/);
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('runIntegrityChecks: spine rows demand product-loop evidence', () => {
+  const cwd = tmp('forge-int-loop-');
+  try {
+    const sessionDir = makeSessionDir(cwd);
+    const spineFile = path.join(sessionDir, 'spine.json');
+    fs.writeFileSync(
+      spineFile,
+      `${JSON.stringify({ change: null, notApplicable: null, rows: [validRow()] }, null, 2)}\n`,
+      'utf8',
+    );
+    const session = { slug: 'wire-worker-jobs', openspecChange: null };
+
+    let result = runIntegrityChecks({ cwd, sessionDir, session });
+    assert.equal(result.ok, false);
+    assert.match(result.problems.join('\n'), /verify-evidence\.md missing/);
+
+    const evidenceFile = path.join(sessionDir, 'verify-evidence.md');
+    fs.writeFileSync(evidenceFile, '# Verify\n\ntier 3 green\n', 'utf8');
+    result = runIntegrityChecks({ cwd, sessionDir, session });
+    assert.equal(result.ok, false);
+    assert.match(result.problems.join('\n'), /no "Product loop" section/);
+
+    fs.writeFileSync(evidenceFile, '# Verify\n\n## Product loop\n\nBLOCKED: no compose here\n', 'utf8');
+    result = runIntegrityChecks({ cwd, sessionDir, session });
+    assert.equal(result.ok, false);
+    assert.match(result.problems.join('\n'), /BLOCKED/);
+
+    fs.writeFileSync(
+      evidenceFile,
+      '# Verify\n\n## Product loop\n\ningest x3 -> analyze -> ratify -> run@R: output differs from baseline\n',
+      'utf8',
+    );
+    result = runIntegrityChecks({ cwd, sessionDir, session });
+    assert.equal(result.ok, true);
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('runIntegrityChecks: invalid spine fails even without jobs signal', () => {
+  const cwd = tmp('forge-int-badspine-');
+  try {
+    const sessionDir = makeSessionDir(cwd);
+    fs.writeFileSync(
+      path.join(sessionDir, 'spine.json'),
+      `${JSON.stringify({ rows: [validRow({ runtimeOwner: '' })] }, null, 2)}\n`,
+      'utf8',
+    );
+    const result = runIntegrityChecks({
+      cwd,
+      sessionDir,
+      session: { slug: 'fix-toolbar', openspecChange: null },
+    });
+    assert.equal(result.ok, false);
+    assert.match(result.problems.join('\n'), /spine: .*runtimeOwner/);
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});
+
+test('runIntegrityChecks: notApplicable spine passes without evidence demands', () => {
+  const cwd = tmp('forge-int-na-');
+  try {
+    const sessionDir = makeSessionDir(cwd);
+    fs.writeFileSync(
+      path.join(sessionDir, 'spine.json'),
+      `${JSON.stringify({ rows: [], notApplicable: 'docs-only change' }, null, 2)}\n`,
+      'utf8',
+    );
+    const result = runIntegrityChecks({
+      cwd,
+      sessionDir,
+      session: { slug: 'wire-worker-jobs', openspecChange: null },
+    });
+    assert.equal(result.ok, true);
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+});

package/src/lib/workspaces.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+/**
+ * Shared workspace loader for repo-level scripts.
+ *
+ * Reads the root `package.json` `workspaces` globs, expands any trailing `/*`
+ * form, and returns `{ name, dir, scripts }` for every member package.json that
+ * declares a `name`. `dir` is repo-relative with forward slashes. Unreadable or
+ * name-less member manifests are skipped.
+ *
+ * Extracted from the duplicate copies that lived in
+ * `scripts/review/signals.mjs` and `scripts/code-health/apply-gate.mjs`; both
+ * (and `scripts/code-health/detect.mjs`) now import it from here.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * @param {string} repoRoot
+ * @returns {Array<{ name: string, dir: string, scripts: Record<string, string> }>}
+ */
+export function loadWorkspaces(repoRoot) {
+  const rootPkg = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8'));
+  const globs = Array.isArray(rootPkg.workspaces) ? rootPkg.workspaces : [];
+  /** @type {string[]} */
+  const dirs = [];
+
+  for (const glob of globs) {
+    if (glob.endsWith('/*')) {
+      const base = glob.slice(0, -2);
+      const baseDir = path.join(repoRoot, base);
+      if (!fs.existsSync(baseDir)) continue;
+      for (const entry of fs.readdirSync(baseDir, { withFileTypes: true })) {
+        if (entry.isDirectory()) dirs.push(`${base}/${entry.name}`);
+      }
+    } else {
+      dirs.push(glob);
+    }
+  }
+
+  const packages = [];
+  for (const dir of dirs) {
+    const pkgPath = path.join(repoRoot, dir, 'package.json');
+    if (!fs.existsSync(pkgPath)) continue;
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      if (pkg.name) {
+        packages.push({ name: pkg.name, dir: dir.replace(/\\/g, '/'), scripts: pkg.scripts ?? {} });
+      }
+    } catch {
+      /* skip unreadable package.json */
+    }
+  }
+  return packages;
+}

package/src/lib.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+/**
+ * Shared helpers for Forge session management.
+ */
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const REPO_ROOT = process.cwd();
+export const FORGE_DIR = path.join(REPO_ROOT, '.forge');
+export const SESSIONS_DIR = path.join(FORGE_DIR, 'sessions');
+export const ACTIVE_FILE = path.join(FORGE_DIR, 'active.json');
+export const RETENTION_DAYS = 14;
+
+export function ensureForgeLayout() {
+  fs.mkdirSync(SESSIONS_DIR, { recursive: true });
+}
+
+export function slugify(input) {
+  return String(input)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48) || 'session';
+}
+
+export function utcCompactNow() {
+  return new Date().toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
+}
+
+export function randomSuffix(bytes = 3) {
+  return crypto.randomBytes(bytes).toString('hex');
+}
+
+export function makeSessionId(slug) {
+  return `${utcCompactNow()}-${slugify(slug)}-${randomSuffix()}`;
+}
+
+export function sessionPath(sessionId) {
+  return path.join(SESSIONS_DIR, sessionId);
+}
+
+export function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+export function writeJson(filePath, data) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+}
+
+export function readActive() {
+  if (!fs.existsSync(ACTIVE_FILE)) return null;
+  try {
+    return readJson(ACTIVE_FILE);
+  } catch {
+    return null;
+  }
+}
+
+export function writeActive(sessionId) {
+  writeJson(ACTIVE_FILE, {
+    sessionId,
+    sessionPath: path.relative(REPO_ROOT, sessionPath(sessionId)).replace(/\\/g, '/'),
+    updatedAt: new Date().toISOString(),
+  });
+}
+
+export function clearActive() {
+  if (fs.existsSync(ACTIVE_FILE)) fs.unlinkSync(ACTIVE_FILE);
+}
+
+export function defaultSession(sessionId, slug) {
+  const now = new Date().toISOString();
+  return {
+    id: sessionId,
+    slug: slugify(slug),
+    createdAt: now,
+    updatedAt: now,
+    phase: 'triage',
+    planType: null,
+    openspecChange: null,
+    forgeSkipped: false,
+    cursorChatId: null,
+    tasksTotal: 0,
+    tasksComplete: 0,
+    /** Requested pace: auto | thorough | standard | brisk | lite */
+    pace: 'auto',
+    /** Concrete pace after auto resolve or explicit pin */
+    resolvedPace: null,
+    paceReason: null,
+    paceSignal: null,
+    pacePinned: false,
+    preferencesOverride: null,
+  };
+}
+
+export function defaultStatus(session) {
+  return {
+    sessionId: session.id,
+    phase: session.phase,
+    planType: session.planType,
+    openspecChange: session.openspecChange,
+    tasksTotal: session.tasksTotal,
+    tasksComplete: session.tasksComplete,
+    pace: session.pace ?? null,
+    resolvedPace: session.resolvedPace ?? null,
+    paceReason: session.paceReason ?? null,
+    updatedAt: session.updatedAt,
+  };
+}
+
+export function scaffoldSessionDirs(dir) {
+  for (const sub of ['brainstorm', 'tasks', 'reviews']) {
+    fs.mkdirSync(path.join(dir, sub), { recursive: true });
+  }
+}
+
+export function loadSession(sessionId) {
+  const dir = sessionPath(sessionId);
+  const file = path.join(dir, 'session.json');
+  if (!fs.existsSync(file)) {
+    throw new Error(`Session not found: ${sessionId}`);
+  }
+  return { dir, session: readJson(file) };
+}
+
+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));
+}
+
+export function sessionAgeDays(session) {
+  const created = new Date(session.createdAt).getTime();
+  return (Date.now() - created) / (1000 * 60 * 60 * 24);
+}

package/src/models.defaults.json

@@ -0,0 +1,41 @@
+{
+  "billing": "included",
+  "agents": {
+    "cursor": {
+      "included": {
+        "fast": "inherit",
+        "standard": "inherit",
+        "capable": "inherit"
+      },
+      "metered": {
+        "fast": "gpt-5.6-terra-medium",
+        "standard": "claude-sonnet-5-thinking-high",
+        "capable": "claude-opus-4-8-thinking-high"
+      }
+    },
+    "claude-code": {
+      "included": {
+        "fast": "haiku",
+        "standard": "sonnet",
+        "capable": "opus"
+      },
+      "metered": {
+        "fast": "haiku",
+        "standard": "sonnet",
+        "capable": "opus"
+      }
+    },
+    "codex": {
+      "included": {
+        "fast": "inherit",
+        "standard": "inherit",
+        "capable": "inherit"
+      },
+      "metered": {
+        "fast": "inherit",
+        "standard": "inherit",
+        "capable": "inherit"
+      }
+    }
+  }
+}

package/src/new-session.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * Create a new Forge session under .forge/sessions/ and set it active.
+ *
+ * Usage:
+ *   forge new mercury-console-validation
+ *   forge new <slug> [--chat-id <id>] [--signal <text>]
+ */
+
+import {
+  defaultSession,
+  defaultStatus,
+  ensureForgeLayout,
+  FORGE_DIR,
+  makeSessionId,
+  saveSession,
+  scaffoldSessionDirs,
+  sessionPath,
+  writeActive,
+} from './lib.mjs';
+import { resolveSessionPaceFields } from './preferences.mjs';
+import { warnIfDoctorFails } from './doctor.mjs';
+
+function usage() {
+  process.stderr.write(
+    'Usage: forge new <slug> [--chat-id <id>] [--signal <text>]\n',
+  );
+  process.exit(1);
+}
+
+const args = process.argv.slice(2);
+if (args.length === 0 || args[0] === '--help' || args[0] === '-h') usage();
+
+const slug = args[0];
+let cursorChatId = null;
+let signalText = null;
+for (let i = 1; i < args.length; i += 1) {
+  if (args[i] === '--chat-id' && args[i + 1]) {
+    cursorChatId = args[i + 1];
+    i += 1;
+  } else if (args[i] === '--signal' && args[i + 1]) {
+    signalText = args[i + 1];
+    i += 1;
+  }
+}
+
+ensureForgeLayout();
+warnIfDoctorFails({ cwd: process.cwd() });
+
+const sessionId = makeSessionId(slug);
+const dir = sessionPath(sessionId);
+scaffoldSessionDirs(dir);
+
+const session = defaultSession(sessionId, slug);
+if (cursorChatId) session.cursorChatId = cursorChatId;
+
+const paceFields = resolveSessionPaceFields({
+  forgeDir: FORGE_DIR,
+  slug: session.slug,
+  signalText: signalText || session.slug,
+});
+Object.assign(session, paceFields);
+
+saveSession(dir, session);
+writeActive(sessionId);
+
+process.stdout.write(
+  `${JSON.stringify(
+    {
+      sessionId,
+      dir,
+      session: defaultStatus(session),
+      pace: {
+        requested: session.pace,
+        resolved: session.resolvedPace,
+        reason: session.paceReason,
+      },
+    },
+    null,
+    2,
+  )}\n`,
+);

package/src/openspec-overlays/README.md

@@ -0,0 +1,19 @@
+# OpenSpec Forge overlays
+
+Vendor OpenSpec skills and `/opsx:*` commands are upgraded in place. **Do not hand-edit** them.
+
+Forge adaptations live here and are applied by:
+
+```bash
+forge overlay
+```
+
+Run after refreshing OpenSpec skills/commands from upstream (usually via `forge init --overlay`).
+
+| Overlay | Targets |
+| ------- | ------- |
+| `opsx-apply-implement-step.md` | Step 6 in `opsx-apply` / `opsx/apply` commands |
+| `opsx-apply-completion-step.md` | Step 7 “all done” bullet in same commands |
+| `openspec-apply-change-footer.md` | Footer on `openspec-apply-change/SKILL.md` (all agents) |
+
+**Forge-owned (never overwritten):** `/forge:apply` command, `forge/` skill tree.

package/src/openspec-overlays/openspec-apply-change-footer.md

@@ -0,0 +1,14 @@
+
+---
+
+<!-- forgekit:openspec-overlay:start -->
+
+## Forge overlay (re-applied by `forge overlay`)
+
+**Do not implement tasks inline in coordinator context.**
+
+1. Prefer **`/forge:apply`** for OpenSpec implement + verify + review.
+2. Otherwise follow vendor steps 1–5 above, then **`{{PHASES_IMPLEMENT}}`** for step 6+.
+3. Re-apply this overlay after upgrading OpenSpec skills: `forge overlay`
+
+<!-- forgekit:openspec-overlay:end -->

package/src/openspec-overlays/opsx-apply-completion-step.md

@@ -0,0 +1 @@
+   - If all done: proceed to Forge [verify]({{PHASES_VERIFY}}) and [review]({{PHASES_REVIEW}}) when in a Forge session (or user invoked `/forge:apply`), then suggest `/opsx:archive`

package/src/openspec-overlays/opsx-apply-implement-step.md

@@ -0,0 +1,11 @@
+**REQUIRED (Forge):** Wrap this loop in the implement phase —
+`{{PHASES_IMPLEMENT}}`.
+Use bundled `skills/subagent-driven-development` + `skills/test-driven-development` per task.
+Prefer **`/forge:apply`** over bare `/opsx:apply` — same OpenSpec CLI steps plus verify and review.
+
+   For each pending task:
+   - Show which task is being worked on
+   - Dispatch **implementer** subagent (TDD first), then **spec** + **quality** reviewers
+   - Keep changes minimal and focused
+   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
+   - Continue to next task