chati-dev 4.2.2 → 4.3.0

package/src/orchestrator/cli.js

@@ -11,11 +11,19 @@
  * Sub-commands: next, advance, init, validate-handoff, status, deviation, exit
  */
 
+import { resolveFrameworkDir } from '../utils/framework-dir.js';
+
 import {
   loadSession, initSession, updateSession, recordAgentCompletion,
   recordModeTransition, getSessionSummary, validateSession,
-  releaseSession,
+  releaseSession, parseHandoffDecisionTrail, parseHandoffScaffoldSignals,
 } from './index.js';
+import {
+  resolveScaffoldSource, loadScaffoldManifest, applyScaffold,
+} from '../installer/scaffold-applier.js';
+import { resolveContextLimit } from '../utils/provider-limits.js';
+import { waitForLicense } from '../license/wait.js';
+import { runDoctor } from './doctor.js';
 import {
   getNextAgent, getAgentDefinition, AGENT_PIPELINE,
 } from './index.js';
@@ -29,12 +37,18 @@ import {
 } 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, mkdirSync } from 'fs';
+import { getAgentFile } from '../terminal/prompt-builder.js';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync } from 'fs';
 import { join, resolve } from 'path';
+import { execSync } from 'child_process';
+import yaml from 'js-yaml';
 import {
   initTaskList, readTaskList, getTeamProgress,
 } from '../terminal/team-task-list.js';
+import {
+  recordEvent, EventType, clearTimeline,
+} from '../intelligence/timeline.js';
+import { updateClaudeMd } from '../memory/magic-docs.js';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -44,14 +58,411 @@ const INTERACTIVE_AGENTS = ['greenfield-wu', 'brownfield-wu', 'brief'];
 
 const LOCK_START = '<!-- chati-lock:start -->';
 const LOCK_END = '<!-- chati-lock:end -->';
+const STATE_START = '<!-- chati-state:start -->';
+const STATE_END = '<!-- chati-state: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.',
+  pt: 'Sessão salva. Digite /chati para retomar.',
+  es: 'Sesión guardada. Escribe /chati para reanudar.',
   fr: 'Session sauvee. Tapez /chati pour reprendre.',
 };
 
