chati-dev 4.0.10 → 4.1.0

package/src/orchestrator/cli.js

@@ -0,0 +1,980 @@
+/**
+ * @fileoverview CLI handler for the `orchestrate` command.
+ *
+ * Exposes deterministic orchestration logic as JSON-outputting sub-commands.
+ * The thin orchestrator prompt calls these instead of reimplementing pipeline
+ * logic in natural language.
+ *
+ * Usage:
+ *   node bin/chati.js orchestrate <subcommand> [--flag value ...]
+ *
+ * Sub-commands: next, advance, init, validate-handoff, status, deviation, exit
+ */
+
+import {
+  loadSession, initSession, updateSession, recordAgentCompletion,
+  recordModeTransition, getSessionSummary, validateSession,
+  releaseSession,
+} from './index.js';
+import {
+  getNextAgent, getAgentDefinition, AGENT_PIPELINE,
+} from './index.js';
+import {
+  initPipeline, initQuickFlowPipeline, initStandardFlowPipeline,
+  advancePipeline, checkPhaseTransition, getPipelineProgress,
+  isPipelineComplete, confirmPreview,
+} from './index.js';
+import {
+  validateHandoffIntegrity, loadHandoffContext, getHandoffHistory,
+} from './index.js';
+import { analyzeDeviationImpact, applyDeviation } from './index.js';
+import { detectQuickFlow, detectStandardFlow } from './index.js';
+import { AGENT_FILE_MAP } from '../terminal/prompt-builder.js';
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join, resolve } from 'path';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const INTERACTIVE_AGENTS = ['greenfield-wu', 'brownfield-wu', 'brief'];
+
+const LOCK_START = '<!-- chati-lock:start -->';
+const LOCK_END = '<!-- chati-lock:end -->';
+
+const RESUME_MESSAGES = {
+  en: 'Session saved. Type /chati anytime to resume.',
+  pt: 'Sessao salva. Digite /chati para retomar.',
+  es: 'Sesion guardada. Escribe /chati para reanudar.',
+  fr: 'Session sauvee. Tapez /chati pour reprendre.',
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) {
+        args[key] = next;
+        i++;
+      } else {
+        args[key] = 'true';
+      }
+    }
+  }
+  return args;
+}
+
+function output(data) {
+  process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+}
+
+function errorResult(message, code) {
+  return { action: 'error', error: message, code: code || 'UNKNOWN' };
+}
+
+/**
+ * Build a pipeline state object from session data.
+ * The session-manager and pipeline-manager use slightly different shapes;
+ * this bridges the two.
+ */
+function sessionToPipelineState(session, projectDir) {
+  const agents = {};
+  if (session.agents) {
+    for (const [name, data] of Object.entries(session.agents)) {
+      agents[name] = {
+        status: data.status || 'pending',
+        score: data.score ?? null,
+        startedAt: data.started_at || null,
+        completedAt: data.completed_at || null,
+      };
+    }
+  }
+
+  return {
+    phase: session.mode || session.project?.state || 'discover',
+    isGreenfield: (session.project_type || session.project?.type) === 'greenfield',
+    sessionId: session.session_id || `${Date.now()}`,
+    targetDir: projectDir,
+    chatiVersion: session.version || 'unknown',
+    startedAt: session.started_at || new Date().toISOString(),
+    completedAt: null,
+    agents,
+    completedAgents: session.completed_agents || [],
+    currentAgent: session.current_agent || null,
+    modeTransitions: session.mode_transitions || [],
+    history: [],
+  };
+}
+
+/**
+ * Build the spawn command string for an autonomous agent.
+ */
+function buildSpawnCommand(agent, projectDir, previousAgent, provider, timeout) {
+  const parts = [
+    'node', 'packages/chati-dev/src/terminal/run-agent.js',
+    '--agent', agent,
+    '--task-id', `${agent}-task`,
+    '--project-dir', resolve(projectDir),
+    '--previous-agent', previousAgent || 'none',
+    '--provider', provider || 'claude',
+    '--timeout', String(timeout || 600000),
+  ];
+  return parts.join(' ');
+}
+
+/**
+ * Build the parallel spawn command string.
+ */
+function buildParallelSpawnCommand(agents, projectDir, previousAgent, provider, timeout) {
+  const taskIds = agents.map(a => `${a}-task`).join(',');
+  const parts = [
+    'node', 'packages/chati-dev/src/terminal/run-parallel.js',
+    '--agents', agents.join(','),
+    '--task-ids', taskIds,
+    '--project-dir', resolve(projectDir),
+    '--previous-agent', previousAgent || 'none',
+    '--provider', provider || 'claude',
+    '--timeout', String(timeout || 900000),
+  ];
+  return parts.join(' ');
+}
+
+/**
+ * Model map — canonical model tier per agent.
+ * Matches framework/hooks/model-governance.js AGENT_MODELS.
+ */
+const AGENT_MODEL_MAP = {
+  'greenfield-wu': { provider: 'claude', model: 'haiku', upgrade: 'sonnet if multi-stack or enterprise' },
+  'brownfield-wu': { provider: 'claude', model: 'opus', upgrade: 'no downgrade' },
+  brief:           { provider: 'claude', model: 'sonnet', upgrade: 'opus if enterprise or 10+ integrations' },
+  detail:          { provider: 'claude', model: 'opus', upgrade: 'no downgrade' },
+  architect:       { provider: 'claude', model: 'opus', upgrade: 'no downgrade' },
+  ux:              { provider: 'claude', model: 'sonnet', upgrade: 'opus if design system from scratch' },
+  phases:          { provider: 'claude', model: 'sonnet', upgrade: 'opus if 20+ requirements' },
+  tasks:           { provider: 'claude', model: 'sonnet', upgrade: 'opus if 50+ tasks' },
+  'qa-planning':   { provider: 'claude', model: 'opus', upgrade: 'no downgrade' },
+  dev:             { provider: 'claude', model: 'opus', upgrade: 'no downgrade' },
+  'qa-implementation': { provider: 'claude', model: 'opus', upgrade: 'no downgrade' },
+  devops:          { provider: 'claude', model: 'sonnet', upgrade: 'opus if multi-environment or IaC' },
+};
+
+/**
+ * Resolve provider and model for an agent.
+ * Checks config.yaml for agent_overrides, falls back to AGENT_MODEL_MAP defaults.
+ */
+function resolveAgentModel(agent, projectDir) {
+  const defaults = AGENT_MODEL_MAP[agent] || { provider: 'claude', model: 'sonnet', upgrade: '' };
+
+  // Check config.yaml for agent_overrides
+  try {
+    const configPath = join(projectDir, 'chati.dev', 'config.yaml');
+    if (existsSync(configPath)) {
+      const configRaw = readFileSync(configPath, 'utf-8');
+      // Simple YAML parsing for agent_overrides section
+      const overrideMatch = configRaw.match(new RegExp(`${agent}:\\s*\\n\\s+provider:\\s*(\\w+)`, 'm'));
+      if (overrideMatch) {
+        return { ...defaults, provider: overrideMatch[1] };
+      }
+    }
+  } catch { /* expected: config may not exist or be malformed */ }
+
+  return defaults;
+}
+
+/**
+ * Estimate context bracket from pipeline progress.
+ */
+function estimateContextBracket(completedCount, totalCount) {
+  const progress = totalCount > 0 ? completedCount / totalCount : 0;
+  // Simple heuristic: context degrades with pipeline progress + conversation length
+  if (progress < 0.3) return { bracket: 'FRESH', remaining: 85 };
+  if (progress < 0.6) return { bracket: 'MODERATE', remaining: 60 };
+  if (progress < 0.85) return { bracket: 'DEPLETED', remaining: 30 };
+  return { bracket: 'CRITICAL', remaining: 10 };
+}
+
+/**
+ * Write session lock block to CLAUDE.local.md.
+ */
+function writeSessionLock(projectDir, currentAgent) {
+  const localMdPath = join(projectDir, 'CLAUDE.local.md');
+  let content = '';
+  if (existsSync(localMdPath)) {
+    content = readFileSync(localMdPath, 'utf-8');
+  }
+
+  // Remove existing lock if present
+  const startIdx = content.indexOf(LOCK_START);
+  const endIdx = content.indexOf(LOCK_END);
+  if (startIdx !== -1 && endIdx !== -1) {
+    content = content.slice(0, startIdx) + content.slice(endIdx + LOCK_END.length);
+  }
+
+  const lockBlock = `${LOCK_START}
+## Session Lock -- ACTIVE
+
+**Chati.dev session is ACTIVE.** Follow these rules for EVERY message:
+
+1. Read \`chati.dev/orchestrator/chati.md\` and follow its routing logic
+2. Route ALL user messages through the current agent: \`${currentAgent}\`
+3. NEVER respond outside of the Chati.dev system
+4. The ONLY way to exit is via \`/chati exit\`, \`/chati stop\`, or \`/chati quit\`
+${LOCK_END}
+`;
+
+  content = content.trimEnd() + '\n\n' + lockBlock;
+  writeFileSync(localMdPath, content, 'utf-8');
+}
+
+/**
+ * Remove session lock block from CLAUDE.local.md.
+ */
+function removeSessionLock(projectDir, resumeMsg) {
+  const localMdPath = join(projectDir, 'CLAUDE.local.md');
+  if (!existsSync(localMdPath)) return;
+
+  let content = readFileSync(localMdPath, 'utf-8');
+
+  const startIdx = content.indexOf(LOCK_START);
+  const endIdx = content.indexOf(LOCK_END);
+  if (startIdx !== -1 && endIdx !== -1) {
+    content = content.slice(0, startIdx) + content.slice(endIdx + LOCK_END.length);
+  }
+
+  if (resumeMsg) {
+    content = content.trimEnd() + `\n\n## Session Paused\n\n${resumeMsg}\n`;
+  }
+
+  writeFileSync(localMdPath, content.trimEnd() + '\n', 'utf-8');
+}
+
+// ---------------------------------------------------------------------------
+// Sub-command handlers
+// ---------------------------------------------------------------------------
+
+async function handleNext(projectDir) {
+  const { loaded, session } = loadSession(projectDir);
+  if (!loaded || !session) {
+    return { action: 'setup', status_summary: 'No session found. Project needs initialization.' };
+  }
+
+  const validation = validateSession(projectDir);
+  if (!validation.valid) {
+    return errorResult(`Session invalid: ${validation.reason}`, 'SESSION_INVALID');
+  }
+
+  const pipelineState = sessionToPipelineState(session, projectDir);
+
+  if (isPipelineComplete(pipelineState)) {
+    return {
+      action: 'complete',
+      pipeline_progress: getPipelineProgress(pipelineState),
+      session: { language: session.language, project_type: session.project_type || session.project?.type, execution_mode: session.execution_mode },
+      status_summary: 'Pipeline complete. All agents finished.',
+    };
+  }
+
+  // Check for in-progress agent (resume scenario)
+  const currentAgent = session.current_agent || null;
+  const completedAgents = session.completed_agents || [];
+  if (currentAgent && !completedAgents.includes(currentAgent)) {
+    const agent = currentAgent;
+    const agentStatus = session.agents?.[agent]?.status;
+    if (agentStatus === 'in_progress' || (agentStatus !== 'completed' && agentStatus !== 'skipped')) {
+      const agentFile = AGENT_FILE_MAP[agent] || null;
+      const agentDef = getAgentDefinition(agent);
+      const isInteractive = INTERACTIVE_AGENTS.includes(agent);
+
+      return {
+        action: isInteractive ? 'activate_interactive' : 'spawn_autonomous',
+        agent,
+        agent_file: agentFile,
+        phase: agentDef?.phase || session.mode,
+        spawn_command: isInteractive ? null : buildSpawnCommand(agent, projectDir, session.last_handoff || 'none', resolveAgentModel(agent, projectDir).provider, 600000),
+        parallel_spawn_command: null,
+        parallel_agents: [],
+        handoff_status: { valid: true, missing: [], warnings: ['Resuming in-progress agent'] },
+        gate_status: { canAdvance: true, reason: 'Agent already in progress' },
+        model_info: resolveAgentModel(agent, projectDir),
+        context_bracket: estimateContextBracket(completedAgents.length, AGENT_PIPELINE.length),
+        pipeline_progress: getPipelineProgress(pipelineState),
+        session: { language: session.language, project_type: session.project_type || session.project?.type, execution_mode: session.execution_mode, user_level: session.user_level || 'auto' },
+        status_summary: `Resuming ${agent} (in progress).`,
+      };
+    }
+  }
+
+  // Determine last completed agent
+  const lastAgent = session.last_handoff || session.current_agent || null;
+
+  // If no agent has started yet, route to first agent
+  if (!lastAgent || completedAgents.length === 0) {
+    const projectType = session.project_type || session.project?.type || 'greenfield';
+    const firstAgent = projectType === 'brownfield' ? 'brownfield-wu' : 'greenfield-wu';
+    const agentFile = AGENT_FILE_MAP[firstAgent] || null;
+
+    return {
+      action: 'activate_interactive',
+      agent: firstAgent,
+      agent_file: agentFile,
+      phase: 'discover',
+      spawn_command: null,
+      parallel_spawn_command: null,
+      parallel_agents: [],
+      handoff_status: { valid: true, missing: [], warnings: [] },
+      gate_status: { canAdvance: true, reason: 'First agent in pipeline' },
+      model_info: resolveAgentModel(firstAgent, projectDir),
+      context_bracket: estimateContextBracket(0, AGENT_PIPELINE.length),
+      pipeline_progress: getPipelineProgress(pipelineState),
+      session: { language: session.language, project_type: projectType, execution_mode: session.execution_mode, user_level: session.user_level || 'auto' },
+      status_summary: `Starting pipeline with ${firstAgent}.`,
+    };
+  }
+
+  // Get next agent
+  const nextInfo = getNextAgent(lastAgent, completedAgents);
+
+  if (!nextInfo || !nextInfo.next) {
+    return {
+      action: 'complete',
+      pipeline_progress: getPipelineProgress(pipelineState),
+      session: { language: session.language, project_type: session.project_type || session.project?.type, execution_mode: session.execution_mode },
+      status_summary: 'Pipeline complete. All agents finished.',
+    };
+  }
+
+  const nextAgent = nextInfo.next;
+  const agentFile = AGENT_FILE_MAP[nextAgent] || null;
+  const agentDef = getAgentDefinition(nextAgent);
+  const isInteractive = INTERACTIVE_AGENTS.includes(nextAgent);
+
+  // Validate handoff from previous agent
+  let handoffStatus;
+  try {
+    const handoffCtx = await loadHandoffContext(projectDir, lastAgent);
+    if (handoffCtx.context.handoff) {
+      handoffStatus = validateHandoffIntegrity(handoffCtx.context.handoff, nextAgent);
+    } else {
+      handoffStatus = { valid: false, missing: ['handoff document'], warnings: [`No handoff found from ${lastAgent}`] };
+    }
+  } catch { /* expected: handoff may not exist for first agent */
+    handoffStatus = { valid: true, missing: [], warnings: ['Could not load handoff (may be first agent)'] };
+  }
+
+  // Check quality gate
+  const gateStatus = checkPhaseTransition(pipelineState);
+
+  // Resolve model for next agent
+  const modelInfo = resolveAgentModel(nextAgent, projectDir);
+
+  // Check for parallel group
+  let action, spawnCommand = null, parallelSpawnCommand = null, parallelAgents = [];
+  if (nextInfo.isParallel && nextInfo.group.length > 1) {
+    action = 'spawn_parallel';
+    parallelAgents = nextInfo.group;
+    parallelSpawnCommand = buildParallelSpawnCommand(nextInfo.group, projectDir, lastAgent, modelInfo.provider, 900000);
+  } else if (isInteractive) {
+    action = 'activate_interactive';
+  } else {
+    action = 'spawn_autonomous';
+    spawnCommand = buildSpawnCommand(nextAgent, projectDir, lastAgent, modelInfo.provider, 600000);
+  }
+
+  const progress = getPipelineProgress(pipelineState);
+  const bracket = estimateContextBracket(completedAgents.length, AGENT_PIPELINE.length);
+
+  return {
+    action,
+    agent: nextAgent,
+    agent_file: agentFile,
+    phase: agentDef?.phase || session.mode,
+    spawn_command: spawnCommand,
+    parallel_spawn_command: parallelSpawnCommand,
+    parallel_agents: parallelAgents,
+    handoff_status: handoffStatus,
+    gate_status: gateStatus,
+    model_info: modelInfo,
+    context_bracket: bracket,
+    pipeline_progress: progress,
+    session: { language: session.language, project_type: session.project_type || session.project?.type, execution_mode: session.execution_mode, user_level: session.user_level || 'auto' },
+    status_summary: `${lastAgent} completed. Next: ${nextAgent} (${action.replace('_', ' ')}, ${agentDef?.phase || 'unknown'} phase).`,
+  };
+}
+
+async function handleAdvance(projectDir, args) {
+  const agent = args.agent;
+  const score = parseInt(args.score, 10);
+  const status = args.status || 'completed';
+  const decision = args.decision || null;
+
+  if (!agent) return errorResult('Missing --agent flag', 'MISSING_AGENT');
+  if (isNaN(score)) return errorResult('Missing or invalid --score flag', 'MISSING_SCORE');
+
+  const { loaded, session } = loadSession(projectDir);
+  if (!loaded || !session) return errorResult('No session found', 'NO_SESSION');
+
+  // Handle user_preview decisions
+  if (decision) {
+    const pipelineState = sessionToPipelineState(session, projectDir);
+    const previewResult = confirmPreview(pipelineState, decision);
+
+    await updateSession(projectDir, {
+      current_agent: previewResult.nextAgent,
+      mode: previewResult.needsModeSwitch ? 'deploy' : session.mode,
+    });
+
+    if (previewResult.needsModeSwitch) {
+      await recordModeTransition(projectDir, {
+        from: session.mode,
+        to: 'deploy',
+        trigger: `user_preview: ${decision}`,
+      });
+    }
+
+    const next = await handleNext(projectDir);
+    return { advanced: true, agent_completed: agent, score, decision, phase_transition: { triggered: previewResult.needsModeSwitch }, next };
+  }
+
+  // Record completion
+  await recordAgentCompletion(projectDir, { agent, status, score });
+
+  // Advance pipeline
+  const pipelineState = sessionToPipelineState(session, projectDir);
+  pipelineState.completedAgents = [...(session.completed_agents || []), agent];
+  pipelineState.agents[agent] = { status: 'completed', score, startedAt: null, completedAt: new Date().toISOString() };
+
+  const advanceResult = advancePipeline(pipelineState, agent, { score });
+
+  // Update session with new state
+  const updates = {
+    current_agent: advanceResult.nextAgent || '',
+    last_handoff: agent,
+  };
+
+  // Handle phase transition
+  let phaseTransition = { triggered: false };
+  if (advanceResult.needsModeSwitch) {
+    const newPhase = advanceResult.state?.phase || session.mode;
+    updates.mode = newPhase;
+    if (session.project) {
+      updates.project = { ...session.project, state: newPhase };
+    }
+    phaseTransition = { triggered: true, from: session.mode, to: newPhase };
+
+    await recordModeTransition(projectDir, {
+      from: session.mode,
+      to: newPhase,
+      trigger: `${agent} completed with score ${score}`,
+    });
+  }
+
+  await updateSession(projectDir, updates);
+
+  // Check if user_preview is needed
+  if (advanceResult.nextAction === 'user_preview') {
+    return {
+      advanced: true,
+      agent_completed: agent,
+      score,
+      phase_transition: phaseTransition,
+      next: {
+        action: 'user_preview',
+        agent: agent,
+        pipeline_progress: getPipelineProgress(advanceResult.state || pipelineState),
+        session: { language: session.language, project_type: session.project_type || session.project?.type, execution_mode: session.execution_mode },
+        status_summary: `${agent} completed with score ${score}%. User preview required before deploy.`,
+      },
+    };
+  }
+
+  const next = await handleNext(projectDir);
+  return { advanced: true, agent_completed: agent, score, phase_transition: phaseTransition, next };
+}
+
+async function handleInit(projectDir, args) {
+  // License validation at init time (moved from per-prompt UserPromptSubmit hook)
+  try {
+    const licensePath = join(process.env.HOME || '', '.chati-dev', 'license.yaml');
+    if (existsSync(licensePath)) {
+      const licenseRaw = readFileSync(licensePath, 'utf-8');
+      const statusMatch = licenseRaw.match(/status:\s*["']?(\w+)/);
+      const checkedMatch = licenseRaw.match(/checked_at:\s*["']?([^"'\n]+)/);
+      if (statusMatch && statusMatch[1] !== 'VALID') {
+        return errorResult(`License status: ${statusMatch[1]}. Run: npx chati-dev activate --key=YOUR-KEY`, 'LICENSE_INVALID');
+      }
+      // Check cache freshness (24h TTL)
+      if (checkedMatch) {
+        const age = Date.now() - new Date(checkedMatch[1]).getTime();
+        if (age > 24 * 60 * 60 * 1000) {
+          process.stderr.write('[chati] license cache expired (24h) — will refresh on next API call\n');
+        }
+      }
+    }
+    // No license file = allow (fail-open, same as license-guard behavior)
+  } catch { /* expected: license file may not exist */ }
+
+  const type = args.type || 'greenfield';
+  const language = args.language || 'en';
+  const name = args.name || '';
+  const workflow = args.workflow || 'full';
+
+  const isGreenfield = type === 'greenfield';
+
+  // Initialize pipeline state based on workflow
+  let pipelineAgents;
+  if (workflow === 'quick') {
+    const p = initQuickFlowPipeline({ isGreenfield, targetDir: projectDir });
+    pipelineAgents = Object.keys(p.agents);
+  } else if (workflow === 'standard') {
+    const p = initStandardFlowPipeline({ isGreenfield, targetDir: projectDir });
+    pipelineAgents = Object.keys(p.agents);
+  } else {
+    const p = initPipeline({ isGreenfield, targetDir: projectDir });
+    pipelineAgents = Object.keys(p.agents);
+  }
+
+  // Initialize session
+  const result = initSession(projectDir, {
+    mode: 'discover',
+    projectName: name,
+    isGreenfield,
+    language,
+  });
+
+  if (!result.created) {
+    return errorResult(`Failed to initialize session: ${result.error}`, 'INIT_FAILED');
+  }
+
+  // Set workflow in session
+  await updateSession(projectDir, { workflow });
+
+  // Determine first agent
+  const firstAgent = isGreenfield ? 'greenfield-wu' : 'brownfield-wu';
+  const firstAgentFile = AGENT_FILE_MAP[firstAgent] || null;
+
+  // Update session with first agent
+  await updateSession(projectDir, { current_agent: firstAgent });
+
+  // Write session lock
+  try {
+    writeSessionLock(projectDir, firstAgent);
+  } catch (err) {
+    // Non-blocking — lock is nice-to-have, not critical
+    process.stderr.write(`[chati] cli lock-write: ${err.message}\n`);
+  }
+
+  return {
+    initialized: true,
+    session_path: '.chati/session.yaml',
+    workflow,
+    pipeline_agents: pipelineAgents,
+    first_agent: firstAgent,
+    first_agent_file: firstAgentFile,
+    lock_written: true,
+    language,
+    project_type: type,
+  };
+}
+
+async function handleValidateHandoff(projectDir, args) {
+  const from = args.from;
+  const to = args.to;
+
+  if (!from) return errorResult('Missing --from flag', 'MISSING_FROM');
+
+  let handoffCtx;
+  try {
+    handoffCtx = await loadHandoffContext(projectDir, from);
+  } catch (err) {
+    return { valid: false, from, to: to || 'unknown', missing: ['handoff document'], warnings: [err.message], handoff_loaded: false, sources: [] };
+  }
+
+  const handoff = handoffCtx.context?.handoff || null;
+  if (!handoff) {
+    return { valid: false, from, to: to || 'unknown', missing: ['handoff document'], warnings: [`No handoff found from ${from}`], handoff_loaded: false, sources: handoffCtx.sources || [] };
+  }
+
+  const receivingAgent = to || getNextAgent(from, [from])?.next || 'unknown';
+  const integrity = validateHandoffIntegrity(handoff, receivingAgent);
+
+  return {
+    valid: integrity.valid,
+    from,
+    to: receivingAgent,
+    missing: integrity.missing,
+    warnings: integrity.warnings,
+    handoff_loaded: true,
+    sources: handoffCtx.sources || [],
+  };
+}
+
+async function handleStatus(projectDir) {
+  const { loaded, session } = loadSession(projectDir);
+  if (!loaded || !session) {
+    return errorResult('No session found. Run `orchestrate init` first.', 'NO_SESSION');
+  }
+
+  const summary = getSessionSummary(projectDir);
+  const pipelineState = sessionToPipelineState(session, projectDir);
+  const progress = getPipelineProgress(pipelineState);
+
+  let handoffHistory = [];
+  try {
+    handoffHistory = getHandoffHistory(projectDir);
+  } catch { /* expected: handoff files may not exist yet */
+  }
+
+  // Build model map for all agents
+  const agentModels = {};
+  for (const agentDef of AGENT_PIPELINE) {
+    agentModels[agentDef.name] = resolveAgentModel(agentDef.name, projectDir);
+  }
+
+  return {
+    session: summary.summary || summary,
+    pipeline: progress,
+    handoff_history: handoffHistory,
+    deviation_count: (session.deviations || []).length,
+    backlog: session.backlog || [],
+    agents: session.agents || {},
+    agent_models: agentModels,
+    context_bracket: estimateContextBracket((session.completed_agents || []).length, AGENT_PIPELINE.length),
+    user_level: session.user_level || 'auto',
+    execution_mode: session.execution_mode || 'interactive',
+  };
+}
+
+async function handleDeviation(projectDir, args) {
+  const type = args.type;
+  const target = args.target || null;
+  const confirm = args.confirm === 'true';
+
+  if (!type) return errorResult('Missing --type flag', 'MISSING_TYPE');
+
+  const { loaded, session } = loadSession(projectDir);
+  if (!loaded || !session) return errorResult('No session found', 'NO_SESSION');
+
+  const pipelineState = sessionToPipelineState(session, projectDir);
+
+  const details = { targetAgent: target };
+  if (args['features-add']) {
+    details.addedFeatures = args['features-add'].split(',').map(s => s.trim());
+  }
+  if (args['features-remove']) {
+    details.removedFeatures = args['features-remove'].split(',').map(s => s.trim());
+  }
+
+  // Phase 1: Impact analysis
+  const impact = analyzeDeviationImpact(type, pipelineState, details);
+
+  if (!confirm) {
+    return { impact, applied: false, changes: [], new_state: null };
+  }
+
+  // Phase 2: Apply deviation
+  const result = applyDeviation(pipelineState, type, details);
+
+  if (result.applied) {
+    // Persist changes to session
+    const updates = {};
+    if (result.state.currentAgent !== session.current_agent) {
+      updates.current_agent = result.state.currentAgent || '';
+    }
+    // Update agent statuses
+    if (result.state.agents) {
+      const agentUpdates = {};
+      for (const [name, data] of Object.entries(result.state.agents)) {
+        agentUpdates[name] = {
+          status: data.status,
+          score: data.score ?? 0,
+          criteria_count: 0,
+          completed_at: data.completedAt || null,
+        };
+      }
+      updates.agents = agentUpdates;
+    }
+    // Update completed_agents
+    if (result.state.completedAgents) {
+      updates.completed_agents = result.state.completedAgents;
+    }
+
+    await updateSession(projectDir, updates);
+  }
+
+  return {
+    impact,
+    applied: result.applied,
+    changes: result.changes,
+    new_state: result.applied ? { current_agent: result.state.currentAgent } : null,
+  };
+}
+
+async function handleExit(projectDir, args) {
+  const { loaded, session } = loadSession(projectDir);
+  if (!loaded || !session) {
+    return { exited: true, session_saved: false, lock_removed: false, resume_message: null };
+  }
+
+  // Save current state
+  await updateSession(projectDir, {});
+
+  // Release session ownership
+  const userId = args['user-id'] || process.env.USER || 'default';
+  try {
+    releaseSession(projectDir, userId);
+  } catch { /* expected: session may already be released */ }
+
+  // Remove lock from CLAUDE.local.md
+  const lang = session.language || 'en';
+  const resumeMsg = RESUME_MESSAGES[lang] || RESUME_MESSAGES.en;
+  try {
+    removeSessionLock(projectDir, resumeMsg);
+  } catch { /* expected: lock file may not exist */ }
+
+  return {
+    exited: true,
+    session_saved: true,
+    lock_removed: true,
+    resume_message: resumeMsg,
+    language: lang,
+  };
+}
+
+async function handleProviders(projectDir) {
+  const agentModels = {};
+  for (const agentDef of AGENT_PIPELINE) {
+    agentModels[agentDef.name] = resolveAgentModel(agentDef.name, projectDir);
+  }
+
+  return {
+    primary_provider: 'claude',
+    agent_models: agentModels,
+  };
+}
+
+async function handleDetectFlow(projectDir, args) {
+  const message = args.message || '';
+  if (!message) return errorResult('Missing --message flag', 'MISSING_MESSAGE');
+
+  const { loaded, session } = loadSession(projectDir);
+  const sessionContext = loaded && session ? { mode: session.mode, project_type: session.project_type } : {};
+
+  const quickResult = detectQuickFlow(message, sessionContext);
+  const standardResult = detectStandardFlow(message, sessionContext);
+
+  let recommended = 'full';
+  if (quickResult.isQuickFlow && quickResult.confidence >= 0.8) {
+    recommended = 'quick';
+  } else if (standardResult.isStandardFlow && standardResult.confidence >= 0.8) {
+    recommended = 'standard';
+  }
+
+  return {
+    recommended,
+    quick_flow: quickResult,
+    standard_flow: standardResult,
+  };
+}
+
+async function handleBacklog(projectDir, args) {
+  const action = args.action || 'list';
+  const { loaded, session } = loadSession(projectDir);
+  if (!loaded || !session) return errorResult('No session found', 'NO_SESSION');
+
+  const backlog = session.backlog || [];
+
+  if (action === 'list') {
+    return { backlog, count: backlog.length };
+  }
+
+  if (action === 'add') {
+    const title = args.title;
+    const priority = args.priority || 'medium';
+    const source = args.source || 'user';
+    if (!title) return errorResult('Missing --title flag', 'MISSING_TITLE');
+
+    const item = {
+      id: `BL-${String(backlog.length + 1).padStart(3, '0')}`,
+      title,
+      priority,
+      status: 'pending',
+      source_agent: source,
+      created_at: new Date().toISOString(),
+    };
+    backlog.push(item);
+    await updateSession(projectDir, { backlog });
+    return { added: true, item, count: backlog.length };
+  }
+
+  return { backlog, count: backlog.length };
+}
+
+// ---------------------------------------------------------------------------
+// QA Scoring Handlers (deterministic — no LLM)
+// ---------------------------------------------------------------------------
+
+function handleQaPlanScore(args) {
+  let score = 100;
+  const penalties = {};
+
+  const penaltyMap = [
+    ['orphans', 10, 'Orphaned requirement'],
+    ['placeholders', 5, 'Placeholder in artifact'],
+    ['weak-criteria', 10, 'Weak/vague criterion'],
+    ['scope-creep', 15, 'Scope creep item'],
+    ['gaps', 20, 'Critical gap'],
+    ['fail-dimensions', 10, 'Failed validation dimension'],
+  ];
+
+  for (const [key, weight, label] of penaltyMap) {
+    const count = parseInt(args[key]) || 0;
+    if (count > 0) {
+      const penalty = count * weight;
+      score -= penalty;
+      penalties[key] = { count, weight, penalty, label };
+    }
+  }
+
+  if (args['adversarial-incomplete'] === 'true') {
+    score -= 15;
+    penalties['adversarial-incomplete'] = { count: 1, weight: 15, penalty: 15, label: 'Adversarial review incomplete' };
+  }
+
+  score = Math.max(0, score);
+  const threshold = 95;
+  const verdict = score >= threshold ? 'APPROVED' : score >= threshold - 5 ? 'NEEDS_REVISION' : 'BLOCKED';
+
+  return { score, threshold, verdict, penalties };
+}
+
+function handleQaImplScore(args) {
+  const weights = { tests: 0.25, coverage: 0.10, security: 0.25, quality: 0.15, acceptance: 0.10, adversarial: 0.15 };
+
+  const scores = {
+    tests: parseInt(args['tests-pass']) || 0,
+    coverage: parseInt(args.coverage) || 0,
+    security: (parseInt(args.critical) === 0 && parseInt(args.high) === 0) ? 100 : (parseInt(args.critical) > 0 ? 0 : 50),
+    quality: parseInt(args['code-quality']) || 0,
+    acceptance: parseInt(args.acceptance) || 0,
+    adversarial: parseInt(args.adversarial) || 0,
+  };
+
+  const weighted = Object.entries(weights).reduce((sum, [k, w]) => sum + (scores[k] || 0) * w, 0);
+  const score = Math.round(weighted);
+  const threshold = 95;
+  const verdict = score >= threshold ? 'APPROVED' : score >= threshold - 5 ? 'NEEDS_REVISION' : 'BLOCKED';
+
+  return { score, threshold, verdict, breakdown: scores, weights };
+}
+
+// ---------------------------------------------------------------------------
+// Scan Handler (deterministic — no LLM)
+// ---------------------------------------------------------------------------
+
+async function handleScan(projectDir, args) {
+  const type = args.type;
+  if (!type) return errorResult('Missing --type flag. Valid: placeholders, leakage, density, env, security', 'MISSING_TYPE');
+
+  try {
+    switch (type) {
+      case 'placeholders': {
+        const file = args.file;
+        if (!file) return errorResult('Missing --file flag', 'MISSING_FILE');
+        const { scanPlaceholders } = await import('../scanning/placeholder-scanner.js');
+        const { join: joinPath } = await import('path');
+        return scanPlaceholders(joinPath(projectDir, file));
+      }
+      case 'leakage': {
+        const file = args.file;
+        if (!file) return errorResult('Missing --file flag', 'MISSING_FILE');
+        const { scanImplementationLeakage } = await import('../scanning/leakage-scanner.js');
+        const { join: joinPath } = await import('path');
+        return scanImplementationLeakage(joinPath(projectDir, file));
+      }
+      case 'density': {
+        const file = args.file;
+        if (!file) return errorResult('Missing --file flag', 'MISSING_FILE');
+        const { scanInformationDensity } = await import('../scanning/density-scanner.js');
+        const { join: joinPath } = await import('path');
+        return scanInformationDensity(joinPath(projectDir, file));
+      }
+      case 'env': {
+        const { scanEnvSync } = await import('../scanning/env-scanner.js');
+        return scanEnvSync(projectDir);
+      }
+      case 'security': {
+        const { scanProjectSecurity } = await import('../scanning/security-scanner.js');
+        return scanProjectSecurity(projectDir, { language: args.language, dir: args.dir });
+      }
+      default:
+        return errorResult(`Unknown scan type: ${type}. Valid: placeholders, leakage, density, env, security`, 'UNKNOWN_SCAN_TYPE');
+    }
+  } catch (err) {
+    return errorResult(`Scan failed: ${err.message}`, 'SCAN_ERROR');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+
+export async function runOrchestrate(subCommand, argv, projectDir) {
+  const args = parseArgs(argv);
+
+  try {
+    switch (subCommand) {
+      case 'next':
+        output(await handleNext(projectDir));
+        break;
+      case 'advance':
+        output(await handleAdvance(projectDir, args));
+        break;
+      case 'init':
+        output(await handleInit(projectDir, args));
+        break;
+      case 'validate-handoff':
+        output(await handleValidateHandoff(projectDir, args));
+        break;
+      case 'status':
+        output(await handleStatus(projectDir));
+        break;
+      case 'deviation':
+        output(await handleDeviation(projectDir, args));
+        break;
+      case 'exit':
+        output(await handleExit(projectDir, args));
+        break;
+      case 'providers':
+        output(await handleProviders(projectDir));
+        break;
+      case 'detect-flow':
+        output(await handleDetectFlow(projectDir, args));
+        break;
+      case 'backlog':
+        output(await handleBacklog(projectDir, args));
+        break;
+      case 'qa-plan-score':
+        output(handleQaPlanScore(args));
+        break;
+      case 'qa-impl-score':
+        output(handleQaImplScore(args));
+        break;
+      case 'scan':
+        output(await handleScan(projectDir, args));
+        break;
+      default:
+        output(errorResult(`Unknown sub-command: ${subCommand}. Valid: next, advance, init, validate-handoff, status, deviation, exit, providers, detect-flow, backlog, qa-plan-score, qa-impl-score, scan`, 'UNKNOWN_COMMAND'));
+        break;
+    }
+  } catch (err) {
+    output(errorResult(`Orchestrate error: ${err.message}`, 'INTERNAL_ERROR'));
+    process.exitCode = 1;
+  }
+}