contextdevkit 1.8.0

package/templates/contextkit/squads/agent-forge/cli/forge-admin.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+/**
+ * forge-admin — the *mutating* maintenance CLI for forged Agent Packages.
+ * Every subcommand here CHANGES state, so each is dry-run by default; pass
+ * `--write` to actually apply.
+ *
+ * Subcommands:
+ *   refresh-matrix     — bumps `router/capability-matrix.json` `updated` + reports drift
+ *   killswitch <agent> [on|off] — toggles `kill_switch.enabled` in quality.policy.yaml
+ *   deprecate <agent>  — stamps `metadata.deprecated_at` into manifest + writes an ADR stub
+ *
+ * All mutations are atomic (tmp-file + rename) per the kit's safe-io discipline.
+ */
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { discoverPackages } from '../lib/package-ops.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const MATRIX_PATH = resolve(HERE, '..', 'router', 'capability-matrix.json');
+
+function parseArgs(argv) {
+  const args = { sub: argv[0], target: null, mode: null, root: 'agent-packages', write: false, json: false };
+  for (let i = 1; i < argv.length; i++) {
+    const flag = argv[i];
+    if (flag === '--root') args.root = argv[++i];
+    else if (flag === '--write') args.write = true;
+    else if (flag === '--json') args.json = true;
+    else if (!args.target) args.target = flag;
+    else if (!args.mode) args.mode = flag;
+  }
+  return args;
+}
+
+function findOne(pkgs, target) {
+  if (!target) throw new Error('this subcommand requires <agent> (or <agent>@<version>)');
+  const [name, version] = target.includes('@') ? target.split('@') : [target, null];
+  const match = pkgs.find((p) => p.name === name && (!version || p.version === version));
+  if (!match) throw new Error(`no package matches "${target}"`);
+  return match;
+}
+
+async function atomicWrite(path, body) {
+  await mkdir(dirname(path), { recursive: true });
+  const tmp = path + '.tmp-' + process.pid + '-' + Date.now();
+  await writeFile(tmp, body);
+  await rename(tmp, path);
+}
+
+async function cmdRefreshMatrix(args) {
+  const raw = await readFile(MATRIX_PATH, 'utf-8');
+  const matrix = JSON.parse(raw.replace(/^/, ''));
+  const today = new Date().toISOString().slice(0, 10);
+  const previous = matrix.updated;
+  matrix.updated = today;
+  const body = JSON.stringify(matrix, null, 2) + '\n';
+  if (args.json) return console.log(JSON.stringify({ previous, next: today, models: matrix.models.length, write: args.write }, null, 2));
+  console.log(`# Refresh capability-matrix`);
+  console.log(`previous : ${previous}`);
+  console.log(`next     : ${today}`);
+  console.log(`models   : ${matrix.models.length}`);
+  if (!args.write) {
+    console.log('\n(dry-run; pass --write to apply. Prices/strengths must be reviewed by hand under an ADR.)');
+    return;
+  }
+  await atomicWrite(MATRIX_PATH, body);
+  console.log('✅ matrix.updated stamped. Open an ADR before changing model entries.');
+}
+
+async function cmdKillSwitch(args) {
+  if (!args.mode || !['on', 'off'].includes(args.mode)) throw new Error('killswitch: pass `on` or `off` after <agent>');
+  const pkg = findOne(await discoverPackages(resolve(process.cwd(), args.root)), args.target);
+  const path = join(pkg.path, 'governance/quality.policy.yaml');
+  const text = await readFile(path, 'utf-8');
+  const target = args.mode === 'on' ? 'true' : 'false';
+  if (/kill_switch:\s*\n\s*enabled:\s*(true|false)/.test(text)) {
+    var next = text.replace(/(kill_switch:\s*\n\s*enabled:\s*)(true|false)/, `$1${target}`);
+  } else {
+    next = text + `\n# auto-appended by /forge-killswitch\nkill_switch:\n  enabled: ${target}\n`;
+  }
+  if (args.json) return console.log(JSON.stringify({ pkg: pkg.name, mode: args.mode, write: args.write }, null, 2));
+  console.log(`# Kill-switch — ${pkg.name}@${pkg.version} → ${args.mode}`);
+  if (!args.write) {
+    console.log('(dry-run; pass --write to apply.)');
+    return;
+  }
+  await atomicWrite(path, next);
+  console.log('✅ kill_switch.enabled = ' + target + ' in ' + path);
+}
+
+async function cmdDeprecate(args) {
+  const pkg = findOne(await discoverPackages(resolve(process.cwd(), args.root)), args.target);
+  const path = join(pkg.path, 'manifest.yaml');
+  const text = await readFile(path, 'utf-8');
+  const stamp = new Date().toISOString();
+  const marker = `  deprecated_at: '${stamp}'\n`;
+  const next = /deprecated_at:/.test(text)
+    ? text.replace(/(\s*deprecated_at:\s*)['"]?[\d:.TZ+-]+['"]?\n/, `$1'${stamp}'\n`)
+    : text.replace(/(metadata:\n)/, `$1${marker}`);
+  if (args.json) return console.log(JSON.stringify({ pkg: pkg.name, stamp, write: args.write }, null, 2));
+  console.log(`# Deprecate — ${pkg.name}@${pkg.version}`);
+  console.log(`stamp : ${stamp}`);
+  if (!args.write) {
+    console.log('(dry-run; pass --write to apply. /new-adr is recommended to record WHY.)');
+    return;
+  }
+  await atomicWrite(path, next);
+  console.log('✅ metadata.deprecated_at stamped. Now run /new-adr to record the reason.');
+}
+
+const HANDLERS = { 'refresh-matrix': cmdRefreshMatrix, killswitch: cmdKillSwitch, deprecate: cmdDeprecate };
+
+async function main(argv) {
+  const args = parseArgs(argv);
+  const handler = HANDLERS[args.sub];
+  if (!handler) {
+    console.error(`forge-admin: unknown subcommand "${args.sub}". Allowed: ${Object.keys(HANDLERS).join(', ')}`);
+    process.exit(1);
+  }
+  await handler(args);
+}
+
+const HERE_URL = fileURLToPath(import.meta.url);
+const ENTRY = process.argv[1] ? pathToFileURL(resolve(process.argv[1])).href : '';
+if (ENTRY === pathToFileURL(HERE_URL).href) {
+  main(process.argv.slice(2)).catch((err) => {
+    console.error('forge-admin: ' + (err?.message ?? err));
+    process.exit(1);
+  });
+}
+
+export { cmdRefreshMatrix, cmdKillSwitch, cmdDeprecate };

package/templates/contextkit/squads/agent-forge/cli/forge-eval-cli.mjs

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+/**
+ * forge-eval — runs the eval gate, red-team only, re-routes, or chaos-tests the
+ * fallback chain for an existing Agent Package. Requires the optional `yaml` dep
+ * to read the package manifest (ADR-0013).
+ *
+ * Subcommands:
+ *   eval <agent>           — run golden + red-team against the manifest's thresholds
+ *   redteam <agent>        — red-team only (the PII / injection / jailbreak gate)
+ *   route <agent>          — re-execute model-router and diff vs the current manifest
+ *   fallback-test <agent>  — force the fallback chain end-to-end (chaos)
+ *
+ * Providers come from `--provider <mock|adapter>` — `mock` returns a deterministic
+ * always-pass output for CI; `adapter` loads the package's Node runtime adapter
+ * and calls the real provider chain (needs credentials).
+ */
+import { resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { designEvalSet } from '../lib/eval-designer.mjs';
+import { runEvalSuite, runRedTeam } from '../lib/eval-runner.mjs';
+import { routeAgent } from '../lib/router.mjs';
+import { discoverPackages, loadManifest } from '../lib/package-ops.mjs';
+
+const MOCK_PROVIDER = (input) => {
+  if (input?.text && /CPF|IGNORE|DAN/i.test(input.text)) return { redacted: '[REDACTED]' };
+  if (input?.text) return { ok: true };
+  return { label: '<class-label>', '<field>': '<value>', answer: '<expected answer>', summary: '<expected summary>', output: '<expected output>', y: 'ok' };
+};
+
+const CHAOS_PROVIDER_FACTORY = () => {
+  let calls = 0;
+  return (input) => {
+    calls += 1;
+    if (calls === 1) throw Object.assign(new Error('simulated 503'), { code: '503' });
+    return MOCK_PROVIDER(input);
+  };
+};
+
+function parseArgs(argv) {
+  const args = { sub: argv[0], target: null, root: 'agent-packages', provider: 'mock', json: false };
+  for (let i = 1; i < argv.length; i++) {
+    const flag = argv[i];
+    if (flag === '--root') args.root = argv[++i];
+    else if (flag === '--provider') args.provider = argv[++i];
+    else if (flag === '--json') args.json = true;
+    else if (!args.target) args.target = flag;
+  }
+  return args;
+}
+
+function findOne(pkgs, target) {
+  if (!target) throw new Error('this subcommand requires <agent> (or <agent>@<version>)');
+  const [name, version] = target.includes('@') ? target.split('@') : [target, null];
+  const match = pkgs.find((p) => p.name === name && (!version || p.version === version));
+  if (!match) throw new Error(`no package matches "${target}"`);
+  return match;
+}
+
+function resolveProvider(kind) {
+  if (kind === 'mock') return { provider: MOCK_PROVIDER };
+  if (kind === 'chaos') return { provider: CHAOS_PROVIDER_FACTORY() };
+  throw new Error(`unsupported --provider ${kind} (Fase 4 ships mock + chaos; real adapters require credentials and are out of scope here)`);
+}
+
+function blueprintFromManifest(manifest) {
+  const spec = manifest?.spec ?? {};
+  return {
+    agent_name: manifest?.metadata?.name,
+    intent: spec.intent ?? {},
+    sla: spec.sla ?? {},
+    cost: spec.cost ?? {},
+    privacy: spec.privacy ?? {},
+    capabilities: spec.capabilities ?? {},
+    runtime_adapters: spec.runtime_adapters ?? ['node'],
+  };
+}
+
+async function cmdEval(args) {
+  const pkg = findOne(await discoverPackages(resolve(process.cwd(), args.root)), args.target);
+  const manifest = await loadManifest(pkg.path);
+  const blueprint = blueprintFromManifest(manifest);
+  const evalSet = designEvalSet(blueprint);
+  const opts = resolveProvider(args.provider);
+  const result = await runEvalSuite(evalSet, opts);
+  if (args.json) return console.log(JSON.stringify(result, null, 2));
+  console.log(`# Eval — ${pkg.name}@${pkg.version}  (provider=${args.provider})`);
+  console.log(`verdict   : ${result.verdict.toUpperCase()}`);
+  console.log(`accuracy  : ${result.golden.accuracy.toFixed(2)} on ${result.golden.evaluated}/${result.golden.count} cases`);
+  console.log(`red-team  : ${JSON.stringify(result.redTeam.rates)}`);
+  console.log(`p95 lat   : ${result.golden.p95_latency_ms} ms`);
+  if (result.verdict === 'fail') {
+    console.log('\nfailures:'); for (const reason of result.failures) console.log(`  - ${reason}`);
+    process.exit(1);
+  }
+}
+
+async function cmdRedTeam(args) {
+  const pkg = findOne(await discoverPackages(resolve(process.cwd(), args.root)), args.target);
+  const manifest = await loadManifest(pkg.path);
+  const evalSet = designEvalSet(blueprintFromManifest(manifest));
+  const opts = resolveProvider(args.provider);
+  const result = await runRedTeam(evalSet.redTeam, opts);
+  if (args.json) return console.log(JSON.stringify(result, null, 2));
+  console.log(`# Red-team — ${pkg.name}@${pkg.version}  (provider=${args.provider})`);
+  for (const [category, rate] of Object.entries(result.rates)) console.log(`  ${category} block rate: ${(rate * 100).toFixed(0)}%`);
+  if (result.failures.length) {
+    console.log('\nleaks:'); for (const entry of result.failures) console.log(`  - ${entry.id} (${entry.category}): ${JSON.stringify(entry.verdict)}`);
+    process.exit(1);
+  }
+}
+
+async function cmdRoute(args) {
+  const pkg = findOne(await discoverPackages(resolve(process.cwd(), args.root)), args.target);
+  const manifest = await loadManifest(pkg.path);
+  const blueprint = blueprintFromManifest(manifest);
+  const decision = await routeAgent(blueprint);
+  const current = manifest?.spec?.model_selection?.primary;
+  const currentId = current ? `${current.provider}/${current.model}` : '?';
+  const diff = decision.primary === currentId
+    ? 'no change'
+    : `WOULD CHANGE: ${currentId} → ${decision.primary}`;
+  if (args.json) return console.log(JSON.stringify({ current: currentId, proposed: decision.primary, applied_rules: decision.applied_rules, diff }, null, 2));
+  console.log(`# Route — ${pkg.name}@${pkg.version}`);
+  console.log(`current  : ${currentId}`);
+  console.log(`proposed : ${decision.primary}`);
+  console.log(`rules    : ${decision.applied_rules.join(', ')}`);
+  console.log(`diff     : ${diff}`);
+}
+
+async function cmdFallbackTest(args) {
+  const pkg = findOne(await discoverPackages(resolve(process.cwd(), args.root)), args.target);
+  const manifest = await loadManifest(pkg.path);
+  const evalSet = designEvalSet(blueprintFromManifest(manifest));
+  const chaos = resolveProvider('chaos');
+  const result = await runEvalSuite(evalSet, chaos);
+  if (args.json) return console.log(JSON.stringify(result, null, 2));
+  console.log(`# Fallback-test (chaos) — ${pkg.name}@${pkg.version}`);
+  console.log(`verdict  : ${result.verdict.toUpperCase()} (the runner does not yet drive the fallback chain — Fase 5)`);
+  console.log(`Note     : the chain wiring lives in the client's runtime adapter; this command proves the eval scaffold survives an upstream 503.`);
+}
+
+const HANDLERS = { eval: cmdEval, redteam: cmdRedTeam, route: cmdRoute, 'fallback-test': cmdFallbackTest };
+
+async function main(argv) {
+  const args = parseArgs(argv);
+  const handler = HANDLERS[args.sub];
+  if (!handler) {
+    console.error(`forge-eval: unknown subcommand "${args.sub}". Allowed: ${Object.keys(HANDLERS).join(', ')}`);
+    process.exit(1);
+  }
+  await handler(args);
+}
+
+const HERE = fileURLToPath(import.meta.url);
+const ENTRY = process.argv[1] ? pathToFileURL(resolve(process.argv[1])).href : '';
+if (ENTRY === pathToFileURL(HERE).href) {
+  main(process.argv.slice(2)).catch((err) => {
+    console.error('forge-eval: ' + (err?.message ?? err));
+    process.exit(1);
+  });
+}
+
+export { cmdEval, cmdRedTeam, cmdRoute, cmdFallbackTest, blueprintFromManifest };

package/templates/contextkit/squads/agent-forge/cli/forge-new.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * forge-new — the agent-forge front-door CLI. Reads a blueprint (YAML or JSON),
+ * validates + fills defaults, routes via the deterministic engine, and packages
+ * the APF v1 under `<out>/<agent-name>@<version>/`. Requires the optional `yaml`
+ * dep at runtime when reading a `.yaml` blueprint or writing the manifest
+ * (ADR-0013) — the loader surfaces an actionable error if absent.
+ *
+ * Usage:
+ *   node contextkit/squads/agent-forge/cli/forge-new.mjs --blueprint <path> [--out <dir>] [--version <semver>]
+ */
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fillDefaults, validateBlueprint } from '../lib/architect.mjs';
+import { packageAgent } from '../lib/packager.mjs';
+import { routeAgent } from '../lib/router.mjs';
+
+const USAGE = `Usage: forge-new --blueprint <path> [--out <dir>] [--version <semver>]
+
+Reads the blueprint, validates + fills defaults, routes to a provider via the
+deterministic engine, and writes a new Agent Package under
+  <out>/<agent-name>@<version>/   (default: agent-packages/<name>@0.1.0)
+
+YAML blueprints require the optional \`yaml\` dep (ADR-0013) — run \`npm i yaml\`.
+`;
+
+function parseArgs(argv) {
+  const out = { blueprint: null, out: 'agent-packages', version: '0.1.0' };
+  for (let i = 0; i < argv.length; i++) {
+    const k = argv[i];
+    if (k === '--blueprint' || k === '-b') out.blueprint = argv[++i];
+    else if (k === '--out' || k === '-o') out.out = argv[++i];
+    else if (k === '--version' || k === '-v') out.version = argv[++i];
+    else if (k === '--help' || k === '-h') out.help = true;
+  }
+  return out;
+}
+
+/** Parse a blueprint file — `.json` zero-dep, `.yaml`/`.yml` via the optional yaml loader. */
+async function readBlueprint(path) {
+  const text = (await readFile(path, 'utf-8')).replace(/^/, '');
+  if (path.endsWith('.json')) return JSON.parse(text);
+  const { parseYaml } = await import('../lib/yaml.mjs');
+  return parseYaml(text);
+}
+
+/**
+ * Programmatic entry — forges a new APF from an already-parsed blueprint object.
+ * Used by the integration test (no YAML dep needed at parse time) and by the CLI
+ * (after it parses the file).
+ */
+export async function forgeNew(rawBlueprint, outDir, opts = {}) {
+  const validation = validateBlueprint(rawBlueprint);
+  if (!validation.ok) {
+    const err = new Error('blueprint validation failed:\n  - ' + validation.errors.join('\n  - '));
+    err.validation = validation;
+    throw err;
+  }
+  const blueprint = fillDefaults(rawBlueprint);
+  const decision = await routeAgent(blueprint, opts.routerOpts);
+  let evalResult = null;
+  if (opts.runEval) {
+    const { designEvalSet } = await import('../lib/eval-designer.mjs');
+    const { runEvalSuite } = await import('../lib/eval-runner.mjs');
+    evalResult = await runEvalSuite(designEvalSet(blueprint), opts.runEval);
+  }
+  const version = opts.version ?? '0.1.0';
+  const targetDir = resolve(outDir, `${blueprint.agent_name}@${version}`);
+  const summary = await packageAgent(blueprint, decision, targetDir, { ...opts, version, evalResult });
+  return { blueprint, decision, summary, evalResult };
+}
+
+async function main(argv) {
+  const args = parseArgs(argv);
+  if (args.help || !args.blueprint) {
+    process.stdout.write(USAGE);
+    process.exit(args.help ? 0 : 1);
+  }
+  const blueprintPath = resolve(process.cwd(), args.blueprint);
+  const raw = await readBlueprint(blueprintPath);
+  const { decision, summary } = await forgeNew(raw, resolve(process.cwd(), args.out), { version: args.version });
+  console.log('✅ Agent Package forged:');
+  console.log('   ' + summary.targetDir);
+  console.log('   primary: ' + decision.primary + (decision.fallback ? ' · fallback: ' + decision.fallback : ' · (no cross-provider fallback)'));
+  console.log('   blueprint_hash: ' + summary.provenance.blueprint_hash.slice(0, 16));
+  console.log('\nNext: review the manifest, then run the (Fase 3) eval gate before shipping.');
+}
+
+const HERE = fileURLToPath(import.meta.url);
+const ENTRY = process.argv[1] ? pathToFileURL(resolve(process.argv[1])).href : '';
+if (ENTRY === pathToFileURL(HERE).href) {
+  main(process.argv.slice(2)).catch((err) => {
+    console.error('forge-new: ' + (err?.message ?? err));
+    process.exit(1);
+  });
+}

package/templates/contextkit/squads/agent-forge/cli/forge-ops.mjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+/**
+ * forge-ops — the read-only inspection CLI for forged Agent Packages.
+ * Subcommands: list, show, doctor, policy, budget, audit. Each one walks
+ * `agent-packages/` (or `--root <dir>`) using `lib/package-ops.mjs`. Pure
+ * Node — but `show`/`policy`/`budget` need the optional `yaml` dep at runtime
+ * (ADR-0013) because they parse the manifest.
+ *
+ * Usage:
+ *   node contextkit/squads/agent-forge/cli/forge-ops.mjs <subcommand> [args] [--root <dir>] [--json]
+ */
+import { readFile } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { aggregateBudgets, diagnosePackage, discoverPackages, loadManifest, loadProvenance, summarize } from '../lib/package-ops.mjs';
+
+const SUB = ['list', 'show', 'doctor', 'policy', 'budget', 'audit'];
+
+function parseArgs(argv) {
+  const args = { sub: argv[0], target: null, root: 'agent-packages', json: false };
+  for (let i = 1; i < argv.length; i++) {
+    const flag = argv[i];
+    if (flag === '--root') args.root = argv[++i];
+    else if (flag === '--json') args.json = true;
+    else if (!args.target) args.target = flag;
+  }
+  return args;
+}
+
+function findOne(pkgs, target) {
+  if (!target) throw new Error('this subcommand requires <agent> (or <agent>@<version>)');
+  const [name, version] = target.includes('@') ? target.split('@') : [target, null];
+  const candidates = pkgs.filter((p) => p.name === name && (!version || p.version === version));
+  if (!candidates.length) throw new Error(`no package matches "${target}" under the registry`);
+  return candidates[candidates.length - 1];
+}
+
+async function cmdList(args) {
+  const pkgs = await discoverPackages(resolve(process.cwd(), args.root));
+  if (args.json) return console.log(JSON.stringify(pkgs, null, 2));
+  if (!pkgs.length) return console.log(`(no packages found under ${args.root}/)`);
+  console.log(`Agent Packages under ${args.root}/  (${pkgs.length}):`);
+  for (const pkg of pkgs) {
+    const manifest = await loadManifest(pkg.path).catch(() => null);
+    const provenance = await loadProvenance(pkg.path);
+    console.log('  ' + summarize(pkg, manifest, provenance));
+  }
+}
+
+async function cmdShow(args) {
+  const pkgs = await discoverPackages(resolve(process.cwd(), args.root));
+  const pkg = findOne(pkgs, args.target);
+  const manifest = await loadManifest(pkg.path);
+  const provenance = await loadProvenance(pkg.path);
+  const payload = { ...pkg, manifest, provenance };
+  if (args.json) return console.log(JSON.stringify(payload, null, 2));
+  console.log(`# ${pkg.name}@${pkg.version}\n`);
+  console.log(`name        : ${manifest?.metadata?.name}`);
+  console.log(`version     : ${manifest?.metadata?.version}`);
+  console.log(`description : ${manifest?.metadata?.description?.trim()}`);
+  console.log(`primary     : ${manifest?.spec?.model_selection?.primary?.provider}/${manifest?.spec?.model_selection?.primary?.model}`);
+  if (manifest?.spec?.model_selection?.fallback?.length) {
+    const fb = manifest.spec.model_selection.fallback[0];
+    console.log(`fallback    : ${fb.provider}/${fb.model}`);
+  }
+  console.log(`runtimes    : ${(manifest?.spec?.runtime_adapters || []).join(', ')}`);
+  console.log(`eval_passed : ${manifest?.metadata?.provenance?.eval_passed_at ?? 'NEVER'}`);
+  console.log(`forged_by   : ${manifest?.metadata?.provenance?.forged_by}`);
+  console.log(`hash        : ${manifest?.metadata?.provenance?.blueprint_hash}`);
+}
+
+async function cmdDoctor(args) {
+  const pkgs = await discoverPackages(resolve(process.cwd(), args.root));
+  if (!pkgs.length) return console.log(`(no packages found under ${args.root}/)`);
+  const report = [];
+  let bad = 0;
+  for (const pkg of pkgs) {
+    const result = await diagnosePackage(pkg.path);
+    report.push({ name: pkg.name, version: pkg.version, ...result });
+    if (!result.ok) bad += 1;
+  }
+  if (args.json) return console.log(JSON.stringify(report, null, 2));
+  for (const entry of report) {
+    if (entry.ok) console.log(`  ✅ ${entry.name}@${entry.version}`);
+    else {
+      console.log(`  ❌ ${entry.name}@${entry.version}`);
+      for (const problem of entry.problems) console.log(`     - ${problem}`);
+    }
+  }
+  console.log(`\n${pkgs.length - bad}/${pkgs.length} healthy${bad ? `; ${bad} need attention` : ''}.`);
+  if (bad) process.exit(1);
+}
+
+async function cmdPolicy(args) {
+  const pkgs = await discoverPackages(resolve(process.cwd(), args.root));
+  const pkg = findOne(pkgs, args.target);
+  const { parseYaml } = await import('../lib/yaml.mjs');
+  const pillars = {};
+  for (const name of ['cost', 'compliance', 'quality']) {
+    pillars[name] = parseYaml(await readFile(join(pkg.path, `governance/${name}.policy.yaml`), 'utf-8'));
+  }
+  pillars.fallback = parseYaml(await readFile(join(pkg.path, 'governance/fallback-chain.yaml'), 'utf-8'));
+  if (args.json) return console.log(JSON.stringify(pillars, null, 2));
+  console.log(`# Governance — ${pkg.name}@${pkg.version}\n`);
+  console.log('cost.budgets:'); console.log(JSON.stringify(pillars.cost?.budgets, null, 2));
+  console.log('\ncompliance.data_residency:'); console.log(JSON.stringify(pillars.compliance?.data_residency, null, 2));
+  console.log('\nquality.eval_gates.pre_release:'); console.log(JSON.stringify(pillars.quality?.eval_gates?.pre_release, null, 2));
+  console.log('\nfallback.chain:'); console.log(JSON.stringify(pillars.fallback?.chain, null, 2));
+}
+
+async function cmdBudget(args) {
+  const pkgs = await discoverPackages(resolve(process.cwd(), args.root));
+  const manifests = [];
+  for (const pkg of pkgs) {
+    const manifest = await loadManifest(pkg.path).catch(() => null);
+    if (manifest) manifests.push(manifest);
+  }
+  const result = aggregateBudgets(manifests);
+  if (args.json) return console.log(JSON.stringify(result, null, 2));
+  console.log(`# Forge Budget — aggregate across ${manifests.length} package(s)\n`);
+  console.log(`monthly target   : $${result.totals.monthly_target_usd.toFixed(2)}`);
+  console.log(`monthly hard cap : $${result.totals.monthly_hard_cap_usd.toFixed(2)}\n`);
+  for (const entry of result.perAgent) {
+    console.log(`  ${entry.name}  target $${entry.target}  cap $${entry.hardCap}  per-call max $${entry.perCallCap}`);
+  }
+}
+
+async function cmdAudit(args) {
+  const pkgs = await discoverPackages(resolve(process.cwd(), args.root));
+  const pkg = findOne(pkgs, args.target);
+  const auditPath = join(pkg.path, 'audit', `${pkg.name}.jsonl`);
+  let raw = '';
+  try { raw = await readFile(auditPath, 'utf-8'); } catch {
+    console.log(`(no audit log at ${auditPath})`);
+    return;
+  }
+  const events = raw.split('\n').filter(Boolean).map((line) => {
+    try { return JSON.parse(line); } catch { return null; }
+  }).filter(Boolean);
+  const totals = { calls: events.length, ok: 0, refused: 0, error: 0, killed: 0, totalCost: 0, fallbacks: 0 };
+  for (const event of events) {
+    if (event.outcome && totals[event.outcome] !== undefined) totals[event.outcome] += 1;
+    if (event.fallback_triggered) totals.fallbacks += 1;
+    totals.totalCost += Number(event.cost_usd ?? 0);
+  }
+  if (args.json) return console.log(JSON.stringify({ pkg, totals }, null, 2));
+  console.log(`# Audit — ${pkg.name}@${pkg.version}  (${events.length} events)\n`);
+  console.log(`  ok        : ${totals.ok}`);
+  console.log(`  refused   : ${totals.refused}`);
+  console.log(`  error     : ${totals.error}`);
+  console.log(`  killed    : ${totals.killed}`);
+  console.log(`  fallbacks : ${totals.fallbacks}`);
+  console.log(`  cost      : $${totals.totalCost.toFixed(4)}`);
+}
+
+const HANDLERS = { list: cmdList, show: cmdShow, doctor: cmdDoctor, policy: cmdPolicy, budget: cmdBudget, audit: cmdAudit };
+
+async function main(argv) {
+  const args = parseArgs(argv);
+  const handler = HANDLERS[args.sub];
+  if (!handler) {
+    console.error(`forge-ops: unknown subcommand "${args.sub}". Allowed: ${SUB.join(', ')}`);
+    process.exit(1);
+  }
+  await handler(args);
+}
+
+const HERE = fileURLToPath(import.meta.url);
+const ENTRY = process.argv[1] ? pathToFileURL(resolve(process.argv[1])).href : '';
+if (ENTRY === pathToFileURL(HERE).href) {
+  main(process.argv.slice(2)).catch((err) => {
+    console.error('forge-ops: ' + (err?.message ?? err));
+    process.exit(1);
+  });
+}
+
+export { cmdList, cmdShow, cmdDoctor, cmdPolicy, cmdBudget, cmdAudit };