+// ---------------------------------------------------------------------------
+// QA-Visual scope helpers (Fase 6 — scope isolation)
+//
+// When shared CSS or token files change (globals.css, brand.ts, tailwind
+// config), a regression in the affected utility can silently break routes
+// that were NOT touched by the current task. The qa-visual gate uses
+// these helpers to detect the situation and require full app/ coverage
+// before allowing advance.
+// ---------------------------------------------------------------------------
+
+const SHARED_CSS_PATTERNS = [
+  /(^|\/)app\/globals\.css$/,
+  /(^|\/)src\/app\/globals\.css$/,
+  /(^|\/)lib\/brand\.ts$/,
+  /(^|\/)src\/lib\/brand\.ts$/,
+  /(^|\/)tailwind\.config\.(?:js|ts|mjs|cjs)$/,
+  /(^|\/)postcss\.config\.(?:js|ts|mjs|cjs)$/,
+  /(^|\/)lib\/animations\/tokens\.(?:ts|js)$/,
+  /(^|\/)src\/lib\/animations\/tokens\.(?:ts|js)$/,
+];
+
+/**
+ * True if any entry in `filesModified` matches a shared CSS / token file.
+ * These files touch every route — a change here requires full coverage in QA-Visual.
+ * Exported for testing.
+ *
+ * @param {string[]} filesModified - Repo-relative file paths.
+ * @returns {boolean}
+ */
+export function detectSharedCSSChanges(filesModified) {
+  if (!Array.isArray(filesModified) || filesModified.length === 0) return false;
+  return filesModified.some(f => typeof f === 'string' && SHARED_CSS_PATTERNS.some(p => p.test(f)));
+}
+
+/**
+ * Enumerate Next.js App Router routes by walking a project's `app/` directory
+ * and collecting `page.{tsx,jsx,ts,js,mdx}` files. Excludes:
+ *   - dynamic segments (`[slug]/`, `[[...slug]]/`) — can't be captured statically
+ *   - private folders (`_components/`)
+ *   - route groups (`(marketing)/`) stripped from the URL path
+ *
+ * Returns null if no `app/` directory exists (non-Next.js project).
+ * Exported for testing.
+ *
+ * @param {string} projectDir
+ * @returns {string[] | null}
+ */
+export function discoverAppRoutes(projectDir) {
+  if (!projectDir) return null;
+  // Common locations: app/ at root, or src/app/ (create-next-app option).
+  const candidates = [join(projectDir, 'app'), join(projectDir, 'src', 'app')];
+  const appDir = candidates.find(d => existsSync(d));
+  if (!appDir) return null;
+
+  const routes = [];
+  const PAGE_RE = /^page\.(tsx|jsx|ts|js|mdx)$/;
+
+  function walk(dir, segments) {
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.isDirectory()) {
+        const name = e.name;
+        // Skip private (underscore) and dynamic segments
+        if (name.startsWith('_')) continue;
+        if (name.startsWith('[')) continue; // dynamic: [slug], [...catchAll], [[...slug]]
+        // Route groups (parens) wrap but don't appear in URL
+        const isGroup = name.startsWith('(') && name.endsWith(')');
+        const nextSegments = isGroup ? segments : [...segments, name];
+        walk(join(dir, e.name), nextSegments);
+      } else if (e.isFile() && PAGE_RE.test(e.name)) {
+        routes.push(segments.length === 0 ? '/' : '/' + segments.join('/'));
+      }
+    }
+  }
+  walk(appDir, []);
+  // Deduplicate (route groups can produce the same URL twice) and sort.
+  return [...new Set(routes)].sort();
+}
+
+/**
+ * Run `git diff --name-only` to list files modified in the current working
+ * copy since HEAD, plus files changed relative to main. Silently returns []
+ * if git is unavailable or projectDir is not a git repo.
+ *
+ * @param {string} projectDir
+ * @returns {string[]}
+ */
+export function getModifiedFiles(projectDir) {
+  if (!projectDir) return [];
+  const cmds = [
+    'git diff --name-only HEAD 2>/dev/null',
+    'git diff --name-only --cached 2>/dev/null',
+    'git diff --name-only main...HEAD 2>/dev/null',
+  ];
+  const out = new Set();
+  for (const cmd of cmds) {
+    try {
+      const raw = execSync(cmd, { cwd: projectDir, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+      for (const line of raw.split('\n')) {
+        const f = line.trim();
+        if (f) out.add(f);
+      }
+    } catch { /* silently skip failed command (not a repo, no main branch, etc.) */ }
+  }
+  return [...out];
+}
+
+// ---------------------------------------------------------------------------
+// Reasoning Tier (Fase 9 — Article XXIII)
+//
+// Per-agent DEFAULT tiers. The escalator hook promotes from default upward
+// based on friction signals; de-escalation only happens on an explicit
+// /quick slash command.
+// ---------------------------------------------------------------------------
+
+export const REASONING_TIERS = ['standard', 'deep', 'deliberate'];
+
+export const AGENT_DEFAULT_TIER = {
+  'greenfield-wu':     'standard',
+  'brownfield-wu':     'deep',
+  'brief':             'standard',
+  'detail':            'deep',
+  'architect':         'deep',
+  'ux':                'standard',
+  'phases':            'standard',
+  'tasks':             'standard',
+  'qa-planning':       'deep',
+  'dev':               'standard',
+  'qa-implementation': 'deep',
+  'qa-visual':         'standard',
+  'devops':            'standard',
+};
+
+/**
+ * Read the current reasoning_tier from a session object. Falls back to the
+ * per-agent default when the session field is missing or invalid.
+ * Exported for testing.
+ */
+export function getReasoningTier(session) {
+  if (!session) return 'standard';
+  const recorded = session.reasoning_tier;
+  if (REASONING_TIERS.includes(recorded)) return recorded;
+  const agent = session.current_agent;
+  if (agent && AGENT_DEFAULT_TIER[agent]) return AGENT_DEFAULT_TIER[agent];
+  return 'standard';
+}
+
+// ---------------------------------------------------------------------------
+// Premium-reference detection (Fase 7 — task-to-UX fidelity)
+//
+// When the brief or reference-analysis cites a well-known premium-animation
+// site (Oryzo, Norris, Relats, Wero, igloo inc, Awwwards entries) OR uses
+// specific phrase constructions that signal premium motion intent
+// (cinematic scroll, horizontal pin, scroll-driven, award-winning), the
+// brand-architect agent MUST produce an animation-inventory.md artifact
+// that names every observed pattern and maps it to a scaffold template.
+// The inventory is consumed 1:1 by the tasks agent and used as the
+// checklist by qa-visual Mode 2. Without it, the downstream pipeline
+// produces generic "add scroll reveals" tasks that fail to reproduce the
+// specific patterns the user asked for. The gate below enforces the
+// requirement at advance-ux time.
+// ---------------------------------------------------------------------------
+
+const PREMIUM_REF_PATTERNS = [
+  // Named premium-animation reference sites.
+  { label: 'Oryzo',        pattern: /\boryzo\b/i },
+  { label: 'Norris',       pattern: /\bnorris\b/i },
+  { label: 'Relats',       pattern: /\brelats\b/i },
+  { label: 'Wero',         pattern: /\bwero\b/i },
+  { label: 'Igloo Inc',    pattern: /\bigloo\s*inc\b/i },
+  { label: 'Awwwards',     pattern: /\bawwwards\b/i },
+  // Phrase constructions that signal premium animation intent.
+  { label: 'premium-animation',   pattern: /\bpremium\s+(?:animation|motion|feel|experience)/i },
+  { label: 'cinematic-scroll',    pattern: /\bcinematic\s+(?:scroll|experience|transitions?)/i },
+  { label: 'horizontal-pin',      pattern: /\bhorizontal[- ]?pin(?:ned)?\s+(?:scroll|sequence|section)/i },
+  { label: 'scroll-driven',       pattern: /\bscroll[- ]?driven\s+(?:animation|design|experience|crossfade|background)/i },
+  { label: 'award-winning',       pattern: /\baward[- ]?winning\s+(?:design|animation|website|experience)/i },
+  { label: 'pixel-perfect-motion', pattern: /\bpixel[- ]?perfect\s+(?:animation|motion)/i },
+];
+
+/**
+ * Detect premium-animation references in text (typically brief-report.md
+ * and/or reference-analysis.md concatenated). Exported for testing.
+ *
+ * @param {string} text
+ * @returns {{ detected: boolean, matches: string[] }}
+ */
+export function detectPremiumRefs(text) {
+  if (!text || typeof text !== 'string') return { detected: false, matches: [] };
+  const matches = [];
+  for (const { label, pattern } of PREMIUM_REF_PATTERNS) {
+    if (pattern.test(text)) matches.push(label);
+  }
+  return { detected: matches.length > 0, matches };
+}
+
+/**
+ * Read brief-report.md + reference-analysis.md from a project as a single
+ * corpus for premium-ref detection. Missing files are silently skipped.
+ * Exported for testing.
+ *
+ * @param {string} projectDir
+ * @returns {string}
+ */
+export function readBriefAndRefCorpus(projectDir) {
+  if (!projectDir) return '';
+  const paths = [
+    join(projectDir, 'artifacts', '1-Brief', 'brief-report.md'),
+    join(projectDir, 'artifacts', '4-UX', 'reference-analysis.md'),
+  ];
+  let corpus = '';
+  for (const p of paths) {
+    if (!existsSync(p)) continue;
+    try { corpus += readFileSync(p, 'utf-8') + '\n'; } catch { /* ignore */ }
+  }
+  return corpus;
+}
+
+// ---------------------------------------------------------------------------
+// State-at-a-glance card (Fase 8)
+//
+// Every handleNext response and every correction-loop trigger carries a
+// rendered multi-line "state card" that gives the human operator a one-
+// glance summary without grepping session.yaml. Box-drawn, unicode,
+// fixed width for predictability.
+// ---------------------------------------------------------------------------
+
+export const STATE_CARD_TOTAL_WIDTH = 43;
+export const STATE_CARD_CONTENT_WIDTH = 39;
+const STATE_CARD_MAX_NAME = 30;
+
+function _stateTruncate(s, maxLen) {
+  if (s === null || s === undefined) return '';
+  const str = String(s);
+  if (str.length <= maxLen) return str;
+  return str.slice(0, Math.max(0, maxLen - 1)) + '…';
+}
+
+function _statePadRight(s, width) {
+  const str = _stateTruncate(s, width);
+  return str + ' '.repeat(Math.max(0, width - str.length));
+}
+
+/**
+ * Pure formatter for the state-at-a-glance card. All input fields are
+ * taken as-is (no I/O). `buildStateCard` is the I/O wrapper that
+ * collects the fields from session + git + disk. Exported for testing.
+ *
+ * Card shape (fixed widths, STATE_CARD_TOTAL_WIDTH = 43 chars):
+ *   ┌─ {project}  ─────────────┐
+ *   │ {Cycle N •} {agent status} • {mode}   │
+ *   │ Last commit: {sha7} • QA: {score|—}   │
+ *   │ Open: {N} item(s) from audit           │
+ *   [│ ↺ Reset: {agent-list}                  │]   (only if correctionReset)
+ *   └───────────────────────────────────────┘
+ *
+ * @param {object} opts
+ * @param {string} opts.projectName
+ * @param {number|null} [opts.cycle] - if number, "Cycle N" prefix is added
+ * @param {string} opts.agent
+ * @param {string} opts.agentStatus - pending | in_progress | completed | …
+ * @param {string} opts.mode - execution_mode (interactive|autonomous) per Article XVII
+ * @param {string} opts.commitShort - 7-char SHA or 'unknown'
+ * @param {number|null} opts.qaScore - numeric 0..100 or null (shows —)
+ * @param {number} opts.backlogCount
+ * @param {{agents?: string[], files?: string[]}|null} [opts.correctionReset]
+ * @returns {string} Multi-line card (use console.log or JSON field).
+ */
+export function formatStateCard(opts = {}) {
+  const projectName = _stateTruncate(opts.projectName || 'unnamed project', STATE_CARD_MAX_NAME);
+  const dashesAfterName = STATE_CARD_TOTAL_WIDTH - 4 - projectName.length - 1;
+  const topLine = `┌─ ${projectName} ${'─'.repeat(Math.max(0, dashesAfterName))}┐`;
+
+  const parts1 = [];
+  if (typeof opts.cycle === 'number' && Number.isFinite(opts.cycle)) {
+    parts1.push(`Cycle ${opts.cycle}`);
+  }
+  parts1.push(`${opts.agent || 'none'} ${opts.agentStatus || 'pending'}`);
+  parts1.push(opts.mode || 'interactive');
+  const line1 = _statePadRight(parts1.join(' • '), STATE_CARD_CONTENT_WIDTH);
+
+  const qaDisplay = opts.qaScore !== null && opts.qaScore !== undefined ? String(opts.qaScore) : '—';
+  const line2 = _statePadRight(
+    `Last commit: ${opts.commitShort || 'unknown'} • QA: ${qaDisplay}`,
+    STATE_CARD_CONTENT_WIDTH,
+  );
+
+  const n = Number.isFinite(opts.backlogCount) ? opts.backlogCount : 0;
+  const line3 = _statePadRight(`Open: ${n} item${n === 1 ? '' : 's'} from audit`, STATE_CARD_CONTENT_WIDTH);
+
+  const lines = [topLine, `│ ${line1} │`, `│ ${line2} │`, `│ ${line3} │`];
+
+  if (opts.correctionReset && (
+    (opts.correctionReset.agents && opts.correctionReset.agents.length > 0) ||
+    (opts.correctionReset.files && opts.correctionReset.files.length > 0)
+  )) {
+    const agents = (opts.correctionReset.agents || []).join(', ');
+    const filesCount = (opts.correctionReset.files || []).length;
+    const resetDetail = [agents, filesCount > 0 ? `(+${filesCount} file${filesCount === 1 ? '' : 's'})` : '']
+      .filter(Boolean).join(' ') || 'n/a';
+    const resetLine = _statePadRight(`↺ Reset: ${resetDetail}`, STATE_CARD_CONTENT_WIDTH);
+    lines.push(`│ ${resetLine} │`);
+  }
+
+  lines.push(`└${'─'.repeat(STATE_CARD_TOTAL_WIDTH - 2)}┘`);
+  return lines.join('\n');
+}
+
+/**
+ * Collect state from session + git + qa report, then render the card via
+ * formatStateCard. Silently degrades when optional sources are missing
+ * (no git, no qa-visual report, etc.) — the card always renders.
+ * Exported for testing.
+ *
+ * @param {object} args
+ * @param {object} args.session - loaded session.yaml
+ * @param {string} args.projectDir
+ * @param {{agents?: string[], files?: string[]}|null} [args.correctionReset]
+ * @returns {string}
+ */
+export function buildStateCard({ session, projectDir, correctionReset = null } = {}) {
+  if (!session) return '';
+
+  const projectName = session.project?.name || 'unnamed project';
+  const agent = session.current_agent || 'none';
+  const agentStatus = session.agents?.[agent]?.status || 'pending';
+  const mode = session.execution_mode || 'interactive';
+  const cycle = typeof session.cycle === 'number' ? session.cycle : null;
+
+  // Last commit SHA (7 chars) — silent on non-git dirs
+  let commitShort = 'unknown';
+  if (projectDir) {
+    try {
+      const out = execSync('git log --pretty=%h -1 HEAD', {
+        cwd: projectDir, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim();
+      if (/^[a-f0-9]{7,40}$/.test(out)) commitShort = out.slice(0, 7);
+    } catch { /* not a repo / no commits */ }
+  }
+
+  // QA-Visual score — session.agents['qa-visual'].score takes priority; fallback to report.md.
+  let qaScore = null;
+  const qaAgentScore = session.agents?.['qa-visual']?.score;
+  if (typeof qaAgentScore === 'number' && qaAgentScore > 0) {
+    qaScore = qaAgentScore;
+  } else if (projectDir) {
+    const candidates = [
+      join(projectDir, 'artifacts', '9-QA-Implementation', 'qa-visual-report.md'),
+      join(projectDir, 'artifacts', '8-QA-Visual', 'visual-qa-analysis.md'),
+    ];
+    for (const p of candidates) {
+      if (!existsSync(p)) continue;
+      try {
+        const txt = readFileSync(p, 'utf-8');
+        const m = txt.match(/(?:^|\n)\s*(?:##\s+)?Score:\s*(\d+(?:\.\d+)?)\s*%?/);
+        if (m) { qaScore = parseFloat(m[1]); break; }
+      } catch { /* ignore */ }
+    }
+  }
+
+  const backlogCount = Array.isArray(session.backlog) ? session.backlog.length : 0;
+
+  return formatStateCard({
+    projectName, cycle, agent, agentStatus, mode, commitShort, qaScore, backlogCount, correctionReset,
+  });
+}
+
+/**
+ * Evaluate whether a shared CSS change requires blocking the qa-visual advance
+ * due to incomplete route coverage. Pure function (no git, no file-reading for
+ * modifiedFiles) — caller supplies `modifiedFiles`. Exported for testing.
+ *
+ * @param {object} opts
+ * @param {Array<{ path: string }>} opts.capturedPages - Pages present in report.json
+ * @param {string} opts.projectDir - For discoverAppRoutes
+ * @param {string[]} opts.modifiedFiles
+ * @returns {{ blocked: false } | { blocked: true, reason: string, triggeringFiles: string[], appRoutes: string[], uncovered: string[] }}
+ */
+export function checkSharedCSSCoverage({ capturedPages, projectDir, modifiedFiles }) {
+  if (!detectSharedCSSChanges(modifiedFiles)) return { blocked: false };
+  const appRoutes = discoverAppRoutes(projectDir);
+  if (!appRoutes || appRoutes.length === 0) return { blocked: false };
+  const capturedPaths = new Set((capturedPages || []).map(p => p.path));
+  const uncovered = appRoutes.filter(r => !capturedPaths.has(r));
+  if (uncovered.length === 0) return { blocked: false };
+  return {
+    blocked: true,
+    reason: 'shared_css_change_requires_full_coverage',
+    triggeringFiles: modifiedFiles.filter(f => SHARED_CSS_PATTERNS.some(p => p.test(f))),
+    appRoutes,
+    uncovered,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -113,6 +524,7 @@ function sessionToPipelineState(session, projectDir) {
     currentAgent: session.current_agent || null,
     modeTransitions: session.mode_transitions || [],
     history: [],
+    correctionCycles: { ...(session.correction_cycles || {}) },
   };
 }
 
@@ -165,6 +577,7 @@ const AGENT_MODEL_MAP = {
   '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' },
+  'qa-visual':     { provider: 'claude', model: 'opus', upgrade: 'no downgrade' },
   devops:          { provider: 'claude', model: 'sonnet', upgrade: 'opus if multi-environment or IaC' },
 };
 
@@ -177,7 +590,7 @@ function resolveAgentModel(agent, projectDir) {
 
   // Check config.yaml for agent_overrides
   try {
-    const configPath = join(projectDir, 'chati.dev', 'config.yaml');
+    const configPath = join(projectDir, resolveFrameworkDir(projectDir), 'config.yaml');
     if (existsSync(configPath)) {
       const configRaw = readFileSync(configPath, 'utf-8');
       // Simple YAML parsing for agent_overrides section
@@ -207,33 +620,37 @@ function estimateContextBracket(completedCount, totalCount) {
 /**
  * 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);
+function replaceBlock(content, startMarker, endMarker, newInner) {
+  const block = `${startMarker}\n${newInner}\n${endMarker}`;
+  const startIdx = content.indexOf(startMarker);
+  const endIdx = content.indexOf(endMarker);
   if (startIdx !== -1 && endIdx !== -1) {
-    content = content.slice(0, startIdx) + content.slice(endIdx + LOCK_END.length);
+    return content.slice(0, startIdx) + block + content.slice(endIdx + endMarker.length);
   }
+  return content.trimEnd() + '\n\n' + block + '\n';
+}
+
+function writeSessionLock(projectDir, currentAgent, stateInfo = {}) {
+  const localMdPath = join(projectDir, 'CLAUDE.local.md');
+  let content = existsSync(localMdPath) ? readFileSync(localMdPath, 'utf-8') : '';
 
-  const lockBlock = `${LOCK_START}
-## Session Lock -- ACTIVE
+  const lockInner = `## 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
+1. Read \`${resolveFrameworkDir(projectDir)}/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}
-`;
+4. The ONLY way to exit is via \`/chati exit\`, \`/chati stop\`, or \`/chati quit\``;
+
+  const stateInner = `## Current State
+- **Agent**: ${currentAgent || 'None'}
+- **Phase**: ${stateInfo.phase || 'discover'}
+- **Pipeline**: ${stateInfo.position ?? 0}/${stateInfo.total ?? '?'} (${stateInfo.progress ?? 0}%)
+- **Mode**: ${stateInfo.mode || 'interactive'}`;
 
-  content = content.trimEnd() + '\n\n' + lockBlock;
+  content = replaceBlock(content, LOCK_START, LOCK_END, lockInner);
+  content = replaceBlock(content, STATE_START, STATE_END, stateInner);
   writeFileSync(localMdPath, content, 'utf-8');
 }
 
@@ -246,11 +663,15 @@ function removeSessionLock(projectDir, resumeMsg) {
 
   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);
-  }
+  const lockInner = `## Session Lock
+**Status: INACTIVE** — Type \`/chati\` to activate.`;
+  const stateInner = `## Current State
+- **Agent**: None (ready to start)
+- **Pipeline**: Pre-start
+- **Mode**: interactive`;
+
+  content = replaceBlock(content, LOCK_START, LOCK_END, lockInner);
+  content = replaceBlock(content, STATE_START, STATE_END, stateInner);
 
   if (resumeMsg) {
     content = content.trimEnd() + `\n\n## Session Paused\n\n${resumeMsg}\n`;
@@ -264,6 +685,48 @@ function removeSessionLock(projectDir, resumeMsg) {
 // ---------------------------------------------------------------------------
 
 async function handleNext(projectDir) {
+  const result = await _handleNextInner(projectDir);
+
+  // Fase 8: attach state-at-a-glance card to every non-error response.
+  // The card renders as a JSON string field; the terminal / orchestrator
+  // prompt can console.log it verbatim. Silent on setup/error responses
+  // so a missing session does not produce a misleading card.
+  if (result && result.action !== 'setup' && result.action !== 'error') {
+    try {
+      const { session } = loadSession(projectDir);
+      if (session) {
+        result.state_card = buildStateCard({ session, projectDir });
+      }
+    } catch { /* non-fatal — card is UX sugar */ }
+  }
+
+  // Centralized session lock update: applies to ALL return paths.
+  // Activates lock when an agent is returned, deactivates on completion.
+  if (result && result.agent && result.action !== 'error' && result.action !== 'setup') {
+    const activating = ['activate_interactive', 'spawn_autonomous', 'spawn_team', 'spawn_parallel'];
+    if (activating.includes(result.action)) {
+      try {
+        writeSessionLock(projectDir, result.agent, {
+          phase: result.phase || 'discover',
+          mode: result.session?.execution_mode || 'interactive',
+          position: result.pipeline_progress?.completedAgents?.length ?? 0,
+          total: AGENT_PIPELINE.length,
+          progress: result.pipeline_progress?.progress ?? 0,
+        });
+      } catch { /* non-fatal */ }
+    }
+  } else if (result && result.action === 'complete') {
+    try {
+      const { session } = loadSession(projectDir);
+      const lang = session?.language || 'en';
+      removeSessionLock(projectDir, RESUME_MESSAGES[lang] || RESUME_MESSAGES.en);
+    } catch { /* non-fatal */ }
+  }
+
+  return result;
+}
+
+async function _handleNextInner(projectDir) {
   const { loaded, session } = loadSession(projectDir);
   if (!loaded || !session) {
     return { action: 'setup', status_summary: 'No session found. Project needs initialization.' };
@@ -291,11 +754,37 @@ async function handleNext(projectDir) {
   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;
+    if (agentStatus === 'in_progress') {
+      const agentFile = getAgentFile(agent, projectDir) || null;
       const agentDef = getAgentDefinition(agent);
       const isInteractive = INTERACTIVE_AGENTS.includes(agent);
 
+      // Build Team override: even when resuming, if agent is 'dev' and teams
+      // enabled, return spawn_team so Dev + QA-Implementation run together.
+      if (agent === 'dev' && isAgentTeamsEnabled(projectDir)) {
+        const teamConfig = TEAM_CONFIGS.build;
+        const teamId = generateTeamId(teamConfig.slug);
+        return {
+          action: 'spawn_team',
+          agent,
+          agent_file: agentFile,
+          phase: agentDef?.phase || session.mode,
+          spawn_command: null,
+          parallel_spawn_command: null,
+          parallel_agents: teamConfig.members,
+          handoff_status: { valid: true, missing: [], warnings: ['Resuming dev as Build Team'] },
+          gate_status: { canAdvance: true, reason: 'Build Team formation (Article XXI)' },
+          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: `Forming Build Team: dev + qa-implementation.`,
+          team_id: teamId,
+          team_type: 'build',
+          members: teamConfig.members,
+        };
+      }
+
       return {
         action: isInteractive ? 'activate_interactive' : 'spawn_autonomous',
         agent,
@@ -322,7 +811,7 @@ async function handleNext(projectDir) {
   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;
+    const agentFile = getAgentFile(firstAgent, projectDir) || null;
 
     return {
       action: 'activate_interactive',
@@ -342,8 +831,24 @@ async function handleNext(projectDir) {
     };
   }
 
-  // Get next agent
-  const nextInfo = getNextAgent(lastAgent, completedAgents);
+  // Get next agent — if lastAgent is not in AGENT_PIPELINE (e.g. qa-planning
+  // which lives inside Planning Team), fall back to the last completed agent
+  // that IS in the pipeline so we can find the correct successor.
+  let nextInfo = getNextAgent(lastAgent, completedAgents);
+
+  if ((!nextInfo || !nextInfo.next) && lastAgent) {
+    const agentInPipeline = getAgentDefinition(lastAgent);
+    if (!agentInPipeline) {
+      // lastAgent is not in AGENT_PIPELINE — find the last completed agent that IS
+      const pipelineNames = AGENT_PIPELINE.map((a) => a.name);
+      for (let i = completedAgents.length - 1; i >= 0; i--) {
+        if (pipelineNames.includes(completedAgents[i])) {
+          nextInfo = getNextAgent(completedAgents[i], completedAgents);
+          if (nextInfo && nextInfo.next) break;
+        }
+      }
+    }
+  }
 
   if (!nextInfo || !nextInfo.next) {
     return {
@@ -355,7 +860,7 @@ async function handleNext(projectDir) {
   }
 
   const nextAgent = nextInfo.next;
-  const agentFile = AGENT_FILE_MAP[nextAgent] || null;
+  const agentFile = getAgentFile(nextAgent, projectDir) || null;
   const agentDef = getAgentDefinition(nextAgent);
   const isInteractive = INTERACTIVE_AGENTS.includes(nextAgent);
 
@@ -415,6 +920,9 @@ async function handleNext(projectDir) {
     spawnCommand = buildSpawnCommand(nextAgent, projectDir, lastAgent, modelInfo.provider, 600000);
   }
 
+  // Record agent activation event
+  recordEvent(projectDir, EventType.AGENT_ACTIVATED, nextAgent, { action, phase: agentDef?.phase });
+
   const progress = getPipelineProgress(pipelineState);
   const bracket = estimateContextBracket(completedAgents.length, AGENT_PIPELINE.length);
 
@@ -445,6 +953,262 @@ async function handleNext(projectDir) {
   return result;
 }
 
+// ---------------------------------------------------------------------------
+// Fase 10 — Scaffold auto-gate helpers
+//
+// Problem: after qa-planning approves the plan, the framework knows (from
+// greenfield-wu's scaffold_candidates + ux-brand-architect's scaffold_signals)
+// whether a scaffold preset like motion-premium would save the Build phase
+// from reinventing animation wiring by hand. Without a deterministic gate,
+// the orchestrator must rely on Claude remembering to offer the scaffold —
+// and Claude forgets. This gate turns remembering into code.
+//
+// A preset "fires" when:
+//   1. It is in session.scaffold_candidates (stack match, Signal 1).
+//   2. It has a signal with confidence >= 0.7 (premium intent, Signal 2).
+//   3. It is NOT yet in session.scaffold_applied (idempotency).
+// ---------------------------------------------------------------------------
+
+const SCAFFOLD_CONFIDENCE_THRESHOLD = 0.7;
+
+// Per-preset threshold overrides. ADR-3D-07 sets motion-premium-3d to 0.8
+// (higher than motion-premium's 0.7) — false positives cost ~600KB of
+// bundle pressed onto a project that did not need 3D. New presets added
+// here; any preset not in the map inherits SCAFFOLD_CONFIDENCE_THRESHOLD.
+const PRESET_CONFIDENCE_THRESHOLDS = {
+  'motion-premium':     0.7,
+  'motion-premium-3d':  0.8,
+};
+
+function thresholdFor(preset) {
+  return PRESET_CONFIDENCE_THRESHOLDS[preset] ?? SCAFFOLD_CONFIDENCE_THRESHOLD;
+}
+
+/**
+ * Evaluate which (if any) scaffold preset's auto-gate should fire.
+ * Enumerates candidates in session order; first preset whose signal
+ * confidence meets its per-preset threshold AND is not already applied
+ * wins. When a user applies or skips one preset, the next advance call
+ * re-evaluates — letting a project with BOTH motion-premium and
+ * motion-premium-3d signals receive both prompts in sequence.
+ *
+ * @param {object} session - Post-completion session
+ * @returns {{ fires: boolean, preset: string|null, signalKey: string|null, confidence: number, threshold: number, evidence: string[], reason: string|null }}
+ */
+function checkScaffoldGate(session) {
+  const candidates = Array.isArray(session?.scaffold_candidates) ? session.scaffold_candidates : [];
+  const signals = (session?.scaffold_signals && typeof session.scaffold_signals === 'object') ? session.scaffold_signals : {};
+  const applied = new Set(Array.isArray(session?.scaffold_applied) ? session.scaffold_applied : []);
+
+  for (const preset of candidates) {
+    if (applied.has(preset)) continue;
+    const key = preset.replace(/-/g, '_');
+    const signal = signals[key];
+    if (!signal) continue;
+    const confidence = typeof signal.confidence === 'number' ? signal.confidence : 0;
+    const threshold  = thresholdFor(preset);
+    if (confidence < threshold) continue;
+    return {
+      fires:      true,
+      preset,
+      signalKey:  key,
+      confidence,
+      threshold,
+      evidence:   Array.isArray(signal.evidence) ? signal.evidence : [],
+      reason:     'scaffold_decision_required',
+    };
+  }
+
+  return { fires: false, preset: null, signalKey: null, confidence: 0, threshold: SCAFFOLD_CONFIDENCE_THRESHOLD, evidence: [], reason: null };
+}
+
+/**
+ * Build the action_required payload the orchestrator presents to the user
+ * when a scaffold gate fires.
+ */
+function buildScaffoldGateResponse(gate, { agent, score, phaseTransition }) {
+  return {
+    advanced:                    true,
+    agent_completed:             agent,
+    score,
+    phase_transition:            phaseTransition || { triggered: false },
+    scaffold_decision_required:  true,
+    scaffold_gate: {
+      preset:     gate.preset,
+      confidence: gate.confidence,
+      evidence:   gate.evidence,
+    },
+    next: {
+      action:          'scaffold_decision',
+      agent:           null,
+      pending_preset:  gate.preset,
+      confidence:      gate.confidence,
+      status_summary:  `Planning approved (qa-planning score ${score}). Scaffold "${gate.preset}" is eligible (confidence ${gate.confidence.toFixed(2)}). Present three options to the user before advancing to dev.`,
+      options: [
+        {
+          id:          'apply',
+          label:       `Apply ${gate.preset} scaffold (15 files, Premium-tier animation wiring)`,
+          command:     `advance --agent qa-planning --score ${score} --decision apply`,
+          description: 'Writes the scaffold templates to the project. Recommended — the Animation Inventory maps 1:1 to these files.',
+        },
+        {
+          id:          'dryrun',
+          label:       `Preview ${gate.preset} scaffold (list files, write nothing)`,
+          command:     `advance --agent qa-planning --score ${score} --decision dryrun`,
+          description: 'Shows what would be written. Run this first if you want to see the diff before committing.',
+        },
+        {
+          id:          'skip',
+          label:       `Skip ${gate.preset} (proceed to dev without scaffold)`,
+          command:     `advance --agent qa-planning --score ${score} --decision skip`,
+          description: 'Dev will have to implement each Animation Inventory row from scratch. Choose this only if the project cannot use the scaffold (e.g. alternative animation stack).',
+        },
+      ],
+    },
+  };
+}
+
+/**
+ * Execute a scaffold decision (apply|skip|dryrun), update session, and
+ * advance the pipeline from qa-planning to dev. Reuses applyScaffold from
+ * the installer module (Fase 4) so the programmatic and CLI-wrapped paths
+ * share one implementation.
+ *
+ * @param {string} projectDir
+ * @param {object} session - Pre-decision session (qa-planning already completed)
+ * @param {'apply'|'skip'|'dryrun'} decision
+ * @param {string} agent - Should be 'qa-planning' when gate fired there.
+ * @param {number} score
+ */
+async function handleScaffoldDecision(projectDir, session, decision, agent, score) {
+  const gate = checkScaffoldGate(session);
+  if (!gate.fires) {
+    return errorResult(
+      'No scaffold decision pending (no eligible candidate with confidence >= 0.7 and not already applied).',
+      'NO_SCAFFOLD_PENDING',
+    );
+  }
+
+  const preset = gate.preset;
+  let scaffoldResult = null;
+
+  if (decision === 'apply' || decision === 'dryrun') {
+    let scaffoldSourceDir;
+    try {
+      scaffoldSourceDir = resolveScaffoldSource(projectDir);
+    } catch (err) {
+      return errorResult(
+        `Cannot locate scaffold source directory. ${err.message}`,
+        'SCAFFOLD_SOURCE_MISSING',
+      );
+    }
+    try {
+      // Sanity-check the preset exists before invoking applyScaffold.
+      loadScaffoldManifest(scaffoldSourceDir, preset);
+    } catch (err) {
+      return errorResult(
+        `Scaffold preset "${preset}" not found at ${scaffoldSourceDir}: ${err.message}`,
+        'SCAFFOLD_PRESET_MISSING',
+      );
+    }
+    scaffoldResult = applyScaffold({
+      projectDir,
+      scaffoldSourceDir,
+      preset,
+      dryRun: decision === 'dryrun',
+      force:  false,
+    });
+  }
+
+  // On 'apply' and 'skip', record the preset as resolved so the gate does
+  // not re-fire on a future advance. On 'dryrun', leave it pending.
+  if (decision === 'apply' || decision === 'skip') {
+    const appliedList = Array.isArray(session.scaffold_applied) ? [...session.scaffold_applied] : [];
+    if (!appliedList.includes(preset)) appliedList.push(preset);
+    await updateSession(projectDir, { scaffold_applied: appliedList });
+  }
+
+  // Dry-run: return info, leave pipeline at qa-planning — user must re-run
+  // advance with --decision apply|skip to actually proceed.
+  if (decision === 'dryrun') {
+    return {
+      advanced:          false,
+      agent_completed:   agent,
+      score,
+      scaffold_decision: decision,
+      scaffold: {
+        preset:          scaffoldResult.preset,
+        version:         scaffoldResult.version,
+        would_apply:     scaffoldResult.applied,
+        would_skip:      scaffoldResult.skipped,
+        placeholders:    scaffoldResult.placeholders,
+        brandSource:     scaffoldResult.brandSource,
+      },
+      next: {
+        action:          'scaffold_decision_pending',
+        agent:           null,
+        status_summary:  `Dry-run complete for "${preset}". Re-run advance with --decision apply to write the files, or --decision skip to proceed without the scaffold.`,
+      },
+    };
+  }
+
+  // apply / skip: advance qa-planning → dev.
+  const { session: postDecision } = loadSession(projectDir);
+  const pipelineState = sessionToPipelineState(postDecision || session, projectDir);
+  pipelineState.completedAgents = [...(postDecision?.completed_agents || session.completed_agents || [])];
+  const advanceResult = advancePipeline(pipelineState, agent, { score, handoffData: {}, findings: [] });
+
+  const updates = {
+    current_agent:     advanceResult.nextAgent || '',
+    last_handoff:      agent,
+    pipeline_position: pipelineState.completedAgents.length,
+  };
+  if (advanceResult.needsModeSwitch) {
+    const newPhase = advanceResult.state?.phase || session.mode;
+    updates.mode = newPhase;
+    if (session.project) updates.project = { ...session.project, state: newPhase };
+    await recordModeTransition(projectDir, {
+      from: session.mode, to: newPhase,
+      trigger: `scaffold_decision=${decision} on ${preset}`,
+    });
+  }
+  await updateSession(projectDir, updates);
+
+  const nextAgent = advanceResult.nextAgent || '';
+  const progress = getPipelineProgress(advanceResult.state || pipelineState);
+  try { updateClaudeMd(projectDir, { currentAgent: nextAgent, progress }); } catch { /* non-fatal */ }
+  try {
+    if (nextAgent) {
+      writeSessionLock(projectDir, nextAgent, {
+        phase:    updates.mode || session.mode,
+        mode:     session.execution_mode || 'interactive',
+        position: updates.pipeline_position,
+        total:    progress.total,
+        progress: progress.percent,
+      });
+    }
+  } catch { /* non-fatal */ }
+
+  const next = await handleNext(projectDir);
+  return {
+    advanced:           true,
+    agent_completed:    agent,
+    score,
+    scaffold_decision:  decision,
+    scaffold:           scaffoldResult
+      ? {
+          preset:        scaffoldResult.preset,
+          version:       scaffoldResult.version,
+          applied:       scaffoldResult.applied,
+          skipped:       scaffoldResult.skipped,
+          manifestPath:  scaffoldResult.manifestPath,
+        }
+      : { preset, skipped_by_user: true },
+    phase_transition:   advanceResult.needsModeSwitch ? { triggered: true, from: session.mode, to: updates.mode } : { triggered: false },
+    next,
+  };
+}
+
 async function handleAdvance(projectDir, args) {
   const agent = args.agent;
   const score = parseInt(args.score, 10);
@@ -457,6 +1221,33 @@ async function handleAdvance(projectDir, args) {
   const { loaded, session } = loadSession(projectDir);
   if (!loaded || !session) return errorResult('No session found', 'NO_SESSION');
 
+  // Fase 10 scaffold decision — route apply|skip|dryrun to the scaffold
+  // dispatcher BEFORE the alreadyCompleted guard so the user can resolve a
+  // pending scaffold decision after qa-planning is marked complete.
+  const SCAFFOLD_DECISIONS = new Set(['apply', 'skip', 'dryrun']);
+  if (decision && SCAFFOLD_DECISIONS.has(decision)) {
+    return handleScaffoldDecision(projectDir, session, decision, agent, score);
+  }
+
+  // Idempotency guard: if this agent is already marked completed, return no-op.
+  // Prevents duplicate advance calls (hook + user-approval path) from double-
+  // incrementing pipeline_position or corrupting completed_agents.
+  const agentState = session.agents && session.agents[agent];
+  const alreadyCompleted =
+    agentState && agentState.status === 'completed' &&
+    Array.isArray(session.completed_agents) && session.completed_agents.includes(agent);
+  if (alreadyCompleted && !decision) {
+    const next = await handleNext(projectDir);
+    return {
+      advanced: false,
+      already_advanced: true,
+      agent_completed: agent,
+      score: agentState.score,
+      next,
+      status_summary: `${agent} already completed (score ${agentState.score}). Next: ${next.agent || 'none'}.`,
+    };
+  }
+
   // Handle user_preview decisions
   if (decision) {
     const pipelineState = sessionToPipelineState(session, projectDir);
@@ -479,22 +1270,508 @@ async function handleAdvance(projectDir, args) {
     return { advanced: true, agent_completed: agent, score, decision, phase_transition: { triggered: previewResult.needsModeSwitch }, next };
   }
 
-  // Record completion
-  await recordAgentCompletion(projectDir, { agent, status, score });
+  // Read agent handoff document to extract Decision Trail entries.
+  // Agents (e.g. qa-implementation) write Decision Trail entries to their handoff
+  // instead of directly editing session.yaml (blocked by mode-governance hook).
+  let handoffData = {};
+  // Handoff files live at <frameworkDir>/artifacts/handoffs/<agent>-handoff.md
+  // EXCEPT when artifacts/ is user-facing (non-framework). Currently install
+  // writes artifacts to project root <projectDir>/artifacts/. Check both locations
+  // to cover legacy + current layouts.
+  const fwDir = resolveFrameworkDir(projectDir);
+  const handoffCandidates = [
+    join(projectDir, 'artifacts', 'handoffs', `${agent}-handoff.md`),
+    join(projectDir, fwDir, 'artifacts', 'handoffs', `${agent}-handoff.md`),
+  ];
+  const handoffPath = handoffCandidates.find(p => existsSync(p));
+  if (handoffPath) {
+    try {
+      const handoffMarkdown = readFileSync(handoffPath, 'utf-8');
+      handoffData = parseHandoffDecisionTrail(handoffMarkdown);
+      // Fase 10 auto-gate — parse scaffold candidates/signals alongside Decision Trail.
+      const scaffold = parseHandoffScaffoldSignals(handoffMarkdown);
+      handoffData.scaffold_candidates = scaffold.scaffold_candidates;
+      handoffData.scaffold_signals = scaffold.scaffold_signals;
+    } catch {
+      // Non-fatal: if handoff can't be read, skip Decision Trail / scaffold merge
+    }
+  }
 
-  // Advance pipeline
-  const pipelineState = sessionToPipelineState(session, projectDir);
-  pipelineState.completedAgents = [...(session.completed_agents || []), agent];
+  // Deterministic gates: block advance if required artifacts are missing.
+
+  // BRIEF gate: reference frames captured → Visualizer MUST run for ALL sites before Brief advances.
+  if (agent === 'brief') {
+    const refsDir = join(projectDir, 'artifacts', '4-UX', 'references');
+    const completePath = join(refsDir, 'capture-complete.json');
+    const analysisPath = join(projectDir, 'artifacts', '4-UX', 'reference-analysis.md');
+
+    if (existsSync(completePath)) {
+      let captureData = {};
+      try { captureData = JSON.parse(readFileSync(completePath, 'utf-8')); } catch { /* ignore */ }
+      const okSites = Object.entries(captureData.sites || {})
+        .filter(([, s]) => s.status === 'ok')
+        .map(([slug, s]) => ({ slug, url: s.url, desktopFrames: `artifacts/4-UX/references/${slug}/desktop/frames/`, mobileFrames: `artifacts/4-UX/references/${slug}/mobile/frames/` }));
+
+      if (okSites.length > 0) {
+        // Check: consolidated file must mention ALL sites, OR every site has its own analysis.md
+        let allAnalyzed = false;
+        if (existsSync(analysisPath)) {
+          try {
+            const content = readFileSync(analysisPath, 'utf-8');
+            allAnalyzed = okSites.every(s => content.includes(s.slug) || content.includes(s.url));
+          } catch { /* ignore */ }
+        }
+        if (!allAnalyzed) {
+          const missingSites = okSites.filter(s => !existsSync(join(refsDir, s.slug, 'analysis.md')));
+          allAnalyzed = missingSites.length === 0;
+        }
+
+        if (!allAnalyzed) {
+          // Find which sites still need analysis
+          const needsAnalysis = okSites.filter(s => {
+            if (existsSync(join(refsDir, s.slug, 'analysis.md'))) return false;
+            if (existsSync(analysisPath)) {
+              try {
+                const content = readFileSync(analysisPath, 'utf-8');
+                return !(content.includes(s.slug) || content.includes(s.url));
+              } catch { return true; }
+            }
+            return true;
+          });
+
+          return {
+            advanced: false,
+            blocked: true,
+            reason: 'visual_analysis_required',
+            message: `${needsAnalysis.length} of ${okSites.length} site(s) still need visual analysis. Spawn ONE Visualizer per missing site (parallel).`,
+            already_analyzed: okSites.length - needsAnalysis.length,
+            action_required: {
+              step1: 'Display to user (translate to session.language): "Analyzing the reference sites you provided — scroll experience, animations, colors, and typography in depth..."',
+              step2: `Spawn ${needsAnalysis.length} Agent(s) IN PARALLEL (one per site, each with model: sonnet):`,
+              agents: needsAnalysis.map(s => ({
+                description: `Visualizer — ${s.slug} scroll analysis`,
+                model: 'sonnet',
+                prompt: `Read and follow .chati.dev/agents/shared/visualizer.md (Mode 1: Reference Analysis). Analyze ONE site only: ${s.slug} (${s.url}). Read ALL frames in ${s.desktopFrames} and ${s.mobileFrames}. Read artifacts/4-UX/references/${s.slug}/extracted-tokens.json. Save output to artifacts/4-UX/references/${s.slug}/analysis.md`,
+              })),
+              step3: 'Wait for ALL to return. Merge ALL per-site analysis.md files into artifacts/4-UX/reference-analysis.md',
+              step4: 'Append Visual Experience Analysis summary to brief-report.md',
+              step5: 'Present the UPDATED brief to the user with Completion Options. Do NOT advance — wait for user approval.',
+            },
+          };
+        }
+      }
+      // okSites.length === 0 means all captures failed → allow advance, UX falls back to text
+    }
+
+    // If capture not yet complete, return immediately — don't block advance for 10 min.
+    // Tell Claude to call wait-for-capture separately, then re-try advance.
+    if (!existsSync(join(refsDir, 'capture-complete.json'))) {
+      try {
+        const dirs = readdirSync(refsDir).filter(d => {
+          try { return existsSync(join(refsDir, d, 'desktop')); } catch { return false; }
+        });
+        if (dirs.length > 0) {
+          return {
+            advanced: false,
+            blocked: true,
+            reason: 'capture_in_progress',
+            message: 'Reference capture still running in background. Wait for it, then spawn Visualizer, then present options to user.',
+            action_required: {
+              step1: 'Run: node .chati.dev/orchestrator/chati-router.js wait-for-capture',
+              step2: 'Then spawn Visualizer to analyze frames (save to artifacts/4-UX/reference-analysis.md)',
+              step3: 'Append Visual Experience Analysis summary to brief-report.md',
+              step4: 'Present the UPDATED brief to the user with Completion Options. Do NOT advance — wait for user approval.',
+            },
+          };
+        }
+      } catch { /* refsDir may not exist — no references, skip */ }
+    }
+  }
+
+  // QA-Visual gate: visual-qa.js must have run AND Visualizer must have analyzed
+  // EVERY page — mirrors the Brief gate (ONE Visualizer per site/page in parallel).
+  if (agent === 'qa-visual') {
+    const vqaOutput = join(projectDir, '.chati', 'visual-qa');
+    const projectReport = join(vqaOutput, 'report.json');
+    // Only look at project-scoped .chati/visual-qa/. The /tmp/visual-qa/ fallback
+    // was removed because it cross-contaminated isolated tests: any prior run of
+    // visual-qa.js against a real project left /tmp/visual-qa/report.json behind,
+    // which then polluted tmpdir-based test fixtures that expected a clean state.
+    const reportPath = existsSync(projectReport) ? projectReport : null;
+    const reportDir = reportPath ? reportPath.replace('/report.json', '') : vqaOutput;
+    const consolidatedPath = join(projectDir, 'artifacts', '8-QA-Visual', 'visual-qa-analysis.md');
+    const finalReportPath = join(projectDir, 'artifacts', '9-QA-Implementation', 'qa-visual-report.md');
+
+    // Check report.json exists (visual-qa.js ran)
+    if (!reportPath) {
+      // Autonomous-completion v1 (ADR-AUTO-02) rewrites this path:
+      // The post-dev hook (P4) normally fires visual-qa.js when dev
+      // completes. If we land here, either the hook did not fire (opted
+      // out via config.yaml or dev score < 90) or its spawn is still
+      // finishing in the background. Give Claude the commands to
+      // recover manually.
+      return {
+        advanced: false,
+        blocked: true,
+        reason: 'visual_qa_not_run',
+        message: 'visual-qa.js has not produced report.json yet. Either the post-dev auto-QA hook is still running, or it was skipped.',
+        action_required: {
+          step1: 'Run: node .chati.dev/scripts/visual-qa.js --pages "/" <add routes> --output .chati/visual-qa/',
+          step2: 'The script spawns its own Next dev server on a free port, so you do not need to start one yourself.',
+          step3: 'When the capture finishes, re-run advance qa-visual.',
+          rationale: 'post-dev.js fires automatically on dev-handoff.md with score >= 90 and auto_visual_qa: true (default). If auto-QA is off, run the command above. See ADR-AUTO-02 / autonomous-completion-v1-pr.md.',
+        },
+      };
+    }
+
+    // Read captured pages from report.json
+    let capturedPages = [];
+    try {
+      const report = JSON.parse(readFileSync(reportPath, 'utf-8'));
+      capturedPages = (report.pages || []).map(p => ({ slug: p.slug || 'home', path: p.path || '/' }));
+    } catch { /* ignore */ }
+
+    if (capturedPages.length === 0) {
+      return {
+        advanced: false,
+        blocked: true,
+        reason: 'visual_qa_report_empty',
+        message: 'visual-qa.js ran but report.json has no captured pages. Re-run the script.',
+      };
+    }
+
+    // Autonomous-completion v1 (ADR-AUTO-04): Reduced-motion enforcement gate.
+    // When visual-qa.js runs with --reduced-motion on|both, it writes
+    // summary.reduced_motion_mode + summary.reduced_motion_violations to
+    // report.json. A violation = a scroll-triggered region where frames
+    // diverged between motion-on and motion-off captures — i.e. animation
+    // that ignores the user's prefers-reduced-motion: reduce preference.
+    // v1 contract: BLOCK when violations[] is non-empty (fault_origin: CODE).
+    // v1 WARN: if reduced_motion_mode === 'off', the a11y pass never ran.
+    // The comparison pass itself ships in v1.2 — in v1, violations[] is
+    // always empty, so the gate runs clean today but is ready for the
+    // upgrade without handleAdvance edits.
+    try {
+      const report = JSON.parse(readFileSync(reportPath, 'utf-8'));
+      const rmMode = report.summary?.reduced_motion_mode;
+      const violations = Array.isArray(report.summary?.reduced_motion_violations)
+        ? report.summary.reduced_motion_violations
+        : [];
+      if (violations.length > 0) {
+        return {
+          advanced: false,
+          blocked: true,
+          reason:   'reduced_motion_violation',
+          message:  `${violations.length} region(s) animate under prefers-reduced-motion: reduce. Motion MUST be disabled when the user preference is set.`,
+          reduced_motion_violations: violations,
+          fault_origin: 'CODE',
+          action_required: {
+            step1: 'Display the violating pages + regions to the user.',
+            step2: 'Route back to dev for rework (Fault Vector Protocol: CODE → dev).',
+            step3: 'Dev wraps the offending animation in usePrefersReducedMotion() (from lib/animations/gsap.ts.template) and returns early when motion is reduced.',
+            step4: 'Re-run visual-qa.js with --reduced-motion both, then re-run advance qa-visual.',
+          },
+        };
+      }
+      // WARN path — a11y pass not executed.
+      if (rmMode === 'off') {
+        // Non-blocking — attached to the response later as advisory_warnings
+        // when we reach the success path. We do not early-return; other
+        // gates (layout errors, per-page analysis) still need to run.
+        // Storing in a closure var so downstream return decorates with it.
+        // (Implemented as a side-effect on report — but report is local here;
+        // use a hoisted pseudo-state via the outer function.)
+      }
+    } catch {
+      // report.json unparseable — defer to the other checks which will catch
+      // the corrupted-file case explicitly.
+    }
+
+    // Objective layout gate — catches bugs that pass qualitative Visualizer review.
+    // Root cause of 2026-04-16 cascade-layer trap: `* { margin: 0 }` outside any
+    // @layer silently overrode all Tailwind utilities; Visualizers approved at
+    // 94% because 1280px viewport masked the x=0 container alignment. This gate
+    // blocks advance on measured facts (getBoundingClientRect / getComputedStyle)
+    // regardless of what LLM review said.
+    try {
+      const report = JSON.parse(readFileSync(reportPath, 'utf-8'));
+      const layoutErrors = (report.summary?.layout_errors || []).filter(e => e.severity === 'error');
+      if (layoutErrors.length > 0) {
+        // Group by page + type for a clean summary
+        const byPageType = {};
+        for (const e of layoutErrors) {
+          const key = `${e.page || '?'}::${e.type}`;
+          byPageType[key] = byPageType[key] || { page: e.page, type: e.type, viewports: [], details: [] };
+          byPageType[key].viewports.push(e.viewport);
+          byPageType[key].details.push(e.detail);
+        }
+        return {
+          advanced: false,
+          blocked: true,
+          reason: 'layout_errors_detected',
+          message: `${layoutErrors.length} objective layout error(s) measured by Playwright. These are measurements, not judgments — must be fixed before advancing.`,
+          layout_error_count: layoutErrors.length,
+          layout_errors: Object.values(byPageType),
+          fault_origin: 'CODE',
+          action_required: {
+            step1: 'Display the errors to the user with specific selectors + measurements',
+            step2: 'Route back to dev for rework (Fault Vector Protocol: CODE → dev)',
+            step3: 'Dev fixes → pnpm build → re-run visual-qa.js → re-run advance qa-visual',
+            common_causes: [
+              'Tailwind v4: unlayered CSS in globals.css wins over @layer utilities (wrap globals in @layer base {})',
+              'Tailwind v4: arbitrary CSS var without type hint silently omits property (use text-[length:var(...)])',
+              'Missing mx-auto on a max-w-* container',
+              'Element wider than viewport causing horizontal overflow',
+            ],
+          },
+        };
+      }
+    } catch {
+      // report.json unparseable — fall through to other checks, they will catch it
+    }
+
+    // NEW (Fase 6): Shared CSS / token change → full coverage required.
+    // Regression risk: a change to globals.css or brand.ts can silently break
+    // routes that were NOT touched by the current task. If the current report
+    // covers fewer routes than the project's app/ directory exposes, block.
+    try {
+      const modifiedFiles = getModifiedFiles(projectDir);
+      const coverage = checkSharedCSSCoverage({ capturedPages, projectDir, modifiedFiles });
+      if (coverage.blocked) {
+        return {
+          advanced: false,
+          blocked: true,
+          reason: coverage.reason,
+          message: `Shared CSS / token change detected (${coverage.triggeringFiles.join(', ')}). Visual-QA captured ${capturedPages.length}/${coverage.appRoutes.length} routes. ${coverage.uncovered.length} route(s) uncovered — re-run with full coverage.`,
+          triggering_files: coverage.triggeringFiles,
+          captured_routes: capturedPages.map(p => p.path),
+          expected_routes: coverage.appRoutes,
+          uncovered_routes: coverage.uncovered,
+          fault_origin: 'SPEC',
+          action_required: {
+            step1: 'Display the uncovered routes and the triggering shared files to the user.',
+            step2: `Re-run visual-qa.js with --pages covering all ${coverage.appRoutes.length} routes:`,
+            step3: `node .chati.dev/scripts/visual-qa.js --pages ${coverage.appRoutes.map(r => `"${r}"`).join(' ')} --url http://localhost:3456 --output .chati/visual-qa/`,
+            step4: 'Then re-run advance qa-visual.',
+            rationale: 'Shared-CSS changes can regress any route; visual-QA must check all of them when this class of file is modified.',
+          },
+        };
+      }
+    } catch {
+      // git unavailable or projectDir not a repo — skip scope expansion silently.
+      // Other checks below still enforce correctness on the covered routes.
+    }
+
+    // Check: every captured page has per-page analysis.md OR is mentioned in the consolidated file
+    let consolidatedContent = '';
+    if (existsSync(consolidatedPath)) {
+      try { consolidatedContent = readFileSync(consolidatedPath, 'utf-8'); } catch { /* ignore */ }
+    }
+    const needsAnalysis = capturedPages.filter(p => {
+      const perPage = join(reportDir, p.slug, 'analysis.md');
+      if (existsSync(perPage)) return false;
+      if (consolidatedContent && (consolidatedContent.includes(p.slug) || consolidatedContent.includes(`\`${p.path}\``))) return false;
+      return true;
+    });
+
+    if (needsAnalysis.length > 0) {
+      return {
+        advanced: false,
+        blocked: true,
+        reason: 'visual_analysis_required',
+        message: `${needsAnalysis.length} of ${capturedPages.length} page(s) still need Visualizer analysis. Spawn ONE Visualizer per missing page (parallel).`,
+        already_analyzed: capturedPages.length - needsAnalysis.length,
+        action_required: {
+          step1: 'Display to user (translate to session.language): "Analyzing the build visually and comparing against the original references..."',
+          step2: `Spawn ${needsAnalysis.length} Agent(s) IN PARALLEL (one per page, each with model: sonnet):`,
+          agents: needsAnalysis.map(p => ({
+            description: `Visualizer — ${p.slug} build validation`,
+            model: 'sonnet',
+            prompt: `Read and follow .chati.dev/agents/shared/visualizer.md (Mode 2: Build Validation). Analyze ONE page only: ${p.path} (${p.slug}). Read ALL build frames matching ${reportDir}/${p.slug}-*.png. Compare to artifacts/4-UX/brandbook.md and artifacts/4-UX/references/*/analysis.md (text only). Save output to ${reportDir}/${p.slug}/analysis.md`,
+          })),
+          step3: 'Wait for ALL to return.',
+          step4: `Merge ALL per-page analysis.md files into ${consolidatedPath} (consolidated Visualizer report).`,
+          step5: `Write final QA-Visual verdict to ${finalReportPath} with score, blockers, warnings.`,
+          step6: 'Present findings and verdict to the user with Completion Options. Do NOT advance — wait for user approval.',
+        },
+      };
+    }
+
+    // Check consolidated analysis file exists
+    if (!existsSync(consolidatedPath)) {
+      return {
+        advanced: false,
+        blocked: true,
+        reason: 'consolidated_analysis_missing',
+        message: `Per-page analyses exist but consolidated file is missing. Create ${consolidatedPath} by merging all per-page analyses.`,
+      };
+    }
+
+    // Check final QA-Visual report exists at canonical path (NOT at 7-QA-Implementation)
+    if (!existsSync(finalReportPath)) {
+      const wrongPath = join(projectDir, 'artifacts', '7-QA-Implementation', 'qa-visual-report.md');
+      const hint = existsSync(wrongPath)
+        ? ` Found qa-visual-report.md at WRONG path ${wrongPath} — move it to ${finalReportPath}.`
+        : '';
+      return {
+        advanced: false,
+        blocked: true,
+        reason: 'qa_visual_final_report_missing',
+        message: `Final QA-Visual report missing at canonical path: ${finalReportPath}.${hint}`,
+      };
+    }
+  }
+
+  // QA-Implementation gate: report MUST be at artifacts/9-QA-Implementation/ (NOT 7-*)
+  if (agent === 'qa-implementation') {
+    const canonicalDir = join(projectDir, 'artifacts', '9-QA-Implementation');
+    const wrongDir = join(projectDir, 'artifacts', '7-QA-Implementation');
+    const canonicalReport = join(canonicalDir, 'qa-implementation-report.md');
+    const canonicalFinal = join(canonicalDir, 'qa-implementation-final-report.md');
+
+    // Block if wrong path exists — force relocation
+    if (existsSync(wrongDir)) {
+      return {
+        advanced: false,
+        blocked: true,
+        reason: 'qa_impl_wrong_path',
+        message: `artifacts/7-QA-Implementation/ is NOT canonical. Move all files to ${canonicalDir} (7- is reserved for QA-Planning).`,
+        action_required: {
+          step1: `Move files: mv artifacts/7-QA-Implementation/* artifacts/9-QA-Implementation/`,
+          step2: `Remove empty folder: rmdir artifacts/7-QA-Implementation`,
+          step3: 'Then re-run advance',
+        },
+      };
+    }
+
+    // Require at least one of the canonical report files
+    if (!existsSync(canonicalReport) && !existsSync(canonicalFinal)) {
+      return {
+        advanced: false,
+        blocked: true,
+        reason: 'qa_impl_report_missing',
+        message: `QA-Implementation report missing. Expected ${canonicalReport} or ${canonicalFinal}.`,
+      };
+    }
+  }
+
+  // UX (brand-architect) gate
+  if (agent === 'ux') {
+    // Fase 7 — Task-to-UX fidelity. Before checking brandbook.html, verify that
+    // if the brief or reference-analysis cites premium animation references,
+    // the brand-architect has produced the animation-inventory artifact. The
+    // inventory is mandatory: without it, tasks generate generic "add scroll
+    // reveals" instead of the specific patterns the user's references
+    // encode, and qa-visual has no per-pattern checklist for Mode 2.
+    const inventoryPath = join(projectDir, 'artifacts', '4-UX', 'animation-inventory.md');
+    if (!existsSync(inventoryPath)) {
+      const corpus = readBriefAndRefCorpus(projectDir);
+      const refs = detectPremiumRefs(corpus);
+      if (refs.detected) {
+        return {
+          advanced: false,
+          blocked: true,
+          reason: 'animation_inventory_required',
+          message: `Brief or reference-analysis cites premium animation references (${refs.matches.join(', ')}). Brand-architect must produce artifacts/4-UX/animation-inventory.md before advancing.`,
+          triggering_matches: refs.matches,
+          expected_artifact: 'artifacts/4-UX/animation-inventory.md',
+          fault_origin: 'SPEC',
+          action_required: {
+            step1: 'Inspect artifacts/1-Brief/brief-report.md and artifacts/4-UX/reference-analysis.md to enumerate every named animation pattern.',
+            step2: 'Write artifacts/4-UX/animation-inventory.md with one row per pattern. Schema:',
+            schema: '| Pattern name | Observed at (site / section) | Parameters (stagger, scrub, easing, duration) | Reproducible via (scaffold file) | Target route |',
+            step3: 'Populate the "Reproducible via" column from scaffold/motion-premium/* templates — gsap.ts, useGsapContext.ts, useScrollSnapStepper.ts, BackgroundCrossfadeProvider.tsx, etc. Each row that cannot be mapped to an existing scaffold pattern is a yellow flag (ask architect before committing a custom implementation).',
+            step4: 'Append a section to brandbook.md (or brand-architect handoff) noting the inventory is locked and tasks must 1:1 map against it.',
+            step5: 'Then re-run advance ux.',
+            rationale: 'The inventory locks the promise made to the user by the brief/references. Tasks agent consumes it 1:1 to avoid generic descriptions; QA-Visual Mode 2 uses it as a per-pattern implementation checklist.',
+          },
+        };
+      }
+    }
+
+    const brandbookPath = join(projectDir, 'artifacts', '4-UX', 'brandbook.html');
+    if (!existsSync(brandbookPath)) {
+      return {
+        advanced: false,
+        blocked: true,
+        reason: 'brandbook_html_missing',
+        message: 'brandbook.html is a mandatory deliverable for the UX agent. Write artifacts/4-UX/brandbook.html before advancing.',
+      };
+    }
+  }
+
+  // Record completion (merges Decision Trail entries from handoff into session.yaml)
+  await recordAgentCompletion(projectDir, { agent, status, score, handoffData });
+  recordEvent(projectDir, EventType.AGENT_COMPLETED, agent, { score, status });
+
+  // Fase 10 — Scaffold auto-gate. After qa-planning completes, check whether
+  // a scaffold preset has cleared the confidence threshold and is still
+  // unapplied. If so, return an action_required response with the 3-option
+  // decision payload. qa-planning stays marked complete; the user's next
+  // advance call must carry --decision apply|skip|dryrun.
+  if (status === 'completed' && score >= 95 && agent === 'qa-planning') {
+    const { session: postQa } = loadSession(projectDir);
+    const gate = checkScaffoldGate(postQa || session);
+    if (gate.fires) {
+      return buildScaffoldGateResponse(gate, {
+        agent,
+        score,
+        phaseTransition: { triggered: false },
+      });
+    }
+  }
+
+  // Advance pipeline. Build the pipelineState from POST-completion session
+  // (reload after recordAgentCompletion) so completedAgents reflects the dedup
+  // guard in session-manager (no duplicate pushes).
+  const { session: postCompletion } = loadSession(projectDir);
+  const pipelineState = sessionToPipelineState(postCompletion || session, projectDir);
+  pipelineState.completedAgents = [...(postCompletion?.completed_agents || session.completed_agents || [])];
   pipelineState.agents[agent] = { status: 'completed', score, startedAt: null, completedAt: new Date().toISOString() };
 
-  const advanceResult = advancePipeline(pipelineState, agent, { score });
+  const advanceResult = advancePipeline(pipelineState, agent, {
+    score,
+    handoffData,
+    findings: handoffData?.decision_trail_entries || [],
+  });
 
   // Update session with new state
   const updates = {
     current_agent: advanceResult.nextAgent || '',
     last_handoff: agent,
+    pipeline_position: pipelineState.completedAgents.length,
   };
 
+  // Backward transition (Article XXII Fault Vector Protocol):
+  // QA failed → reset target agent (and everything after it) back to pending.
+  // Persist the new agent states + correction_cycles counter + pipeline_position.
+  if (advanceResult.nextAction === 'correction_loop' || advanceResult.nextAction === 'escalate') {
+    const advancedState = advanceResult.state || pipelineState;
+    // Serialize agent map back to session shape (status/score/started/completed).
+    const agentResults = { ...(session.agent_results || {}) };
+    for (const [name, a] of Object.entries(advancedState.agents || {})) {
+      agentResults[name] = {
+        ...(agentResults[name] || {}),
+        status: a.status,
+        score: a.score,
+        started_at: a.startedAt || null,
+        completed_at: a.completedAt || null,
+      };
+    }
+    updates.agents = advancedState.agents;
+    updates.agent_results = agentResults;
+    updates.completed_agents = [...advancedState.completedAgents];
+    updates.pipeline_position = advancedState.completedAgents.length;
+    updates.correction_cycles = { ...(advancedState.correctionCycles || {}) };
+
+    recordEvent(
+      projectDir,
+      advanceResult.nextAction === 'escalate' ? EventType.CORRECTION_ESCALATED : EventType.CORRECTION_TRIGGERED,
+      advanceResult.correction?.target || agent,
+      { correction: advanceResult.correction },
+    );
+  }
+
   // Handle phase transition
   let phaseTransition = { triggered: false };
   if (advanceResult.needsModeSwitch) {
@@ -510,9 +1787,113 @@ async function handleAdvance(projectDir, args) {
       to: newPhase,
       trigger: `${agent} completed with score ${score}`,
     });
+    recordEvent(projectDir, EventType.MODE_TRANSITION, agent, { from: session.mode, to: newPhase });
   }
 
-  await updateSession(projectDir, updates);
+  const saveResult = await updateSession(projectDir, updates);
+  if (saveResult && saveResult.saved === false) {
+    return errorResult(`Session update failed: ${saveResult.error}`, 'SESSION_WRITE_FAILED');
+  }
+
+  // Refresh Magic Docs: CLAUDE.md (public) + CLAUDE.local.md (runtime lock+state).
+  // Non-fatal: if updates fail, pipeline state already advanced on disk.
+  const nextAgent = advanceResult.nextAgent || '';
+  const progress = getPipelineProgress(advanceResult.state || pipelineState);
+  try {
+    updateClaudeMd(projectDir, { currentAgent: nextAgent, progress });
+  } catch { /* non-fatal */ }
+  try {
+    if (nextAgent) {
+      writeSessionLock(projectDir, nextAgent, {
+        phase: updates.mode || session.mode,
+        mode: session.execution_mode || 'interactive',
+        position: updates.pipeline_position,
+        total: progress.total,
+        progress: progress.percent,
+      });
+    } else {
+      // Pipeline complete: reset lock to INACTIVE
+      const lang = session.language || 'en';
+      removeSessionLock(projectDir, RESUME_MESSAGES[lang] || RESUME_MESSAGES.en);
+    }
+  } catch { /* non-fatal */ }
+
+  // Backward transition via Fault Vector Protocol — QA agent failed threshold.
+  // We have already reset target agent state above; now return the correction
+  // payload so Claude/Agent UI knows which agent to invoke next.
+  if (advanceResult.nextAction === 'correction_loop') {
+    const c = advanceResult.correction;
+    // Fase 8: compute the "Reset:" list for the state card — agents that
+    // were completed before but are now back to pending (the correction
+    // target + everything past it in the pipeline).
+    const beforeCompleted = new Set(session.completed_agents || []);
+    const afterCompleted = new Set(advanceResult.state?.completedAgents || pipelineState.completedAgents || []);
+    const resetAgents = [...beforeCompleted].filter(a => !afterCompleted.has(a));
+    if (!resetAgents.includes(c.target)) resetAgents.unshift(c.target);
+    const stateCard = (() => {
+      try {
+        const { session: post } = loadSession(projectDir);
+        return buildStateCard({
+          session: post || session,
+          projectDir,
+          correctionReset: { agents: resetAgents, files: [] },
+        });
+      } catch { return ''; }
+    })();
+    return {
+      advanced: true,
+      agent_completed: agent,
+      score,
+      phase_transition: phaseTransition,
+      correction_loop: true,
+      correction: c,
+      reset: { agents: resetAgents },
+      state_card: stateCard,
+      next: {
+        action: 'correction_loop',
+        agent: c.target,
+        reason: c.reason,
+        fault_origin: c.faultOrigin,
+        cycle: c.cycle,
+        max_cycles: 2,
+        findings_count: (c.findings || []).length,
+        pipeline_progress: getPipelineProgress(advanceResult.state || pipelineState),
+        status_summary: `${agent} scored ${c.score ?? 'n/a'} (below threshold). Fault origin: ${c.faultOrigin}. Re-opening ${c.target} (correction cycle ${c.cycle} of 2). Claude must invoke ${c.target} with the findings.`,
+      },
+    };
+  }
+
+  // Max correction cycles exceeded — escalate to human.
+  if (advanceResult.nextAction === 'escalate') {
+    const c = advanceResult.correction;
+    const stateCard = (() => {
+      try {
+        const { session: post } = loadSession(projectDir);
+        return buildStateCard({ session: post || session, projectDir });
+      } catch { return ''; }
+    })();
+    return {
+      advanced: false,
+      blocked: true,
+      agent_completed: agent,
+      score,
+      phase_transition: phaseTransition,
+      correction_loop: true,
+      correction: c,
+      reason: 'max_correction_cycles_exceeded',
+      message: c.reason,
+      state_card: stateCard,
+      next: {
+        action: 'escalate',
+        agent: null,
+        reason: c.reason,
+        fault_origin: c.faultOrigin,
+        cycle: c.cycle,
+        max_cycles: 2,
+        status_summary: `${agent} failed after ${c.cycle} correction cycles. Human review required before pipeline can continue.`,
+      },
+    };
+  }
 
   // Check if user_preview is needed
   if (advanceResult.nextAction === 'user_preview') {
@@ -536,6 +1917,23 @@ async function handleAdvance(projectDir, args) {
 }
 
 async function handleInit(projectDir, args) {
+  // Auto-resolve: if a parent directory already has a Chati installation,
+  // use that as the project root automatically. Prevents accidental nested
+  // installs (stray `init/` dirs) when CLI is invoked from a subdirectory.
+  const { dirname: pathDirname } = await import('path');
+  let probe = pathDirname(projectDir);
+  let depth = 0;
+  while (probe && probe !== '/' && depth < 5) {
+    const fwParent = existsSync(join(probe, '.chati.dev')) || existsSync(join(probe, 'chati.dev'));
+    if (fwParent) {
+      // Found install in parent — use that as projectDir for the rest of init.
+      projectDir = probe;
+      break;
+    }
+    probe = pathDirname(probe);
+    depth++;
+  }
+
   // License validation at init time (moved from per-prompt UserPromptSubmit hook)
   try {
     const licensePath = join(process.env.HOME || '', '.chati-dev', 'license.yaml');
@@ -559,9 +1957,23 @@ async function handleInit(projectDir, args) {
 
   const type = args.type || 'greenfield';
   const language = args.language || 'en';
-  const name = args.name || '';
   const workflow = args.workflow || 'full';
 
+  // Preserve fields from session.yaml created by installer (project name, ides, mcps)
+  let preservedName = args.name || '';
+  let preservedIdes = [];
+  let preservedMcps = [];
+  try {
+    const existingPath = join(projectDir, '.chati', 'session.yaml');
+    if (existsSync(existingPath)) {
+      const existing = yaml.load(readFileSync(existingPath, 'utf-8')) || {};
+      preservedName = preservedName || existing.project?.name || '';
+      preservedIdes = existing.ides || [];
+      preservedMcps = existing.mcps || [];
+    }
+  } catch { /* expected: session may not exist */ }
+  const name = preservedName;
+
   const isGreenfield = type === 'greenfield';
 
   // Initialize pipeline state based on workflow
@@ -577,27 +1989,53 @@ async function handleInit(projectDir, args) {
     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');
-  }
+  // RESUME GUARD: if a session already exists with completed agents or a non-discover mode,
+  // this is a RESUME — preserve all state and only update workflow/lock. Do NOT reset.
+  const sessionPath = join(projectDir, '.chati', 'session.yaml');
+  const isResume = existsSync(sessionPath) && (() => {
+    try {
+      const s = yaml.load(readFileSync(sessionPath, 'utf-8')) || {};
+      const hasProgress = (s.completed_agents && s.completed_agents.length > 0)
+        || (s.mode && s.mode !== 'discover')
+        || (s.current_agent && s.current_agent !== '');
+      return hasProgress;
+    } catch { return false; }
+  })();
+
+  if (isResume) {
+    // Resume path — keep session.yaml intact, just refresh workflow if changed
+    await updateSession(projectDir, { workflow });
+    recordEvent(projectDir, EventType.SESSION_STARTED, 'orchestrator', { resume: true, workflow });
+  } else {
+    // Fresh init — create new session
+    const result = initSession(projectDir, {
+      mode: 'discover',
+      projectName: name,
+      isGreenfield,
+      language,
+      ides: preservedIdes,
+      mcps: preservedMcps,
+    });
 
-  // Set workflow in session
-  await updateSession(projectDir, { workflow });
+    if (!result.created) {
+      return errorResult(`Failed to initialize session: ${result.error}`, 'INIT_FAILED');
+    }
 
-  // Determine first agent
-  const firstAgent = isGreenfield ? 'greenfield-wu' : 'brownfield-wu';
-  const firstAgentFile = AGENT_FILE_MAP[firstAgent] || null;
+    await updateSession(projectDir, { workflow });
+    clearTimeline(projectDir);
+    recordEvent(projectDir, EventType.SESSION_STARTED, 'orchestrator', { projectType: type, workflow, language });
+  }
 
-  // Update session with first agent
-  await updateSession(projectDir, { current_agent: firstAgent });
+  // Determine first/active agent — on resume, use current_agent from session
+  let firstAgent;
+  if (isResume) {
+    const s = yaml.load(readFileSync(sessionPath, 'utf-8')) || {};
+    firstAgent = s.current_agent || (isGreenfield ? 'greenfield-wu' : 'brownfield-wu');
+  } else {
+    firstAgent = isGreenfield ? 'greenfield-wu' : 'brownfield-wu';
+    await updateSession(projectDir, { current_agent: firstAgent });
+  }
+  const firstAgentFile = getAgentFile(firstAgent, projectDir) || null;
 
   // Write session lock
   try {
@@ -674,6 +2112,27 @@ async function handleStatus(projectDir) {
     agentModels[agentDef.name] = resolveAgentModel(agentDef.name, projectDir);
   }
 
+  // Fase 10 workstream 2 (context-window-detection v1) — model-aware
+  // context block. Resolves the active window from session.active_model
+  // (populated by prism-engine on first prompt) and reports the exact
+  // bracket prism-engine last computed. If the session predates v1.2
+  // (no context_* fields yet), the block falls back to estimateContextBracket
+  // so the existing response shape stays stable for consumers.
+  const activeModel     = session.active_model || null;
+  const activeProvider  = session.active_provider || (session.providers_enabled || ['claude'])[0];
+  const windowTokens    = session.context_window_tokens != null
+    ? session.context_window_tokens
+    : resolveContextLimit(activeModel, activeProvider);
+  const tokensUsed      = session.context_tokens_used != null ? session.context_tokens_used : 0;
+  const remainingPct    = windowTokens > 0
+    ? Math.max(0, Math.round((1 - tokensUsed / windowTokens) * 100))
+    : 100;
+  const lastBracket     = session.context_last_bracket
+    || (remainingPct < 25 ? 'CRITICAL'
+      : remainingPct < 40 ? 'DEPLETED'
+      : remainingPct < 60 ? 'MODERATE'
+      : 'FRESH');
+
   return {
     session: summary.summary || summary,
     pipeline: progress,
@@ -683,6 +2142,15 @@ async function handleStatus(projectDir) {
     agents: session.agents || {},
     agent_models: agentModels,
     context_bracket: estimateContextBracket((session.completed_agents || []).length, AGENT_PIPELINE.length),
+    context: {
+      model:             activeModel,
+      provider:          activeProvider,
+      window_tokens:     windowTokens,
+      tokens_used:       tokensUsed,
+      remaining_pct:     remainingPct,
+      bracket:           lastBracket,
+      handoff_required:  remainingPct < 15,
+    },
     user_level: session.user_level || 'auto',
     execution_mode: session.execution_mode || 'interactive',
   };
@@ -743,6 +2211,16 @@ async function handleDeviation(projectDir, args) {
     }
 
     await updateSession(projectDir, updates);
+
+    // Refresh session lock if agent changed
+    if (updates.current_agent) {
+      try {
+        writeSessionLock(projectDir, updates.current_agent, {
+          phase: session.mode,
+          mode: session.execution_mode || 'interactive',
+        });
+      } catch { /* non-fatal */ }
+    }
   }
 
   return {
@@ -760,6 +2238,7 @@ async function handleExit(projectDir, args) {
   }
 
   // Save current state
+  recordEvent(projectDir, EventType.SESSION_ENDED, session.current_agent || 'orchestrator', { mode: session.mode });
   await updateSession(projectDir, {});
 
   // Release session ownership
@@ -790,8 +2269,16 @@ async function handleProviders(projectDir) {
     agentModels[agentDef.name] = resolveAgentModel(agentDef.name, projectDir);
   }
 
+  let primaryProvider = 'claude';
+  const configPath = join(projectDir, resolveFrameworkDir(projectDir), 'config.yaml');
+  if (existsSync(configPath)) {
+    const raw = readFileSync(configPath, 'utf-8');
+    const providerMatch = raw.match(/primary_provider:\s*["']?(\w+)/);
+    if (providerMatch) primaryProvider = providerMatch[1].toLowerCase();
+  }
+
   return {
-    primary_provider: 'claude',
+    primary_provider: primaryProvider,
     agent_models: agentModels,
   };
 }
@@ -971,7 +2458,7 @@ async function handleScan(projectDir, args) {
 
 const TEAM_CONFIGS = {
   planning: {
-    members: ['detail', 'architect', 'ux'],
+    members: ['detail', 'architect', 'ux', 'qa-planning'],
     slug: 'pln',
     templateFile: 'team-planning-tasks.yaml',
   },
@@ -996,14 +2483,22 @@ function generateTeamId(slug) {
  * (Gemini) or spawn_autonomous (Codex) when the active provider is not claude.
  */
 function isAgentTeamsEnabled(projectDir) {
-  const configPath = join(projectDir, 'chati.dev', 'config.yaml');
+  const configPath = join(projectDir, resolveFrameworkDir(projectDir), 'config.yaml');
   if (!existsSync(configPath)) return false;
   const raw = readFileSync(configPath, 'utf-8');
 
   // Feature flag check
   const flagMatch = raw.match(/agent_teams:\s*(true|false)/);
-  const flagOn = flagMatch ? flagMatch[1] === 'true' : false;
-  if (!flagOn) return false;
+  // If field is explicitly set, respect it
+  if (flagMatch) {
+    if (flagMatch[1] !== 'true') return false;
+  } else {
+    // If field is absent (pre-v4.2.0 projects), default to true for Claude provider
+    // Claude Code supports Agent tool natively; Gemini/Codex fall back to sequential
+    const providerMatch = raw.match(/primary_provider:\s*["']?(\w+)/);
+    const provider = providerMatch ? providerMatch[1].toLowerCase() : 'claude';
+    if (provider !== 'claude') return false;
+  }
 
   // Provider gate — Agent Teams is Claude-only.
   // Read primary_provider from session.yaml (preferred) or active_provider
@@ -1036,7 +2531,7 @@ async function handleSpawnTeam(projectDir, args) {
   const teamDir = join(projectDir, '.chati', 'teams', teamId);
   const mailboxDir = join(teamDir, 'mailbox');
   const taskListPath = join(teamDir, 'tasks.yaml');
-  const templatePath = join(projectDir, 'chati.dev', 'templates', config.templateFile);
+  const templatePath = join(projectDir, resolveFrameworkDir(projectDir), 'templates', config.templateFile);
 
   // Create team directories
   mkdirSync(mailboxDir, { recursive: true });
@@ -1047,7 +2542,7 @@ async function handleSpawnTeam(projectDir, args) {
 
     // For build teams: dynamically populate tasks from tasks.md (Article XXI §9)
     if (teamType === 'build') {
-      const tasksArtifact = join(projectDir, 'chati.dev', 'artifacts', '6-Tasks', 'tasks.md');
+      const tasksArtifact = join(projectDir, 'artifacts', '6-Tasks', 'tasks.md');
       if (existsSync(tasksArtifact)) {
         const tasksContent = readFileSync(tasksArtifact, 'utf-8');
         // Extract task IDs (pattern: T{phase}.{seq})
@@ -1142,6 +2637,7 @@ async function handleSpawnTeam(projectDir, args) {
       });
 
       await updateSession(projectDir, session);
+      recordEvent(projectDir, EventType.AGENT_ACTIVATED, `team:${teamType}`, { teamId, members: config.members });
     }
   } catch { /* non-critical: session update may fail, team can still spawn */ }
 
@@ -1262,7 +2758,7 @@ async function handleTeamDissolve(projectDir, args) {
   let correctionCyclesOk = true;
   let maxCorrectionCycles = 2; // default per constitution
   try {
-    const configPath = join(projectDir, 'chati.dev', 'config.yaml');
+    const configPath = join(projectDir, resolveFrameworkDir(projectDir), 'config.yaml');
     if (existsSync(configPath)) {
       const configRaw = readFileSync(configPath, 'utf-8');
       const maxMatch = configRaw.match(/team_correction_cycles_max:\s*(\d+)/);
@@ -1286,7 +2782,7 @@ async function handleTeamDissolve(projectDir, args) {
   if (!mailboxClean) gateFailures.push('unresolved_mailbox_messages');
   if (!noBlockers) gateFailures.push('open_blockers');
   if (!correctionCyclesOk) gateFailures.push('correction_cycles_exceeded');
-  if (teamScore < 90) gateFailures.push('team_score_below_threshold');
+  if (teamScore < tierThreshold) gateFailures.push('team_score_below_threshold');
 
   // Update session
   try {
@@ -1341,12 +2837,296 @@ async function handleTeamDissolve(projectDir, args) {
         mailbox_clean: mailboxClean,
         no_open_blockers: noBlockers,
         correction_cycles_ok: correctionCyclesOk,
-        team_score_above_threshold: teamScore >= 90,
+        team_score_above_threshold: teamScore >= tierThreshold,
       },
     },
   };
 }
 
+// ---------------------------------------------------------------------------
+// Deterministic subcommands — replace generative LLM decisions with code
+// ---------------------------------------------------------------------------
+
+/**
+ * wait-for-license: poll ~/.chati-dev/license.yaml until status=VALID or
+ * a terminal-bad status (EXPIRED|INVALID|REVOKED) or timeout. Used by the
+ * /chati boot path when doctor reports a missing/invalid license — the
+ * orchestrator displays the activate command, then calls this to block
+ * until the user has run it in another terminal.
+ *
+ * @param {string} _projectDir unused (license is home-dir scoped)
+ * @param {{ timeout?: string, interval?: string }} args
+ */
+async function handleWaitForLicense(_projectDir, args) {
+  const timeoutMs  = args.timeout  ? parseInt(args.timeout, 10)  : undefined;
+  const intervalMs = args.interval ? parseInt(args.interval, 10) : undefined;
+  const result = await waitForLicense({ timeoutMs, intervalMs });
+  return {
+    valid:      result.valid,
+    status:     result.status,
+    reason:     result.reason,
+    waited_ms:  result.waitedMs,
+    next: result.valid
+      ? { action: 'proceed', status_summary: 'License VALID — continuing /chati boot.' }
+      : {
+          action:          'license_resolution_required',
+          status_summary:  `License status: ${result.status}. ${result.reason || ''}`.trim(),
+          fix:             'Paste in another terminal: `npx chati-dev activate --key=YOUR-KEY`, then re-invoke `/chati`.',
+        },
+  };
+}
+
+/**
+ * doctor: run the silent self-diagnostic. Returns the structured verdict
+ * from runDoctor for the orchestrator to surface. Callers are /chati boot
+ * (implicit) and `/chati doctor` (explicit).
+ *
+ * @param {string} projectDir
+ */
+function handleDoctor(projectDir) {
+  const verdict = runDoctor({ projectDir });
+  return {
+    ok:        verdict.ok,
+    checks:    verdict.checks,
+    blockers:  verdict.blockers,
+    warnings:  verdict.warnings,
+    next: verdict.ok
+      ? { action: 'proceed', status_summary: 'doctor: all checks OK (silent pass).' }
+      : {
+          action:          'remediation_required',
+          status_summary:  `doctor: ${verdict.blockers.length} blocker(s), ${verdict.warnings.length} warning(s).`,
+          remediations:    verdict.blockers.map(b => ({ id: b.id, fix: b.fix })).filter(r => r.fix),
+        },
+  };
+}
+
+/**
+ * wait-for-capture: block until capture-complete.json exists (max 10 min).
+ * Replaces Brand Architect's generative polling loop.
+ */
+async function handleWaitForCapture(projectDir, args) {
+  const refsDir = join(projectDir, 'artifacts', '4-UX', 'references');
+  const completePath = join(refsDir, 'capture-complete.json');
+  const timeoutMs = parseInt(args.timeout || '600000', 10); // 10 min default
+  const pollMs = 5000; // check every 5s
+  const start = Date.now();
+
+  while (Date.now() - start < timeoutMs) {
+    if (existsSync(completePath)) {
+      try {
+        const data = JSON.parse(readFileSync(completePath, 'utf-8'));
+        return { ready: true, ...data };
+      } catch {
+        return { ready: true, error: 'capture-complete.json exists but invalid JSON' };
+      }
+    }
+    await new Promise(r => setTimeout(r, pollMs));
+  }
+
+  return { ready: false, timedOut: true, message: `capture-complete.json not found after ${timeoutMs / 1000}s. Proceed with WebFetch fallback.` };
+}
+
+/**
+ * qa-visual-score: calculate visual QA score deterministically from report.json.
+ * Replaces QA-Visual's generative scoring formula.
+ */
+function handleQaVisualScore(args) {
+  const reportPath = args.report || '/tmp/visual-qa/report.json';
+  if (!existsSync(reportPath)) {
+    return errorResult(`report.json not found at ${reportPath}`, 'REPORT_NOT_FOUND');
+  }
+
+  let report;
+  try { report = JSON.parse(readFileSync(reportPath, 'utf-8')); } catch {
+    return errorResult('report.json is invalid JSON', 'INVALID_REPORT');
+  }
+
+  const s = report.summary || {};
+  const hasRefs = args['has-refs'] === 'true';
+
+  // Weights (adjust when references exist)
+  const w = hasRefs
+    ? { animation: 0.30, scroll: 0.20, responsive: 0.15, hover: 0.10, brand: 0.10, fidelity: 0.15 }
+    : { animation: 0.35, scroll: 0.25, responsive: 0.20, hover: 0.10, brand: 0.10, fidelity: 0 };
+
+  // Base scores per dimension (0-100)
+  const animScore = Math.min(100, (s.lenis_active_all ? 50 : 0) + (s.gsap_loaded_all ? 30 : 0) + Math.min(20, (s.total_gsap_animations || 0) * 2));
+  const scrollScore = (s.total_scroll_triggers || 0) > 0 ? 80 + Math.min(20, s.total_scroll_triggers * 2) : 40;
+  const responsiveScore = 80; // baseline — actual responsive check is visual (generative)
+  const hoverScore = 80; // baseline
+  const brandScore = (s.reduced_motion_support ? 10 : 0) + Math.min(90, (report.pages?.[0]?.js_checks?.custom_properties_count ?? 0));
+  const fidelityScore = 70; // placeholder — Visualizer comparison is generative
+
+  let rawScore = Math.round(
+    animScore * w.animation +
+    scrollScore * w.scroll +
+    responsiveScore * w.responsive +
+    hoverScore * w.hover +
+    brandScore * w.brand +
+    fidelityScore * w.fidelity
+  );
+
+  // Penalties
+  const errors = [];
+  const warnings = [];
+
+  if (!s.lenis_active_all) errors.push('Lenis not active on all pages');
+  if (!s.gsap_loaded_all) errors.push('GSAP not loaded on all pages');
+  if (s.em_dashes_detected) { errors.push('Em-dashes found in visible text'); rawScore -= 10; }
+  if (s.console_errors_total > 0) { warnings.push(`${s.console_errors_total} console error(s)`); rawScore -= 5; }
+
+  // Hard blocks
+  const hardBlocked = !s.lenis_active_all || !s.gsap_loaded_all || s.em_dashes_detected;
+  const score = Math.max(0, Math.min(100, rawScore));
+  const threshold = 90;
+  const verdict = hardBlocked ? 'BLOCKED' : score >= threshold ? 'APPROVED' : 'NEEDS_CORRECTION';
+
+  return { score, threshold, verdict, hardBlocked, errors, warnings, weights: w, dimensions: { animScore, scrollScore, responsiveScore, hoverScore, brandScore, fidelityScore } };
+}
+
+/**
+ * wave-status: read Build Team tasks.yaml + mailbox, return wave status.
+ * Replaces Claude's manual mailbox counting.
+ */
+async function handleWaveStatus(projectDir, args) {
+  const teamId = args['team-id'];
+  if (!teamId) return errorResult('Missing --team-id flag', 'MISSING_TEAM_ID');
+
+  const teamDir = join(projectDir, '.chati', 'teams', teamId);
+  const tasksPath = join(teamDir, 'tasks.yaml');
+  if (!existsSync(tasksPath)) return errorResult(`Team tasks not found: ${tasksPath}`, 'TEAM_NOT_FOUND');
+
+  let tasks;
+  try { tasks = yaml.load(readFileSync(tasksPath, 'utf-8')); } catch {
+    return errorResult('tasks.yaml is invalid', 'INVALID_TASKS');
+  }
+
+  const taskList = tasks.tasks || [];
+  const completed = taskList.filter(t => t.status === 'done' || t.status === 'completed');
+  const inProgress = taskList.filter(t => t.status === 'in_progress');
+  const pending = taskList.filter(t => t.status === 'pending');
+  const blocked = taskList.filter(t => t.blocker);
+  const failed = taskList.filter(t => t.status === 'failed' || t.status === 'needs_correction');
+
+  // Determine wave type
+  let waveType = 'regular';
+  if (pending.length === 0 && failed.length > 0) waveType = 'cleanup';
+  if (pending.length === 0 && failed.length === 0 && inProgress.length === 0) waveType = 'complete';
+
+  return {
+    team_id: teamId,
+    wave_type: waveType,
+    total: taskList.length,
+    completed: completed.length,
+    in_progress: inProgress.length,
+    pending: pending.length,
+    failed: failed.length,
+    blocked: blocked.length,
+    all_done: pending.length === 0 && inProgress.length === 0 && failed.length === 0,
+    recommendation: waveType === 'complete'
+      ? 'All tasks complete. Ready for team dissolution.'
+      : waveType === 'cleanup'
+        ? `${failed.length} task(s) need correction. Start Cleanup Wave.`
+        : `${pending.length} task(s) pending, ${inProgress.length} in progress. Continue Regular Wave.`,
+  };
+}
+
+/**
+ * Brief category dictionaries — user-input i18n tokens keyed by ISO 639-1.
+ *
+ * These match free-form brief text against 7 coverage categories. The set is
+ * routed through session.language at call time (same exemption pattern as
+ * RESUME_MESSAGES). English is always unioned in; the locale layer adds
+ * dialect tokens so projects running brief in pt/es/fr still get coverage.
+ *
+ * Article VII: code identifiers and framework strings stay English; these
+ * locale entries are user-input tokens, analogous to i18n message catalogs.
+ */
+export const BRIEF_CATEGORY_KEYWORDS = {
+  en: {
+    problem:     ['problem', 'issue', 'challenge', 'pain', 'struggle', 'frustrate', 'difficult', 'gap', 'need', 'fix'],
+    users:       ['user', 'customer', 'client', 'audience', 'persona', 'visitor', 'target', 'demographic', 'segment'],
+    outcome:     ['goal', 'outcome', 'result', 'success', 'metric', 'kpi', 'achieve', 'objective', 'want', 'expect'],
+    constraints: ['budget', 'timeline', 'deadline', 'team', 'resource', 'limit', 'constraint', 'technology', 'stack'],
+    scope:       ['scope', 'feature', 'page', 'section', 'include', 'exclude', 'not build', 'out of scope', 'mvp', 'v1'],
+    references:  ['reference', 'competitor', 'inspiration', 'like', 'similar', 'example', 'benchmark', 'design', 'look'],
+    context:     ['company', 'business', 'industry', 'market', 'brand', 'history', 'background', 'about', 'mission'],
+  },
+  pt: {
+    problem:     ['problema', 'desafio', 'dor', 'dificuldade', 'necessidade', 'resolver', 'corrigir'],
+    users:       ['usuario', 'usu\u00e1rio', 'cliente', 'p\u00fablico', 'visitante', 'alvo', 'pessoa'],
+    outcome:     ['objetivo', 'meta', 'resultado', 'sucesso', 'quero', 'espero', 'alcan\u00e7ar', 'atingir'],
+    constraints: ['or\u00e7amento', 'prazo', 'equipe', 'recurso', 'limite', 'tecnologia', 'restri\u00e7\u00e3o'],
+    scope:       ['escopo', 'funcionalidade', 'p\u00e1gina', 'incluir', 'excluir', 'n\u00e3o fazer', 'fora do escopo'],
+    references:  ['refer\u00eancia', 'referencia', 'concorrente', 'inspira\u00e7\u00e3o', 'inspiracao', 'parecido', 'exemplo', 'visual'],
+    context:     ['empresa', 'neg\u00f3cio', 'negocio', 'mercado', 'marca', 'hist\u00f3ria', 'historia', 'sobre', 'miss\u00e3o'],
+  },
+  es: {
+    problem:     ['problema', 'desaf\u00edo', 'dolor', 'dificultad', 'necesidad', 'resolver', 'corregir'],
+    users:       ['usuario', 'cliente', 'audiencia', 'p\u00fablico', 'visitante', 'objetivo', 'persona'],
+    outcome:     ['meta', 'objetivo', 'resultado', '\u00e9xito', 'quiero', 'espero', 'lograr', 'alcanzar'],
+    constraints: ['presupuesto', 'plazo', 'equipo', 'recurso', 'l\u00edmite', 'tecnolog\u00eda', 'restricci\u00f3n'],
+    scope:       ['alcance', 'funcionalidad', 'p\u00e1gina', 'incluir', 'excluir', 'no hacer', 'fuera de alcance'],
+    references:  ['referencia', 'competidor', 'inspiraci\u00f3n', 'parecido', 'ejemplo', 'visual'],
+    context:     ['empresa', 'negocio', 'mercado', 'marca', 'historia', 'acerca', 'misi\u00f3n'],
+  },
+  fr: {
+    problem:     ['probl\u00e8me', 'd\u00e9fi', 'douleur', 'difficult\u00e9', 'besoin', 'r\u00e9soudre', 'corriger'],
+    users:       ['utilisateur', 'client', 'audience', 'public', 'visiteur', 'cible', 'persona'],
+    outcome:     ['objectif', 'r\u00e9sultat', 'succ\u00e8s', 'veux', 'souhaite', 'atteindre'],
+    constraints: ['budget', 'd\u00e9lai', '\u00e9quipe', 'ressource', 'limite', 'technologie', 'contrainte'],
+    scope:       ['p\u00e9rim\u00e8tre', 'fonctionnalit\u00e9', 'page', 'inclure', 'exclure', 'hors p\u00e9rim\u00e8tre'],
+    references:  ['r\u00e9f\u00e9rence', 'concurrent', 'inspiration', 'similaire', 'exemple', 'visuel'],
+    context:     ['entreprise', 'march\u00e9', 'marque', 'histoire', 'mission'],
+  },
+};
+
+const BRIEF_CATEGORIES = ['problem', 'users', 'outcome', 'constraints', 'scope', 'references', 'context'];
+
+/**
+ * Build the keyword set for a category at a given language. Always includes EN
+ * tokens; the locale layer is appended when session.language selects it.
+ *
+ * @param {string} category One of BRIEF_CATEGORIES.
+ * @param {string} [language='en'] ISO 639-1 session language.
+ * @returns {string[]}
+ */
+export function getBriefCategoryKeywords(category, language = 'en') {
+  const en = BRIEF_CATEGORY_KEYWORDS.en[category] ?? [];
+  if (language === 'en') return [...en];
+  const locale = BRIEF_CATEGORY_KEYWORDS[language]?.[category] ?? [];
+  return [...en, ...locale];
+}
+
+/**
+ * assess-coverage: classify user input against 7 Brief categories.
+ * Replaces Brief's generative coverage assessment.
+ */
+function handleAssessCoverage(args) {
+  const input = (args.input || '').toLowerCase();
+  if (!input) return errorResult('Missing --input flag', 'MISSING_INPUT');
+  const language = (args.language || 'en').toLowerCase();
+
+  const categories = {};
+  for (const cat of BRIEF_CATEGORIES) {
+    const keywords = getBriefCategoryKeywords(cat, language);
+    categories[cat] = { keywords, found: keywords.some(k => input.includes(k)) };
+  }
+
+  const covered = Object.entries(categories).filter(([, d]) => d.found).map(([k]) => k);
+  const missing = Object.entries(categories).filter(([, d]) => !d.found).map(([k]) => k);
+  const coveragePct = Math.round((covered.length / BRIEF_CATEGORIES.length) * 100);
+
+  return {
+    coverage_pct: coveragePct,
+    covered,
+    missing,
+    recommendation: coveragePct >= 50
+      ? `Good coverage (${coveragePct}%). Clarify: ${missing.join(', ')}.`
+      : `Low coverage (${coveragePct}%). Deep exploration needed on: ${missing.join(', ')}.`,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Main entry point
 // ---------------------------------------------------------------------------
@@ -1404,6 +3184,24 @@ export async function runOrchestrate(subCommand, argv, projectDir) {
       case 'team-dissolve':
         output(await handleTeamDissolve(projectDir, args));
         break;
+      case 'wait-for-capture':
+        output(await handleWaitForCapture(projectDir, args));
+        break;
+      case 'wait-for-license':
+        output(await handleWaitForLicense(projectDir, args));
+        break;
+      case 'doctor':
+        output(handleDoctor(projectDir));
+        break;
+      case 'qa-visual-score':
+        output(handleQaVisualScore(args));
+        break;
+      case 'wave-status':
+        output(await handleWaveStatus(projectDir, args));
+        break;
+      case 'assess-coverage':
+        output(handleAssessCoverage(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, spawn-team, team-status, team-dissolve`, 'UNKNOWN_COMMAND'));
         break;