dual-brain 7.1.25 → 7.1.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dual-brain",
-  "version": "7.1.25",
+  "version": "7.1.26",
   "description": "AI orchestration across Claude + OpenAI subscriptions — smart routing, budget awareness, and dual-brain collaboration",
   "type": "module",
   "bin": {
@@ -20,7 +20,9 @@
     "./decompose": "./src/decompose.mjs",
     "./brief": "./src/brief.mjs",
     "./redact": "./src/redact.mjs",
-    "./calibration": "./src/calibration.mjs"
+    "./calibration": "./src/calibration.mjs",
+    "./models": "./src/models.mjs",
+    "./prompt-intel": "./src/prompt-intel.mjs"
   },
   "keywords": [
     "claude-code",
@@ -60,6 +62,7 @@
     "src/brief.mjs",
     "src/redact.mjs",
     "src/calibration.mjs",
+    "src/models.mjs",
     "src/pipeline.mjs",
     "src/context.mjs",
     "src/outcome.mjs",
@@ -71,10 +74,12 @@
     "src/index.mjs",
     "src/ledger.mjs",
     "src/intelligence.mjs",
+    "src/awareness.mjs",
     "src/tui.mjs",
     "src/living-docs.mjs",
     "src/install-hooks.mjs",
     "src/update-check.mjs",
+    "src/prompt-intel.mjs",
     "bin/*.mjs",
     "hooks/enforce-tier.mjs",
     "hooks/cost-logger.mjs",

package/src/awareness.mjs

@@ -0,0 +1,343 @@
+/**
+ * awareness.mjs — Environment awareness layer for dual-brain.
+ * Scans runtime environment once on startup and caches results with TTL.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+
+let _cache = null;
+let _cacheTime = 0;
+
+function safeExec(cmd, timeoutMs = 2000) {
+  try {
+    return execSync(cmd, {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: timeoutMs,
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function extractVersion(output) {
+  if (!output) return null;
+  const m = output.match(/(\d+\.\d+[\.\d]*)/);
+  return m ? m[1] : null;
+}
+
+function probeToolAvailability(name) {
+  const path = safeExec(`which ${name}`);
+  if (!path) return { available: false, version: null };
+  if (name === 'rg' || name === 'replit' || name === 'gh') {
+    return { available: true };
+  }
+  const versionOutput = safeExec(`${name} --version`);
+  return { available: true, version: extractVersion(versionOutput) };
+}
+
+function detectContainerType() {
+  const env = process.env;
+  if (env.REPL_ID || env.REPL_SLUG) return 'replit';
+  if (env.CODESPACES) return 'codespace';
+  if (env.CI || env.GITHUB_ACTIONS || env.GITLAB_CI || env.JENKINS_URL) return 'ci';
+  return 'local';
+}
+
+function scanSecrets() {
+  const keys = [
+    'OPENAI_API_KEY',
+    'ANTHROPIC_API_KEY',
+    'NPM_TOKEN',
+    'DATABASE_URL',
+    'GITHUB_TOKEN',
+    'REPLIT_DB_URL',
+  ];
+  const result = {};
+  for (const key of keys) {
+    result[key] = Boolean(process.env[key]);
+  }
+  return result;
+}
+
+function scanReplitTools() {
+  const home = homedir();
+  const candidates = [
+    join(home, '.replit-tools'),
+    join('/home/runner/workspace', '.replit-tools'),
+    join(process.cwd(), '.replit-tools'),
+  ];
+
+  let toolsDir = null;
+  for (const c of candidates) {
+    if (existsSync(c)) {
+      toolsDir = c;
+      break;
+    }
+  }
+
+  if (!toolsDir) {
+    return { installed: false, version: null, sessionArchivePath: null, capabilities: [] };
+  }
+
+  let version = null;
+  const versionFile = join(toolsDir, '.version');
+  if (existsSync(versionFile)) {
+    try { version = readFileSync(versionFile, 'utf8').trim() || null; } catch { /* skip */ }
+  }
+
+  const persistentBase = join(toolsDir, '.claude-persistent');
+  const projectDir = join(persistentBase, 'projects');
+  let sessionArchivePath = null;
+  if (existsSync(projectDir)) {
+    sessionArchivePath = projectDir;
+  } else if (existsSync(persistentBase)) {
+    sessionArchivePath = persistentBase;
+  }
+
+  const capabilities = [];
+  if (existsSync(join(toolsDir, '.claude-persistent'))) capabilities.push('sessions');
+  const hasSearch = existsSync(join(toolsDir, 'search')) || existsSync(join(toolsDir, 'search.mjs'));
+  if (hasSearch) capabilities.push('search');
+  const hasContext = existsSync(join(toolsDir, 'context')) || existsSync(join(toolsDir, 'context.mjs'));
+  if (hasContext) capabilities.push('context');
+  const hasMcp = existsSync(join(toolsDir, 'mcp-server')) || existsSync(join(toolsDir, 'mcp'));
+  if (hasMcp) capabilities.push('mcp');
+
+  return { installed: true, version, sessionArchivePath, capabilities };
+}
+
+function scanReplit(cwd) {
+  const env = process.env;
+  const isReplit = Boolean(env.REPL_ID || env.REPL_SLUG);
+
+  let hasDeployments = false;
+  const replitConfigPath = join(cwd, '.replit');
+  if (existsSync(replitConfigPath)) {
+    try {
+      const content = readFileSync(replitConfigPath, 'utf8');
+      hasDeployments = content.includes('[deployment]');
+    } catch { /* skip */ }
+  }
+
+  return {
+    isReplit,
+    replId: env.REPL_ID || null,
+    replSlug: env.REPL_SLUG || null,
+    hasDatabase: Boolean(env.DATABASE_URL),
+    hasKV: Boolean(env.REPLIT_DB_URL),
+    hasObjectStorage: Boolean(env.REPLIT_BUCKET_URL || env.OBJECT_STORAGE_URL),
+    hasAuth: existsSync(join(cwd, '.replit-auth')) || Boolean(env.REPLIT_AUTH),
+    hasDeployments,
+  };
+}
+
+function scanClaudeCode(cwd) {
+  const claudeDir = join(cwd, '.claude');
+  const homeClaudeDir = join(homedir(), '.claude');
+  const isInsideClaude = Boolean(
+    process.env.CLAUDE_CODE || process.env.CLAUDE_AGENT || process.env.ANTHROPIC_CLAUDE_CODE
+  );
+
+  let hooksDir = null;
+  const localHooks = join(claudeDir, 'hooks');
+  const rootHooks = join(cwd, 'hooks');
+  if (existsSync(localHooks)) {
+    hooksDir = localHooks;
+  } else if (existsSync(rootHooks)) {
+    hooksDir = rootHooks;
+  }
+
+  let mcpConfigured = false;
+  const mcpPaths = [
+    join(claudeDir, 'mcp.json'),
+    join(claudeDir, 'mcp_servers.json'),
+    join(homeClaudeDir, 'mcp.json'),
+  ];
+  for (const p of mcpPaths) {
+    if (existsSync(p)) { mcpConfigured = true; break; }
+  }
+
+  let settingsPath = null;
+  const settingsCandidates = [
+    join(claudeDir, 'settings.json'),
+    join(homeClaudeDir, 'settings.json'),
+  ];
+  for (const p of settingsCandidates) {
+    if (existsSync(p)) { settingsPath = p; break; }
+  }
+
+  return { isInsideClaude, hooksDir, mcpConfigured, settingsPath };
+}
+
+function scanDualBrain(cwd) {
+  let version = '0.0.0';
+  try {
+    const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'));
+    version = pkg.version ?? '0.0.0';
+  } catch { /* skip */ }
+
+  const livingDocsDir = join(cwd, '.dual-brain');
+  const livingDocsInit = existsSync(livingDocsDir);
+
+  let sessionCount = 0;
+  const sessionDir = join(cwd, '.dualbrain', 'sessions');
+  if (existsSync(sessionDir)) {
+    try {
+      sessionCount = readdirSync(sessionDir).filter(f => f.endsWith('.jsonl')).length;
+    } catch { /* skip */ }
+  }
+
+  const hasLedger = existsSync(join(cwd, '.dualbrain', 'ledger.jsonl'));
+  const hasFailureMemory = existsSync(join(cwd, '.dualbrain', 'failures.jsonl'));
+
+  return { version, livingDocsInit, sessionCount, hasLedger, hasFailureMemory };
+}
+
+export function scanEnvironment(cwd, options = {}) {
+  const ttl = options.ttl ?? 300000;
+  if (_cache && Date.now() - _cacheTime < ttl && !options.force) return _cache;
+
+  const resolvedCwd = resolve(cwd || process.cwd());
+
+  const container = {
+    type: detectContainerType(),
+    hostname: process.env.HOSTNAME || process.env.REPL_ID || 'unknown',
+    nodeVersion: process.version,
+    platform: process.platform,
+    arch: process.arch,
+  };
+
+  const toolNames = ['git', 'node', 'npm', 'codex', 'claude'];
+  const flagOnlyTools = ['rg', 'replit', 'gh'];
+  const tools = {};
+
+  for (const name of toolNames) {
+    tools[name] = probeToolAvailability(name);
+  }
+  for (const name of flagOnlyTools) {
+    const path = safeExec(`which ${name}`);
+    tools[name] = { available: Boolean(path) };
+  }
+
+  const secrets = scanSecrets();
+  const replitTools = scanReplitTools();
+  const replit = scanReplit(resolvedCwd);
+  const claudeCode = scanClaudeCode(resolvedCwd);
+  const dualBrain = scanDualBrain(resolvedCwd);
+
+  const report = {
+    scannedAt: Date.now(),
+    ttl,
+    container,
+    tools,
+    secrets,
+    replitTools,
+    replit,
+    claudeCode,
+    dualBrain,
+  };
+
+  _cache = report;
+  _cacheTime = Date.now();
+  return report;
+}
+
+export function formatEnvironment(report) {
+  const { container, tools, secrets, replitTools, replit, dualBrain } = report;
+
+  const nodeShort = container.nodeVersion.replace(/^v/, '').split('.')[0];
+  const containerLabel = container.type === 'replit'
+    ? 'Replit'
+    : container.type.charAt(0).toUpperCase() + container.type.slice(1);
+
+  const lines = [];
+
+  lines.push(`Environment: ${containerLabel} (node ${nodeShort}.x)`);
+
+  const toolEntries = [];
+  for (const [name, info] of Object.entries(tools)) {
+    if (info.available) toolEntries.push(`${name} ✓`);
+  }
+  if (toolEntries.length) lines.push(`Tools: ${toolEntries.join('  ')}`);
+
+  const secretMap = {
+    OPENAI_API_KEY: 'OpenAI',
+    ANTHROPIC_API_KEY: 'Anthropic',
+    NPM_TOKEN: 'npm',
+    GITHUB_TOKEN: 'GitHub',
+    DATABASE_URL: 'PostgreSQL',
+    REPLIT_DB_URL: 'KV',
+  };
+  const secretEntries = [];
+  for (const [key, label] of Object.entries(secretMap)) {
+    if (secrets[key]) secretEntries.push(`${label} ✓`);
+  }
+  if (secretEntries.length) lines.push(`Secrets: ${secretEntries.join('  ')}`);
+
+  const platformParts = [];
+  if (replit.hasDatabase) platformParts.push('PostgreSQL ✓');
+  if (replit.hasKV) platformParts.push('KV ✓');
+  if (replit.hasObjectStorage) platformParts.push('ObjectStorage ✓');
+  if (replit.hasAuth) platformParts.push('Auth ✓');
+  if (replit.hasDeployments) platformParts.push('Deployments ✓');
+  if (platformParts.length) lines.push(`Platform: ${platformParts.join('  ')}`);
+
+  if (replitTools.installed) {
+    const ver = replitTools.version ? `v${replitTools.version}` : 'installed';
+    const caps = replitTools.capabilities.join(', ');
+    lines.push(`replit-tools: ${ver}${caps ? ` (${caps})` : ''}`);
+  }
+
+  const dbFlag = dualBrain.hasLedger ? ', ledger ✓' : '';
+  const docsFlag = dualBrain.livingDocsInit ? 'living docs ✓' : 'living docs ✗';
+  lines.push(`dual-brain: v${dualBrain.version} (${docsFlag}${dbFlag})`);
+
+  return lines.join('\n');
+}
+
+export function getCapabilitySummary(report) {
+  const caps = [];
+
+  if (report.container.type !== 'unknown') {
+    caps.push(`${report.container.type}-container`);
+  }
+
+  if (report.replit.hasDatabase) caps.push('postgresql');
+  if (report.replit.hasKV) caps.push('replit-kv');
+  if (report.replit.hasObjectStorage) caps.push('object-storage');
+  if (report.replit.hasAuth) caps.push('replit-auth');
+  if (report.replit.hasDeployments) caps.push('replit-deployments');
+
+  if (report.tools.codex?.available) caps.push('codex-cli');
+  if (report.tools.claude?.available) caps.push('claude-cli');
+  if (report.tools.git?.available) caps.push('git');
+  if (report.tools.gh?.available) caps.push('github-cli');
+  if (report.tools.rg?.available) caps.push('ripgrep');
+
+  if (report.secrets.OPENAI_API_KEY) caps.push('openai-key');
+  if (report.secrets.ANTHROPIC_API_KEY) caps.push('anthropic-key');
+
+  if (report.replitTools.installed) {
+    for (const c of report.replitTools.capabilities) {
+      caps.push(`replit-tools-${c}`);
+    }
+  }
+
+  if (report.claudeCode.mcpConfigured) caps.push('mcp-configured');
+  if (report.claudeCode.hooksDir) caps.push('claude-hooks');
+
+  if (report.dualBrain.hasLedger) caps.push('dual-brain-ledger');
+  if (report.dualBrain.hasFailureMemory) caps.push('dual-brain-failure-memory');
+  if (report.dualBrain.livingDocsInit) caps.push('dual-brain-living-docs');
+
+  return caps;
+}
+
+export function invalidateCache() {
+  _cache = null;
+  _cacheTime = 0;
+}

