mindforge-cc 11.4.0 → 11.5.1

package/bin/models/openai-provider.js

@@ -1,13 +1,36 @@
 /**
- * MindForge v2 — OpenAI Provider
+ * MindForge v2 — OpenAI-compatible Provider
+ *
+ * Wave 3 (3.6): parameterized for an arbitrary OpenAI-compatible base URL, so a
+ * single class backs OpenAI + Azure OpenAI + Together / Groq / OpenRouter / vLLM.
+ * baseUrl/apiKeyEnv are driven from an optional `base_url` field per model in
+ * revops.market_registry; default stays api.openai.com so existing behavior is
+ * unchanged. Errors are classified via the typed llm-errors taxonomy.
  */
 'use strict';
 
 const https = require('https');
+const http = require('http');
+const { URL } = require('url');
+const { classifyError } = require('./llm-errors');
 
 class OpenAIProvider {
-  constructor(apiKey) {
+  /**
+   * @param {string} apiKey
+   * @param {object} [opts]
+   * @param {string} [opts.baseUrl] e.g. "https://api.groq.com/openai/v1". Defaults
+   *   to OpenAI. Accepts with or without a trailing /v1.
+   */
+  constructor(apiKey, opts = {}) {
     this.apiKey = apiKey;
+    this.baseUrl = opts.baseUrl || process.env.OPENAI_BASE_URL || 'https://api.openai.com/v1';
+  }
+
+  _endpoint(pathSuffix) {
+    const base = this.baseUrl.replace(/\/+$/, '');
+    // Allow base with or without /v1; chat path is appended after the base.
+    const full = /\/v\d+$/.test(base) ? `${base}${pathSuffix}` : `${base}/v1${pathSuffix}`;
+    return new URL(full);
   }
 
   async complete(params) {
@@ -23,10 +46,14 @@ class OpenAIProvider {
       temperature,
     });
 
+    const url = this._endpoint('/chat/completions');
+    const transport = url.protocol === 'http:' ? http : https;
+
     return new Promise((resolve, reject) => {
-      const req = https.request({
-        hostname: 'api.openai.com',
-        path: '/v1/chat/completions',
+      const req = transport.request({
+        hostname: url.hostname,
+        port: url.port || undefined,
+        path: url.pathname,
         method: 'POST',
         headers: {
           'Content-Type': 'application/json',
@@ -41,7 +68,7 @@ class OpenAIProvider {
           try {
             const json = JSON.parse(body);
             if (res.statusCode !== 200) {
-              return reject(Object.assign(new Error(json.error?.message || 'OpenAI API error'), { status: res.statusCode }));
+              return reject(classifyError(json.error?.message || 'OpenAI API error', { provider: 'openai', status: res.statusCode }));
             }
 
             const inputTokens = json.usage.prompt_tokens;
@@ -88,10 +115,14 @@ class OpenAIProvider {
       stream: true,
     });
 
+    const url = this._endpoint('/chat/completions');
+    const transport = url.protocol === 'http:' ? http : https;
+
     return new Promise((resolve, reject) => {
-      const req = https.request({
-        hostname: 'api.openai.com',
-        path: '/v1/chat/completions',
+      const req = transport.request({
+        hostname: url.hostname,
+        port: url.port || undefined,
+        path: url.pathname,
         method: 'POST',
         headers: {
           'Content-Type': 'application/json',

package/bin/models/profiles-loader.js

@@ -0,0 +1,147 @@
+'use strict';
+
+/**
+ * MindForge — Layered agent-profile + orchestration-template resolver.
+ *
+ * Ports the two pure algorithms from ECC's ecc2/src/config/mod.rs as JSON (no
+ * TOML dep): reusable agent profiles with single-inheritance, and named
+ * multi-step orchestration templates with {{var}} interpolation. Lets MindForge
+ * declare reusable reviewer/security profiles and named swarm templates that
+ * feed model-router / model-broker / the swarm-execution skill.
+ *
+ *   resolveAgentProfile(profiles, name)
+ *     - single-inheritance via `inherits`, with cycle detection (throws on cycle)
+ *     - tool/dir lists merge-unique; scalars override; append_system_prompt
+ *       concatenates parent\n\nchild (ECC semantics).
+ *   resolveOrchestrationTemplate(templates, profiles, name, vars)
+ *     - {{var}} interpolation that FAILS LOUD listing every missing variable
+ *     - validates each referenced profile resolves.
+ */
+
+const PLACEHOLDER = /\{\{\s*([A-Za-z0-9_-]+)\s*\}\}/g;
+
+function mergeUnique(base, additions) {
+  const out = base.slice();
+  for (const v of (additions || [])) {
+    if (!out.includes(v)) out.push(v);
+  }
+  return out;
+}
+
+/**
+ * Resolve an agent profile by name against a { name: profileConfig } map.
+ * Each profileConfig may have: inherits, agent, model, allowedTools[],
+ * disallowedTools[], permissionMode, addDirs[], maxBudgetUsd, tokenBudget,
+ * appendSystemPrompt.
+ */
+function resolveAgentProfile(profiles, name, _chain) {
+  const chain = _chain || [];
+  if (chain.includes(name)) {
+    throw new Error(`agent profile inheritance cycle: ${[...chain, name].join(' -> ')}`);
+  }
+  const profile = profiles && profiles[name];
+  if (!profile) {
+    throw new Error(`Unknown agent profile: ${name}`);
+  }
+
+  chain.push(name);
+  const resolved = profile.inherits
+    ? resolveAgentProfile(profiles, profile.inherits, chain)
+    : { profileName: '', allowedTools: [], disallowedTools: [], addDirs: [], appendSystemPrompt: null };
+  chain.pop();
+
+  return applyProfile(resolved, name, profile);
+}
+
+function applyProfile(resolved, name, config) {
+  const next = Object.assign({}, resolved, { profileName: name });
+  if (config.agent != null) next.agent = config.agent;
+  if (config.model != null) next.model = config.model;
+  next.allowedTools = mergeUnique(resolved.allowedTools || [], config.allowedTools);
+  next.disallowedTools = mergeUnique(resolved.disallowedTools || [], config.disallowedTools);
+  if (config.permissionMode != null) next.permissionMode = config.permissionMode;
+  next.addDirs = mergeUnique(resolved.addDirs || [], config.addDirs);
+  if (config.maxBudgetUsd != null) next.maxBudgetUsd = config.maxBudgetUsd;
+  if (config.tokenBudget != null) next.tokenBudget = config.tokenBudget;
+
+  const parentPrompt = resolved.appendSystemPrompt || null;
+  const childPrompt = config.appendSystemPrompt || null;
+  next.appendSystemPrompt =
+    parentPrompt && childPrompt ? `${parentPrompt}\n\n${childPrompt}`
+      : parentPrompt || childPrompt || null;
+
+  return next;
+}
+
+/**
+ * Interpolate {{var}} placeholders. Collects ALL missing keys and throws a
+ * single error listing them (fail-loud), matching ECC's behavior.
+ */
+function interpolateRequired(value, vars) {
+  const missing = new Set();
+  const rendered = String(value).replace(PLACEHOLDER, (_m, key) => {
+    if (vars && Object.prototype.hasOwnProperty.call(vars, key)) return String(vars[key]);
+    missing.add(key);
+    return '';
+  });
+  if (missing.size > 0) {
+    throw new Error(`missing orchestration template variable(s): ${[...missing].sort().join(', ')}`);
+  }
+  return rendered;
+}
+
+function interpolateOptional(value, vars) {
+  if (value == null) return null;
+  const rendered = interpolateRequired(value, vars).trim();
+  return rendered === '' ? null : rendered;
+}
+
+/**
+ * Resolve a named orchestration template into concrete steps.
+ * templates: { name: { description?, project?, taskGroup?, agent?, profile?,
+ *   worktree?, steps: [{ name?, task, agent?, profile?, worktree?, project?, taskGroup? }] } }
+ */
+function resolveOrchestrationTemplate(templates, profiles, name, vars = {}) {
+  const template = templates && templates[name];
+  if (!template) throw new Error(`Unknown orchestration template: ${name}`);
+  if (!Array.isArray(template.steps) || template.steps.length === 0) {
+    throw new Error(`orchestration template ${name} has no steps`);
+  }
+
+  const description = interpolateOptional(template.description, vars);
+  const project = interpolateOptional(template.project, vars);
+  const taskGroup = interpolateOptional(template.taskGroup, vars);
+  const defaultAgent = interpolateOptional(template.agent, vars);
+  const defaultProfile = interpolateOptional(template.profile, vars);
+  if (defaultProfile) resolveAgentProfile(profiles, defaultProfile); // validate
+
+  const steps = template.steps.map((step, index) => {
+    let task;
+    try {
+      task = interpolateRequired(step.task, vars);
+    } catch (err) {
+      throw new Error(`resolve task for orchestration template ${name} step ${index + 1}: ${err.message}`);
+    }
+    const stepName = interpolateOptional(step.name, vars) || `step ${index + 1}`;
+    const agent = interpolateOptional(step.agent != null ? step.agent : defaultAgent, vars);
+    const profile = interpolateOptional(step.profile != null ? step.profile : defaultProfile, vars);
+    if (profile) resolveAgentProfile(profiles, profile); // validate
+
+    const worktree = step.worktree != null ? step.worktree
+      : (template.worktree != null ? template.worktree : false);
+
+    return {
+      name: stepName,
+      task,
+      agent,
+      profile,
+      worktree,
+      project: interpolateOptional(step.project != null ? step.project : project, vars),
+      taskGroup: interpolateOptional(step.taskGroup != null ? step.taskGroup : taskGroup, vars),
+    };
+  });
+
+  return { templateName: name, description, project, taskGroup, steps };
+}
+
+module.exports = { resolveAgentProfile, resolveOrchestrationTemplate, interpolateRequired };

package/bin/models/provider-registry.js

@@ -0,0 +1,59 @@
+/**
+ * MindForge — Provider Registry / Resolver seam.
+ *
+ * Adapted from ECC (src/llm/providers/resolver.py) as a pure internal seam.
+ * model-client.js consults resolveProvider(modelId) BEFORE its prefix-matching
+ * fallback, so providers are pluggable (e.g. add a custom OpenAI-compatible
+ * endpoint, or force a sovereign local provider) without editing _getProvider.
+ *
+ * Sovereignty / cost-capping / offline-test override:
+ *   MINDFORGE_LLM_PROVIDER=ollama  forces every resolve to the named provider.
+ *
+ * Does NOT adopt ECC's .llm.env file convention — that would violate MindForge's
+ * single-source-of-truth (MINDFORGE.md carries *_MODEL, .mindforge/config.json
+ * carries cost_routing). Registration is in-process only.
+ */
+'use strict';
+
+// name -> factory(modelId) => provider instance (or null if unavailable)
+const _registry = new Map();
+
+/**
+ * Register a provider factory under a name. The factory receives the modelId and
+ * returns a provider instance or null (e.g. when its API key/base URL is unset).
+ */
+function registerProvider(name, factory) {
+  if (typeof name !== 'string' || !name) throw new Error('provider name must be a non-empty string');
+  if (typeof factory !== 'function') throw new Error('provider factory must be a function');
+  _registry.set(name.toLowerCase(), factory);
+}
+
+function hasProvider(name) {
+  return _registry.has(String(name || '').toLowerCase());
+}
+
+/**
+ * Resolve a provider for a modelId. Honors the MINDFORGE_LLM_PROVIDER override
+ * first (sovereignty/offline), then any explicitly registered factory. Returns
+ * null if nothing matches — the caller's built-in prefix fallback then runs.
+ */
+function resolveProvider(modelId) {
+  const override = String(process.env.MINDFORGE_LLM_PROVIDER || '').trim().toLowerCase();
+  if (override && _registry.has(override)) {
+    return _registry.get(override)(modelId);
+  }
+  // No name-based match here by default; model-client owns the prefix routing.
+  // Registered factories are consulted by explicit name only (via the override
+  // or a caller that knows the provider name). This keeps the seam additive.
+  return null;
+}
+
+function listProviders() {
+  return [..._registry.keys()];
+}
+
+function _reset() {
+  _registry.clear();
+}
+
+module.exports = { registerProvider, resolveProvider, hasProvider, listProviders, _reset };

package/bin/review/ads-engine.js

@@ -8,7 +8,7 @@ const fs = require('fs');
 const path = require('path');
 const ModelClient = require('../models/model-client');
 const { calculateSoulScore, parseMetrics, synthesizeADSPlan } = require('./ads-synthesizer');
-const { v4: uuidv4 } = require('uuid');
+const crypto = require('crypto');
 
 async function runADSSynthesis(params) {
   const {
@@ -89,7 +89,7 @@ Finalize the PLAN.md. Include the [ADS_VERDICT]: [MERGED|BLUE|RED] (Score: X.XXX
   process.stdout.write('done.\n');
 
   // Finalize outputs
-  const adsUuid = uuidv4();
+  const adsUuid = crypto.randomUUID();
   const adrDir = path.join(process.cwd(), '.planning', 'decisions');
   if (!fs.existsSync(adrDir)) fs.mkdirSync(adrDir, { recursive: true });
 

package/bin/revops/market-evaluator.js

@@ -48,10 +48,31 @@ class MarketEvaluator {
 
   /**
    * Intelligence fallback for mission-critical tasks.
+   *
+   * Resolves a model that ACTUALLY exists in the market registry (with real
+   * cost/benchmark fields), so downstream cost accounting can never silently
+   * zero out. Order: configured premium_fallback_model -> highest-benchmark
+   * registry entry. FAILS CLOSED (throws) if the registry is empty rather than
+   * returning a phantom costless model — a missing cost must never let the
+   * AgRevOps hard-limit escalation become a no-op.
+   *
+   * (Previously hardcoded 'claude-3-5-sonnet', which is ABSENT from the registry
+   * — `gold` was undefined and this returned a model with no cost fields.)
    */
   getPremiumProvider() {
-    const gold = this.marketRegistry['claude-3-5-sonnet'];
-    return { model_id: 'claude-3-5-sonnet', ...gold };
+    const preferred = configManager.get('revops.premium_fallback_model', null);
+    if (preferred && this.marketRegistry[preferred]) {
+      return { model_id: preferred, ...this.marketRegistry[preferred] };
+    }
+
+    // Fall back to the highest-benchmark registry entry.
+    const ranked = Object.entries(this.marketRegistry)
+      .sort((a, b) => (b[1].benchmark || 0) - (a[1].benchmark || 0));
+    if (ranked.length === 0) {
+      throw new Error('[market-evaluator] no models in revops.market_registry — cannot resolve a premium provider (failing closed)');
+    }
+    const [id, data] = ranked[0];
+    return { model_id: id, ...data };
   }
 
   /**

package/bin/revops/router-steering-v2.js

@@ -8,6 +8,7 @@
 'use strict';
 
 const marketEvaluator = require('./market-evaluator');
+const configManager = require('../governance/config-manager');
 
 class RouterSteering {
   constructor() {
@@ -16,6 +17,16 @@ class RouterSteering {
 
   /**
    * Steers a reasoning task to the optimal model.
+   *
+   * SHADOW MODE (cost_routing.shadow_mode, default true): the latch that gates
+   * whether arbitrage steering is AUTHORITATIVE. When shadow_mode is on, we
+   * still COMPUTE and record the recommendation (for observation/telemetry) but
+   * mark the selection `shadow:true` / `authoritative:false` so callers do NOT
+   * act on the model switch — the steerer observes without changing routing.
+   * Only when shadow_mode is explicitly false does it return an authoritative
+   * selection. Previously this config was never read and steering was always
+   * live regardless of the latch (Wave 6 governance-theater fix).
+   *
    * @param {string} spanId - From Nexus Tracer
    * @param {string} taskDescription - Natural language task context
    * @param {Object} preferences - Manual overrides (optional)
@@ -23,6 +34,7 @@ class RouterSteering {
   async steer(spanId, taskDescription, preferences = {}) {
     const mir = preferences.mir || this._calculateMIR(taskDescription);
     const recommendation = marketEvaluator.getBestProvider(mir);
+    const shadowMode = configManager.get('cost_routing.shadow_mode', true) === true;
 
     const selection = {
       span_id: spanId,
@@ -30,11 +42,14 @@ class RouterSteering {
       selected_model: recommendation.model_id,
       provider: recommendation.provider,
       estimated_arbitrage_savings: marketEvaluator.calculateArbitrageSavings(recommendation.model_id),
+      shadow: shadowMode,
+      authoritative: !shadowMode,
       timestamp: new Date().toISOString()
     };
 
-    console.log(`[AgRevOps] Steered Span ${spanId} to ${selection.selected_model} (MIR: ${mir})`);
-    
+    const mode = shadowMode ? 'SHADOW (observe-only)' : 'LIVE';
+    console.log(`[AgRevOps] ${mode}: Span ${spanId} -> ${selection.selected_model} (MIR: ${mir})`);
+
     this.history.push(selection);
     return selection;
   }

package/bin/security/trust-boundaries.js

@@ -79,8 +79,18 @@ const IFS_TOKEN = /\$\{IFS\}|\$IFS/g;
 /**
  * De-obfuscates shell metacharacter tricks WITHOUT emulating a real shell.
  * Strips quotes (' ") and backslash escapes, collapses ${IFS}/$IFS to a space,
- * then collapses runs of whitespace. This turns r''m, r"m, r\m and
- * rm${IFS}-rf${IFS}/ back into plain `rm -rf /` so the existing patterns fire.
+ * removes bare `#` tokens, then collapses runs of whitespace. This turns r''m,
+ * r"m, r\m, rm${IFS}-rf${IFS}/ and the quoted-hash evasion rm "#" -rf / back
+ * into plain `rm -rf /` so the existing patterns fire.
+ *
+ * The `#` step closes a real bypass (audit, Wave 6): quote-stripping turns the
+ * DESTRUCTIVE `rm "#" -rf /` (in bash, "#" is a literal arg, so rm -rf / runs)
+ * into `rm # -rf /`, where the bare `#` sat between `rm` and its flags and broke
+ * the regex. We drop standalone `#` tokens (a `#` delimited by whitespace/start/
+ * end) so the de-obfuscated form collapses to `rm -rf /` and matches. We do NOT
+ * strip `#`-to-end-of-line (that would swallow flags after a genuine comment and
+ * could MASK a destructive prefix); only the lone token is removed.
+ *
  * Intentionally conservative: it removes characters rather than interpreting
  * them, which can only make a string MORE likely to match (fail-toward-block).
  */
@@ -89,7 +99,9 @@ function normalizeShell(input) {
     .split(NUL).join('')          // shells ignore NUL; never let it split a token
     .replace(IFS_TOKEN, ' ')       // ${IFS}/$IFS -> space
     .replace(/[\\'"]/g, '')        // drop backslash escapes and quote chars
-    .replace(/\s+/g, ' ');         // collapse whitespace runs
+    .replace(/(^|\s)#(?=\s|$)/g, '$1') // drop bare `#` tokens (post-unquote evasion)
+    .replace(/\s+/g, ' ')          // collapse whitespace runs
+    .trim();
 }
 
 /**
@@ -112,6 +124,11 @@ function isHighImpact(command) {
     /git\s+reset\s+--hard/i,
     /delete\s+from/i,
     /truncate\s+table/i,
+    // Unix `truncate -s <size> <path>` zeroes/shrinks a file in place — a
+    // destructive data-loss op the SQL-only `truncate table` pattern above
+    // misses. Match the size flag (-s, -s0, --size) so `truncate -s 0 <path>`
+    // is gated; benign words ("truncated output") and the SQL form are not.
+    /\btruncate\s+(-{1,2}s\w*|--size)\b/i,
     /\bmkfs(\.\w+)?\s+\/dev\//i,
     // #11: any dd write target, not just /dev/ (dd if=... of=important.db).
     // Original /dev/-only check is a subset of this, so it stays covered.

package/bin/utils/readiness-gate.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * MindForge — Reusable deterministic readiness-gate engine.
+ *
+ * Adapted from ECC's observability-readiness.js engine SHAPE (buildReport /
+ * renderText / {pass, fix, points, top_actions} / exit 0|1). This is the shared
+ * helper that bin/harness-audit.js's pattern and a release-readiness check-set
+ * both reuse, instead of shipping two near-identical engines.
+ *
+ * A "check set" is an array of { id, label, points, pass:boolean, fix:string }.
+ * buildReport scores them; renderText prints; runGate exits 0 (pass) or 1 (fail)
+ * so CI can block on it.
+ *
+ * Also ships a MindForge RELEASE-READINESS check set: version parity across
+ * package.json / MINDFORGE.md / config.json, RELEASENOTES + CHANGELOG presence,
+ * and required .planning artifacts.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const RUBRIC_VERSION = '2026-06-10';
+
+function fileExists(root, rel) {
+  return fs.existsSync(path.join(root, rel));
+}
+
+function safeRead(root, rel) {
+  try { return fs.readFileSync(path.join(root, rel), 'utf8'); } catch { return ''; }
+}
+
+function safeJson(text) {
+  try { return JSON.parse(text); } catch { return null; }
+}
+
+/**
+ * Score a check set into the standard report contract.
+ */
+function buildReport(name, checks) {
+  const maxScore = checks.reduce((s, c) => s + c.points, 0);
+  const score = checks.filter(c => c.pass).reduce((s, c) => s + c.points, 0);
+  const failed = checks.filter(c => !c.pass);
+  const topActions = failed
+    .slice()
+    .sort((a, b) => b.points - a.points)
+    .slice(0, 3)
+    .map(c => ({ action: c.fix, id: c.id, points: c.points }));
+
+  return {
+    gate: name,
+    deterministic: true,
+    rubric_version: RUBRIC_VERSION,
+    score,
+    max_score: maxScore,
+    pass: failed.length === 0,
+    checks: checks.map(c => ({ id: c.id, label: c.label, points: c.points, pass: c.pass })),
+    top_actions: topActions,
+  };
+}
+
+function renderText(report) {
+  const lines = [`${report.gate} readiness: ${report.score}/${report.max_score} ${report.pass ? '(PASS)' : '(FAIL)'}`, ''];
+  for (const c of report.checks) {
+    lines.push(`  ${c.pass ? 'PASS' : 'FAIL'}  [${c.points}] ${c.label}`);
+  }
+  if (report.top_actions.length) {
+    lines.push('', 'Top actions:');
+    report.top_actions.forEach((a, i) => lines.push(`  ${i + 1}) ${a.action} (${a.id})`));
+  }
+  return lines.join('\n');
+}
+
+/**
+ * MindForge release-readiness check set. CI can block a release on this.
+ */
+function releaseReadinessChecks(root) {
+  const pkg = safeJson(safeRead(root, 'package.json')) || {};
+  const mindforgeMd = safeRead(root, 'MINDFORGE.md');
+  const config = safeJson(safeRead(root, '.mindforge/config.json')) || {};
+
+  const pkgVersion = pkg.version || '';
+  const mdVersionMatch = mindforgeMd.match(/\[VERSION\]\s*=\s*([0-9]+\.[0-9]+\.[0-9]+)/);
+  const mdVersion = mdVersionMatch ? mdVersionMatch[1] : '';
+  const configVersion = config.version || '';
+
+  return [
+    {
+      id: 'version-parity-md',
+      label: 'package.json version matches MINDFORGE.md [VERSION]',
+      points: 3,
+      pass: Boolean(pkgVersion) && pkgVersion === mdVersion,
+      fix: `Align versions: package.json=${pkgVersion || '?'} vs MINDFORGE.md=${mdVersion || '?'}`,
+    },
+    {
+      id: 'version-parity-config',
+      label: 'package.json version matches .mindforge/config.json version',
+      points: 3,
+      pass: Boolean(pkgVersion) && pkgVersion === configVersion,
+      fix: `Align versions: package.json=${pkgVersion || '?'} vs config.json=${configVersion || '?'}`,
+    },
+    {
+      id: 'releasenotes',
+      label: 'RELEASENOTES.md present',
+      points: 2,
+      pass: fileExists(root, 'RELEASENOTES.md'),
+      fix: 'Add RELEASENOTES.md for this release.',
+    },
+    {
+      id: 'changelog',
+      label: 'CHANGELOG.md present',
+      points: 2,
+      pass: fileExists(root, 'CHANGELOG.md'),
+      fix: 'Add/update CHANGELOG.md.',
+    },
+    {
+      id: 'security-policy',
+      label: 'SECURITY.md + agentic threat model present',
+      points: 2,
+      pass: fileExists(root, 'SECURITY.md') && fileExists(root, 'MINDFORGE-AGENTIC-SECURITY.md'),
+      fix: 'Ensure SECURITY.md and MINDFORGE-AGENTIC-SECURITY.md exist.',
+    },
+    {
+      id: 'test-entrypoint',
+      label: 'test runner present (tests/run-all.js or npm test)',
+      points: 2,
+      pass: fileExists(root, 'tests/run-all.js') || typeof pkg.scripts?.test === 'string',
+      fix: 'Add tests/run-all.js or a package.json test script.',
+    },
+  ];
+}
+
+const GATES = {
+  release: releaseReadinessChecks,
+};
+
+function runGate(name, root) {
+  const builder = GATES[name];
+  if (!builder) throw new Error(`Unknown gate: ${name}. Available: ${Object.keys(GATES).join(', ')}`);
+  return buildReport(name, builder(root));
+}
+
+module.exports = { buildReport, renderText, runGate, releaseReadinessChecks, fileExists, safeRead, safeJson, RUBRIC_VERSION, GATES };
+
+// CLI: node bin/utils/readiness-gate.js [gate] [--format json] [--root dir]
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  let gate = 'release';
+  let format = 'text';
+  let root = process.cwd();
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--format') { format = (args[++i] || 'text').toLowerCase(); continue; }
+    if (a.startsWith('--format=')) { format = a.split('=')[1].toLowerCase(); continue; }
+    if (a === '--root') { root = path.resolve(args[++i] || process.cwd()); continue; }
+    if (a.startsWith('--root=')) { root = path.resolve(a.split('=')[1]); continue; }
+    if (!a.startsWith('-')) { gate = a; continue; }
+  }
+  try {
+    const report = runGate(gate, root);
+    if (format === 'json') process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    else process.stdout.write(renderText(report) + '\n');
+    process.exit(report.pass ? 0 : 1);
+  } catch (err) {
+    process.stderr.write(`Error: ${err.message}\n`);
+    process.exit(1);
+  }
+}