dual-brain 0.1.0

package/src/decompose.mjs

@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+/**
+ * decompose.mjs — Task graph decomposition for the Dual-Brain Orchestrator HEAD.
+ *
+ * Splits complex prompts into a dependency-aware task graph using heuristic
+ * analysis. Pure data — returns a plan, does NOT spawn agents.
+ *
+ * Exports: decompose, isSimpleTask, taskGraphToWaves
+ */
+
+import { detectTask, classifyIntent, extractPaths } from './detect.mjs';
+import { loadPlaybook } from './playbook.mjs';
+
+// ─── Role inference ───────────────────────────────────────────────────────────
+
+/**
+ * Map a tier + intent to the appropriate agent role.
+ * @param {string} tier
+ * @param {string} intent
+ * @returns {'researcher'|'implementer'|'reviewer'|'verifier'}
+ */
+function inferRole(tier, intent) {
+  if (tier === 'search') return 'researcher';
+  if (tier === 'think') {
+    if (intent === 'review') return 'reviewer';
+    return 'researcher'; // architect/planner stays researcher (read-only)
+  }
+  // execute tier
+  if (intent === 'test') return 'verifier';
+  if (intent === 'review') return 'reviewer';
+  return 'implementer';
+}
+
+// ─── Conjunction splitter ─────────────────────────────────────────────────────
+
+const CONJUNCTIONS = /\s+(?:and(?:\s+also)?|then|also|plus|after\s+that|additionally|as\s+well\s+as)\s+/i;
+
+/**
+ * Split a prompt on natural-language conjunctions into clauses.
+ * @param {string} prompt
+ * @returns {string[]}
+ */
+function splitClauses(prompt) {
+  const parts = prompt.split(CONJUNCTIONS).map(s => s.trim()).filter(Boolean);
+  return parts.length > 1 ? parts : [prompt];
+}
+
+// ─── File ownership inference ─────────────────────────────────────────────────
+
+/**
+ * Extract file globs from a clause, falling back to intent-based heuristics.
+ * @param {string} clause
+ * @param {string} intent
+ * @param {string[]} contextFiles  — file paths provided in decompose context
+ * @returns {string[]}
+ */
+function inferOwnership(clause, intent, contextFiles = []) {
+  const readOnly = ['search', 'explain', 'compare', 'review'];
+  if (readOnly.includes(intent)) return []; // read-only roles own nothing
+
+  // Paths mentioned explicitly in the clause
+  const mentioned = extractPaths(clause);
+  if (mentioned.length > 0) return mentioned;
+
+  // Paths from context that relate to this clause (simple keyword match)
+  const clauseLower = clause.toLowerCase();
+  const related = contextFiles.filter(f => {
+    const base = f.split('/').pop() ?? '';
+    return clauseLower.includes(base.replace(/\.[^.]+$/, ''));
+  });
+  if (related.length > 0) return related;
+
+  // Structural heuristics by intent
+  if (intent === 'test')     return ['**/*.test.*', '**/*.spec.*'];
+  if (intent === 'document') return ['**/*.md'];
+  if (intent === 'format')   return ['**/*'];
+
+  return [];
+}
+
+// ─── Dependency ordering ──────────────────────────────────────────────────────
+
+const ROLE_ORDER = { researcher: 0, reviewer: 1, implementer: 2, verifier: 3 };
+
+/**
+ * Build dependency graph: earlier-role tasks must complete before later-role tasks.
+ * @param {{ id: string, role: string }[]} tasks
+ * @returns {{ [taskId: string]: string[] }}  task id → list of dependent task ids
+ */
+function buildDependencies(tasks) {
+  const deps = {};
+  for (const task of tasks) {
+    deps[task.id] = [];
+  }
+
+  // Each task depends on all tasks with a strictly lower role rank
+  for (let i = 0; i < tasks.length; i++) {
+    for (let j = 0; j < i; j++) {
+      if (ROLE_ORDER[tasks[j].role] < ROLE_ORDER[tasks[i].role]) {
+        deps[tasks[i].id].push(tasks[j].id);
+      }
+    }
+  }
+
+  return deps;
+}
+
+// ─── Exported: taskGraphToWaves ───────────────────────────────────────────────
+
+/**
+ * Topological sort: group tasks into dependency layers (waves).
+ * Tasks with no unmet dependencies form the earliest wave.
+ * @param {{ id: string, dependsOn: string[] }[]} tasks
+ * @returns {string[][]}  each element is an array of task IDs in that wave
+ */
+export function taskGraphToWaves(tasks) {
+  const remaining = new Set(tasks.map(t => t.id));
+  const satisfied = new Set();
+  const waves = [];
+
+  while (remaining.size > 0) {
+    const wave = [];
+    for (const task of tasks) {
+      if (!remaining.has(task.id)) continue;
+      const allDepsSatisfied = task.dependsOn.every(dep => satisfied.has(dep));
+      if (allDepsSatisfied) wave.push(task.id);
+    }
+
+    if (wave.length === 0) {
+      // Cycle or unresolvable — dump remaining tasks into one last wave
+      waves.push([...remaining]);
+      break;
+    }
+
+    waves.push(wave);
+    for (const id of wave) {
+      remaining.delete(id);
+      satisfied.add(id);
+    }
+  }
+
+  return waves;
+}
+
+// ─── Exported: isSimpleTask ───────────────────────────────────────────────────
+
+/**
+ * Returns true if the detection indicates a trivial or simple task that does
+ * not need decomposition.
+ * @param {{ complexity: string }} detection
+ * @returns {boolean}
+ */
+export function isSimpleTask(detection) {
+  return detection.complexity === 'trivial' || detection.complexity === 'simple';
+}
+
+// ─── Playbook → task graph ────────────────────────────────────────────────────
+
+/**
+ * Convert a loaded playbook's steps into a task graph.
+ * @param {object} playbook
+ * @param {string[]} contextFiles
+ * @returns {{ id, title, goal, tier, role, owns, dependsOn, consensus, risk }[]}
+ */
+function playbookToTasks(playbook, contextFiles = []) {
+  const steps = playbook.steps ?? [];
+  const tasks = steps.map(step => {
+    const tier = step.tier ?? 'execute';
+    const intent = tier === 'think' ? 'architecture' : tier === 'search' ? 'search' : 'edit';
+    const role = inferRole(tier, intent);
+    return {
+      id:        step.id,
+      title:     step.title,
+      goal:      step.goal,
+      tier,
+      role,
+      owns:      inferOwnership(step.goal, intent, contextFiles),
+      dependsOn: [], // will be filled below
+      consensus: step.consensus === true,
+      risk:      'medium',
+    };
+  });
+
+  // Each task depends on the immediately prior task (sequential playbook flow)
+  for (let i = 1; i < tasks.length; i++) {
+    tasks[i].dependsOn = [tasks[i - 1].id];
+  }
+
+  return tasks;
+}
+
+// ─── Heuristic task graph from clause splitting ───────────────────────────────
+
+/**
+ * Build a task graph from clause-split sub-prompts via independent detection.
+ * @param {string[]} clauses
+ * @param {string[]} files
+ * @returns {{ id, title, goal, tier, role, owns, dependsOn, consensus, risk }[]}
+ */
+function clausesToTasks(clauses, files = []) {
+  const raw = clauses.map((clause, idx) => {
+    const detection = detectTask({ prompt: clause, files });
+    const { intent, tier, risk } = detection;
+    const role = inferRole(tier, intent);
+    return {
+      id:        `task-${idx + 1}`,
+      title:     clause.length > 60 ? clause.slice(0, 57) + '...' : clause,
+      goal:      clause,
+      tier,
+      role,
+      owns:      inferOwnership(clause, intent, files),
+      dependsOn: [], // placeholder
+      consensus: risk === 'critical' || (risk === 'high' && tier === 'think'),
+      risk,
+    };
+  });
+
+  // Build dependency graph and fill in dependsOn
+  const deps = buildDependencies(raw);
+  for (const task of raw) {
+    task.dependsOn = deps[task.id];
+  }
+
+  return raw;
+}
+
+// ─── Exported: decompose ──────────────────────────────────────────────────────
+
+/**
+ * Decompose a prompt into a dependency-aware task graph.
+ * Pure data — returns a plan, does NOT spawn agents.
+ *
+ * @param {string} prompt
+ * @param {{ files?: string[], cwd?: string, repo?: object, profile?: object }} [context]
+ * @returns {{
+ *   tasks: object[],
+ *   waves: string[][],
+ *   confidence: 'high'|'medium'|'low',
+ *   needsResearch: boolean,
+ *   parallelizable: boolean,
+ * }}
+ */
+export function decompose(prompt, context = {}) {
+  const { files = [], cwd } = context;
+
+  // 1. Classify the full prompt
+  const detection = detectTask({ prompt, files });
+
+  // 2. Trivial/simple → single-task graph
+  if (isSimpleTask(detection)) {
+    const { intent, tier, risk } = detection;
+    const role = inferRole(tier, intent);
+    const task = {
+      id:        'task-1',
+      title:     prompt.length > 60 ? prompt.slice(0, 57) + '...' : prompt,
+      goal:      prompt,
+      tier,
+      role,
+      owns:      inferOwnership(prompt, intent, files),
+      dependsOn: [],
+      consensus: false,
+      risk,
+    };
+    return {
+      tasks:          [task],
+      waves:          [['task-1']],
+      confidence:     'high',
+      needsResearch:  false,
+      parallelizable: false,
+    };
+  }
+
+  // 3. Try to match a playbook
+  const playbook = loadPlaybook(detection.intent, cwd);
+  if (playbook) {
+    const tasks = playbookToTasks(playbook, files);
+    const waves = taskGraphToWaves(tasks);
+    return {
+      tasks,
+      waves,
+      confidence:     'high',
+      needsResearch:  false,
+      parallelizable: waves.some(w => w.length > 1),
+    };
+  }
+
+  // 4. Heuristic clause splitting
+  const clauses = splitClauses(prompt);
+  const hasResearch = files.length === 0 && detection.complexity !== 'trivial';
+
+  // If splitting didn't help (single clause), add a research task prefix for complex tasks
+  let allClauses = clauses;
+  if (clauses.length === 1 && hasResearch) {
+    allClauses = [`Research: find all files and context relevant to: ${prompt}`, ...clauses];
+  }
+
+  const tasks = clausesToTasks(allClauses, files);
+  const waves = taskGraphToWaves(tasks);
+
+  // Confidence: medium if we split cleanly (>1 clause), low if ambiguous
+  const confidence = clauses.length > 1 ? 'medium' : 'low';
+
+  return {
+    tasks,
+    waves,
+    confidence,
+    needsResearch:  hasResearch,
+    parallelizable: waves.some(w => w.length > 1),
+  };
+}
+
+// ─── CLI ──────────────────────────────────────────────────────────────────────
+
+if (process.argv[1] && new URL(import.meta.url).pathname === process.argv[1]) {
+  const args = process.argv.slice(2);
+  const prompt = args.find(a => !a.startsWith('--')) || '';
+
+  if (!prompt) {
+    console.error('Usage: node src/decompose.mjs "task description" [--files a,b]');
+    process.exit(1);
+  }
+
+  const filesFlag = args.find(a => a.startsWith('--files=')) ||
+    (args.includes('--files') ? args[args.indexOf('--files') + 1] : null);
+  const files = filesFlag
+    ? filesFlag.replace(/^--files=/, '').split(',').map(f => f.trim()).filter(Boolean)
+    : [];
+
+  const result = decompose(prompt, { files });
+  console.log(JSON.stringify(result, null, 2));
+}

