@codewithjuber/forgekit 0.8.0

package/scripts/bump.mjs

@@ -0,0 +1,322 @@
+#!/usr/bin/env node
+/**
+ * Zero-dependency version bump for forgekit (node stdlib only).
+ *
+ * Usage:
+ *   node scripts/bump.mjs <patch|minor|major|auto>   # bump every version field + CHANGELOG
+ *   node scripts/bump.mjs check                      # assert all version fields agree (CI guard)
+ *   node scripts/bump.mjs <kind> --dry-run           # compute + print, write nothing
+ *
+ * "auto" heuristic (deliberately simple):
+ *   1. Conventional commits since the last v* tag:
+ *        BREAKING CHANGE / "type!:" -> major, feat -> minor, anything else -> patch.
+ *   2. If git yields no commits, fall back to the CHANGELOG [Unreleased] body:
+ *        "BREAKING" -> major, a "### Added" section -> minor, any other content -> patch.
+ *   3. Nothing found anywhere -> error (nothing to release).
+ *
+ * Files touched (all version fields in the repo):
+ *   package.json, package-lock.json (root "version" + packages[""].version),
+ *   .claude-plugin/plugin.json, .codex-plugin/plugin.json,
+ *   CITATION.cff (version + date-released), landing/index.html (display string),
+ *   CHANGELOG.md ([Unreleased] rotated under "## [X.Y.Z] - <date>" + compare links).
+ *
+ * Prints ONLY the new version on stdout (diagnostics go to stderr) so callers can
+ * capture it: NEW="$(node scripts/bump.mjs auto)".
+ */
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// ---------------------------------------------------------------------------
+// Pure version math
+// ---------------------------------------------------------------------------
+
+export function parseVersion(v) {
+  const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(String(v).trim());
+  if (!m) throw new Error(`unsupported version format: ${JSON.stringify(v)} (want X.Y.Z)`);
+  return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]) };
+}
+
+export function computeNext(current, kind) {
+  const { major, minor, patch } = parseVersion(current);
+  switch (kind) {
+    case "major":
+      return `${major + 1}.0.0`;
+    case "minor":
+      return `${major}.${minor + 1}.0`;
+    case "patch":
+      return `${major}.${minor}.${patch + 1}`;
+    default:
+      throw new Error(`unknown bump kind: ${JSON.stringify(kind)} (want patch|minor|major)`);
+  }
+}
+
+/**
+ * Conventional-commit heuristic. `commits` is [{ subject, body }].
+ * BREAKING -> major, feat -> minor, anything else -> patch, no commits -> null.
+ */
+export function inferKindFromCommits(commits) {
+  if (!commits || commits.length === 0) return null;
+  let kind = "patch";
+  for (const { subject = "", body = "" } of commits) {
+    if (/^[a-z]+(\([^)]*\))?!:/.test(subject) || /BREAKING[ -]CHANGE/.test(`${subject}\n${body}`)) {
+      return "major";
+    }
+    if (/^feat(\([^)]*\))?:/.test(subject)) kind = "minor";
+  }
+  return kind;
+}
+
+/**
+ * CHANGELOG fallback heuristic on the [Unreleased] body.
+ * "BREAKING" -> major, "### Added" section -> minor, other content -> patch, empty -> null.
+ */
+export function inferKindFromChangelog(unreleasedBody) {
+  const body = (unreleasedBody || "").trim();
+  if (!body) return null;
+  if (/\bBREAKING\b/.test(body)) return "major";
+  if (/^### Added\b/m.test(body)) return "minor";
+  return "patch";
+}
+
+// ---------------------------------------------------------------------------
+// CHANGELOG rotation (pure)
+// ---------------------------------------------------------------------------
+
+/** Returns the text between "## [Unreleased]" and the next "## [" heading (or EOF/link refs). */
+export function extractUnreleased(changelog) {
+  const start = changelog.search(/^## \[Unreleased\][^\n]*\n/m);
+  if (start === -1) return null;
+  const afterHeading = changelog.indexOf("\n", start) + 1;
+  const rest = changelog.slice(afterHeading);
+  const next = rest.search(/^(## \[|\[Unreleased\]:)/m);
+  return next === -1 ? rest : rest.slice(0, next);
+}
+
+/**
+ * Moves the [Unreleased] body under "## [newVersion] - date", leaves a fresh empty
+ * [Unreleased], and rewrites the keep-a-changelog compare links at the bottom.
+ */
+// Complete regex escape (CodeQL js/incomplete-sanitization): versions are semver-shaped
+// by the time main() calls this, but rotateChangelog is exported — escape EVERY
+// metacharacter, not just dots, so a direct caller can't smuggle a pattern in.
+const reEscape = (s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+export function rotateChangelog(changelog, newVersion, prevVersion, date) {
+  if (new RegExp(`^## \\[${reEscape(newVersion)}\\]`, "m").test(changelog)) {
+    throw new Error(`CHANGELOG.md already has a [${newVersion}] section`);
+  }
+  const body = extractUnreleased(changelog);
+  if (body === null) throw new Error("CHANGELOG.md has no ## [Unreleased] section");
+  const start = changelog.search(/^## \[Unreleased\][^\n]*\n/m);
+  const afterHeading = changelog.indexOf("\n", start) + 1;
+  const head = changelog.slice(0, afterHeading);
+  const tail = changelog.slice(afterHeading + body.length);
+  const released = `\n## [${newVersion}] - ${date}\n\n${body.trim()}\n\n`;
+  let out = head + released + tail;
+
+  // Rewrite the compare links: [Unreleased] -> vNEW...HEAD, insert [NEW] -> vPREV...vNEW.
+  const refRe = /^\[Unreleased\]:\s*(\S+?)\/compare\/\S+\s*$/m;
+  const refMatch = refRe.exec(out);
+  if (refMatch) {
+    const base = refMatch[1];
+    out = out.replace(
+      refRe,
+      `[Unreleased]: ${base}/compare/v${newVersion}...HEAD\n` +
+        `[${newVersion}]: ${base}/compare/v${prevVersion}...v${newVersion}`,
+    );
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// File mutation
+// ---------------------------------------------------------------------------
+
+export const JSON_VERSION_FILES = [
+  "package.json",
+  ".claude-plugin/plugin.json",
+  ".codex-plugin/plugin.json",
+];
+
+function readIfExists(file) {
+  return fs.existsSync(file) ? fs.readFileSync(file, "utf8") : null;
+}
+
+/** Replaces the first `"version": "<old>"` in raw JSON text (keeps formatting/escapes). */
+export function setJsonVersionText(text, oldVersion, newVersion) {
+  const needle = `"version": "${oldVersion}"`;
+  const idx = text.indexOf(needle);
+  if (idx === -1) throw new Error(`no "version": "${oldVersion}" field found`);
+  const out = `${text.slice(0, idx)}"version": "${newVersion}"${text.slice(idx + needle.length)}`;
+  JSON.parse(out); // sanity: still valid JSON
+  return out;
+}
+
+/** Collects every tracked version field, as { file: version }. Missing files are skipped. */
+export function collectVersions(root) {
+  const found = {};
+  for (const rel of JSON_VERSION_FILES) {
+    const text = readIfExists(path.join(root, rel));
+    if (text !== null) found[rel] = JSON.parse(text).version;
+  }
+  const lockText = readIfExists(path.join(root, "package-lock.json"));
+  if (lockText !== null) {
+    const lock = JSON.parse(lockText);
+    found["package-lock.json (root)"] = lock.version;
+    if (lock.packages?.[""]) found['package-lock.json (packages."")'] = lock.packages[""].version;
+  }
+  const cff = readIfExists(path.join(root, "CITATION.cff"));
+  if (cff !== null) {
+    const m = /^version:\s*(\S+)\s*$/m.exec(cff);
+    if (m) found["CITATION.cff"] = m[1];
+  }
+  return found;
+}
+
+/**
+ * Writes `newVersion` (and `date`) into every version field. Returns the list of
+ * files changed. Files absent from `root` are skipped so fixtures can be partial.
+ */
+export function applyBump(root, currentVersion, newVersion, date) {
+  const changed = [];
+  const write = (rel, text) => {
+    fs.writeFileSync(path.join(root, rel), text);
+    changed.push(rel);
+  };
+
+  for (const rel of JSON_VERSION_FILES) {
+    const text = readIfExists(path.join(root, rel));
+    if (text !== null) write(rel, setJsonVersionText(text, currentVersion, newVersion));
+  }
+
+  const lockRel = "package-lock.json";
+  const lockText = readIfExists(path.join(root, lockRel));
+  if (lockText !== null) {
+    const lock = JSON.parse(lockText);
+    lock.version = newVersion;
+    if (lock.packages?.[""]) lock.packages[""].version = newVersion;
+    write(lockRel, `${JSON.stringify(lock, null, 2)}\n`);
+  }
+
+  const cffRel = "CITATION.cff";
+  const cff = readIfExists(path.join(root, cffRel));
+  if (cff !== null) {
+    write(
+      cffRel,
+      cff
+        .replace(/^version:\s*.*$/m, `version: ${newVersion}`)
+        .replace(/^date-released:\s*.*$/m, `date-released: "${date}"`),
+    );
+  }
+
+  const landingRel = "landing/index.html";
+  const landing = readIfExists(path.join(root, landingRel));
+  if (landing !== null && /forgekit v\d+\.\d+\.\d+/.test(landing)) {
+    write(landingRel, landing.replace(/forgekit v\d+\.\d+\.\d+/g, `forgekit v${newVersion}`));
+  }
+
+  const clRel = "CHANGELOG.md";
+  const changelog = readIfExists(path.join(root, clRel));
+  if (changelog !== null) {
+    write(clRel, rotateChangelog(changelog, newVersion, currentVersion, date));
+  }
+
+  return changed;
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+function today() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function gitCommitsSinceLastTag(root) {
+  const git = (args) =>
+    execFileSync("git", args, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+  try {
+    let range;
+    try {
+      const tag = git(["describe", "--tags", "--abbrev=0", "--match", "v*"]).trim();
+      range = [`${tag}..HEAD`];
+    } catch {
+      range = ["HEAD"]; // no tag yet: consider all commits
+    }
+    const raw = git(["log", ...range, "--pretty=%s%x1f%b%x1e"]);
+    return raw
+      .split("\x1e")
+      .map((c) => c.trim())
+      .filter(Boolean)
+      .map((c) => {
+        const [subject, body = ""] = c.split("\x1f");
+        return { subject: subject.trim(), body: body.trim() };
+      });
+  } catch {
+    return null; // not a git checkout
+  }
+}
+
+function runCheck(root) {
+  const found = collectVersions(root);
+  const versions = new Set(Object.values(found));
+  if (versions.size === 1) {
+    process.stderr.write(`version fields agree: ${[...versions][0]}\n`);
+    return 0;
+  }
+  process.stderr.write("version drift detected:\n");
+  for (const [file, v] of Object.entries(found)) process.stderr.write(`  ${file}: ${v}\n`);
+  return 1;
+}
+
+function main(argv) {
+  const flags = argv.filter((a) => a.startsWith("--"));
+  const args = argv.filter((a) => !a.startsWith("--"));
+  const dryRun = flags.includes("--dry-run");
+  const cmd = args[0];
+  const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+  if (cmd === "check") return runCheck(root);
+
+  if (!["patch", "minor", "major", "auto"].includes(cmd)) {
+    process.stderr.write(
+      "usage: node scripts/bump.mjs <patch|minor|major|auto|check> [--dry-run]\n",
+    );
+    return 2;
+  }
+
+  const current = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")).version;
+  let kind = cmd;
+  if (cmd === "auto") {
+    const commits = gitCommitsSinceLastTag(root);
+    kind = inferKindFromCommits(commits);
+    if (!kind) {
+      kind = inferKindFromChangelog(
+        extractUnreleased(readIfExists(path.join(root, "CHANGELOG.md")) || ""),
+      );
+    }
+    if (!kind) {
+      process.stderr.write(
+        "auto: no commits since the last tag and an empty CHANGELOG [Unreleased] — nothing to release\n",
+      );
+      return 1;
+    }
+    process.stderr.write(`auto -> ${kind}\n`);
+  }
+
+  const next = computeNext(current, kind);
+  if (dryRun) {
+    process.stderr.write(`dry-run: ${current} -> ${next} (no files written)\n`);
+  } else {
+    const changed = applyBump(root, current, next, today());
+    process.stderr.write(`bumped ${current} -> ${next}: ${changed.join(", ")}\n`);
+  }
+  process.stdout.write(`${next}\n`);
+  return 0;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  process.exit(main(process.argv.slice(2)));
+}

package/skills/cognitive-substrate/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: cognitive-substrate
+description: >-
+  Use before ambiguous, expensive, multi-file, or mutating coding work to run
+  Forge's cognitive substrate: assumption gate, model routing, impact
+  prediction, scope decomposition, memory/lesson lookup, minimality check, and
+  verification planning. Trigger when a user asks to edit/refactor/fix/design
+  production code, integrate features, choose model effort, inspect blast
+  radius, or avoid agent assumptions.
+---
+
+# Cognitive Substrate
+
+Wrap the frozen model in a pre-action check: gate assumptions, route model effort, predict
+blast radius, decompose scope, surface past lessons, and plan verification — **before** editing.
+
+## When to run it
+
+Any ambiguous, expensive, multi-file, or mutating task. Skip one-line, well-specified fixes.
+In Claude Code it fires automatically on every prompt (UserPromptSubmit hook); in other
+agents run the CLI yourself, or call the MCP tool `substrate_check`.
+
+## Run
+
+```bash
+forge substrate "<task>" --json     # full contract; use the fields below
+```
+
+## Act on the result
+
+1. **`okToProceed: false`** → ask the returned `assumption.questions` before editing. Do not guess.
+2. **`route.tier`** → start at that model tier (cheapest capable); escalate only after an external verifier fails.
+3. **`impact.impactedFiles`** → read these before editing a named symbol/file (the blast radius).
+4. **`scope.clusters`** → split independent groups into separate sessions; note coupled files you didn't name.
+5. **`memory.advisory`** → context, not law; tests and human corrections override it.
+6. **`verification.checklist`** → run it and show output before claiming done.
+
+## Worked example
+
+`forge substrate "make the auth better"` → `proceed: ASK FIRST` + clarify
+questions: ask them instead of editing. A clear task returns `proceed: yes` plus
+the impacted files — including importers you didn't name.
+
+## Deeper single checks
+
+`forge preflight "<task>"` (assumptions) · `forge route "<task>"` (model tier) ·
+`forge impact <symbol|file>` (blast radius) · `forge scope <file…>` (decomposition) ·
+`forge context "<task>"` (budgeted context assembly; *computes* what's missing) ·
+`forge imagine "<task>" [--run]` (predicted breaks + minimal covering test suite;
+`--run` dry-runs it in a sandboxed worktree) ·
+`forge diagnose "<error>"` (doom-loop: 3× the same failure signature = stop retrying,
+escalate one tier with the minted diagnosis claim at the head of the prompt).
+MCP equivalents: `assumption_gate`, `route_task`, `predict_impact`, `scope_files`.
+
+For the full guide (how it works, extending it, the honesty boundary) and the white paper,
+see `docs/cognitive-substrate/README.md`. `references/capability-map.md` maps faculties to commands.

package/skills/cognitive-substrate/references/capability-map.md

@@ -0,0 +1,17 @@
+# Cognitive substrate capability map
+
+| Paper capability | Forge surface | Guarantee |
+| --- | --- | --- |
+| Memory | `forge recall`, `forge cortex`, `forge ledger` | Facts/lessons persist as content-addressed ledger claims; `forge ledger blame` shows provenance. |
+| Learning | `forge cortex`, ledger oracles | External outcomes (tests, CI, human accept/revert) move claim confidence; model weights do not change. |
+| Imagination | `forge imagine [--run]`, `forge impact` | Predicted breaks + minimal covering test suite; `--run` dry-runs it in a sandboxed worktree. |
+| Self-correction | `forge verify`, `forge diagnose` | Tests/builds beat model claims; 3× the same failure signature mints a diagnosis + escalation. |
+| Impact-awareness | `forge atlas`, `forge impact` | Known symbols/files and likely dependents are surfaced. |
+| M1 routing | `forge route` | Transparent model-tier recommendation. |
+| M2 assumption gate | `forge preflight`, `forge context` | Under-specified tasks return *computed* missing-set questions. |
+| M3 decomposition | `forge scope` | Import clusters show independent vs coupled files. |
+| M4 goal anchoring | `forge anchor`, `forge substrate` | Changed files are checked against the stated goal. |
+| M5 anti-over-engineering | `forge lean`, `forge uicheck design` | Footprint vs ask; UI slop-distance + fingerprint conformance gate. |
+| M6 inline verification | `forge verify` | External checks are required before done. |
+
+Limits: static graph edges are conservative; memory relevance and model routing are advisory; non-hook tools cannot be forcibly blocked.

package/source/mcp.json

@@ -0,0 +1,10 @@
+{
+  "context7": {
+    "command": "npx",
+    "args": ["-y", "@upstash/context7-mcp@3.2.2"]
+  },
+  "forge-cortex": {
+    "command": "forge",
+    "args": ["cortex-mcp"]
+  }
+}

package/source/rules.json

@@ -0,0 +1,106 @@
+{
+  "title": "engineering rules",
+  "intro": "Shared rules for every AI coding tool in this repo. Generated into each tool's native format by `forge sync` — edit this source, not the generated files. Keep lean (tools cap the combined size).",
+  "sections": [
+    {
+      "id": "workflow",
+      "title": "Workflow",
+      "rules": [
+        "Explore -> plan -> code -> verify. For multi-file or unfamiliar changes, plan first; skip planning for one-line fixes.",
+        "Never call work done without a check you can run: tests, build exit code, lint, or a diff against expected. Show the command + output, don't just assert success.",
+        "Fix root causes, not symptoms. Never suppress an error to make a check pass."
+      ]
+    },
+    {
+      "id": "substrate",
+      "title": "Cognitive substrate (run before acting)",
+      "rules": [
+        "Before ambiguous, expensive, multi-file, or mutating work, run `forge substrate \"<task>\" --json` (or call the MCP tool `substrate_check`). In Claude Code this fires automatically on each prompt; in other tools invoke it yourself.",
+        "If it returns `okToProceed:false`, ask the returned `assumption.questions` before editing — do not guess an under-specified task.",
+        "Start at the recommended `route.tier` (cheapest capable model); escalate only after an external verifier fails, never preemptively.",
+        "Read `impact.impactedFiles` (predicted blast radius) before editing a named symbol/file, and split `scope.clusters` of independent work into separate sessions.",
+        "Treat `memory.advisory` and minimality warnings as advisory; tests, graph membership, and human corrections always override the model.",
+        "Run `verification.checklist` and show the output before claiming done."
+      ]
+    },
+    {
+      "id": "reuse",
+      "title": "Reuse & dependencies",
+      "rules": [
+        "Reuse an existing util/component/pattern before writing new; the smallest change that fits wins.",
+        "Before adding a dependency, verify the current best option from live sources (docs, GitHub health) — prefer what the project already uses.",
+        "Only build from scratch when reuse genuinely doesn't fit, and say why."
+      ]
+    },
+    {
+      "id": "code",
+      "title": "Code style",
+      "rules": [
+        "Match the surrounding file's conventions over any personal default.",
+        "Comment the non-obvious \"why\", never restate the \"what\".",
+        "Guard array/object access; wrap fallible async in try/catch; handle errors explicitly (no empty catch).",
+        "Keep functions small and single-purpose; separate pure logic from I/O so it's testable."
+      ]
+    },
+    {
+      "id": "testing",
+      "title": "Testing",
+      "rules": [
+        "Write tests with the code. For a bug fix, write the failing test first, then fix.",
+        "Cover the edge cases the task names: empty, error, boundary. Prefer real inputs over heavy mocking.",
+        "Run the suite + typecheck + lint and show the output before claiming done."
+      ]
+    },
+    {
+      "id": "security",
+      "title": "Security",
+      "rules": [
+        "Never write secrets, tokens, or keys into code or commits. `.env*` and key files are guard-protected — don't work around it.",
+        "Validate and sanitize input at trust boundaries; use parameterized queries, never string-concatenated SQL.",
+        "Check paths for traversal before file operations; prefer HTTPS for external requests."
+      ]
+    },
+    {
+      "id": "production",
+      "title": "Production standards (2026)",
+      "rules": [
+        "Validate at trust boundaries with a schema (e.g. Zod): parse untrusted input (API, env, file, LLM output) into typed values before use — never trust it raw.",
+        "Keep business logic in use-cases/domain, not controllers; hide the DB/ORM behind a repository interface; return DTOs, never raw DB models.",
+        "Check ownership/authorization on every object access (OWASP API #1 — never trust a user-supplied ID); paginate every list; make retried mutations idempotent.",
+        "Use a typed error model: typed codes, safe public messages, internal detail logged with a requestId. Never swallow errors or leak stack traces to clients.",
+        "Emit structured logs (level, message, requestId, service, durationMs); for services add metrics/traces (OpenTelemetry) and track error rate, p95 latency, and AI token cost.",
+        "Treat AI/LLM output as untrusted (OWASP LLM Top 10): verify it, never execute it directly, never put secrets/PII in prompts, give agent tools least privilege + human approval for destructive actions.",
+        "Prefer boring, typed, maintained tech; contract-first APIs (OpenAPI 3.1) with a new version for every breaking change; don't over-pattern simple code."
+      ]
+    },
+    {
+      "id": "git",
+      "title": "Git",
+      "rules": [
+        "Conventional commits: `type(scope): description` (feat, fix, refactor, docs, test, chore, perf).",
+        "Stage specific files, not `git add .`. Never force-push shared branches.",
+        "Ask before: push, commit, PR merge, history rewrite, `rm -rf`, dropping DB tables, or touching production."
+      ]
+    },
+    {
+      "id": "ui",
+      "title": "UI",
+      "rules": [
+        "Build and check mobile AND desktop. Include clear loading/empty/error states; avoid layout shift.",
+        "Follow DESIGN.md if present; keep one visual direction per project."
+      ]
+    },
+    {
+      "id": "ai-ux",
+      "title": "AI interfaces & design quality",
+      "rules": [
+        "Commit to an aesthetic before coding; avoid AI-slop defaults (Inter/Roboto/Arial/system fonts, purple-gradient-on-white, generic card grids). Pick 2–3 typefaces and a 4–6 color palette with semantic roles.",
+        "Meet WCAG: body text ≥4.5:1 contrast (large/UI ≥3:1), visible :focus-visible on every interactive element, tap targets ≥24×24px, alt text + form labels, and wrap animations ≥200ms in prefers-reduced-motion.",
+        "Empty states are never dead ends: show a plain-language message + a clear next step. Error messages name the field, explain the problem, and suggest a fix — never 'Something went wrong'.",
+        "For AI-driven UIs: show model confidence/uncertainty, make chain-of-thought and tool actions visible, give live preview/feedback over blind prompting, and provide fallback paths when the model fails.",
+        "Pick the interaction pattern deliberately — a co-editing canvas or inline controls beat a wall-of-text chatbot when the user is steering structured output.",
+        "When AI audits a UI, only ASSERT the deterministic (contrast math, missing focus ring/alt/label) — keep hierarchy/taste/pattern-fit advisory so the audit doesn't hallucinate false positives."
+      ]
+    }
+  ]
+}

package/source/substrate.json

@@ -0,0 +1,41 @@
+{
+  "version": 1,
+  "summary": "Forge cognitive substrate wraps a frozen model with deterministic pre-action gates, repo state, memory, routing, impact simulation, and verification discipline.",
+  "faculties": [
+    { "id": "memory", "forge": "recall + cortex", "status": "partial", "guarantee": "facts and lessons are persisted as auditable files; relevance is advisory" },
+    { "id": "learning", "forge": "cortex lessons", "status": "partial", "guarantee": "external outcomes update lesson confidence; no model weights are changed" },
+    { "id": "imagination", "forge": "impact graph", "status": "operational-v1", "guarantee": "reverse dependency traversal predicts possible blast radius" },
+    { "id": "self-correction", "forge": "verify + doom-loop guard", "status": "partial", "guarantee": "tests/builds are trusted over model claims" },
+    { "id": "impact-awareness", "forge": "atlas + impact", "status": "operational-v1", "guarantee": "known symbols/files and likely dependents are surfaced before edits" }
+  ],
+  "mechanisms": [
+    { "id": "M1", "name": "complexity-aware routing", "command": "forge route", "status": "solved-with-transparency-layer" },
+    { "id": "M2", "name": "assumption gate", "command": "forge preflight", "status": "operational-v1" },
+    { "id": "M3", "name": "task/session decomposition", "command": "forge scope", "status": "solved-with-boundary-helper" },
+    { "id": "M4", "name": "goal anchoring", "command": "forge substrate", "status": "partial" },
+    { "id": "M5", "name": "scope minimality", "command": "forge substrate", "status": "operational-v1-advisory" },
+    { "id": "M6", "name": "inline verification", "command": "forge verify", "status": "partial" }
+  ],
+  "defaults": { "askThreshold": 0.6, "impactThreshold": 0.1 },
+  "llm": {
+    "enabled": false,
+    "model": "haiku",
+    "timeoutMs": 20000,
+    "bidirectional": true,
+    "band": 0.25,
+    "routingBand": 0.2,
+    "signalFloor": 0.4,
+    "note": "Opt-in (FORGE_LLM=1). The model PROPOSES; the deterministic rubric + repo grounding + tests VERIFY. Any failure falls back to the deterministic path — never blind, never blocking. `bidirectional` (default true) lets a verified reading also clear a false ask / route a tier down, within `band`/`routingBand` and never past the hard floors (`signalFloor`, repo grounding, no-anchor). Set false for the conservative tighten/raise-only mode."
+  },
+  "policies": {
+    "preAction": "Run substrate before ambiguous, expensive, multi-file, or mutating work.",
+    "escalation": "Start with the cheapest capable tier and escalate only after an external verifier failure.",
+    "hookEnforcement": "Block or warn only on deterministic risks; keep research-edge judgments advisory.",
+    "honesty": "Label memory relevance, routing fit, and minimality as advisory unless verified by tests, graph membership, or explicit user scope."
+  },
+  "limits": [
+    "Graph edges are static and conservative; dynamic dispatch and generated code may be missed.",
+    "Memory and learning are external file-backed lessons, not weight-level learning.",
+    "Non-hook editors receive advisory MCP/context only; Forge cannot enforce hooks where the host has no hook surface."
+  ]
+}

package/src/adjudicate.js

@@ -0,0 +1,84 @@
+// forge adjudicate — the substrate's ONE shared "LLM proposes, checks verify" primitive.
+// The whitepaper's load-bearing rule (Panickssery et al. C12; tabayyun, 49:6) is that a
+// model is never its own judge: it may PROPOSE, but an external check arbitrates. This module
+// supplies only the proposer half — a cheap, opt-in, fail-safe model call — while each faculty
+// keeps its deterministic rubric as the judge and reconciles the two (verify, don't trust).
+//
+// Design contract (identical to src/cortex_distill.js, generalized so all faculties share it):
+//   - OPT-IN. Off by default (FORGE_LLM!=1) → callers keep their deterministic result and this
+//     module is never invoked. Behavior is byte-identical to the pre-LLM substrate.
+//   - FAIL-SAFE. Any error/timeout/garble/secret → returns null. A null NEVER changes a verdict.
+//   - ZERO-DEP. Access is a `claude -p` CLI shell-out; the runner is injectable so the pure
+//     prompt/parse/verify logic is fully testable without the CLI or the network.
+import { execFileSync } from "node:child_process";
+import { SECRET_RE } from "./recall.js";
+
+/**
+ * Is the LLM proposer layer active for this call? Explicit opt-in wins; env is the default.
+ * @param {{llm?:boolean}} [opts]
+ */
+export function llmEnabled(opts = {}) {
+  if (typeof opts.llm === "boolean") return opts.llm;
+  return process.env.FORGE_LLM === "1";
+}
+
+/** Build an injectable `claude -p` runner. Pure config in, a (prompt)->string runner out. */
+export function buildRunner({ model = "haiku", timeoutMs = 20000 } = {}) {
+  return (prompt) =>
+    execFileSync("claude", ["-p", "--model", model], {
+      input: prompt,
+      encoding: "utf8",
+      timeout: timeoutMs,
+      stdio: ["pipe", "pipe", "ignore"],
+    });
+}
+
+/** Extract the first balanced-ish JSON object from model output, or null. */
+export function extractJson(text) {
+  if (!text) return null;
+  const match = String(text).match(/\{[\s\S]*\}/);
+  if (!match) return null;
+  try {
+    return JSON.parse(match[0]);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Run one adjudication: send `prompt`, parse+validate the reply, refuse secrets both ways.
+ * The proposer half only — the caller must still verify the returned value against ground truth.
+ * @template T
+ * @param {{prompt:string, parse:(obj:any)=>(T|null), run?:(p:string)=>string}} spec
+ * @returns {T|null} the validated proposal, or null on ANY failure (caller keeps deterministic).
+ */
+export function adjudicate({ prompt, parse, run = buildRunner() }) {
+  try {
+    if (SECRET_RE.test(String(prompt))) return null; // never send a secret to the model
+    const raw = run(prompt);
+    if (SECRET_RE.test(String(raw))) return null; // never trust a reply that leaked one back
+    const obj = extractJson(raw);
+    if (obj == null) return null;
+    const parsed = parse(obj);
+    return parsed ?? null;
+  } catch (err) {
+    if (process.env.FORGE_DEBUG === "1")
+      process.stderr.write(`forge adjudicate: ${err?.message ?? err}\n`);
+    return null;
+  }
+}
+
+import { clamp01 } from "./util.js";
+
+/** Coerce an unknown model field to a number in [0,1], or null if it isn't one. */
+export function asUnit(v) {
+  const n = typeof v === "number" ? v : Number(v);
+  return Number.isFinite(n) ? clamp01(n) : null;
+}
+
+/** Coerce an unknown model field to a trimmed, length-capped string (empty → ""). */
+export function asText(v, cap = 200) {
+  return String(v ?? "")
+    .trim()
+    .slice(0, cap);
+}