chati-dev 4.2.2 → 4.3.0

package/framework/hooks/advance-trigger.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+/**
+ * Advance Trigger Hook — PostToolUse (runs after each Write tool call)
+ *
+ * Autonomous pipeline advance: when an agent writes its handoff file,
+ * this hook detects it and fires `chati-router.js advance` in the background
+ * so session.yaml, Magic Docs, and the next agent activation happen
+ * deterministically — without depending on Claude remembering to call advance.
+ *
+ * Trigger condition: the Write tool just wrote a file at
+ *   artifacts/handoffs/<agent>-handoff.md
+ * where the handoff's YAML frontmatter declares `status: completed` and
+ * contains `score: <N>`.
+ *
+ * The hook is observational — it always returns `{}` (no permission decision)
+ * and never blocks the tool call. The router is spawned detached with stdio
+ * ignored so it outlives the hook process.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { spawn } from 'child_process';
+
+async function readStdin() {
+  let data = '';
+  for await (const chunk of process.stdin) data += chunk;
+  return data;
+}
+
+function extractFrontmatter(markdown) {
+  if (!markdown.startsWith('---')) return null;
+  const end = markdown.indexOf('\n---', 3);
+  if (end === -1) return null;
+  const fm = markdown.slice(3, end + 1);
+  const fields = {};
+  for (const line of fm.split('\n')) {
+    const m = line.match(/^([a-zA-Z_][\w-]*):\s*(.+)$/);
+    if (m) fields[m[1].trim()] = m[2].trim().replace(/^["']|["']$/g, '');
+  }
+  return fields;
+}
+
+async function main() {
+  let input;
+  try {
+    input = JSON.parse(await readStdin() || '{}');
+  } catch {
+    process.stdout.write('{}\n');
+    return;
+  }
+
+  const toolName = input.tool_name || '';
+  const toolInput = input.tool_input || {};
+  const filePath = toolInput.file_path || '';
+  const cwd = input.cwd || process.cwd();
+
+  // Observational default — always allow the tool call through.
+  process.stdout.write('{}\n');
+
+  if (toolName !== 'Write') return;
+  if (!filePath) return;
+
+  // Match agent handoff files in either layout:
+  //   <root>/artifacts/handoffs/<agent>-handoff.md
+  //   <root>/.chati.dev/artifacts/handoffs/<agent>-handoff.md
+  const handoffMatch = filePath.match(/artifacts\/handoffs\/([a-z0-9-]+)-handoff\.md$/);
+  if (!handoffMatch) return;
+  const agent = handoffMatch[1];
+
+  // Load execution_mode from session to decide firing policy (Article XVII).
+  //
+  // Firing policy (v4.3.1):
+  // - autonomous: always fire (as before)
+  // - interactive (default): fire ONLY when the handoff is a QA agent
+  //   that failed its threshold (score below cutoff) OR verdict is
+  //   NEEDS_FIX/REJECTED. Correction loops are an INTERNAL quality process
+  //   (Fault Vector Protocol, Article XXII), not a forward step.
+  const sessionPath = join(cwd, '.chati', 'session.yaml');
+  if (!existsSync(sessionPath)) return;
+  let raw;
+  try { raw = readFileSync(sessionPath, 'utf-8'); } catch { return; }
+  const modeMatch = raw.match(/^\s*execution_mode:\s*(.+)$/m);
+  const profile = modeMatch ? modeMatch[1].trim().replace(/^["']|["']$/g, '') : 'interactive';
+
+  // Read the written handoff and check its frontmatter declares completion.
+  if (!existsSync(filePath)) return;
+  let content;
+  try { content = readFileSync(filePath, 'utf-8'); } catch { return; }
+  const fm = extractFrontmatter(content);
+  if (!fm) return;
+  if ((fm.status || '').toLowerCase() !== 'completed' && (fm.status || '').toLowerCase() !== 'complete') return;
+  const score = parseInt(fm.score, 10);
+  if (isNaN(score)) return;
+  if ((fm.agent || agent) !== agent) return;
+
+  // Decide whether to fire under interactive mode.
+  if (profile !== 'autonomous') {
+    const QA_THRESHOLDS = { 'qa-planning': 95, 'qa-implementation': 95, 'qa-visual': 90 };
+    const threshold = QA_THRESHOLDS[agent];
+    const isQA = threshold !== undefined;
+    const verdict = (fm.verdict || '').toUpperCase();
+    const qaFailed = isQA && (
+      score < threshold ||
+      verdict === 'NEEDS_FIX' ||
+      verdict === 'REJECTED'
+    );
+    if (!qaFailed) return;
+  }
+
+  // Locate the router relative to the project root.
+  // Prefer .chati.dev/ layout; fall back to legacy chati.dev/.
+  const fwCandidates = ['.chati.dev', 'chati.dev'];
+  let routerPath = null;
+  for (const fw of fwCandidates) {
+    const p = join(cwd, fw, 'orchestrator', 'chati-router.js');
+    if (existsSync(p)) { routerPath = p; break; }
+  }
+  if (!routerPath) return;
+
+  // Fire and forget: detach so the router outlives this hook process.
+  try {
+    const child = spawn('node', [routerPath, 'advance', '--agent', agent, '--score', String(score)], {
+      cwd,
+      detached: true,
+      stdio: 'ignore',
+    });
+    child.unref();
+  } catch { /* non-fatal */ }
+}
+
+main().catch(() => process.stdout.write('{}\n'));