package/src/models.mjs

@@ -0,0 +1,363 @@
+/**
+ * models.mjs — Static model intelligence registry for the Dual-Brain Orchestrator.
+ *
+ * Pure in-memory registry of AI model capabilities used by routing modules.
+ * No file I/O, no API calls. Updated with each package release.
+ */
+
+export const REGISTRY_VERSION = '2026-05-15';
+export const REGISTRY_UPDATED = '2026-05-15';
+
+export const MODEL_REGISTRY = Object.freeze({
+  'claude-opus-4-6': {
+    provider: 'anthropic',
+    name: 'Claude Opus 4.6',
+    tier: 'frontier',
+    contextWindow: 200000,
+    maxOutput: 32000,
+    strengths: ['complex reasoning', 'architecture', 'code review', 'long context', 'multi-step planning'],
+    weaknesses: ['speed', 'cost'],
+    costTier: 'high',
+    bestFor: ['think', 'review', 'architecture', 'complex debugging'],
+    speed: 'slow',
+    reasoning: true,
+    vision: true,
+    tools: true,
+    agentCapable: true,
+  },
+  'claude-sonnet-4-6': {
+    provider: 'anthropic',
+    name: 'Claude Sonnet 4.6',
+    tier: 'workhorse',
+    contextWindow: 200000,
+    maxOutput: 16000,
+    strengths: ['balanced speed/quality', 'code generation', 'editing', 'testing'],
+    weaknesses: ['less depth on architecture decisions'],
+    costTier: 'medium',
+    bestFor: ['execute', 'implement', 'test', 'fix'],
+    speed: 'medium',
+    reasoning: true,
+    vision: true,
+    tools: true,
+    agentCapable: true,
+  },
+  'claude-haiku-4-5-20251001': {
+    provider: 'anthropic',
+    name: 'Claude Haiku 4.5',
+    tier: 'fast',
+    contextWindow: 200000,
+    maxOutput: 8192,
+    strengths: ['speed', 'low cost', 'simple tasks', 'search', 'classification'],
+    weaknesses: ['complex reasoning', 'multi-step tasks'],
+    costTier: 'low',
+    bestFor: ['search', 'classify', 'simple edits', 'grep'],
+    speed: 'fast',
+    reasoning: false,
+    vision: true,
+    tools: true,
+    agentCapable: true,
+  },
+  'gpt-5.5': {
+    provider: 'openai',
+    name: 'GPT-5.5',
+    tier: 'frontier',
+    contextWindow: 1050000,
+    maxOutput: 128000,
+    strengths: ['massive context', 'complex professional work', 'reasoning', 'web search', 'code interpreter'],
+    weaknesses: ['cost', 'latency on complex reasoning'],
+    costTier: 'premium',
+    bestFor: ['think', 'review', 'research', 'long-context analysis'],
+    speed: 'medium',
+    reasoning: true,
+    vision: true,
+    tools: true,
+    agentCapable: true,
+  },
+  'o3': {
+    provider: 'openai',
+    name: 'o3',
+    tier: 'reasoning',
+    contextWindow: 200000,
+    maxOutput: 100000,
+    strengths: ['deep reasoning', 'math', 'code', 'science', 'multi-step logic'],
+    weaknesses: ['speed', 'cost', 'simple tasks overkill'],
+    costTier: 'premium',
+    bestFor: ['think', 'complex debugging', 'algorithm design', 'security analysis'],
+    speed: 'slow',
+    reasoning: true,
+    vision: true,
+    tools: true,
+    agentCapable: true,
+  },
+  'gpt-4o': {
+    provider: 'openai',
+    name: 'GPT-4o',
+    tier: 'workhorse',
+    contextWindow: 128000,
+    maxOutput: 16384,
+    strengths: ['balanced', 'fast', 'multimodal', 'tool use'],
+    weaknesses: ['less depth than frontier models'],
+    costTier: 'medium',
+    bestFor: ['execute', 'implement', 'chat', 'multimodal'],
+    speed: 'fast',
+    reasoning: false,
+    vision: true,
+    tools: true,
+    agentCapable: true,
+  },
+  'gpt-4o-mini': {
+    provider: 'openai',
+    name: 'GPT-4o Mini',
+    tier: 'fast',
+    contextWindow: 128000,
+    maxOutput: 16384,
+    strengths: ['very fast', 'very cheap', 'good enough for simple tasks'],
+    weaknesses: ['complex reasoning', 'nuanced code review'],
+    costTier: 'low',
+    bestFor: ['search', 'classify', 'simple tasks', 'formatting'],
+    speed: 'fast',
+    reasoning: false,
+    vision: true,
+    tools: true,
+    agentCapable: false,
+  },
+});
+
+const COST_TIER_ORDER = ['low', 'medium', 'high', 'premium'];
+const SPEED_ORDER = ['fast', 'medium', 'slow'];
+const TIER_ORDER = ['fast', 'workhorse', 'reasoning', 'frontier'];
+
+const MODEL_QUIRKS = {
+  'claude-opus-4-6': [
+    'Best for architecture decisions',
+    'Use for code review when quality matters',
+    'Expensive — reserve for high-value tasks',
+  ],
+  'claude-sonnet-4-6': [
+    'Best general-purpose worker',
+    'Good balance of speed and quality',
+    'Use Agent(model: "sonnet") for work dispatch',
+  ],
+  'claude-haiku-4-5-20251001': [
+    'Best for fast search and classification',
+    'Not reliable for multi-step edits',
+    'Use for disposable search agents',
+  ],
+  'gpt-5.5': [
+    'Massive 1M+ context window',
+    'Good challenger for dual-brain think',
+    'Web search and code interpreter available',
+  ],
+  'o3': [
+    'Purpose-built for deep reasoning chains',
+    'Strong challenger for security analysis',
+    'Slow — avoid for quick tasks',
+  ],
+  'gpt-4o': [
+    'Fast and multimodal',
+    'Solid fallback for execute-tier GPT work',
+    'Native tool use support',
+  ],
+  'gpt-4o-mini': [
+    'Cheapest GPT option for simple tasks',
+    'Not agent-capable — single-shot only',
+    'Good for classification and formatting',
+  ],
+};
+
+export function getModel(modelId) {
+  return MODEL_REGISTRY[modelId] ?? null;
+}
+
+export function getModelsForTask(taskType, provider = null) {
+  const entries = Object.entries(MODEL_REGISTRY);
+
+  const filtered = entries.filter(([, m]) => {
+    if (provider && m.provider !== provider) return false;
+    return true;
+  });
+
+  filtered.sort(([, a], [, b]) => {
+    const aMatch = a.bestFor.includes(taskType) ? 1 : 0;
+    const bMatch = b.bestFor.includes(taskType) ? 1 : 0;
+    if (bMatch !== aMatch) return bMatch - aMatch;
+
+    const aTier = TIER_ORDER.indexOf(a.tier);
+    const bTier = TIER_ORDER.indexOf(b.tier);
+    if (bTier !== aTier) return bTier - aTier;
+
+    return SPEED_ORDER.indexOf(a.speed) - SPEED_ORDER.indexOf(b.speed);
+  });
+
+  return filtered.map(([id, m]) => ({ id, ...m }));
+}
+
+export function getBestModel(taskType, constraints = {}) {
+  const { provider = null, maxCost = null, preferSpeed = false, requireReasoning = false, minContext = 0 } = constraints;
+
+  let candidates = getModelsForTask(taskType, provider);
+
+  if (requireReasoning) {
+    candidates = candidates.filter(m => m.reasoning);
+  }
+
+  if (minContext > 0) {
+    candidates = candidates.filter(m => m.contextWindow >= minContext);
+  }
+
+  if (maxCost) {
+    const maxIdx = COST_TIER_ORDER.indexOf(maxCost);
+    if (maxIdx !== -1) {
+      candidates = candidates.filter(m => COST_TIER_ORDER.indexOf(m.costTier) <= maxIdx);
+    }
+  }
+
+  if (preferSpeed) {
+    candidates.sort((a, b) => SPEED_ORDER.indexOf(a.speed) - SPEED_ORDER.indexOf(b.speed));
+  }
+
+  return candidates[0] ?? null;
+}
+
+export function compareModels(modelA, modelB) {
+  const a = MODEL_REGISTRY[modelA];
+  const b = MODEL_REGISTRY[modelB];
+
+  if (!a || !b) {
+    return {
+      contextAdvantage: 'tie',
+      speedAdvantage: 'tie',
+      costAdvantage: 'tie',
+      reasoningAdvantage: 'tie',
+      recommendation: 'One or both model IDs are unknown.',
+    };
+  }
+
+  const ctxAdv = a.contextWindow > b.contextWindow ? 'a'
+    : b.contextWindow > a.contextWindow ? 'b'
+    : 'tie';
+
+  const spdA = SPEED_ORDER.indexOf(a.speed);
+  const spdB = SPEED_ORDER.indexOf(b.speed);
+  const spdAdv = spdA < spdB ? 'a' : spdB < spdA ? 'b' : 'tie';
+
+  const costA = COST_TIER_ORDER.indexOf(a.costTier);
+  const costB = COST_TIER_ORDER.indexOf(b.costTier);
+  const costAdv = costA < costB ? 'a' : costB < costA ? 'b' : 'tie';
+
+  const rsnAdv = (a.reasoning && !b.reasoning) ? 'a'
+    : (b.reasoning && !a.reasoning) ? 'b'
+    : 'tie';
+
+  const aAdvantages = [ctxAdv, spdAdv, costAdv, rsnAdv].filter(v => v === 'a').length;
+  const bAdvantages = [ctxAdv, spdAdv, costAdv, rsnAdv].filter(v => v === 'b').length;
+
+  let recommendation;
+  if (aAdvantages > bAdvantages) {
+    recommendation = `Use ${a.name} for ${a.bestFor.slice(0, 2).join('/')}; ${b.name} as a lighter alternative.`;
+  } else if (bAdvantages > aAdvantages) {
+    recommendation = `Use ${b.name} for ${b.bestFor.slice(0, 2).join('/')}; ${a.name} as a lighter alternative.`;
+  } else {
+    recommendation = `${a.name} and ${b.name} are comparable — choose based on provider availability.`;
+  }
+
+  return { contextAdvantage: ctxAdv, speedAdvantage: spdAdv, costAdvantage: costAdv, reasoningAdvantage: rsnAdv, recommendation };
+}
+
+export function getRegistryAge() {
+  const updated = new Date(REGISTRY_UPDATED);
+  const now = new Date();
+  return Math.floor((now - updated) / (1000 * 60 * 60 * 24));
+}
+
+const COST_SYMBOL = { low: '$', medium: '$$', high: '$$$', premium: '$$$$' };
+
+function fmtCtx(n) {
+  if (n >= 1000000) return `${(n / 1000000).toFixed(2)}M ctx`;
+  return `${Math.round(n / 1000)}K ctx`;
+}
+
+export function formatModelTable(provider = null) {
+  const groups = {};
+  for (const [id, m] of Object.entries(MODEL_REGISTRY)) {
+    if (provider && m.provider !== provider) continue;
+    if (!groups[m.provider]) groups[m.provider] = [];
+    groups[m.provider].push({ id, ...m });
+  }
+
+  const lines = [];
+  const providerLabels = { anthropic: 'Claude Models', openai: 'OpenAI Models' };
+  const providerOrder = ['anthropic', 'openai'];
+
+  for (const prov of providerOrder) {
+    if (!groups[prov]) continue;
+    lines.push(`${providerLabels[prov] ?? prov}:`);
+    for (const m of groups[prov]) {
+      const displayName = m.provider === 'anthropic' ? m.name.replace(/^Claude /, '') : m.name;
+      const name = displayName.padEnd(12);
+      const tier = m.tier.padEnd(10);
+      const ctx = fmtCtx(m.contextWindow).padEnd(10);
+      const speed = m.speed.padEnd(8);
+      const cost = (COST_SYMBOL[m.costTier] ?? '?').padEnd(6);
+      const tasks = m.bestFor.slice(0, 2).join('/');
+      lines.push(`  ${name}${tier}${ctx}${speed}${cost}${tasks}`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n').trimEnd();
+}
+
+export function getModelQuirks(modelId) {
+  return MODEL_QUIRKS[modelId] ?? [];
+}
+
+export function suggestModel(intent, risk, complexity, availableProviders = ['anthropic', 'openai']) {
+  const intentLower = (intent || '').toLowerCase();
+
+  const TASK_MAP = {
+    think: ['architect', 'design', 'plan', 'review', 'security', 'audit', 'analysis', 'analyze'],
+    execute: ['implement', 'edit', 'fix', 'refactor', 'test', 'build', 'write', 'update', 'create'],
+    search: ['search', 'find', 'grep', 'look', 'explore', 'classify', 'format', 'list'],
+  };
+
+  let taskType = 'execute';
+  for (const [type, keywords] of Object.entries(TASK_MAP)) {
+    if (keywords.some(kw => intentLower.includes(kw))) {
+      taskType = type;
+      break;
+    }
+  }
+
+  if ((risk === 'critical' || risk === 'high') && taskType !== 'think') {
+    taskType = 'think';
+  }
+
+  const requireReasoning = complexity === 'complex' || risk === 'critical';
+  const preferSpeed = risk === 'low' && complexity === 'simple';
+  const maxCost = risk === 'low' && complexity !== 'complex' ? 'medium' : null;
+
+  const candidates = getModelsForTask(taskType)
+    .filter(m => availableProviders.includes(m.provider))
+    .filter(m => !requireReasoning || m.reasoning)
+    .filter(m => !maxCost || COST_TIER_ORDER.indexOf(m.costTier) <= COST_TIER_ORDER.indexOf(maxCost));
+
+  if (preferSpeed) {
+    candidates.sort((a, b) => SPEED_ORDER.indexOf(a.speed) - SPEED_ORDER.indexOf(b.speed));
+  }
+
+  const best = candidates[0] ?? null;
+  if (!best) {
+    return { model: null, reason: 'No suitable model found for the given constraints.', alternatives: [] };
+  }
+
+  const reason = [
+    `Selected ${best.name} for ${taskType}-tier work`,
+    risk !== 'low' ? `(${risk} risk)` : null,
+    requireReasoning ? '— reasoning required' : null,
+  ].filter(Boolean).join(' ');
+
+  const alternatives = candidates.slice(1, 3).map(m => ({ id: m.id, name: m.name }));
+
+  return { model: best.id, reason, alternatives };
+}

package/src/prompt-intel.mjs

@@ -0,0 +1,325 @@
+// prompt-intel.mjs — Layer 3 prompt analysis, enrichment, risk detection, and intervention routing.
+// Pure functions only. No I/O, no exec. Caller provides projectBrief and calibration.
+
+const INTENT_PATTERNS = {
+  fix:      /\b(?:fix|bug|broken|error|crash|failing|fails|wrong|issue|problem|broken|not\s+working|doesn't\s+work|doesn't\s+work)\b/i,
+  feature:  /\b(?:add|create|build|implement|new|introduce|support|enable)\b/i,
+  refactor: /\b(?:refactor|clean\s+up|reorganize|simplify|extract|restructure|dedup|consolidate|move)\b/i,
+  review:   /\b(?:review|check|audit|look\s+at|examine|inspect|assess|evaluate)\b/i,
+  ship:     /\b(?:ship|deploy|publish|release|push|merge|go\s+live|launch)\b/i,
+  explore:  /\b(?:what|how|why|where|find|search|explain|show\s+me|tell\s+me|list|which)\b/i,
+  test:     /\b(?:test|spec|coverage|assert|jest|mocha|vitest|unit\s+test|integration)\b/i,
+  docs:     /\b(?:doc|readme|comment|jsdoc|document|explain|annotate)\b/i,
+  deploy:   /\b(?:deploy|provision|infrastructure|ci|cd|pipeline|k8s|kubernetes|docker)\b/i,
+};
+
+const RISK_PATTERNS = [
+  { type: 'destructive',  severity: 'block', re: /\b(?:delete\s+all|remove\s+all|drop\s+all|wipe|destroy|rm\s+-rf|truncate\s+all|nuke)\b/i, detail: 'Prompt contains mass-destructive operation' },
+  { type: 'force_push',   severity: 'block', re: /(?:force\s+push|--force|-f\s+origin|reset\s+--hard)/i,                                      detail: 'Prompt implies forced git operation' },
+  { type: 'secret',       severity: 'warn',  re: /\b(?:api\s+key|access\s+token|secret\s+key|\.env|private\s+key|bearer\s+token)\b/i,         detail: 'Touches secret or credential material' },
+  { type: 'auth',         severity: 'warn',  re: /\b(?:auth(?:entication)?|login|logout|password|credential|jwt|oauth|session\s+token)\b/i,    detail: 'Touches authentication code' },
+  { type: 'deploy',       severity: 'warn',  re: /\b(?:ship\s+to|deploy\s+to|release\s+to|push\s+to\s+prod)\b/i,                              detail: 'Targets a deployment action' },
+  { type: 'data_loss',    severity: 'warn',  re: /\b(?:drop\s+table|alter\s+table|schema\s+migration|migrate\s+data|database\s+reset)\b/i,     detail: 'Touches schema or migration — data loss risk' },
+  { type: 'production',   severity: 'warn',  re: /\b(?:production|prod\b|live\s+environment|live\s+site)\b/i,                                  detail: 'References production environment' },
+];
+
+const FILE_REF_RE   = /(?:src\/|\.mjs|\.tsx?|\.jsx?|\.json|\.ya?ml|\.sh|line\s+\d+|\bL\d+\b)/i;
+const FUNC_REF_RE   = /\b\w+\((?:\)|[^)]{0,40}\))/;
+const STEP_RE       = /\b(?:step\s+\d|first[,\s]|then[,\s]|finally[,\s]|must|should\s+(?:use|call|return|handle))\b/i;
+const CRITERIA_RE   = /\b(?:accept(?:ance)?\s+criteria|definition\s+of\s+done|constraints?|requirements?|must\s+(?:not|be|have)|should\s+not)\b/i;
+
+function clamp(v, min = 1, max = 5) {
+  return Math.min(max, Math.max(min, v));
+}
+
+function scoreSpecificity(prompt) {
+  const hasFile  = FILE_REF_RE.test(prompt);
+  const hasFunc  = FUNC_REF_RE.test(prompt);
+  const hasLine  = /\bL\d+\b|\bline\s+\d+/i.test(prompt);
+  const words    = prompt.trim().split(/\s+/).length;
+
+  if (hasFile && (hasFunc || hasLine)) return 5;
+  if (hasFile || hasFunc) return 4;
+  if (words >= 10) return 3;
+  if (words >= 5)  return 2;
+  return 1;
+}
+
+function scoreActionability(prompt) {
+  const hasStep    = STEP_RE.test(prompt);
+  const hasVerb    = /\b(?:fix|add|remove|refactor|create|update|write|delete|move|rename|replace|ensure|make)\b/i.test(prompt);
+  const hasOutcome = /\b(?:so\s+that|in\s+order\s+to|result(?:ing)?\s+in|should\s+(?:return|output|produce|show))\b/i.test(prompt);
+  const words      = prompt.trim().split(/\s+/).length;
+
+  if (hasStep && hasVerb) return 5;
+  if (hasOutcome && hasVerb) return 4;
+  if (hasVerb && words >= 6) return 3;
+  if (hasVerb) return 2;
+  return 1;
+}
+
+function scoreSafety(risks) {
+  if (risks.some(r => r.severity === 'block')) return 1;
+  if (risks.some(r => r.type === 'auth' || r.type === 'secret' || r.type === 'production')) return 2;
+  if (risks.some(r => r.type === 'deploy' || r.type === 'data_loss')) return 3;
+  if (risks.length > 0) return 4;
+  return 5;
+}
+
+function scoreCompleteness(prompt) {
+  const hasCriteria = CRITERIA_RE.test(prompt);
+  const hasContext  = /\b(?:because|since|currently|right\s+now|the\s+issue\s+is|error\s+is|it\s+(?:crashes|fails|returns))\b/i.test(prompt);
+  const hasScope    = FILE_REF_RE.test(prompt);
+  const words       = prompt.trim().split(/\s+/).length;
+
+  if (hasCriteria && hasContext && hasScope) return 5;
+  if ((hasCriteria || hasContext) && hasScope) return 4;
+  if (hasContext || (hasScope && words >= 8)) return 3;
+  if (words >= 6) return 2;
+  return 1;
+}
+
+function detectIntent(prompt) {
+  const counts = {};
+  for (const [type, re] of Object.entries(INTENT_PATTERNS)) {
+    const matches = prompt.match(new RegExp(re.source, 'gi')) ?? [];
+    if (matches.length > 0) counts[type] = matches.length;
+  }
+
+  const entries = Object.entries(counts).sort((a, b) => b[1] - a[1]);
+  if (entries.length === 0) {
+    return { type: 'unknown', confidence: 0, keywords: [] };
+  }
+
+  const [topType, topCount] = entries[0];
+  const totalMatches = Object.values(counts).reduce((s, n) => s + n, 0);
+  const confidence = Math.min(1, topCount / Math.max(totalMatches, 1) * (entries.length === 1 ? 1.5 : 1));
+
+  const allWords = prompt.match(new RegExp(INTENT_PATTERNS[topType].source, 'gi')) ?? [];
+  const keywords = [...new Set(allWords.map(w => w.toLowerCase().trim()))].slice(0, 5);
+
+  return { type: topType, confidence: Math.round(confidence * 100) / 100, keywords };
+}
+
+function detectRisks(prompt) {
+  const found = [];
+  for (const { type, severity, re, detail } of RISK_PATTERNS) {
+    if (re.test(prompt)) {
+      found.push({ type, severity, detail });
+    }
+  }
+  return found;
+}
+
+function findMissingInfo(prompt, intent, specificity, completeness) {
+  const missing = [];
+
+  if (intent.type === 'fix') {
+    if (!/error|exception|crash|fail|wrong|issue/i.test(prompt)) missing.push('error description or failure symptom');
+    if (!FILE_REF_RE.test(prompt)) missing.push('affected file or component');
+    if (!/repro|reproduce|steps|trigger|when\s+I/i.test(prompt)) missing.push('reproduction steps');
+  }
+
+  if (intent.type === 'feature') {
+    if (!FILE_REF_RE.test(prompt)) missing.push('target file or module to add feature to');
+    if (!/user\s+(?:can|should|will)|should\s+(?:allow|enable|support)/i.test(prompt)) missing.push('user-facing outcome');
+  }
+
+  if (intent.type === 'refactor' && !FILE_REF_RE.test(prompt)) {
+    missing.push('which file or function to refactor');
+  }
+
+  if (specificity < 2) missing.push('file name or component reference');
+  if (completeness < 2) missing.push('context about current behavior');
+
+  return [...new Set(missing)].slice(0, 3);
+}
+
+function chooseIntervention(quality, risks, calibration) {
+  if (risks.some(r => r.severity === 'block')) return 'block';
+
+  const autonomy    = calibration?.autonomy    ?? 3;
+  const specificity = calibration?.specificity ?? 3;
+
+  if (quality.score >= 4 && risks.length === 0 && autonomy > 4) return 'pass';
+  if (quality.score < 2 && specificity < 3)  return 'confirm_rewrite';
+  if (quality.score < 3 && quality.completeness <= 2) return 'clarify_once';
+  return 'silent_enrich';
+}
+
+export function analyzePrompt(prompt, projectBrief, calibration) {
+  const risks        = detectRisks(prompt);
+  const intent       = detectIntent(prompt);
+  const specificity  = scoreSpecificity(prompt);
+  const actionability= scoreActionability(prompt);
+  const safety       = scoreSafety(risks);
+  const completeness = scoreCompleteness(prompt);
+  const score        = Math.round(((specificity + actionability + safety + completeness) / 4) * 10) / 10;
+
+  const quality = { score, specificity, actionability, safety, completeness };
+  const missingInfo   = findMissingInfo(prompt, intent, specificity, completeness);
+  const intervention  = chooseIntervention(quality, risks, calibration);
+
+  return {
+    original:     prompt,
+    quality,
+    intent,
+    risks,
+    missingInfo,
+    intervention,
+  };
+}
+
+function relevantDirtyFiles(dirtyFiles, intent) {
+  if (!Array.isArray(dirtyFiles) || dirtyFiles.length === 0) return [];
+
+  const INTENT_HINTS = {
+    fix:      /\bfix|bug|error\b/i,
+    ship:     /.*/,
+    review:   /.*/,
+    feature:  /src\//i,
+    refactor: /src\//i,
+    test:     /test|spec/i,
+    docs:     /\.md$|readme/i,
+  };
+
+  const re = INTENT_HINTS[intent.type] ?? /src\//i;
+  return dirtyFiles.filter(f => re.test(f)).slice(0, 4);
+}
+
+export function enrichPrompt(prompt, projectBrief, analysis) {
+  if (!projectBrief) return prompt;
+
+  const lines = [prompt, ''];
+  const { branch, dirtyFiles = [], recentCommits = [], aheadOfRemote = 0, recentFailures = [] } = projectBrief;
+  const { intent } = analysis;
+
+  const uncommitted = dirtyFiles.length;
+  if (branch || uncommitted > 0) {
+    const parts = [];
+    if (branch) parts.push(`${branch} branch`);
+    if (uncommitted > 0) parts.push(`${uncommitted} uncommitted file${uncommitted !== 1 ? 's' : ''}`);
+    if (aheadOfRemote > 0) parts.push(`${aheadOfRemote} ahead of remote`);
+    lines.push(`[Context: ${parts.join(', ')}]`);
+  }
+
+  const relFiles = relevantDirtyFiles(dirtyFiles, intent);
+  if (relFiles.length > 0) {
+    lines.push(`[Files: ${relFiles.join(', ')}]`);
+  }
+
+  if (recentCommits.length > 0 && ['fix', 'review', 'ship'].includes(intent.type)) {
+    lines.push(`[Recent: ${recentCommits[0].slice(0, 80)}]`);
+  }
+
+  if (recentFailures.length > 0) {
+    const related = recentFailures.find(f => {
+      const fp = (f.prompt ?? '').toLowerCase();
+      const pp = prompt.toLowerCase();
+      const words = pp.split(/\s+/).filter(w => w.length > 3);
+      return words.some(w => fp.includes(w));
+    });
+    if (related) {
+      lines.push(`[Failures: previous attempt failed — ${(related.error ?? 'unknown error').slice(0, 80)}]`);
+    }
+  }
+
+  return lines.slice(0, lines.length).join('\n');
+}
+
+export function formatRiskWarning(risks) {
+  if (!risks || risks.length === 0) return '';
+  const lines = ['⚠️  RISK DETECTED'];
+  for (const risk of risks) {
+    const icon   = risk.severity === 'block' ? '🔴' : '🟡';
+    const suffix = risk.severity === 'block' ? ' (BLOCKED)' : ' (proceed with caution)';
+    lines.push(`  ${icon} ${risk.type}: ${risk.detail}${suffix}`);
+  }
+  return lines.join('\n');
+}
+
+export function formatQuality(analysis) {
+  const { quality, intent, intervention } = analysis;
+  const q = quality;
+  return `Quality: ${q.score}/5 (specificity:${q.specificity} action:${q.actionability} safety:${q.safety} complete:${q.completeness})\nIntent: ${intent.type} (${intent.confidence}) | Intervention: ${intervention}`;
+}
+
+export function suggestImprovement(analysis) {
+  const { intent, missingInfo, quality } = analysis;
+
+  const templates = {
+    fix:      `Fix the [specific function or behavior] in [file path] — it [symptom/error], causing [impact]`,
+    feature:  `Add [feature name] to [file/component] — it should [user outcome] when [condition]`,
+    refactor: `Refactor [function/module] in [file] to [desired outcome] — keep [what to preserve]`,
+    review:   `Review [file or PR] for [concern] — focus on [specific area or risk]`,
+    ship:     `Ship [branch/feature] — verify [test status], then merge and publish`,
+    explore:  `Explain how [specific mechanism] works in [file/component]`,
+    test:     `Write tests for [function/module] in [file] covering [edge cases]`,
+    docs:     `Document [function or module] in [file] — cover [params, return, examples]`,
+    deploy:   `Deploy [service] to [environment] — confirm [readiness checks]`,
+    unknown:  `Describe what you want changed, which file it's in, and what the expected result is`,
+  };
+
+  const base = templates[intent.type] ?? templates.unknown;
+  const tips  = missingInfo.length > 0
+    ? ` (missing: ${missingInfo.join(', ')})`
+    : '';
+
+  return `Try: '${base}'${tips}`;
+}
+
+export function getTaskTemplate(intentType) {
+  const templates = {
+    fix: {
+      needs:    ['error_description', 'affected_files', 'reproduction_steps'],
+      auto_add: ['test_expectations', 'rollback_plan'],
+    },
+    feature: {
+      needs:    ['feature_description', 'affected_area'],
+      auto_add: ['test_plan', 'acceptance_criteria'],
+    },
+    refactor: {
+      needs:    ['target_code', 'desired_outcome'],
+      auto_add: ['test_preservation', 'scope_boundary'],
+    },
+    review: {
+      needs:    ['scope'],
+      auto_add: ['recent_changes', 'risk_areas'],
+    },
+    ship: {
+      needs:    ['readiness_check'],
+      auto_add: ['test_status', 'git_status', 'uncommitted_changes'],
+    },
+    explore: {
+      needs:    ['topic'],
+      auto_add: ['related_files', 'recent_changes'],
+    },
+    test: {
+      needs:    ['target_function', 'test_framework'],
+      auto_add: ['edge_cases', 'existing_coverage'],
+    },
+    docs: {
+      needs:    ['target_module'],
+      auto_add: ['param_descriptions', 'usage_example'],
+    },
+    deploy: {
+      needs:    ['target_environment', 'service_name'],
+      auto_add: ['pre_deploy_checks', 'rollback_plan'],
+    },
+    unknown: {
+      needs:    ['prompt_clarification'],
+      auto_add: [],
+    },
+  };
+
+  return templates[intentType] ?? templates.unknown;
+}
+
+export function shouldBlock(analysis) {
+  return analysis.risks.some(r => r.severity === 'block');
+}
+
+export function getBlockReason(analysis) {
+  const blocking = analysis.risks.find(r => r.severity === 'block');
+  return blocking ? blocking.detail : null;
+}