@codewithjuber/forgekit 0.8.0

package/src/route.js

@@ -0,0 +1,323 @@
+// forge route — complexity-based model routing. Generic routers score prompt difficulty;
+// this scores CODE-TASK complexity from signals Forge already computes (files in scope, impact
+// fan-out, churn/fragility, past-mistake density here, ambiguity, task size) → cheapest capable
+// tier. Advisory by default; a LiteLLM config emit exposes the tiers as gateway aliases you request.
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { adjudicate, asText, buildRunner, llmEnabled } from "./adjudicate.js";
+import { matchingLessons } from "./cortex.js";
+import { gitChurn, grepFanout } from "./cortex_features.js";
+import { recordRoute } from "./cost_report.js";
+import { mergedLessons } from "./ledger_read.js";
+import { MODELS } from "./model_tiers.js";
+import { preflightRepo, referencedEntities } from "./preflight.js";
+import { activeProvider } from "./providers.js";
+import { clamp01, contentHash, epochDay } from "./util.js";
+
+// Weights sum to 1. Each raw signal is normalized by the point where it reads as "complex".
+
+const ALGO_TERMS =
+  /\b(recursion|recursive|recursive-?descent|dynamic programming|dijkstra|a\*|concurren|thread-?safe|mutex|race condition|deadlock|distributed|consensus|parser|compiler|cryptograph|np-hard|state machine|invariant|numerical stability|back-?pressure|token[- ]bucket|rate limiter|idempoten|migration|producer|consumer|blocking queue|condition[- ]variable)\b/i;
+const ARCH_TERMS =
+  /\b(architect|\bdesign\b|trade-?off|refactor a|migrate|scal(e|able|ing)|schema (migration|design)|api design|multi-?module|cross-?module|end-?to-?end|consistency (guarantee|trade)|locking strategy|module boundaries)\b/i;
+const MODERATE_TERMS =
+  /\b(class\b|cache|lru|queue|stack|heap|linked list|binary tree|tree|traversal|graph|decorator|regex|debounce|throttle|merge|sort(ed|ing)?|parse|o\(\s*\d|o\(n|o\(1|thread|async|lock|validate|in-?order|adjacency)\b/i;
+const TRIVIAL_TERMS =
+  /\b(hello world|rename|typo|indent|add a comment|reverse a string|reverse the string|is[_ ]?even|is[_ ]?odd|factorial|fibonacci|is[_ ]?prime|prime\b|sum of|sum_list|capitalize|count vowels|celsius|fahrenheit|lower ?case|upper ?case)\b/i;
+const MULTISTEP =
+  /\b(and then|after that|first.*then|step \d|multiple|several|each of|for every)\b/i;
+
+export function rubricSignals(task = "") {
+  const text = String(task);
+  return {
+    lengthTokens: Math.max(1, Math.floor(text.length / 4)),
+    hasAlgorithmicTerms: ALGO_TERMS.test(text),
+    hasArchitecturalTerms: ARCH_TERMS.test(text),
+    hasModerateTerms: MODERATE_TERMS.test(text),
+    hasTrivialMarkers: TRIVIAL_TERMS.test(text),
+    hasMultistep: MULTISTEP.test(text),
+    hasCodeContext: /```/.test(text),
+    nConstraints: (text.match(/(^\s*[-*\d.]|\b(must|should|ensure|require|constraint)\b)/gim) || [])
+      .length,
+  };
+}
+
+export function rubricComplexity(task = "") {
+  const sig = rubricSignals(task);
+  const reasons = [{ weight: 1.5, reason: "base cost of any task" }];
+  let score = 1.5;
+  if (sig.hasAlgorithmicTerms) {
+    score += 4;
+    reasons.push({ weight: 4, reason: "algorithmic/systems difficulty" });
+  }
+  if (sig.hasArchitecturalTerms) {
+    score += 4;
+    reasons.push({ weight: 4, reason: "architectural/design scope" });
+  }
+  if (sig.hasModerateTerms) {
+    score += 2;
+    reasons.push({ weight: 2, reason: "data-structure/class/library-level work" });
+  }
+  if (sig.hasMultistep) {
+    score += 1;
+    reasons.push({ weight: 1, reason: "multi-step request" });
+  }
+  if (sig.hasCodeContext) {
+    score += 1;
+    reasons.push({ weight: 1, reason: "carries code context" });
+  }
+  if (sig.lengthTokens > 120) {
+    score += 1.5;
+    reasons.push({ weight: 1.5, reason: `long spec (~${sig.lengthTokens} tok)` });
+  } else if (sig.lengthTokens > 55) {
+    score += 0.7;
+    reasons.push({ weight: 0.7, reason: `medium spec (~${sig.lengthTokens} tok)` });
+  }
+  if (sig.nConstraints >= 5) {
+    score += 1;
+    reasons.push({ weight: 1, reason: `${sig.nConstraints} explicit constraints` });
+  }
+  if (sig.hasTrivialMarkers && !sig.hasAlgorithmicTerms && !sig.hasArchitecturalTerms) {
+    score -= 3;
+    reasons.push({ weight: -3, reason: "trivial-task marker" });
+  }
+  const rawScore = Math.max(0, score);
+  const band = rawScore < 3 ? "cheap" : rawScore <= 6 ? "mid" : "premium";
+  return { rawScore, band, signals: sig, reasons };
+}
+
+const WEIGHTS = {
+  files: 0.22,
+  fanout: 0.22,
+  churn: 0.12,
+  mistakes: 0.18,
+  ambiguity: 0.12,
+  size: 0.14,
+};
+
+/**
+ * Pure: raw task signals → complexity in [0,1].
+ * @param {{files?:number, fanout?:number, churn?:number, pastMistakes?:number, ambiguity?:number, sizeWords?:number}} s
+ */
+export function complexity(s = {}) {
+  const norm = {
+    files: clamp01((s.files ?? 0) / 5), // >5 files touched = complex
+    fanout: clamp01((s.fanout ?? 0) / 15), // >15 call sites = complex
+    churn: clamp01((s.churn ?? 0) / 12), // fragile, frequently-changed area
+    mistakes: clamp01((s.pastMistakes ?? 0) / 3), // repeated pain here
+    ambiguity: clamp01(s.ambiguity ?? 0), // already 0..1 (from preflight)
+    size: clamp01((s.sizeWords ?? 0) / 60), // long ask = more moving parts
+  };
+  let score = 0;
+  for (const k of Object.keys(WEIGHTS)) score += WEIGHTS[k] * norm[k];
+  return { score: clamp01(score), norm };
+}
+
+/** Pure: score → recommended model + the reasons that drove it. */
+export function recommend(score, norm = {}) {
+  const key = score < 0.25 ? "haiku" : score < 0.55 ? "sonnet" : score < 0.8 ? "opus" : "fable";
+  const reasons = Object.entries(norm)
+    .filter(([, v]) => v >= 0.5)
+    .map(([k]) => k)
+    .sort();
+  return { key, model: MODELS[key], tier: MODELS[key].tier, reasons };
+}
+
+// M1 routing — LLM proposer. Estimates task complexity c(x) as a coarse band. PROPOSER ONLY:
+// the reconcile in routeTask() lets a RAISE through freely but bounds any LOWER (within one band
+// and never below a strong-signal floor), so the model can escalate on hidden complexity yet can
+// never under-provision a genuinely hard task; escalation still gates on a verified failure.
+const BAND_FLOOR = { cheap: 0.15, mid: 0.4, premium: 0.65 };
+
+export function buildComplexityPrompt(task) {
+  return `Judge the intrinsic complexity of this coding task for model selection (not how to do it).
+Task: """${String(task).slice(0, 1200)}"""
+Answer with STRICT JSON and nothing else:
+{"band":"cheap|mid|premium","reason":"<short why>"}
+cheap = trivial/boilerplate; mid = a data structure, class, or library-level change; premium =
+algorithmic/systems/architectural/multi-module work. No text outside the JSON object.`;
+}
+
+export function parseComplexityProposal(obj) {
+  const band = String(obj.band ?? "")
+    .trim()
+    .toLowerCase();
+  if (!(band in BAND_FLOOR)) return null;
+  return { band, score: BAND_FLOOR[band], reason: asText(obj.reason) };
+}
+
+/** Ask the model for a complexity band (proposer). Returns null when off/unavailable. */
+export function complexityLLM(task, { run = buildRunner() } = {}) {
+  return adjudicate({ prompt: buildComplexityPrompt(task), parse: parseComplexityProposal, run });
+}
+
+/**
+ * Repo wrapper: gather the real signals for a task and route it. `run` is injectable for tests.
+ * @param {string} root
+ * @param {string} task
+ * @param {object} [opts]
+ * @param {boolean} [opts.llm]
+ * @param {string} [opts.model]
+ * @param {number} [opts.timeoutMs]
+ * @param {(p:string)=>string} [opts.run]
+ * @param {boolean} [opts.bidirectional]
+ * @param {number} [opts.routingBand]
+ * @param {number} [opts.signalFloor]
+ * @param {number} [opts.ambiguity] precomputed information-gap (skips a duplicate preflight pass)
+ */
+export function routeTask(
+  root,
+  task,
+  {
+    llm,
+    model,
+    timeoutMs,
+    run,
+    bidirectional = true,
+    routingBand = 0.2,
+    signalFloor = 0.4,
+    ambiguity,
+  } = {},
+) {
+  const { symbols, files } = referencedEntities(task);
+  const fanout = symbols.reduce((m, sym) => Math.max(m, grepFanout(root, sym)), 0);
+  const churn = files.reduce((m, f) => Math.max(m, gitChurn(root, f)), 0);
+  // Merged view (P2 read flip): teammate lessons raise past-mistake density here too.
+  const pastMistakes = matchingLessons(mergedLessons(root, epochDay()), {
+    files,
+    symbols,
+  }).length;
+  // The routing signal only needs the DETERMINISTIC gap. Accept a precomputed one (substrate
+  // already has it) and, when computing our own, force llm:false — the gap never depends on the
+  // model, so an LLM assumption call here would be pure wasted latency.
+  const ambiguityScore =
+    typeof ambiguity === "number"
+      ? ambiguity
+      : preflightRepo(root, task, { allowBuild: false, llm: false }).gap;
+  const sizeWords = task.trim().split(/\s+/).filter(Boolean).length;
+  const signals = {
+    files: files.length,
+    fanout,
+    churn,
+    pastMistakes,
+    ambiguity: ambiguityScore,
+    sizeWords,
+  };
+  const { score: repoScore, norm } = complexity(signals);
+  const rubric = rubricComplexity(task);
+  const rubricScore = Math.min(1, rubric.rawScore / 10);
+  const detScore = Math.max(repoScore, rubricScore);
+  // M1 proposer (opt-in): the model PROPOSES a complexity band. A RAISE is free (spotting hidden
+  // complexity costs at most a bigger model). A LOWER is bounded — never more than one `band`
+  // below the rubric, and never below `signalFloor` when the rubric detected algorithmic or
+  // architectural terms, so a "distributed rate-limiter" can't be talked down to the cheap tier.
+  // With `bidirectional:false` it stays raise-only. Fail-safe: a null proposal is ignored.
+  const proposal = llmEnabled({ llm })
+    ? complexityLLM(task, { run: run || buildRunner({ model, timeoutMs }) })
+    : null;
+  const strongSignal = rubric.signals.hasAlgorithmicTerms || rubric.signals.hasArchitecturalTerms;
+  let score = detScore;
+  let path = proposal ? "llm-agreed" : "deterministic";
+  if (proposal) {
+    if (proposal.score > detScore) {
+      score = proposal.score; // free raise
+      path = "llm-raised";
+    } else if (bidirectional && proposal.score < detScore) {
+      const floor = Math.max(detScore - routingBand, strongSignal ? signalFloor : 0);
+      const lowered = Math.max(floor, proposal.score);
+      if (lowered < detScore) {
+        score = lowered; // bounded lower
+        path = "llm-lowered";
+      }
+    }
+  }
+  const recommended = recommend(score, norm);
+  return {
+    score,
+    repoScore,
+    signals,
+    rubric,
+    llm: proposal
+      ? { band: proposal.band, reason: proposal.reason, direction: path.replace("llm-", "") }
+      : null,
+    provenance: { path },
+    ...recommended,
+    reasons: [
+      ...new Set([
+        ...(recommended.reasons || []),
+        ...rubric.reasons.filter((r) => r.weight > 0).map((r) => r.reason),
+        ...(path === "llm-raised" || path === "llm-lowered"
+          ? [`model judged ${proposal.band} (${path.replace("llm-", "")}): ${proposal.reason}`]
+          : []),
+      ]),
+    ],
+  };
+}
+
+/**
+ * Best-effort route-stage metering (05-cost-model.md) for EXPLICIT callers only — the
+ * `forge route` CLI and the explicit substrate gate call this AFTER a routing decision.
+ * Deliberately NOT called from routeTask itself: ambient hooks route on every prompt
+ * and must stay write-free, same rule as recordGate in substrate.js. One metrics line:
+ * the chosen tier + a short task hash as the ref (never the task text — metrics are
+ * telemetry, not a prompt log). No token counts here — this is an advisory routing
+ * decision, not a priced generation, and the cost report excludes unpriced events
+ * rather than estimating them.
+ * @param {string} root
+ * @param {string} task
+ * @param {{tier?: string}} rec the routeTask result (only .tier is read)
+ */
+export function meterRoute(root, task, rec) {
+  try {
+    recordRoute(root, { tier: rec?.tier, ref: contentHash(String(task)).slice(0, 12) });
+  } catch {}
+}
+
+/** Emit a LiteLLM config exposing the complexity tiers as aliases (request the one `forge route` picks).
+ *  Provider-aware: uses the active provider's model IDs for the passthrough entries
+ *  and the correct LiteLLM model prefix (anthropic/ for direct, openrouter/ for OR).
+ *  Returns `{ ok: false, reason }` for hosted gateways the user cannot configure. */
+export function emitGatewayConfig(root = process.cwd()) {
+  const prov = activeProvider(root);
+  if (prov._autoDetected && prov._source === "LITELLM_BASE_URL") {
+    return {
+      ok: false,
+      reason:
+        `Hosted LiteLLM gateway detected at ${prov.baseUrl}. ` +
+        `No local config needed — requests go directly to the hosted gateway. ` +
+        `Use standard model names (the gateway handles routing).`,
+    };
+  }
+  const prefix = prov.type === "openrouter" ? "openrouter/" : "anthropic/";
+  const path = join(root, "litellm.config.yaml");
+  const body = `# Forge Preflight — LiteLLM routing config (complexity tier -> model).
+# HOW ROUTING WORKS: LiteLLM routes by the REQUESTED model name; it cannot infer task
+# complexity on its own. So 'forge route' tells you the tier, and your tool REQUESTS the
+# matching alias (forge-simple/medium/complex). A normal claude-* request passes through
+# unchanged — pointing ANTHROPIC_BASE_URL here never breaks existing traffic.
+#   pip install "litellm[proxy]==<pin an exact verified version>"   # supply-chain: pin exact, no floating tag
+#   litellm --config litellm.config.yaml       # then export ANTHROPIC_BASE_URL=http://localhost:4000
+# Provider: ${prov.label || prov.name} (${prov.type})
+# Models verified 2026-07-05; re-verify via dev-radar.
+model_list:
+  # Tier aliases — request one of these (per 'forge route') to pick a model by complexity.
+  - model_name: forge-simple   # ${MODELS.haiku.name} — ${MODELS.haiku.use}
+    litellm_params: { model: ${prefix}${MODELS.haiku.id} }
+  - model_name: forge-medium   # ${MODELS.sonnet.name} — default
+    litellm_params: { model: ${prefix}${MODELS.sonnet.id} }
+  - model_name: forge-complex  # ${MODELS.opus.name}
+    litellm_params: { model: ${prefix}${MODELS.opus.id} }
+  # Passthrough — a normal claude-* request still works when pointed at the gateway.
+  - model_name: ${MODELS.haiku.id}
+    litellm_params: { model: ${prefix}${MODELS.haiku.id} }
+  - model_name: ${MODELS.sonnet.id}
+    litellm_params: { model: ${prefix}${MODELS.sonnet.id} }
+  - model_name: ${MODELS.opus.id}
+    litellm_params: { model: ${prefix}${MODELS.opus.id} }
+${prov.envKey ? `litellm_settings:\n  drop_params: true\n  set_verbose: false` : ""}
+router_settings:
+  routing_strategy: simple-shuffle
+`;
+  writeFileSync(path, body);
+  return path;
+}

package/src/scope.js

@@ -0,0 +1,122 @@
+// forge scope — deterministic task decomposition. Build a cheap import graph (no LLM), find
+// connected components, and tell the developer which touched files are INDEPENDENT (→ run in
+// separate sessions, so the context window isn't polluted) vs. COUPLED — and which coupled
+// files they didn't mention (the "forgot the related module" guard). Regex imports are
+// approximate (dynamic/DI edges missed) — a real call-graph MCP is the upgrade seam.
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { IGNORE_DIRS, SRC_EXT } from "./util.js";
+
+const IMPORT_RES = [
+  /import\s+[^'"]*from\s+['"]([^'"]+)['"]/g, // import x from "y"
+  /import\s+['"]([^'"]+)['"]/g, // import "y"
+  /require\(\s*['"]([^'"]+)['"]\s*\)/g, // require("y")
+  /export\s+[^'"]*from\s+['"]([^'"]+)['"]/g, // export … from "y"
+  /import\(\s*['"]([^'"]+)['"]\s*\)/g, // dynamic import("y")
+  /^\s*from\s+(\.[.\w/]*)\s+import/gm, // python: from .y import
+];
+
+function walk(dir, root, out) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (IGNORE_DIRS.has(entry.name)) continue;
+    const p = join(dir, entry.name);
+    if (entry.isDirectory()) walk(p, root, out);
+    else if (SRC_EXT.test(entry.name)) out.push(relative(root, p));
+  }
+}
+
+function resolveSpec(fromRel, spec, root, fileSet) {
+  if (!spec.startsWith(".")) return null; // external / stdlib — not a local edge
+  const raw = resolve(root, dirname(fromRel), spec);
+  const cands = [
+    raw,
+    ...[".js", ".ts", ".tsx", ".jsx", ".mjs", ".cjs", ".py"].map((ext) => raw + ext),
+    ...["index.js", "index.ts"].map((idx) => join(raw, idx)),
+  ];
+  for (const c of cands) {
+    const rel = relative(root, c);
+    if (fileSet.has(rel)) return rel;
+  }
+  return null;
+}
+
+/** Build an UNDIRECTED file→file import graph (coupling is symmetric for decomposition). */
+export function importGraph(root) {
+  const files = [];
+  walk(root, root, files);
+  const fileSet = new Set(files);
+  const edges = new Map(files.map((f) => [f, new Set()]));
+  for (const f of files) {
+    let text = "";
+    try {
+      text = readFileSync(join(root, f), "utf8");
+    } catch {
+      continue;
+    }
+    for (const re of IMPORT_RES) {
+      for (const m of text.matchAll(re)) {
+        const target = resolveSpec(f, m[1], root, fileSet);
+        if (target && target !== f) {
+          edges.get(f).add(target);
+          edges.get(target)?.add(f);
+        }
+      }
+    }
+  }
+  return { nodes: files, edges };
+}
+
+/** Connected components (iterative DFS). Each = a set of mutually-coupled files. */
+export function components(graph) {
+  const seen = new Set();
+  const comps = [];
+  for (const start of graph.nodes) {
+    if (seen.has(start)) continue;
+    const stack = [start];
+    const comp = [];
+    seen.add(start);
+    while (stack.length) {
+      const cur = stack.pop();
+      comp.push(cur);
+      for (const nb of graph.edges.get(cur) ?? []) {
+        if (!seen.has(nb)) {
+          seen.add(nb);
+          stack.push(nb);
+        }
+      }
+    }
+    comps.push(comp);
+  }
+  return comps;
+}
+
+/**
+ * Decompose a set of touched files into independent clusters + the coupled files not mentioned.
+ * @returns {{clusters:{touched:string[], coupled:string[]}[], independentGroups:number}}
+ */
+export function decompose(root, touched) {
+  // Normalize to repo-relative (the graph's key form) so `./src/a.js` or an absolute path
+  // still matches — otherwise a coupled file is missed and reported as an independent solo.
+  const norm = touched.map((t) => relative(root, resolve(root, t)));
+  const normSet = new Set(norm);
+  const comps = components(importGraph(root));
+  const compOf = new Map();
+  comps.forEach((comp, i) => {
+    for (const f of comp) compOf.set(f, i);
+  });
+  const buckets = new Map();
+  let singleton = 0;
+  for (const t of norm) {
+    const id = compOf.has(t) ? compOf.get(t) : `solo:${singleton++}`;
+    if (!buckets.has(id)) buckets.set(id, { touched: [], coupled: new Set() });
+    buckets.get(id).touched.push(t);
+    if (typeof id === "number") {
+      for (const f of comps[id]) if (!normSet.has(f)) buckets.get(id).coupled.add(f);
+    }
+  }
+  const clusters = [...buckets.values()].map((b) => ({
+    touched: b.touched,
+    coupled: [...b.coupled],
+  }));
+  return { clusters, independentGroups: clusters.length };
+}

package/src/skillgate.js

@@ -0,0 +1,89 @@
+// forge skill-gate — vet a skill / MCP config BEFORE it's installed. ToxicSkills
+// found ~36% of skills flawed / 13.4% critical, ~60% of the risk in the instruction
+// (markdown) layer — so string prose matters as much as code. Prefer a real scanner
+// (Snyk agent-scan) when present; otherwise a built-in heuristic catches the loud cases.
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+
+// Instruction-layer + tool-layer red flags. `critical` blocks install.
+const RULES = [
+  {
+    re: /\bcurl\b[^\n|]*\|\s*(sh|bash|zsh)\b/i,
+    sev: "critical",
+    msg: "pipes curl to a shell (remote code execution)",
+  },
+  {
+    re: /\bwget\b[^\n|]*\|\s*(sh|bash|zsh)\b/i,
+    sev: "critical",
+    msg: "pipes wget to a shell (remote code execution)",
+  },
+  {
+    re: /base64\s+(--decode|-d|-D)\b[^\n]*\|\s*(sh|bash)/i,
+    sev: "critical",
+    msg: "decodes and executes an obfuscated payload",
+  },
+  {
+    re: /ignore\s+(all\s+)?(your\s+)?previous\s+instructions|disregard\s+(your|the|all)\s+(system|previous|prior)/i,
+    sev: "critical",
+    msg: "prompt-injection phrasing in the instruction layer",
+  },
+  {
+    re: /(id_rsa|id_ed25519|\.aws\/credentials|\.claude\.json|\.env)\b[^\n]{0,80}\b(curl|wget|nc|https?:\/\/|base64|>\s*\/dev\/tcp)/i,
+    sev: "critical",
+    msg: "reads a credential file near a network/exfil call",
+  },
+  {
+    re: /\brm\s+-rf\s+[~/]/i,
+    sev: "high",
+    msg: "destructive recursive delete of an absolute/home path",
+  },
+  {
+    re: /\beval\s*\(\s*(await\s+)?fetch|child_process|\bexec(Sync)?\s*\(/i,
+    sev: "high",
+    msg: "dynamic code execution / process spawn",
+  },
+];
+
+/** Pure: scan raw text for red flags. Returns findings [{sev, msg}]. */
+export function heuristicScan(text) {
+  const s = String(text);
+  return RULES.filter((r) => r.re.test(s)).map(({ sev, msg }) => ({
+    sev,
+    msg,
+  }));
+}
+
+/** Scan a path (SKILL.md/.mcp.json) or raw text. Real scanner if available, else heuristic. */
+export function scan(target) {
+  const isPath = typeof target === "string" && existsSync(target);
+  const content = isPath ? readFileSync(target, "utf8") : String(target);
+
+  if (isPath && process.env.FORGE_SKILLGATE_NOEXTERNAL !== "1") {
+    try {
+      // Pinned (verified 2026-07-05) — never @latest for code we execute; re-verify via dev-radar.
+      const out = execFileSync("uvx", ["snyk-agent-scan==0.5.12", target], {
+        encoding: "utf8",
+        stdio: "pipe",
+        timeout: 90000,
+      });
+      const critical = /\bcritical\b|tool poisoning|prompt injection|malicious/i.test(out);
+      return {
+        ok: !critical,
+        critical,
+        scanner: "snyk-agent-scan",
+        findings: [],
+        raw: out,
+      };
+    } catch (err) {
+      if (process.env.FORGE_DEBUG === "1")
+        process.stderr.write(
+          `forge skillgate: scanner failed, using heuristic: ${err?.message ?? err}\n`,
+        );
+    }
+  }
+
+  const findings = heuristicScan(content);
+  const critical = findings.some((f) => f.sev === "critical");
+  return { ok: !critical, critical, scanner: "heuristic", findings };
+}

package/src/speclock.js

@@ -0,0 +1,64 @@
+// forge spec-lock — cheap spec-as-contract drift detection. It does NOT rebuild a
+// spec framework (OpenSpec / Spec Kit do that); it snapshots which code symbols each
+// spec CLAIMS (via the atlas index) and later flags a spec that still claims a symbol
+// the code no longer defines — i.e. the code moved on and the spec didn't.
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { build as buildAtlas, has } from "./atlas.js";
+import { hashContent } from "./emit/_shared.js";
+
+const SPEC_DIRS = ["specs", "openspec/changes", "openspec/specs", ".kiro/steering"];
+
+function walk(dir, files) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, entry.name);
+    if (entry.isDirectory()) walk(p, files);
+    else if (entry.name.endsWith(".md")) files.push(p);
+  }
+}
+
+function specFiles(root) {
+  const files = [];
+  for (const d of SPEC_DIRS) {
+    const dir = join(root, d);
+    if (existsSync(dir)) walk(dir, files);
+  }
+  return files;
+}
+
+/** Pure: code-identifier tokens a spec references — `backtick` tokens, 3+ chars. */
+export function referencedSymbols(text) {
+  const out = new Set();
+  for (const m of String(text).matchAll(/`([A-Za-z_$][\w$]{2,})`/g)) out.add(m[1]);
+  return [...out];
+}
+
+/** Record, per spec, the symbols it references that currently EXIST in the code. */
+export function snapshot(root = process.cwd()) {
+  const atlas = buildAtlas({ root });
+  const specs = {};
+  for (const f of specFiles(root)) {
+    const text = readFileSync(f, "utf8");
+    const claimed = referencedSymbols(text).filter((s) => has(atlas, s));
+    specs[relative(root, f)] = { hash: hashContent(text), claimed };
+  }
+  mkdirSync(join(root, ".forge"), { recursive: true });
+  writeFileSync(join(root, ".forge", "spec-lock.json"), JSON.stringify(specs, null, 2));
+  return { specs, count: Object.keys(specs).length };
+}
+
+/** Flag specs that still claim a symbol the code no longer defines (drift). */
+export function check(root = process.cwd()) {
+  const lockPath = join(root, ".forge", "spec-lock.json");
+  if (!existsSync(lockPath))
+    return { ok: true, drift: [], note: "no lock — run `forge spec lock`" };
+  const lock = JSON.parse(readFileSync(lockPath, "utf8"));
+  const atlas = buildAtlas({ root });
+  const drift = [];
+  for (const [spec, entry] of Object.entries(lock)) {
+    for (const sym of entry.claimed || []) {
+      if (!has(atlas, sym)) drift.push({ spec, symbol: sym });
+    }
+  }
+  return { ok: drift.length === 0, drift };
+}