package/framework/hooks/brief-validator.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * Brief Validator Hook — PostToolUse (runs after Write tool)
+ *
+ * When brief-handoff.md is written, validates that brief-report.md exists
+ * and contains required fields. Writes warnings directly into the handoff
+ * if validation fails. Deterministic — replaces Brief's self-validation.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+async function readStdin() {
+  let data = '';
+  for await (const chunk of process.stdin) data += chunk;
+  return data;
+}
+
+async function main() {
+  let input;
+  try {
+    input = JSON.parse(await readStdin() || '{}');
+  } catch {
+    process.stdout.write('{}\n');
+    return;
+  }
+
+  const toolName = input.tool_name || '';
+  const toolInput = input.tool_input || {};
+  const filePath = toolInput.file_path || '';
+  const cwd = input.cwd || process.cwd();
+
+  process.stdout.write('{}\n');
+
+  if (toolName !== 'Write') return;
+  if (!filePath.endsWith('handoffs/brief-handoff.md')) return;
+
+  // Validate brief-report.md
+  const reportCandidates = [
+    join(cwd, 'artifacts', '1-Brief', 'brief-report.md'),
+  ];
+  const reportPath = reportCandidates.find(p => existsSync(p));
+
+  const warnings = [];
+
+  if (!reportPath) {
+    warnings.push('brief-report.md NOT FOUND — handoff written without artifact');
+  } else {
+    const content = readFileSync(reportPath, 'utf-8');
+
+    if (!content.includes('visual_quality')) {
+      warnings.push('visual_quality field missing — downstream UX agent needs this to set quality bar');
+    }
+    if (content.includes('[TODO]') || content.includes('[TBD]')) {
+      warnings.push('Placeholders found ([TODO] or [TBD]) — report has incomplete sections');
+    }
+    if (content.length < 500) {
+      warnings.push(`brief-report.md is very short (${content.length} chars) — may be incomplete`);
+    }
+    // Check if visual_references URLs exist but captures section is missing
+    const hasUrls = content.match(/url:\s*["']?https?:\/\//);
+    if (hasUrls && !content.includes('Visual Reference Captures')) {
+      warnings.push('visual_references URLs found but Visual Reference Captures section missing — reference-trigger hook may not have fired');
+    }
+  }
+
+  if (warnings.length === 0) return;
+
+  // Append warnings to the handoff file
+  try {
+    let handoff = readFileSync(filePath, 'utf-8');
+    if (handoff.includes('## Brief Validation Warnings')) return; // idempotent
+
+    handoff += `\n\n## Brief Validation Warnings\n\n`;
+    handoff += `> Auto-generated by brief-validator hook. These are deterministic checks.\n\n`;
+    for (const w of warnings) {
+      handoff += `- ⚠ ${w}\n`;
+    }
+    writeFileSync(filePath, handoff, 'utf-8');
+  } catch { /* ignore */ }
+}
+
+main().catch(() => process.stdout.write('{}\n'));

package/framework/hooks/constitution-guard.js

@@ -72,9 +72,25 @@ async function main() {
 
   try {
     const event = JSON.parse(input);
+    const projectDir = event.cwd || process.cwd();
     const toolName = event.tool_name || '';
     const toolInput = event.tool_input || {};
 
+    // Integrity check: verify license-guard.js exists on disk.
+    // If someone deletes license-guard.js to bypass license enforcement,
+    // constitution-guard (which is a separate hook) catches it.
+    // Cross-hook verification = no single point of removal.
+    const { existsSync } = await import('fs');
+    const { join } = await import('path');
+    const fwDir = existsSync(join(projectDir, '.chati.dev')) ? '.chati.dev' : 'chati.dev';
+    const licenseGuardPath = join(projectDir, fwDir, 'hooks', 'license-guard.js');
+    if (!existsSync(licenseGuardPath)) {
+      process.stdout.write(JSON.stringify(denyOutput(
+        'License enforcement file (license-guard.js) is missing. System integrity compromised. Reinstall with: npx chati-dev init'
+      )));
+      return;
+    }
+
     // Check Write/Edit operations for secrets
     if (toolName === 'Write' || toolName === 'Edit') {
       const content = toolInput.content || toolInput.new_string || '';
@@ -92,13 +108,16 @@ async function main() {
     if (toolName === 'Bash') {
       const command = toolInput.command || '';
       if (isDestructiveCommand(command)) {
-        process.stdout.write(JSON.stringify(denyOutput(
-          `[Article IV] Destructive command detected: "${command.slice(0, 60)}...". This requires explicit user confirmation.`
+        // Advisory, not blocking — destructive commands should be confirmed
+        // by the user via Claude Code's permission prompt, not hard-blocked
+        // by the hook (which runs AFTER user approval and blocks anyway).
+        process.stdout.write(JSON.stringify(allowOutput(
+          `[Article IV] Destructive command: "${command.slice(0, 60)}..." — proceeding with user approval.`
         )));
         return;
       }
 
-      // Run 23-point shell injection security checks
+      // Run 21-point shell injection security checks
       const injectionFindings = runShellInjectionChecks(command);
       if (injectionFindings.length > 0) {
         const critical = injectionFindings.filter(f => f.severity === 'critical');
@@ -147,11 +166,11 @@ function denyOutput(reason) {
 }
 
 /**
- * 23-point shell injection security checks.
+ * 21-point shell injection security checks.
  * Inline implementation (hooks are standalone — no imports from src/).
  * Based on Claude Code's bashSecurity.ts patterns.
  */
-// SYNC: These 23 check IDs MUST match packages/chati-dev/src/security/bash-security.js
+// SYNC: These 21 check IDs MUST match packages/chati-dev/src/security/bash-security.js
 // Hooks are standalone (no imports from src/), so duplication is necessary.
 // If you update here, update bash-security.js too. Run: npm test to verify both.
 // Severity tiers:

package/framework/hooks/license-guard.js

@@ -3,15 +3,18 @@
  * License Guard Hook — UserPromptSubmit
  *
  * Validates license status before each user prompt turn.
- * Uses a 4-hour cache stored in ~/.chati-dev/license.yaml (global, all projects).
+ * Once activated, the license is trusted until explicitly revoked by the API.
  *
  * Behavior:
  * - No license file        → block with activation instructions
- * - Cache VALID < 4h       → allow silently
+ * - Cache VALID            → allow silently (always trust cached VALID status)
  * - Cache EXPIRED/INVALID  → block with renewal message
- * - Cache stale (> 4h)     → call API, refresh cache, then allow or block
- * - API unreachable + cache VALID < 24h → grace allow
- * - API unreachable + cache stale       → block (cannot verify)
+ * - Cache stale (> 24h) + API reachable → refresh cache in background
+ * - API unreachable        → use cached status (no blocking on network issues)
+ *
+ * Rationale: users activate once at install time. After that, the hook should
+ * never block due to cache expiry or network issues. Only explicit server-side
+ * revocation (EXPIRED/INVALID status returned by API) blocks the user.
  *
  * Telemetry pings are owned by session-digest.js (PreCompact event), not here.
  */
@@ -47,19 +50,24 @@ export async function checkLicense() {
     return { valid: false, reason: 'No license key configured. Run: npx chati-dev activate --key=YOUR-KEY\nGet a license at https://chati.dev/pricing', status: 'MISSING' };
   }
 
-  // Check cache validity
   const status = readYamlField(licenseRaw, 'status');
   const checkedAt = readYamlField(licenseRaw, 'checked_at');
   const age = checkedAt ? Date.now() - new Date(checkedAt).getTime() : Infinity;
 
-  if (age < CACHE_TTL_MS) {
-    if (status === 'VALID') return { valid: true, status: 'VALID' };
-    if (status === 'EXPIRED' || status === 'INVALID') {
-      return { valid: false, reason: buildMessage(status, readYamlField(licenseRaw, 'reason')), status };
-    }
+  // EXPLICIT REVOCATION — block immediately
+  // Server explicitly said this license is no longer valid.
+  if (status === 'EXPIRED' || status === 'INVALID' || status === 'REVOKED') {
+    return { valid: false, reason: buildMessage(status, readYamlField(licenseRaw, 'reason')), status };
   }
 
-  // Cache stale — call API
+  // Fresh cache (< CACHE_TTL_MS) — trust without API call
+  if (status === 'VALID' && age < CACHE_TTL_MS) {
+    return { valid: true, status: 'VALID' };
+  }
+
+  // Stale cache — try background refresh.
+  // CRITICAL: cached VALID is trusted indefinitely. API call only updates the
+  // cache or detects revocation. Network failures NEVER block the user.
   try {
     const machineId = await computeMachineId();
     const res = await fetch(
@@ -85,11 +93,13 @@ export async function checkLicense() {
     if (data.status === 'VALID') return { valid: true, status: 'VALID' };
     return { valid: false, reason: buildMessage(data.status, data.reason), status: data.status };
   } catch {
-    // API unreachable — grace period if cache is recent and was VALID
-    if (age < 24 * 60 * 60 * 1000 && status === 'VALID') {
+    // API unreachable — trust the last known status indefinitely.
+    // The user activated once; we never block due to network issues.
+    if (status === 'VALID') {
       return { valid: true, status: 'VALID', graced: true };
     }
-    return { valid: false, reason: 'Unable to verify license (network issue). If this persists, check your connection.\nRun: npx chati-dev activate --key=YOUR-KEY', status: 'NETWORK_ERROR' };
+    // Status is unknown/null and API is unreachable — only now we ask user to retry.
+    return { valid: false, reason: 'License status unknown and unable to reach validation server. Try again when online.\nRun: npx chati-dev activate --key=YOUR-KEY', status: 'NETWORK_ERROR' };
   }
 }
 
@@ -97,30 +107,55 @@ async function main() {
   let input = '';
   for await (const chunk of process.stdin) input += chunk;
 
+  // Detect hook event from stdin to output the correct schema.
+  // PreToolUse needs hookSpecificOutput.permissionDecision.
+  // UserPromptSubmit needs exit 2 + stderr (silent block).
+  let event = null;
+  try {
+    const parsed = JSON.parse(input);
+    event = parsed.hook_event_name || null;
+  } catch { /* expected: may not be JSON */ }
+
+  const isPreToolUse = event === 'PreToolUse';
+
   try {
     const result = await checkLicense();
     if (result.valid) {
-      allow();
+      process.stdout.write(isPreToolUse
+        ? JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow' } })
+        : '{}');
     } else {
-      block(result.reason);
+      if (isPreToolUse) {
+        process.stdout.write(JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'deny',
+            permissionDecisionReason: result.reason,
+          },
+        }));
+      } else {
+        process.stderr.write(result.reason);
+        process.exit(2);
+      }
     }
-  } catch { /* expected: stdin parse may fail — fail open */
-    allow();
+  } catch { /* fail open */
+    process.stdout.write(isPreToolUse
+      ? JSON.stringify({ hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow' } })
+      : '{}');
   }
 }
 
 // ---------------------------------------------------------------------------
-// Decision helpers
+// Decision helpers (used only for non-hook Bash invocations via checkLicense)
 // ---------------------------------------------------------------------------
 
-function allow() {
-  // UserPromptSubmit canonical "allow" is empty object — omit decision.
-  process.stdout.write('{}');
-}
-
 function block(reason) {
-  // UserPromptSubmit blocking schema: decision + reason at top level.
-  process.stdout.write(JSON.stringify({ decision: 'block', reason }));
+  // v4.2.2 → v4.2.3 hotfix test: try exit code 2 + stderr instead of
+  // {decision:block} JSON. The JSON form was silently consumed as context
+  // injection in production. Per docs (variant 2), exit 2 + stderr is the
+  // canonical UserPromptSubmit block mechanism.
+  process.stderr.write(reason);
+  process.exit(2);
 }
 
 function buildMessage(status, reason) {

package/framework/hooks/mode-governance.js

@@ -15,8 +15,8 @@ import { join, relative, isAbsolute } from 'path';
 
 const MODE_SCOPES = {
   planning: {
-    allowed: ['chati.dev/', '.chati/', 'chati.dev/artifacts/'],
-    description: 'Planning mode: write only to chati.dev/ and .chati/',
+    allowed: ['chati.dev/', '.chati.dev/', '.chati/', 'artifacts/', 'CLAUDE.local.md', 'CLAUDE.md', '.claude/'],
+    description: 'Planning mode: write only to framework dir, .chati/, artifacts/, and Claude config files',
   },
   build: {
     allowed: ['*'],
@@ -91,6 +91,17 @@ async function main() {
       return;
     }
 
+    // Block direct edits to session.yaml — it must be managed by CLI only.
+    // CLI uses fs.writeFileSync (not intercepted by hooks), so this only blocks
+    // Claude's Edit/Write tool calls, which is exactly what we want.
+    const rel = isAbsolute(filePath) ? relative(projectDir, filePath) : filePath;
+    if (rel === join('.chati', 'session.yaml') || rel === '.chati/session.yaml') {
+      process.stdout.write(JSON.stringify(denyOutput(
+        '[Article XV] session.yaml is managed by the CLI. Use the router: node chati.dev/orchestrator/chati-router.js advance --agent {name} --score {score}'
+      )));
+      return;
+    }
+
     const mode = getCurrentMode(projectDir);
 
     if (isPathAllowed(filePath, projectDir, mode)) {

package/framework/hooks/model-governance.js

@@ -38,6 +38,7 @@ const AGENT_MODELS = {
   tasks: { provider: 'claude', model: 'sonnet', tier: 'sonnet' },
   'qa-planning': { provider: 'claude', model: 'opus', tier: 'opus' },
   'qa-implementation': { provider: 'claude', model: 'opus', tier: 'opus' },
+  'qa-visual': { provider: 'claude', model: 'opus', tier: 'opus' },
   dev: { provider: 'claude', model: 'opus', tier: 'opus' },
   devops: { provider: 'claude', model: 'sonnet', tier: 'sonnet' },
 };

package/framework/hooks/post-dev.js

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+/**
+ * Post-Dev Auto-QA Hook — PostToolUse (runs after Write tool calls)
+ *
+ * Autonomous-completion v1 (ADR-AUTO-06). When dev writes its handoff file
+ * with status=completed and score >= threshold, this hook spawns
+ * visual-qa.js detached — 6 viewports + reduced-motion pass — so the next
+ * `/chati` turn finds .chati/visual-qa/report.json already populated.
+ *
+ * The user never types `pnpm build && pnpm start`. visual-qa.js owns its
+ * own dev-server (`npx next dev -p <port>` unless --no-server); this hook
+ * just spawns it with the right arguments and exits.
+ *
+ * Opt-out: set `auto_visual_qa: false` in `chati.dev/config.yaml` (or
+ * `.chati.dev/config.yaml` for installed projects). Default is true — the
+ * zero-commands thesis.
+ *
+ * Trigger condition:
+ *   Write tool wrote `artifacts/handoffs/dev-handoff.md` with frontmatter
+ *   `status: completed` AND `score: >= 90`.
+ *
+ * Observational: always returns `{}` — never blocks the Write call. The
+ * spawn is detached with stdio ignored so it outlives this hook process.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { spawn } from 'child_process';
+
+export const DEV_SCORE_THRESHOLD = 90;
+
+// ---------------------------------------------------------------------------
+// Config loader — checks both installed (.chati.dev) and dev (chati.dev).
+// ---------------------------------------------------------------------------
+
+export function readAutoVisualQaConfig(projectDir) {
+  const candidates = [
+    join(projectDir, '.chati.dev', 'config.yaml'),
+    join(projectDir, 'chati.dev', 'config.yaml'),
+  ];
+  for (const p of candidates) {
+    if (!existsSync(p)) continue;
+    try {
+      const raw = readFileSync(p, 'utf-8');
+      const match = raw.match(/^\s*auto_visual_qa:\s*(true|false)\s*$/m);
+      if (match) return match[1] === 'true';
+    } catch { /* fall through — config unreadable, use default */ }
+  }
+  return true; // default ON per ADR-AUTO-06
+}
+
+// ---------------------------------------------------------------------------
+// Handoff frontmatter extraction.
+// ---------------------------------------------------------------------------
+
+export function extractHandoffMeta(markdown) {
+  if (!markdown || !markdown.startsWith('---')) return null;
+  const end = markdown.indexOf('\n---', 3);
+  if (end === -1) return null;
+  const fm = markdown.slice(3, end + 1);
+  const meta = {};
+  for (const line of fm.split('\n')) {
+    const m = line.match(/^([a-zA-Z_][\w-]*):\s*(.+)$/);
+    if (m) meta[m[1].trim()] = m[2].trim().replace(/^["']|["']$/g, '');
+  }
+  return meta;
+}
+
+// ---------------------------------------------------------------------------
+// Route discovery (duplicate of cli.js discoverAppRoutes — hooks cannot
+// import package modules).
+// ---------------------------------------------------------------------------
+
+import { readdirSync } from 'fs';
+
+export function discoverRoutes(projectDir) {
+  const candidates = [join(projectDir, 'app'), join(projectDir, 'src', 'app')];
+  const appDir = candidates.find(d => existsSync(d));
+  if (!appDir) return ['/'];
+  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;
+        if (name.startsWith('_')) continue;
+        if (name.startsWith('[')) continue;
+        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, []);
+  const unique = [...new Set(routes)].sort();
+  return unique.length > 0 ? unique : ['/'];
+}
+
+// ---------------------------------------------------------------------------
+// Spawn decision — returns the command + args to run, or null when auto-QA
+// should not fire. Pure for testability.
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {{ projectDir: string, toolName: string, filePath: string }} ctx
+ * @returns {{ command: string, args: string[] } | null}
+ */
+export function decideSpawn(ctx) {
+  if (ctx.toolName !== 'Write') return null;
+  if (!ctx.filePath) return null;
+
+  // Match only dev-handoff.md in the canonical paths.
+  const handoffMatch = ctx.filePath.match(/artifacts\/handoffs\/dev-handoff\.md$/);
+  if (!handoffMatch) return null;
+
+  // Read the handoff to confirm status=completed and score passes threshold.
+  let meta = null;
+  try {
+    const raw = readFileSync(ctx.filePath, 'utf-8');
+    meta = extractHandoffMeta(raw);
+  } catch { return null; }
+  if (!meta) return null;
+  if (meta.status !== 'completed') return null;
+  const score = parseInt(meta.score, 10);
+  if (!Number.isFinite(score) || score < DEV_SCORE_THRESHOLD) return null;
+
+  // Config opt-out wins.
+  if (!readAutoVisualQaConfig(ctx.projectDir)) return null;
+
+  // Resolve script path.
+  const scriptCandidates = [
+    join(ctx.projectDir, '.chati.dev', 'scripts', 'visual-qa.js'),
+    join(ctx.projectDir, 'chati.dev', 'scripts', 'visual-qa.js'),
+  ];
+  const script = scriptCandidates.find(existsSync);
+  if (!script) return null;
+
+  const routes = discoverRoutes(ctx.projectDir);
+  const output = join(ctx.projectDir, '.chati', 'visual-qa');
+
+  return {
+    command: 'node',
+    args: [
+      script,
+      '--pages', ...routes,
+      '--output', output,
+      '--reduced-motion', 'on', // accessibility pass; gate in P6 reads this
+    ],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Hook entry point.
+// ---------------------------------------------------------------------------
+
+async function readStdin() {
+  let data = '';
+  for await (const chunk of process.stdin) data += chunk;
+  return data;
+}
+
+async function main() {
+  let input;
+  try {
+    input = JSON.parse(await readStdin() || '{}');
+  } catch {
+    process.stdout.write('{}\n');
+    return;
+  }
+
+  const ctx = {
+    projectDir: input.cwd || process.cwd(),
+    toolName:   input.tool_name || '',
+    filePath:   (input.tool_input && input.tool_input.file_path) || '',
+  };
+
+  // Observational default — the hook never blocks the Write call.
+  process.stdout.write('{}\n');
+
+  const plan = decideSpawn(ctx);
+  if (!plan) return;
+
+  try {
+    const child = spawn(plan.command, plan.args, {
+      cwd:      ctx.projectDir,
+      detached: true,
+      stdio:    'ignore',
+    });
+    child.unref();
+  } catch (err) {
+    process.stderr.write(`[chati] post-dev spawn failed: ${err.message}\n`);
+  }
+}
+
+import { fileURLToPath } from 'url';
+import { realpathSync } from 'fs';
+if (process.argv[1]) {
+  try {
+    if (realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+      main();
+    }
+  } catch { /* not invoked as a script */ }
+}