chati-dev 4.3.1 → 4.4.1

package/src/memory/session-digest.js

@@ -177,18 +177,23 @@ export function buildStructuredDigest(projectDir, sessionState, enrichment = {})
     },
   };
 
-  // Final budget enforcement — iterative truncation until within budget
+  // Final budget enforcement — iterative truncation until within budget.
+  // Cache `JSON.stringify(digest).length` and refresh only after a real
+  // mutation; the prior implementation serialised the entire object twice
+  // per iteration, which became expensive for large sessions.
   const truncOrder = ['next_steps', 'gotchas_found', 'files_changed', 'blockers', 'decisions_made'];
+  const measure = () => JSON.stringify(digest).length;
+  let size = measure();
   let pass = 0;
-  while (JSON.stringify(digest).length > MAX_STRUCTURED_CHARS && pass < truncOrder.length) {
+  while (size > MAX_STRUCTURED_CHARS && pass < truncOrder.length) {
     const field = truncOrder[pass];
     if (Array.isArray(digest[field]) && digest[field].length > 1) {
       digest[field] = digest[field].slice(0, Math.max(1, Math.ceil(digest[field].length / 2)));
+      size = measure();
+      if (size > MAX_STRUCTURED_CHARS) pass++; // still too big — move on
     } else {
       pass++;
     }
-    // If we halved and still too big, move to next field
-    if (JSON.stringify(digest).length > MAX_STRUCTURED_CHARS) pass++;
   }
 
   return digest;

package/src/orchestrator/cli.js

@@ -12,6 +12,8 @@
  */
 
 import { resolveFrameworkDir } from '../utils/framework-dir.js';
+import { isFeatureEnabled } from '../utils/feature-flags.js';
+import { runScriptTask, formatScriptHandoff } from '../executors/runner.js';
 
 import {
   loadSession, initSession, updateSession, recordAgentCompletion,
@@ -24,6 +26,7 @@ import {
 import { resolveContextLimit } from '../utils/provider-limits.js';
 import { waitForLicense } from '../license/wait.js';
 import { runDoctor } from './doctor.js';
+import { evaluateSurfaceCriteria } from '../autonomy/surface-criteria.js';
 import {
   getNextAgent, getAgentDefinition, AGENT_PIPELINE,
 } from './index.js';
@@ -38,8 +41,9 @@ import {
 import { analyzeDeviationImpact, applyDeviation } from './index.js';
 import { detectQuickFlow, detectStandardFlow } from './index.js';
 import { getAgentFile } from '../terminal/prompt-builder.js';
-import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync } from 'fs';
-import { join, resolve } from 'path';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from 'fs';
+import { join, resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
 import { execSync } from 'child_process';
 import yaml from 'js-yaml';
 import {
@@ -50,6 +54,15 @@ import {
 } from '../intelligence/timeline.js';
 import { updateClaudeMd } from '../memory/magic-docs.js';
 
+// Spawn commands must reference the terminal runners with an absolute,
+// layout-independent path: the old monorepo-relative
+// 'packages/chati-dev/src/terminal/...' only resolves when the command runs
+// from the monorepo root, never in an installed project (.chati.dev/_cli/ or
+// node_modules). Anchoring to this file's own location works in every layout
+// because the src/ tree shape is preserved verbatim by the CLI bundling.
+const _THISDIR = dirname(fileURLToPath(import.meta.url));
+const RUNNER = (name) => JSON.stringify(join(_THISDIR, '..', 'terminal', name));
+
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -530,13 +543,14 @@ function sessionToPipelineState(session, projectDir) {
 
 /**
  * Build the spawn command string for an autonomous agent.
+ * Exported for testing (path resolution must hold in every install layout).
  */
-function buildSpawnCommand(agent, projectDir, previousAgent, provider, timeout) {
+export function buildSpawnCommand(agent, projectDir, previousAgent, provider, timeout) {
   const parts = [
-    'node', 'packages/chati-dev/src/terminal/run-agent.js',
+    'node', RUNNER('run-agent.js'),
     '--agent', agent,
     '--task-id', `${agent}-task`,
-    '--project-dir', resolve(projectDir),
+    '--project-dir', JSON.stringify(resolve(projectDir)),
     '--previous-agent', previousAgent || 'none',
     '--provider', provider || 'claude',
     '--timeout', String(timeout || 600000),
@@ -546,14 +560,15 @@ function buildSpawnCommand(agent, projectDir, previousAgent, provider, timeout)
 
 /**
  * Build the parallel spawn command string.
+ * Exported for testing.
  */
-function buildParallelSpawnCommand(agents, projectDir, previousAgent, provider, timeout) {
+export function buildParallelSpawnCommand(agents, projectDir, previousAgent, provider, timeout) {
   const taskIds = agents.map(a => `${a}-task`).join(',');
   const parts = [
-    'node', 'packages/chati-dev/src/terminal/run-parallel.js',
+    'node', RUNNER('run-parallel.js'),
     '--agents', agents.join(','),
     '--task-ids', taskIds,
-    '--project-dir', resolve(projectDir),
+    '--project-dir', JSON.stringify(resolve(projectDir)),
     '--previous-agent', previousAgent || 'none',
     '--provider', provider || 'claude',
     '--timeout', String(timeout || 900000),
@@ -931,6 +946,25 @@ async function _handleNextInner(projectDir) {
     spawnCommand = buildSpawnCommand(nextAgent, projectDir, lastAgent, modelInfo.provider, 600000);
   }
 
+  // Surface criteria (Article XVII): even in autonomous mode, a high-stakes
+  // transition still needs a human nod. Deploy is external and effectively
+  // irreversible, so it trips a critical criterion and is never auto-confirmed
+  // by the gates alone. Hold the autonomous spawn and hand control back to the
+  // user for that step.
+  let surfaceHold = null;
+  if (action === 'spawn_autonomous' && (agentDef?.phase === 'deploy' || nextAgent === 'devops')) {
+    const verdict = evaluateSurfaceCriteria(
+      { type: 'deploy', description: `${nextAgent} (${agentDef?.phase || 'deploy'} phase)`, tags: ['external', 'destructive'] },
+      {},
+    );
+    const critical = verdict.triggers.filter((t) => t.severity === 'critical');
+    if (critical.length > 0) {
+      action = 'activate_interactive';
+      spawnCommand = null;
+      surfaceHold = { criteria: critical.map((t) => t.id), reason: critical.map((t) => t.reason).join('; ') };
+    }
+  }
+
   // Record agent activation event
   recordEvent(projectDir, EventType.AGENT_ACTIVATED, nextAgent, { action, phase: agentDef?.phase });
 
@@ -952,6 +986,7 @@ async function _handleNextInner(projectDir) {
     pipeline_progress: progress,
     session: { language: session.language, project_type: session.project_type || session.project?.type, execution_mode: session.execution_mode, user_level: session.user_level || 'auto' },
     status_summary: `${lastAgent} completed. Next: ${nextAgent} (${action.replace('_', ' ')}, ${agentDef?.phase || 'unknown'} phase).`,
+    ...(surfaceHold ? { surface: surfaceHold } : {}),
   };
 
   // Include team data when spawn_team action is selected (Article XXI)
@@ -989,6 +1024,7 @@ const SCAFFOLD_CONFIDENCE_THRESHOLD = 0.7;
 const PRESET_CONFIDENCE_THRESHOLDS = {
   'motion-premium':     0.7,
   'motion-premium-3d':  0.8,
+  'saas-dashboard':     0.7,
 };
 
 function thresholdFor(preset) {
@@ -1537,6 +1573,28 @@ async function handleAdvance(projectDir, args) {
           },
         };
       }
+
+      // Spring-motion veto: linear easing on a transition and transition-property:
+      // all are amateur-motion tells measured by visual-qa.js. Block the
+      // autonomous advance on them, the same way layout_errors block, so the code
+      // gate enforces premium motion and not only the QA-Visual agent prose.
+      const motionErrors = (report.summary?.motion_errors || []).filter(e => e.severity === 'error');
+      if (motionErrors.length > 0) {
+        return {
+          advanced: false,
+          blocked: true,
+          reason: 'motion_errors_detected',
+          message: `${motionErrors.length} amateur-motion error(s) measured: linear easing on a transition, or transition-property: all. Premium motion uses spring or cubic-bezier easing on specific compositor properties (transform, opacity).`,
+          motion_error_count: motionErrors.length,
+          motion_errors: motionErrors,
+          fault_origin: 'CODE',
+          action_required: {
+            step1: 'Display the motion errors to the user with the offending selectors',
+            step2: 'Route back to dev for rework (Fault Vector Protocol: CODE -> dev)',
+            step3: 'Dev replaces linear/all easing with a cubic-bezier on transform/opacity, re-runs visual-qa.js, then re-runs advance qa-visual',
+          },
+        };
+      }
     } catch {
       // report.json unparseable — fall through to other checks, they will catch it
     }
@@ -2654,10 +2712,10 @@ async function handleSpawnTeam(projectDir, args) {
 
   // Build spawn command
   const spawnCmd = [
-    'node', join('packages', 'chati-dev', 'src', 'terminal', 'run-team.js'),
+    'node', RUNNER('run-team.js'),
     '--team-id', teamId,
     '--team-type', teamType,
-    '--project-dir', resolve(projectDir),
+    '--project-dir', JSON.stringify(resolve(projectDir)),
     '--previous-agent', previousAgent,
     '--provider', provider,
     '--timeout', args.timeout || '1800000',
@@ -2941,7 +2999,7 @@ async function handleWaitForCapture(projectDir, args) {
  * qa-visual-score: calculate visual QA score deterministically from report.json.
  * Replaces QA-Visual's generative scoring formula.
  */
-function handleQaVisualScore(args) {
+export 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');
@@ -2955,18 +3013,51 @@ function handleQaVisualScore(args) {
   const s = report.summary || {};
   const hasRefs = args['has-refs'] === 'true';
 
+  // The animation stack the project actually uses. The motion-premium presets
+  // ship GSAP + Lenis; the saas-dashboard app-shell preset ships framer-motion;
+  // some projects use CSS only. The Lenis/GSAP presence checks apply ONLY to the
+  // gsap-lenis stack, so a framer-motion project is not falsely blocked for
+  // missing libraries it deliberately does not use. The agent resolves the stack
+  // from architecture.md and passes --animation-library (default gsap-lenis for
+  // backward compatibility with the motion presets).
+  // Default to gsap-lenis for backward compatibility (the motion presets), but do
+  // NOT assume it when the flag is absent AND the report shows no GSAP or Lenis
+  // usage at all: a clean framer-motion or CSS project would otherwise be
+  // phantom-blocked for libraries it never used. In that case fall back to a
+  // non-GSAP stack (no GSAP/Lenis hard-block) and warn that --animation-library
+  // should be passed explicitly. A project that passes the flag is unaffected.
+  const animLibFlag = args['animation-library'];
+  const animLibInferred = !animLibFlag;
+  let animLib = String(animLibFlag || 'gsap-lenis').toLowerCase();
+  if (animLibInferred && !s.gsap_loaded_all && !(s.total_gsap_animations > 0) && !s.lenis_active_all) {
+    animLib = 'unknown';
+  }
+  const isGsapStack = animLib === 'gsap-lenis' || animLib === 'gsap' || animLib === 'lenis';
+
+  // Measured error signals from the report (objective, not judged).
+  const motionErrorCount = (s.motion_errors || []).filter(e => e.severity === 'error').length;
+  const layoutErrorCount = s.layout_error_count || 0;
+  const reducedMotionViolations = (s.reduced_motion_violations || []).length;
+
   // 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
+  // Animation score is stack-aware. The gsap-lenis stack scores on Lenis + GSAP
+  // presence and animation count; any other stack scores on the motion discipline
+  // the report can measure: reduced-motion support and the absence of amateur
+  // motion (the spring-motion veto), since premium motion can be built without
+  // GSAP.
+  const animScore = isGsapStack
+    ? Math.min(100, (s.lenis_active_all ? 50 : 0) + (s.gsap_loaded_all ? 30 : 0) + Math.min(20, (s.total_gsap_animations || 0) * 2))
+    : Math.max(0, Math.min(100, 70 + (s.reduced_motion_support ? 20 : 0) + (motionErrorCount === 0 ? 10 : -30)));
+
+  const scrollScore = (s.total_scroll_triggers || 0) > 0 ? 80 + Math.min(20, s.total_scroll_triggers * 2) : (isGsapStack ? 40 : 80);
+  const responsiveScore = layoutErrorCount > 0 ? 40 : 80; // layout errors are measured; the agent judges the rest
+  const hoverScore = 80; // baseline; the agent judges interaction states from screenshots
   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
+  const fidelityScore = 70; // placeholder; the Visualizer comparison is the agent's judged signal
 
   let rawScore = Math.round(
     animScore * w.animation +
@@ -2981,18 +3072,96 @@ function handleQaVisualScore(args) {
   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 (isGsapStack && !s.lenis_active_all) errors.push('Lenis not active on all pages');
+  if (isGsapStack && !s.gsap_loaded_all) errors.push('GSAP not loaded on all pages');
+  if (motionErrorCount > 0) { errors.push(`${motionErrorCount} amateur-motion error(s): linear easing or transition:all`); rawScore -= 15; }
+  if (layoutErrorCount > 0) { errors.push(`${layoutErrorCount} objective layout error(s)`); rawScore -= 15; }
+  if (reducedMotionViolations > 0) { errors.push(`${reducedMotionViolations} reduced-motion violation(s)`); rawScore -= 10; }
   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; }
+  if (animLibInferred) warnings.push('No --animation-library was passed; resolve the motion stack from architecture.md and pass it (gsap-lenis | framer-motion | css | none) for an accurate verdict.');
+
+  // Hard blocks: measured failures that cannot be APPROVED regardless of the
+  // agent's judged 8-dimension rubric score. The agent applies visual_rubric on
+  // top of this measured floor and SHALL NOT issue APPROVED when hardBlocked.
+  const hardBlocked =
+    (isGsapStack && (!s.lenis_active_all || !s.gsap_loaded_all)) ||
+    motionErrorCount > 0 ||
+    layoutErrorCount > 0 ||
+    reducedMotionViolations > 0 ||
+    !!s.em_dashes_detected;
 
-  // 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';
+  // FLOOR_COMPUTED (not NEEDS_CORRECTION) is the label for a clean-but-below-floor
+  // measured score: it signals that this is the CLI's measured floor, NOT the gate
+  // verdict. The gate verdict is the QA-Visual agent's 8-dimension rubric score. A
+  // clean framer-motion build can sit below the measured floor yet still be APPROVED
+  // by the agent, so the CLI must not emit a correction-sounding label here.
+  const verdict = hardBlocked ? 'BLOCKED' : score >= threshold ? 'APPROVED' : 'FLOOR_COMPUTED';
+
+  return {
+    score, threshold, verdict, hardBlocked, animation_library: animLib, errors, warnings, weights: w,
+    measured_signals: {
+      motion_error_count: motionErrorCount,
+      layout_error_count: layoutErrorCount,
+      reduced_motion_violations: reducedMotionViolations,
+      em_dashes: !!s.em_dashes_detected,
+    },
+    dimensions: { animScore, scrollScore, responsiveScore, hoverScore, brandScore, fidelityScore },
+    note: 'Measured objective floor plus hard-blocks. BLOCKED is binding (a measured failure). APPROVED and FLOOR_COMPUTED are NOT the gate verdict: the QA-Visual agent applies the 8-dimension visual_rubric (chati.dev/data/qa-rubrics.yaml) for the judged dimensions and issues the verdict. FLOOR_COMPUTED means the measured floor is below the threshold but nothing is hard-blocked, so the agent rubric score decides. The agent cannot issue APPROVED when hardBlocked is true.',
+  };
+}
+
+/**
+ * run-script-task: execute a task whose execution_kind is `script` through its
+ * deterministic executor (no LLM). Gated by the execution_kinds feature flag;
+ * when the flag is off it returns ran:false so the orchestrator uses the agent
+ * path and the pipeline is unchanged. The orchestrator resolves the task fields
+ * from tasks.yaml and passes them as flags (--ref, --id, --title).
+ */
+export async function handleRunScriptTask(projectDir, args) {
+  if (!isFeatureEnabled(projectDir, 'execution_kinds')) {
+    return { ran: false, reason: 'The execution_kinds feature is off. Run this task through the agent path.', fallback: 'agent' };
+  }
+
+  const kind = String(args.kind || 'script');
+  if (kind !== 'script') {
+    return { ran: false, reason: `execution_kind "${kind}" is not auto-run by the script runner (only "script" is). Route through the normal path.`, kind };
+  }
 
-  return { score, threshold, verdict, hardBlocked, errors, warnings, weights: w, dimensions: { animScore, scrollScore, responsiveScore, hoverScore, brandScore, fidelityScore } };
+  const ref = args.ref || '';
+  if (!ref) {
+    return { ran: false, reason: 'Missing --ref (the execution_ref, for example "npm-script:test").' };
+  }
+
+  const id = args.id || args.task || '';
+  const title = args.title || '';
+  const result = await runScriptTask(projectDir, { id, title, execution_ref: ref });
+
+  // Write a synthetic handoff so the pipeline reads it like an agent handoff.
+  const timestamp = new Date().toISOString();
+  const handoff = formatScriptHandoff({ id, title }, result, timestamp);
+  let handoffPath = null;
+  try {
+    const dir = join(projectDir, resolveFrameworkDir(projectDir), 'artifacts', 'handoffs');
+    mkdirSync(dir, { recursive: true });
+    handoffPath = join(dir, `script-${(id || 'task').replace(/[^A-Za-z0-9._-]/g, '_')}.md`);
+    writeFileSync(handoffPath, handoff, 'utf-8');
+  } catch {
+    // best-effort; the structured result is still returned for the orchestrator
+  }
+
+  return {
+    ran: true,
+    executor: result.executor,
+    arg: result.arg,
+    status: result.status,
+    summary: result.summary,
+    durationMs: result.durationMs,
+    handoffPath,
+    details: result.details,
+  };
 }
 
 /**
@@ -3213,6 +3382,9 @@ export async function runOrchestrate(subCommand, argv, projectDir) {
       case 'assess-coverage':
         output(handleAssessCoverage(args));
         break;
+      case 'run-script-task':
+        output(await handleRunScriptTask(projectDir, args));
+        break;
       default:
         output(errorResult(`Unknown sub-command: ${subCommand}. Valid: next, advance, init, validate-handoff, status, deviation, exit, providers, detect-flow, backlog, qa-plan-score, qa-impl-score, scan, spawn-team, team-status, team-dissolve`, 'UNKNOWN_COMMAND'));
         break;

package/src/orchestrator/deviation-handler.js

@@ -105,7 +105,9 @@ export function detectDeviation(userMessage, _pipelineState) {
  * @returns {{ impact: 'low'|'medium'|'high', affectedAgents: string[], recommendation: string, requiresConfirmation: boolean }}
  */
 export function analyzeDeviationImpact(deviationType, pipelineState, details = {}) {
-  const currentAgent = pipelineState.current_agent;
+  // sessionToPipelineState produces camelCase (currentAgent); accept the legacy
+  // snake_case shape too so direct callers keep working.
+  const currentAgent = pipelineState.currentAgent ?? pipelineState.current_agent;
   const completedAgents = Object.entries(pipelineState.agents || {})
     .filter(([, data]) => data.status === 'completed')
     .map(([name]) => name);
@@ -268,7 +270,7 @@ export function applyDeviation(pipelineState, deviationType, details) {
           changes.push(`Reset agent: ${agentName}`);
         }
 
-        newState.current_agent = targetAgent;
+        newState.currentAgent = targetAgent;
         changes.push(`Rolled back to: ${targetAgent}`);
 
         break;
@@ -302,7 +304,7 @@ export function applyDeviation(pipelineState, deviationType, details) {
         }
 
         // Reset to initial state
-        newState.current_agent = '';
+        newState.currentAgent = '';
         newState.backlog = [];
         changes.push('Reset all agents to initial state');
 

package/src/orchestrator/doctor.js

@@ -1,21 +1,22 @@
 /**
- * @fileoverview /chati doctor — silent boot-time self-diagnostic.
+ * @fileoverview /chati doctor — silent self-diagnostic.
  *
- * Runs a battery of fast (< 200ms) filesystem + version checks every time
- * /chati boots. Pass-silent, fail-loud: the intent is that the user never
- * sees doctor output when everything is fine; they see a specific,
- * actionable message ONLY when something is off.
+ * Runs a battery of fast (< 200ms) filesystem + version checks when invoked
+ * via the /chati doctor subcommand. Pass-silent, fail-loud: the intent is that
+ * the user never sees doctor output when everything is fine; they see a
+ * specific, actionable message ONLY when something is off.
  *
- * Six checks, two severities:
+ * Seven checks, two severities:
  *
- *   id         severity  description
- *   ---------  --------  -----------
- *   license    BLOCK     ~/.chati-dev/license.yaml status != VALID (fail-open if missing)
- *   scaffold   BLOCK     projectDir/.chati.dev/ directory exists
- *   session    BLOCK     .chati/session.yaml parses cleanly (or is absent)
- *   hooks      WARN      .claude/settings.json has expected hook registrations
- *   model      WARN      session.active_model is populated (hook fills on first fire)
- *   node       BLOCK     process version >= 22
+ *   id            severity  description
+ *   ------------  --------  -----------
+ *   license       BLOCK     ~/.chati-dev/license.yaml status != VALID (fail-open if missing)
+ *   scaffold      BLOCK     projectDir/.chati.dev/ directory exists
+ *   session       BLOCK     .chati/session.yaml parses cleanly (or is absent)
+ *   hooks         WARN      .claude/settings.json has expected hook registrations
+ *   model         WARN      session.active_model is populated (hook fills on first fire)
+ *   node          BLOCK     process version >= 22
+ *   constitution  WARN      articleCount + i18n match the real "## Article" count
  *
  * BLOCK failures short-circuit boot with a fix instruction. WARN failures
  * surface as non-blocking notices.
@@ -25,7 +26,7 @@
  * verdict.
  */
 
-import { existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { readLicenseStatus } from '../license/wait.js';
 
@@ -242,8 +243,87 @@ export function checkNode({ versionString = process.version } = {}) {
   };
 }
 
+/**
+ * Constitution metadata drift. The articleCount in domains/constitution.yaml
+ * and the per-locale i18n strings must match the real number of "## Article"
+ * headings in constitution.md. Drift here is metadata-only (runtime is
+ * unaffected), so it is a WARN. Catching it keeps the registry, the localized
+ * UI and the document in sync.
+ * @param {{ projectDir: string }} opts
+ * @returns {CheckResult}
+ */
+export function checkConstitution({ projectDir }) {
+  const fwDir = ['.chati.dev', 'chati.dev']
+    .map(d => join(projectDir, d))
+    .find(d => existsSync(join(d, 'constitution.md')));
+  if (!fwDir) {
+    return { id: 'constitution', severity: SEVERITY.WARN, status: 'pass', message: 'constitution.md not found — skipping drift check.' };
+  }
+  try {
+    const md = readFileSync(join(fwDir, 'constitution.md'), 'utf-8');
+    const real = (md.match(/^#{2,3} Article /gm) || []).length;
+    const mismatches = [];
+
+    const domainPath = join(fwDir, 'domains', 'constitution.yaml');
+    if (existsSync(domainPath)) {
+      const m = readFileSync(domainPath, 'utf-8').match(/^articleCount:\s*(\d+)/m);
+      if (m && parseInt(m[1], 10) !== real) mismatches.push(`domains/constitution.yaml=${m[1]}`);
+    }
+
+    for (const locale of ['en', 'es', 'fr', 'pt']) {
+      const p = join(fwDir, 'i18n', `${locale}.yaml`);
+      if (!existsSync(p)) continue;
+      const m = readFileSync(p, 'utf-8').match(/constitution:\s*"[^"]*?(\d{1,3})\s*(?:Article|Articulo|Artigo)/i);
+      if (m && parseInt(m[1], 10) !== real) mismatches.push(`i18n/${locale}.yaml=${m[1]}`);
+    }
+
+    if (mismatches.length === 0) {
+      return { id: 'constitution', severity: SEVERITY.WARN, status: 'pass', message: `Constitution metadata in sync (${real} Articles).` };
+    }
+    return {
+      id:       'constitution',
+      severity: SEVERITY.WARN,
+      status:   'fail',
+      message:  `Constitution article-count drift (real=${real}): ${mismatches.join('; ')}`,
+      fix:      `Set those values to ${real} to match constitution.md.`,
+    };
+  } catch (err) {
+    return { id: 'constitution', severity: SEVERITY.WARN, status: 'pass', message: `Cannot verify constitution metadata: ${err.message}` };
+  }
+}
+
+/**
+ * Surface durable pipeline-advance failure markers. advance-trigger.js drops a
+ * JSON marker in .chati/failures/ when it cannot spawn the router (a silent
+ * pipeline stall). Re-surface them here so the stall is visible on the next
+ * doctor run instead of only living as an unread file.
+ * @param {{ projectDir: string }} opts
+ * @returns {CheckResult}
+ */
+export function checkFailures({ projectDir }) {
+  const failuresDir = join(projectDir, '.chati', 'failures');
+  if (!existsSync(failuresDir)) {
+    return { id: 'failures', severity: SEVERITY.WARN, status: 'pass', message: 'No pipeline-advance failures recorded.' };
+  }
+  try {
+    const markers = readdirSync(failuresDir).filter(f => f.endsWith('.json'));
+    if (markers.length === 0) {
+      return { id: 'failures', severity: SEVERITY.WARN, status: 'pass', message: 'No pipeline-advance failures recorded.' };
+    }
+    return {
+      id:       'failures',
+      severity: SEVERITY.WARN,
+      status:   'fail',
+      message:  `${markers.length} pipeline-advance failure marker(s) in .chati/failures/ — the pipeline may have stalled silently.`,
+      fix:      'Inspect .chati/failures/*.json, resolve the cause (often node not on PATH for the hook process), then delete the markers.',
+    };
+  } catch (err) {
+    return { id: 'failures', severity: SEVERITY.WARN, status: 'pass', message: `Cannot read .chati/failures/: ${err.message}` };
+  }
+}
+
 // ---------------------------------------------------------------------------
-// runDoctor — aggregate all six checks.
+// runDoctor — aggregate all checks.
 // ---------------------------------------------------------------------------
 
 /**
@@ -263,6 +343,8 @@ export function runDoctor(opts) {
     checkHooks({ projectDir: opts.projectDir }),
     checkModel({ projectDir: opts.projectDir }),
     checkNode(),
+    checkConstitution({ projectDir: opts.projectDir }),
+    checkFailures({ projectDir: opts.projectDir }),
   ];
   const blockers = checks.filter(c => c.status === 'fail' && c.severity === SEVERITY.BLOCK);
   const warnings = checks.filter(c => c.status === 'fail' && c.severity === SEVERITY.WARN);