package/src/detect.mjs

@@ -0,0 +1,345 @@
+#!/usr/bin/env node
+// detect.mjs — Task detection for dual-brain. Self-contained, no internal imports.
+// Exports: detectTask, classifyIntent, classifyRisk, estimateComplexity, inferTier, extractPaths, classifySpecialist
+
+import { readFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// ─── Intent definitions ────────────────────────────────────────────────────────
+
+const INTENTS = {
+  search:       /\b(grep|find|locate|where is|where are|list|explore|read|look up|look for|check|what is|show me|display)\b/i,
+  explain:      /\b(explain|walk me through|what does|how does|describe|summarize|understand|clarify)\b/i,
+  compare:      /\b(compare|contrast|difference|versus|vs\.?|trade.?off|which is better|pros and cons|benchmark|performance)\b/i,
+  document:     /\b(document|docs?|readme|jsdoc|typedoc|api docs|write docs|add docs|update docs)\b/i,
+  format:       /\b(format|lint|prettier|style|indent|whitespace|typo|typos|comment[s]?|reformat)\b/i,
+  planning:     /\b(plan|roadmap|strategy|prioritize|break down|decompose|prioritise)\b/i,
+  architecture: /\b(design|architect|architecture|propose|how should we|system design|system architecture)\b/i,
+  security:     /\b(auth(?:enticat\w*)?|credential|secret|token|password|encrypt|permission[s]?|vulnerability|vulnerabilities|CVE|oauth|jwt|api.?key)\b/i,
+  review:       /\b(review|audit|check for issues|evaluate|assess|inspect code|code review)\b/i,
+  debug:        /\b(debug|investigate|why (is|does|isn't|doesn't)|trace|diagnose|figure out|broken|not working|failing|regression)\b/i,
+  test:         /\b(test[s]?|spec[s]?|add test|fix test|test coverage|unit test|e2e|integration test|jest|vitest|mocha)\b/i,
+  refactor:     /\b(refactor|restructure|reorganize|reorganise|extract|split|consolidate|clean up|cleanup|dedupe|dedup)\b/i,
+  edit:         /\b(fix|add|update|modify|change|rename|move|replace|write|implement|create|remove|delete|insert)\b/i,
+};
+
+const INTENT_PRIORITY = [
+  'security', 'architecture', 'planning', 'compare', 'review',
+  'debug', 'refactor', 'test', 'explain', 'document', 'format', 'search', 'edit',
+];
+
+// ─── Risk patterns (file path based) ──────────────────────────────────────────
+
+const RISK_PATTERNS = [
+  { level: 'critical', regex: /\b(auth|credential|secret|\.env|key[s]?|token[s]?|password|encrypt|certificate|cert[s]?|\.pem|\.key)\b/i, label: 'security-sensitive' },
+  { level: 'high',     regex: /\b(billing|payment|migration|deploy|ci[-/]cd|\.github\/workflows|security|permission|policy|schema\.prisma|schema\.sql|api[-_]?contract|openapi|swagger)\b/i, label: 'high-impact infrastructure' },
+  { level: 'medium',   regex: /\b(test|spec|\.test\.|\.spec\.|shared|util[s]?|lib\/|public[-_]?api|integrat|config|\.config\.)\b/i, label: 'shared/tested code' },
+  { level: 'low',      regex: /\b(readme|\.md$|docs?\/|comment|format|lint|\.prettierrc|local[-_]?script|internal[-_]?only|changelog)\b/i, label: 'docs/formatting' },
+];
+
+// ─── Description-level risk keywords ──────────────────────────────────────────
+
+const RISK_KEYWORDS = [
+  { level: 'critical', regex: /\b(auth|secret|credential|token|password|encrypt|certificate|oauth|jwt|api.?key|vulnerability|CVE)\b/i },
+  { level: 'high',     regex: /\b(billing|payment|migration|deploy|ci.?cd|security|permission|policy|schema|openapi|swagger|production|prod)\b/i },
+  { level: 'medium',   regex: /\b(test|spec|config|shared|util|lib|integration|public.?api)\b/i },
+  { level: 'low',      regex: /\b(readme|docs?|comment|format|lint|changelog|typo|whitespace)\b/i },
+];
+
+const DESIGN_IMPACT_PATTERNS = [
+  /\bbin\/dual-brain\.mjs\b/,
+  /\bsrc\/(?:tui|profile|detect|decide|dispatch|session|health|index)\.mjs\b/,
+  /\bhooks\/(?:head-guard|enforce-tier|budget-balancer|dual-brain-think|dual-brain-review|wave-orchestrator)\.mjs\b/,
+  /\bVISION\.md\b/,
+];
+
+const LEVEL_ORDER = { critical: 3, high: 2, medium: 1, low: 0 };
+
+// ─── Helpers / Exported functions ─────────────────────────────────────────────
+
+function higherRisk(a, b) { return LEVEL_ORDER[a] >= LEVEL_ORDER[b] ? a : b; }
+
+/** Extract file paths from free-form text. */
+function extractPaths(text) {
+  if (!text) return [];
+  const matches = text.match(/(?:^|\s|["'`])([./~]?(?:[\w@.-]+\/)+[\w@.*-]+(?:\.\w+)?)/g);
+  if (!matches) return [];
+  return matches.map(m => m.trim().replace(/^["'`]/, ''));
+}
+
+/** Classify risk from an array of file paths. Returns { level, riskyFiles }. */
+function classifyRisk(paths) {
+  if (!paths || paths.length === 0) {
+    return { level: 'low', riskyFiles: [] };
+  }
+
+  let highestLevel = 'low';
+  const riskyFiles = [];
+
+  for (const p of paths) {
+    for (const pattern of RISK_PATTERNS) {
+      if (pattern.regex.test(p)) {
+        if (LEVEL_ORDER[pattern.level] > LEVEL_ORDER['low']) {
+          riskyFiles.push({ path: p, risk: pattern.level, reason: pattern.label });
+        }
+        if (LEVEL_ORDER[pattern.level] > LEVEL_ORDER[highestLevel]) {
+          highestLevel = pattern.level;
+          if (highestLevel === 'critical') break;
+        }
+        break; // use highest-priority match for this path
+      }
+    }
+    if (highestLevel === 'critical') break;
+  }
+
+  return { level: highestLevel, riskyFiles };
+}
+
+/** Extract the dominant intent from a task description. */
+function classifyIntent(prompt) {
+  for (const key of INTENT_PRIORITY) {
+    if (INTENTS[key].test(prompt)) return key;
+  }
+  return 'edit';
+}
+
+/** Determine complexity from description, file count, risk, intent, prior failures. */
+function estimateComplexity({ prompt, fileCount = 0, risk = 'low', intent = 'edit', priorFailures = 0 }) {
+  const isAmbiguous = prompt.length > 120 || /\b(and also|as well as|plus|additionally|also)\b/i.test(prompt);
+
+  if (priorFailures >= 2 || intent === 'architecture' || risk === 'critical' || fileCount >= 6) {
+    return 'complex';
+  }
+  if (fileCount >= 3 || intent === 'refactor' || intent === 'debug' || risk === 'high' || isAmbiguous) {
+    return 'moderate';
+  }
+  if (fileCount <= 2 && (risk === 'low' || risk === 'medium')) {
+    if (intent === 'format' || (fileCount <= 1 && risk === 'low')) return 'trivial';
+    return 'simple';
+  }
+  return 'moderate';
+}
+
+/** Map intent + risk + complexity → tier (think / search / execute). */
+function inferTier({ intent, risk, complexity, effort, specialistTierBias }) {
+  const thinkIntents = ['architecture', 'security', 'planning', 'compare', 'review'];
+  if (thinkIntents.includes(intent) || risk === 'critical') return 'think';
+
+  // Specialist tier_bias can elevate to think before general tier logic
+  if (specialistTierBias === 'think') return 'think';
+
+  const searchIntents = ['search', 'explain', 'format'];
+  if (searchIntents.includes(intent) && effort === 'low') return 'search';
+
+  return 'execute';
+}
+
+/** Whether this task likely requires writing/editing files. */
+function requiresWrite(intent) {
+  const readOnly = ['search', 'explain', 'compare', 'review'];
+  return !readOnly.includes(intent);
+}
+
+/** Build a one-sentence explanation of the classification. */
+function buildExplanation({ intent, risk, complexity, fileCount, priorFailures }) {
+  const parts = [];
+
+  const complexityWord = { trivial: 'Trivial', simple: 'Simple', moderate: 'Moderate', complex: 'Complex' }[complexity];
+  const riskWord = risk === 'low' ? 'low-risk' : `${risk}-risk`;
+  parts.push(`${complexityWord} ${riskWord} ${intent}`);
+
+  if (fileCount > 0) parts.push(`touching ${fileCount} file${fileCount === 1 ? '' : 's'}`);
+  if (priorFailures > 0) parts.push(`with ${priorFailures} prior failure${priorFailures === 1 ? '' : 's'} — elevated effort`);
+
+  return parts.join(' ') + '.';
+}
+
+/** Main detection function. Input: { prompt, files?, priorFailures? } */
+function detectTask(input) {
+  const { prompt = '', files = [], priorFailures = 0 } = input;
+
+  // 1. Intent
+  const intent = classifyIntent(prompt);
+
+  // 2. Paths and risk
+  const extractedPaths = extractPaths(prompt);
+  const allPaths = [...files, ...extractedPaths];
+  const { level: pathRiskLevel, riskyFiles } = classifyRisk(allPaths);
+  const designImpact = allPaths.some(p => DESIGN_IMPACT_PATTERNS.some(re => re.test(p)));
+
+  // 3. Keyword risk from description
+  let keywordRisk = 'low';
+  for (const { level, regex } of RISK_KEYWORDS) {
+    if (regex.test(prompt)) { keywordRisk = level; break; }
+  }
+
+  const risk = higherRisk(pathRiskLevel, keywordRisk);
+  const fileCount = files.length;
+
+  // 4. Complexity
+  const complexity = estimateComplexity({ prompt, fileCount, risk, intent, priorFailures });
+
+  // 5. Effort
+  const effortOrder = ['low', 'medium', 'high', 'xhigh'];
+  function bumpEffort(e, n = 1) {
+    return effortOrder[Math.min(effortOrder.indexOf(e) + n, effortOrder.length - 1)];
+  }
+
+  let effort = { trivial: 'low', simple: 'medium', moderate: 'high', complex: 'high' }[complexity];
+  if (risk === 'critical' && LEVEL_ORDER[effort] < LEVEL_ORDER['high']) effort = 'high';
+  if (priorFailures >= 2) {
+    effort = 'xhigh';
+  } else if (priorFailures === 1) {
+    effort = bumpEffort(effort, 1);
+  }
+  if (intent === 'format' || intent === 'search') {
+    if (LEVEL_ORDER[effort] > LEVEL_ORDER['medium']) effort = 'medium';
+  }
+  if ((intent === 'architecture' || intent === 'security') && LEVEL_ORDER[effort] < LEVEL_ORDER['high']) {
+    effort = 'high';
+  }
+
+  // 6. Specialist
+  const specialistResult = classifySpecialist(prompt, files);
+  const specialistDef = SPECIALIST_DEFS[specialistResult.specialist] || null;
+  const specialistTierBias = specialistDef?.tier_bias || null;
+
+  // 7. Tier
+  const tier = inferTier({ intent, risk, complexity, effort, specialistTierBias });
+
+  // 8. Explanation
+  const explanation = buildExplanation({ intent, risk, complexity, fileCount, priorFailures });
+
+  return {
+    intent,
+    risk,
+    complexity,
+    effort,
+    tier,
+    fileCount,
+    riskyFiles,
+    designImpact,
+    requiresWrite: requiresWrite(intent),
+    explanation,
+    specialist: specialistResult,
+  };
+}
+
+// ─── Specialist registry ──────────────────────────────────────────────────────
+
+const SPECIALIST_REGISTRY_PATH = resolve(__dirname, '../agents/specialists/registry.json');
+
+const DEFAULT_SPECIALISTS = {
+  python:     { triggers: { extensions: ['.py', '.pyx', '.pyi'], keywords: ['python', 'pip', 'pytest', 'django', 'flask', 'asyncio'] } },
+  typescript: { triggers: { extensions: ['.ts', '.tsx', '.mts'], keywords: ['typescript', 'tsc', 'generics', 'react', 'next', 'node'] } },
+  html:       { triggers: { extensions: ['.html', '.css', '.scss', '.svg'], keywords: ['html', 'css', 'accessibility', 'a11y', 'aria', 'responsive', 'tailwind'] } },
+  linux:      { triggers: { extensions: ['.sh', '.bash', '.conf', '.service', '.dockerfile'], keywords: ['linux', 'bash', 'shell', 'systemd', 'nginx', 'docker', 'ssh', 'deploy'] } },
+  security:   { triggers: { extensions: [], keywords: ['auth', 'oauth', 'jwt', 'credential', 'secret', 'encrypt', 'vulnerability', 'vulnerabilities', 'audit', 'owasp', 'xss', 'csrf'] }, tier_bias: 'think' },
+};
+
+function loadSpecialistRegistry() {
+  try {
+    const raw = readFileSync(SPECIALIST_REGISTRY_PATH, 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed.specialists || DEFAULT_SPECIALISTS;
+  } catch {
+    return DEFAULT_SPECIALISTS;
+  }
+}
+
+const SPECIALIST_DEFS = loadSpecialistRegistry();
+
+/**
+ * Classify which specialist domain best matches the prompt and file list.
+ * Returns { specialist, confidence, triggers }.
+ */
+function classifySpecialist(prompt = '', files = []) {
+  const promptLower = prompt.toLowerCase();
+  const scores = {};
+  const matchedTriggers = {};
+
+  for (const [name, def] of Object.entries(SPECIALIST_DEFS)) {
+    const { extensions = [], keywords = [] } = def.triggers || {};
+    let score = 0;
+    const hits = [];
+
+    // +2 per matching file extension
+    for (const file of files) {
+      for (const ext of extensions) {
+        if (file.endsWith(ext)) {
+          score += 2;
+          hits.push(ext);
+          break; // count each file once per specialist
+        }
+      }
+    }
+
+    // +1 per matching keyword in prompt
+    for (const kw of keywords) {
+      // Use word-boundary-aware match where possible
+      const re = new RegExp(`\\b${kw.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'i');
+      if (re.test(promptLower)) {
+        score += 1;
+        hits.push(kw);
+      }
+    }
+
+    scores[name] = score;
+    matchedTriggers[name] = hits;
+  }
+
+  // Find highest score
+  let best = null;
+  let bestScore = 0;
+  let bestExtCount = 0;
+
+  for (const [name, score] of Object.entries(scores)) {
+    if (score < 2) continue;
+    const extCount = matchedTriggers[name].filter(t => t.startsWith('.')).length;
+    if (
+      score > bestScore ||
+      (score === bestScore && extCount > bestExtCount)
+    ) {
+      best = name;
+      bestScore = score;
+      bestExtCount = extCount;
+    }
+  }
+
+  if (!best) {
+    return { specialist: 'generic', confidence: 'low', triggers: [] };
+  }
+
+  const confidence = bestScore >= 4 ? 'high' : 'medium';
+  return { specialist: best, confidence, triggers: matchedTriggers[best] };
+}
+
+// ─── CLI ──────────────────────────────────────────────────────────────────────
+
+if (process.argv[1] && new URL(import.meta.url).pathname === process.argv[1]) {
+  const args = process.argv.slice(2);
+  const prompt = args.find(a => !a.startsWith('--')) || '';
+
+  if (!prompt) {
+    console.error('Usage: node src/detect.mjs "task description" [--files a,b]');
+    process.exit(1);
+  }
+
+  const filesFlag = args.find(a => a.startsWith('--files=')) ||
+    (args.includes('--files') ? args[args.indexOf('--files') + 1] : null);
+  const files = filesFlag
+    ? filesFlag.replace(/^--files=/, '').split(',').map(f => f.trim()).filter(Boolean)
+    : [];
+
+  const failuresFlag = args.find(a => a.startsWith('--failures=')) ||
+    (args.includes('--failures') ? args[args.indexOf('--failures') + 1] : null);
+  const priorFailures = failuresFlag ? parseInt(failuresFlag.replace(/^--failures=/, ''), 10) : 0;
+
+  const result = detectTask({ prompt, files, priorFailures });
+  console.log(JSON.stringify(result, null, 2));
+}
+
+export { detectTask, classifyIntent, classifyRisk, estimateComplexity, inferTier, extractPaths, classifySpecialist };