@codewithjuber/forgekit 0.8.0

package/src/extract.js

@@ -0,0 +1,82 @@
+// forge extract — the ONE call-site extractor, shared so atlas.js and verify.js can't drift.
+// `CALL_RE` matches a called identifier while skipping `.method(` member calls; `CALL_IGNORE` is
+// the language/runtime builtins that are never project symbols. Kept dependency-free and pure.
+
+export const CALL_RE = /(?:^|[^.\w$])([A-Za-z_$][\w$]*)\s*\(/g;
+
+// Builtins/keywords that look like calls but are never a project-defined symbol. Superset of the
+// two sets atlas.js and verify.js used to keep separately (so neither under-ignores).
+export const CALL_IGNORE = new Set([
+  "if",
+  "for",
+  "while",
+  "switch",
+  "catch",
+  "function",
+  "return",
+  "typeof",
+  "await",
+  "new",
+  "delete",
+  "void",
+  "yield",
+  "import",
+  "export",
+  "require",
+  "super",
+  "console",
+  "Math",
+  "JSON",
+  "Object",
+  "Array",
+  "String",
+  "Number",
+  "Boolean",
+  "Promise",
+  "Set",
+  "Map",
+  "WeakMap",
+  "Date",
+  "Error",
+  "RegExp",
+  "Symbol",
+  "Buffer",
+  "parseInt",
+  "parseFloat",
+  "isNaN",
+  "isFinite",
+  "setTimeout",
+  "setInterval",
+  "clearTimeout",
+  "clearInterval",
+  "fetch",
+  "structuredClone",
+  "process",
+  "assert",
+  // Python-ish builtins seen in mixed repos
+  "print",
+  "range",
+  "len",
+  "int",
+  "str",
+  "float",
+  "dict",
+  "list",
+  "set",
+  "tuple",
+  "bool",
+]);
+
+/** Pure: the called identifiers in a block of source (member calls `.foo(` are skipped). */
+export function extractCalledSymbols(text, ignore = CALL_IGNORE) {
+  const found = new Set();
+  for (const line of String(text).split("\n")) {
+    CALL_RE.lastIndex = 0;
+    let m;
+    while ((m = CALL_RE.exec(line))) {
+      const name = m[1];
+      if (!ignore.has(name)) found.add(name);
+    }
+  }
+  return [...found];
+}

package/src/harden.js

@@ -0,0 +1,44 @@
+// forge harden — WIRE the mature security controls Anthropic/the community already
+// own: enable the Claude Code sandbox (84% fewer prompts, per Anthropic) and install
+// a Gitleaks pre-commit hook. We never auto-edit ~/.claude/settings.json (no clobber)
+// — we write the sandbox block for the user to merge, and only touch the repo's own hooks.
+
+import { chmodSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { hasBin as have } from "./util.js";
+
+// The sandbox config to merge into settings — deny the credential dirs an agent should never read.
+const SANDBOX = {
+  sandbox: { enabled: true, allowUnsandboxedCommands: false },
+  credentials: { deny: ["~/.aws", "~/.ssh", "GITHUB_TOKEN", "NPM_TOKEN"] },
+};
+
+export function harden({ targetRoot = process.cwd() } = {}) {
+  const report = {};
+
+  // Gitleaks pre-commit (WIRE) — only in a git repo, only if gitleaks is installed.
+  if (!existsSync(join(targetRoot, ".git"))) {
+    report.gitleaks = "not a git repo — skipped";
+  } else if (!have("gitleaks")) {
+    report.gitleaks = "gitleaks not installed — `brew install gitleaks` then re-run";
+  } else {
+    const hooks = join(targetRoot, ".git", "hooks");
+    mkdirSync(hooks, { recursive: true });
+    writeFileSync(
+      join(hooks, "pre-commit"),
+      "#!/usr/bin/env bash\n# installed by forge harden\nexec gitleaks protect --staged --redact -v\n",
+    );
+    try {
+      chmodSync(join(hooks, "pre-commit"), 0o755);
+    } catch {
+      /* best effort */
+    }
+    report.gitleaks = "installed pre-commit";
+  }
+
+  // Sandbox settings (WIRE — Anthropic owns the sandbox; we write the block to merge).
+  mkdirSync(join(targetRoot, ".forge"), { recursive: true });
+  writeFileSync(join(targetRoot, ".forge", "sandbox.json"), JSON.stringify(SANDBOX, null, 2));
+  report.sandbox = "written to .forge/sandbox.json";
+  return report;
+}

package/src/imagine.js

@@ -0,0 +1,301 @@
+// forge imagine — the consequence simulator ĉ = g(a, C) (paper Eq. 4;
+// docs/plans/substrate-v2/06-faculties-and-mechanisms.md §2). The atlas gives the
+// exact-structure half: entities → blast radius → predicted breaks with confidence.
+// This module adds impacted-test SELECTION — the minimal dry-run suite that makes
+// pre-action simulation affordable at all (minutes → seconds vs "run everything") —
+// and the sandboxed worktree runner (spec §2.2) that EXECUTES that suite: dryRun()
+// checks out HEAD into an ephemeral `git worktree`, runs the suite there, parses the
+// TAP summary, and always discards the sandbox. Selection stays useful on its own as
+// "run these, in this order"; dryRun turns the prediction into measured evidence.
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { build as buildAtlas, impact, load as loadAtlas } from "./atlas.js";
+import { referencedEntities } from "./preflight.js";
+import { isTestFile, predictFailingTests } from "./substrate.js";
+import { hasBin } from "./util.js";
+
+/**
+ * Weighted greedy set cover over the covers(test, source) relation: candidates are
+ * substrate's predicted-failing tests plus any test files among the impacted set
+ * (those cover themselves — they are predicted to break, so the suite must include
+ * them). Weight = file size, a duration proxy until measured runtimes exist (P8).
+ * Each round picks the test minimizing weight / newly-covered — the classical
+ * greedy H(n) ≈ ln n approximation to weighted set cover (Chvátal 1979), and exact
+ * on the tiny instances a single edit produces. Impacted sources with no covering
+ * test simply can't constrain the suite; the gaps surface via selectTestsReport.
+ * @param {string} root
+ * @param {string[]} impactedFiles
+ * @returns {string[]} minimal ordered dry-run suite (best value first)
+ */
+export function selectTests(root, impactedFiles) {
+  return selectTestsReport(root, impactedFiles).tests;
+}
+
+/** selectTests plus the sources no known test covers (the honest gap in the cover). */
+export function selectTestsReport(root, impactedFiles) {
+  const files = [...new Set(impactedFiles.map(String))];
+  const covers = new Map(); // test → Set of covered elements (sources + itself)
+  const addCover = (test, el) => {
+    if (!covers.has(test)) covers.set(test, new Set());
+    covers.get(test).add(el);
+  };
+  for (const f of files) {
+    if (isTestFile(f)) addCover(f, f);
+    else for (const t of predictFailingTests(root, [f])) addCover(t, f);
+  }
+  const universe = new Set();
+  for (const els of covers.values()) for (const el of els) universe.add(el);
+  const weights = new Map(
+    [...covers.keys()].map((t) => {
+      // Unreadable candidate → weight 1, never a throw: selection must not die on a
+      // just-deleted test file; running it later fails honestly instead.
+      let w = 1;
+      try {
+        w = Math.max(1, statSync(join(root, t)).size);
+      } catch {}
+      return [t, w];
+    }),
+  );
+  const tests = [];
+  const covered = new Set();
+  while (covered.size < universe.size) {
+    let best = null;
+    let bestRatio = Infinity;
+    for (const [t, els] of covers) {
+      let gain = 0;
+      for (const el of els) if (!covered.has(el)) gain++;
+      if (!gain) continue; // also skips already-chosen tests (their gain is 0)
+      const ratio = weights.get(t) / gain;
+      // Deterministic tie-break by path so the suite order is stable across runs.
+      if (ratio < bestRatio || (ratio === bestRatio && best !== null && t < best)) {
+        best = t;
+        bestRatio = ratio;
+      }
+    }
+    if (best === null) break;
+    tests.push(best);
+    for (const el of covers.get(best)) covered.add(el);
+  }
+  const uncovered = files.filter((f) => !isTestFile(f) && !covered.has(f)).sort();
+  return { tests, uncovered };
+}
+
+/** Strip a TAP `location: '/abs/file.js:1:2'` diagnostic down to its file path. */
+const locFile = (line) => {
+  const m = /^\s+location:\s*'(.+):\d+:\d+'/.exec(line);
+  return m ? m[1] : null;
+};
+
+/**
+ * @typedef {{ok: boolean, reason?: string, passed?: number, failed?: number,
+ *   perFile?: Record<string, "pass"|"fail">, durationMs?: number, runner?: string,
+ *   output?: string, worktree?: string}} DryRunVerdict
+ */
+
+/**
+ * Sandboxed dry-run of a selected suite — the simulation half of ĉ = g(a, C)
+ * (spec §2.2): run the tests in an EPHEMERAL `git worktree` of HEAD and discard it.
+ * The worktree is HEAD, not the working tree — worktrees share the object store,
+ * never uncommitted files — so callers MUST surface that a dirty tree dry-runs the
+ * last commit, not the in-flight proposal (the CLI refuses dirty trees by default).
+ * ok means the RUN completed and produced a verdict; failing tests are ok:true with
+ * failed>0 — that IS the imagined consequence, delivered as evidence. Never throws:
+ * unmet preconditions return { ok:false, reason }.
+ * @param {string} root
+ * @param {{tests?: string[], timeoutMs?: number}} [opts] repo-relative test paths
+ * @returns {DryRunVerdict}
+ */
+export function dryRun(root, { tests, timeoutMs = 120000 } = {}) {
+  if (!Array.isArray(tests) || tests.length === 0)
+    return { ok: false, reason: "no tests selected — nothing to dry-run" };
+  if (!hasBin("git")) return { ok: false, reason: "git not found — the sandbox is a git worktree" };
+  try {
+    execFileSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd: root, stdio: "ignore" });
+  } catch {
+    return { ok: false, reason: `not a git repository: ${root}` };
+  }
+  // mkdtemp reserves a unique parent; the worktree goes one level down because
+  // `git worktree add` wants to create its target path itself.
+  const parent = mkdtempSync(join(tmpdir(), "forge-dryrun-"));
+  const wt = join(parent, "wt");
+  const started = Date.now();
+  // The body runs in a closure so every exit path — verdict, timeout, crash — flows
+  // through the same finally-cleanup AND the same verified `worktree` stamp below.
+  /** @returns {DryRunVerdict} */
+  const body = () => {
+    try {
+      execFileSync("git", ["worktree", "add", "--detach", wt, "HEAD"], {
+        cwd: root,
+        stdio: "pipe",
+      });
+    } catch (e) {
+      const msg = /** @type {{stderr?: Buffer}} */ (e).stderr?.toString().trim() || String(e);
+      return { ok: false, reason: `git worktree add failed: ${msg}` };
+    }
+    // Runner policy: always `node --test <files...>` — a custom package test script
+    // (jest, vitest, …) is a WHOLE-SUITE command that can't be scoped per-file safely,
+    // which would defeat minimal selection. We still run node --test and say so, so a
+    // surprising verdict is attributable to the runner mismatch.
+    let runner = "node --test";
+    try {
+      const pkg = JSON.parse(readFileSync(join(wt, "package.json"), "utf8"));
+      const script = pkg?.scripts?.test;
+      if (script && !/\bnode\s+(--[\w-]+\s+)*--test\b/.test(script))
+        runner = `node --test (package.json test script is custom: ${String(script).slice(0, 60)})`;
+    } catch {} // no/unreadable package.json → default runner
+    // TAP reporter is forced: the default reporter depends on TTY-ness, and the
+    // `# pass/# fail` summary below is the contract this parser relies on. The env
+    // must NOT leak a parent test-runner's context — when dryRun itself runs under
+    // `node --test` (our own tests, or an agent's), an inherited NODE_TEST_CONTEXT
+    // makes the child speak the runner's internal protocol instead of TAP.
+    const env = { ...process.env };
+    delete env.NODE_TEST_CONTEXT;
+    const run = spawnSync(
+      process.execPath,
+      ["--test", "--test-reporter=tap", ...tests.map(String)],
+      {
+        cwd: wt,
+        env,
+        encoding: "utf8",
+        timeout: timeoutMs,
+        killSignal: "SIGKILL", // node --test forks workers; SIGKILL is the reliable stop
+        maxBuffer: 16 * 1024 * 1024,
+      },
+    );
+    const combined = `${run.stdout ?? ""}${run.stderr ? `\n${run.stderr}` : ""}`.trim();
+    const output = combined.length > 2000 ? `…${combined.slice(-2000)}` : combined;
+    const durationMs = Date.now() - started;
+    if (run.error || run.signal) {
+      const reason =
+        /** @type {{code?: string}} */ (run.error)?.code === "ETIMEDOUT" || run.signal
+          ? `dry-run timed out after ${timeoutMs}ms (killed with ${run.signal ?? "SIGKILL"})`
+          : `runner failed to start: ${run.error}`;
+      return { ok: false, reason, durationMs, runner, output };
+    }
+    const mPass = /^# pass (\d+)$/m.exec(run.stdout ?? "");
+    const mFail = /^# fail (\d+)$/m.exec(run.stdout ?? "");
+    if (!mPass || !mFail) {
+      // Non-zero exit with no TAP summary = the RUN failed (crash, bad flags), which
+      // is a different fact than "the tests failed" — report it as one.
+      return {
+        ok: false,
+        reason: `runner exited ${run.status} without a TAP summary`,
+        durationMs,
+        runner,
+        output,
+      };
+    }
+    // perFile is best-effort: node ≥20 TAP flattens per-TEST (no per-file points), but
+    // every failure block carries a `location: '<abs path>:l:c'` diagnostic — map those
+    // back to the requested files; anything never implicated passed. Omitted when a
+    // failure can't be attributed (partial attribution would misassign blame).
+    /** @type {Record<string, "pass"|"fail">} */
+    const perFile = Object.fromEntries(tests.map((t) => [String(t), "pass"]));
+    let attributable = true;
+    for (const block of (run.stdout ?? "").split(/^not ok /m).slice(1)) {
+      const file = block.split("\n").map(locFile).find(Boolean);
+      const t = file && tests.find((c) => file === join(wt, String(c)));
+      if (t) perFile[String(t)] = "fail";
+      else attributable = false;
+    }
+    return {
+      ok: true,
+      passed: Number(mPass[1]),
+      failed: Number(mFail[1]),
+      ...(attributable ? { perFile } : {}),
+      durationMs,
+      runner,
+      output,
+    };
+  };
+  let result;
+  try {
+    result = body();
+  } finally {
+    // ALWAYS discard the sandbox — a leaked worktree pins refs and litters
+    // `git worktree list` forever. remove --force, prune the bookkeeping, then
+    // belt-and-braces rm of the parent; the verdict below verifies, never assumes.
+    try {
+      execFileSync("git", ["worktree", "remove", "--force", wt], { cwd: root, stdio: "ignore" });
+    } catch {}
+    try {
+      execFileSync("git", ["worktree", "prune"], { cwd: root, stdio: "ignore" });
+    } catch {}
+    try {
+      rmSync(parent, { recursive: true, force: true });
+    } catch {}
+  }
+  result.worktree = existsSync(wt) ? "leaked" : "removed";
+  return result;
+}
+
+/**
+ * Imagine the consequences of a task before acting: entities → impact() blast
+ * radius → predicted breaks (per-file max confidence across targets), the minimal
+ * dry-run suite, and riskScore = Σ confidence — the number spec §2.3 thresholds to
+ * decide whether the (follow-up) sandboxed dry-run is worth paying for.
+ * @param {string} root
+ * @param {string} task
+ * @param {{atlas?: object, threshold?: number}} [opts] inject `atlas` to skip the build.
+ */
+export function imagineTask(root, task, { atlas, threshold = 0.1 } = {}) {
+  const graph = atlas || loadAtlas(root) || buildAtlas({ root });
+  const entities = referencedEntities(task);
+  const targets = [...new Set([...entities.symbols, ...entities.files])].slice(0, 8);
+  const reports = targets.map((t) => impact(graph, t, { threshold }));
+  const byFile = new Map();
+  for (const r of reports) {
+    for (const x of r.impacted) {
+      const f = x.node?.file;
+      if (f) byFile.set(f, Math.max(byFile.get(f) ?? 0, x.confidence));
+    }
+  }
+  const predictedBreaks = [...byFile]
+    .map(([file, confidence]) => ({ file, confidence }))
+    .sort((a, b) => b.confidence - a.confidence || (a.file < b.file ? -1 : 1));
+  const { tests, uncovered } = selectTestsReport(
+    root,
+    predictedBreaks.map((b) => b.file),
+  );
+  return {
+    task: String(task),
+    targets,
+    found: reports.some((r) => r.found),
+    predictedBreaks,
+    tests,
+    uncovered,
+    riskScore: Number(predictedBreaks.reduce((s, b) => s + b.confidence, 0).toFixed(4)),
+  };
+}
+
+/** @param {ReturnType<typeof imagineTask>} r
+ *  @param {{footer?: boolean}} [opts] footer=false when the caller runs the dry-run itself */
+export function renderImagine(r, { footer = true } = {}) {
+  const lines = ["Forge imagine — consequence simulation (pre-action)", ""];
+  lines.push(`  targets: ${r.targets.length ? r.targets.join(", ") : "(none named)"}`);
+  if (!r.found) {
+    lines.push("", "  nothing in the code graph matches this task — no consequences to predict.");
+    return lines.join("\n");
+  }
+  lines.push(`  risk score: ${r.riskScore}  (Σ confidence over predicted breaks)`);
+  lines.push("", `  predicted breaks (${r.predictedBreaks.length}):`);
+  for (const b of r.predictedBreaks.slice(0, 12))
+    lines.push(`    ${b.confidence.toFixed(2)}  ${b.file}`);
+  if (r.predictedBreaks.length > 12) lines.push(`    … ${r.predictedBreaks.length - 12} more`);
+  if (r.tests.length) {
+    lines.push("", `  minimal dry-run suite (${r.tests.length}) — run these, in this order:`);
+    for (const t of r.tests) lines.push(`    - ${t}`);
+  } else {
+    lines.push("", "  no covering tests found for the predicted breaks.");
+  }
+  if (r.uncovered.length)
+    lines.push(
+      "",
+      `  ! no test covers: ${r.uncovered.slice(0, 6).join(", ")}${r.uncovered.length > 6 ? " …" : ""}`,
+    );
+  if (footer)
+    lines.push("", "  (measure it: re-run with --run — sandboxed worktree dry-run of HEAD)");
+  return lines.join("\n");
+}

package/src/init.js

@@ -0,0 +1,178 @@
+// forge init / catalog — the onboarding surface. init gets a repo to a working
+// state in one command; catalog is the "Start Here" index of everything active.
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { BRAND } from "./brand.js";
+import { GITATTRIBUTES_RULE } from "./ledger_store.js";
+import { autoDetectProvider } from "./providers.js";
+import { sync } from "./sync.js";
+import { list as tasteList } from "./taste.js";
+
+/** Without the union merge driver, two teammates appending to the same ledger log get
+ *  a git conflict — the exact thing the ledger's design promises can't happen
+ *  (docs/plans/substrate-v2/02-team-memory.md §1). Idempotent append. */
+export function ensureLedgerGitattributes(targetRoot = process.cwd()) {
+  const path = join(targetRoot, ".gitattributes");
+  const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+  if (existing.includes(".forge/ledger/")) return { written: false };
+  appendFileSync(
+    path,
+    `${existing && !existing.endsWith("\n") ? "\n" : ""}${GITATTRIBUTES_RULE}\n`,
+  );
+  return { written: true };
+}
+
+// ---------------------------------------------------------------------------
+// Settings merge — auto-install Forge hooks + permissions into the user's
+// ~/.claude/settings.json without clobbering existing entries.
+// ---------------------------------------------------------------------------
+
+const FORGE_SETTINGS_MARKER = "forge-managed";
+
+function loadTemplate() {
+  const path = join(BRAND.root, "global", "settings.template.json");
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+function readJsonSafe(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Deduplicated union of two string arrays. */
+function unionStrings(a = [], b = []) {
+  const set = new Set(a);
+  for (const s of b) set.add(s);
+  return [...set];
+}
+
+/** Merge Forge hook entries into existing hook arrays, matching by command to avoid duplicates. */
+function mergeHooks(existing = {}, template = {}) {
+  const merged = { ...existing };
+  for (const [event, entries] of Object.entries(template)) {
+    const existingEntries = merged[event] || [];
+    const existingCommands = new Set(
+      existingEntries.flatMap((e) => (e.hooks || []).map((h) => h.command)).filter(Boolean),
+    );
+    const newEntries = [];
+    for (const entry of entries) {
+      const hooks = (entry.hooks || []).filter((h) => !existingCommands.has(h.command));
+      if (hooks.length) {
+        newEntries.push({ ...entry, hooks });
+      }
+    }
+    merged[event] = [...existingEntries, ...newEntries];
+  }
+  return merged;
+}
+
+/**
+ * Merge Forge settings (hooks, permissions, statusline) into the user's
+ * ~/.claude/settings.json. Preserves all existing entries. Idempotent.
+ * @param {{settingsPath?: string, noSettings?: boolean}} [opts]
+ */
+export function mergeSettings({ settingsPath, noSettings } = {}) {
+  if (noSettings) return { action: "skipped", reason: "--no-settings" };
+  const target = settingsPath || join(homedir(), ".claude", "settings.json");
+  const template = loadTemplate();
+  const existing = readJsonSafe(target) || {};
+  const report = { added: [], unchanged: [], path: target };
+
+  // Hooks
+  if (template.hooks) {
+    const before = JSON.stringify(existing.hooks || {});
+    existing.hooks = mergeHooks(existing.hooks, template.hooks);
+    if (JSON.stringify(existing.hooks) !== before) report.added.push("hooks");
+    else report.unchanged.push("hooks");
+  }
+
+  // Permissions
+  if (template.permissions) {
+    const ep = existing.permissions || {};
+    for (const level of ["allow", "ask", "deny"]) {
+      if (template.permissions[level]) {
+        const before = (ep[level] || []).length;
+        ep[level] = unionStrings(ep[level], template.permissions[level]);
+        if (ep[level].length > before) report.added.push(`permissions.${level}`);
+        else report.unchanged.push(`permissions.${level}`);
+      }
+    }
+    if (!ep.defaultMode) ep.defaultMode = template.permissions.defaultMode || "default";
+    existing.permissions = ep;
+  }
+
+  // Statusline — set only if not already configured
+  if (template.statusLine && !existing.statusLine) {
+    existing.statusLine = template.statusLine;
+    report.added.push("statusLine");
+  } else if (template.statusLine) {
+    report.unchanged.push("statusLine");
+  }
+
+  // Schema
+  if (template.$schema && !existing.$schema) existing.$schema = template.$schema;
+
+  // Mark as forge-managed (metadata, won't affect Claude Code)
+  existing._forge = FORGE_SETTINGS_MARKER;
+
+  // Write back
+  const dir = dirname(target);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(target, `${JSON.stringify(existing, null, 2)}\n`);
+
+  return {
+    action: report.added.length ? "merged" : "unchanged",
+    ...report,
+  };
+}
+
+/** Scaffold this repo's cross-tool config (emit every tool) in one step. */
+export function init({ targetRoot = process.cwd(), noSettings = false } = {}) {
+  const r = sync({ targetRoot });
+  ensureLedgerGitattributes(targetRoot);
+  const settings = mergeSettings({ noSettings });
+  const detected = autoDetectProvider();
+  return { ...r, settings, detected };
+}
+
+function skillDescription(dir) {
+  try {
+    const match = readFileSync(join(dir, "SKILL.md"), "utf8").match(/description:\s*(.*)/);
+    return match ? match[1].trim() : "";
+  } catch {
+    return "";
+  }
+}
+
+/** Everything Forge makes available, grouped by layer, for the Start-Here list. */
+export function catalog() {
+  const g = join(BRAND.root, "global");
+  const dir = (p) => (existsSync(p) ? readdirSync(p) : []);
+  return {
+    tools: dir(join(g, "tools"))
+      .filter((name) => existsSync(join(g, "tools", name, "SKILL.md")))
+      .map((name) => ({ name, why: skillDescription(join(g, "tools", name)) })),
+    crew: dir(join(g, "crew"))
+      .filter((f) => f.endsWith(".md"))
+      .map((f) => f.replace(/\.md$/, "")),
+    guards: dir(join(g, "guards"))
+      .filter((f) => f.endsWith(".sh") && !f.startsWith("_"))
+      .map((f) => f.replace(/\.sh$/, "")),
+    taste: tasteList(),
+    cortex:
+      "self-correcting project memory — learns from your mistakes on this repo (`forge cortex`)",
+    preflight:
+      "size the work before spending tokens — assumption-check / model-route / decompose (`forge preflight` · `route` · `scope`)",
+  };
+}