@chemx/starter-kit 26.9.21-8 → 26.9.24-393

package/cli/audit/reporter-clones.js

@@ -0,0 +1,33 @@
+import { ANSI } from '../theme.js';
+
+export const formatCloneReport = (cloneResult) => {
+  const { count, threshold, exactClones = [], nearClones = [], pairs = [] } = cloneResult;
+  const hasPairs = Array.isArray(pairs) && pairs.length > 0;
+  if (!hasPairs) {
+    return `   ${ANSI.LIME}✔ Zero duplicate clone hazards detected (threshold: ${threshold})${ANSI.RESET}\n`;
+  }
+
+  const lines = [
+    `   ${ANSI.BOLD}${ANSI.PINK}Semantic Clone Detection (${count} candidate pairs >= ${threshold})${ANSI.RESET}`
+  ];
+
+  const hasExact = exactClones.length > 0;
+  if (hasExact) {
+    lines.push(`     ${ANSI.RED}${ANSI.BOLD}Hazard: ${exactClones.length} high-similarity duplicate(s) (>= 0.95)${ANSI.RESET}`);
+    for (const p of exactClones) {
+      const simPct = Math.round(p.similarity * 100);
+      lines.push(`       ${ANSI.RED}[${simPct}%]${ANSI.RESET} ${p.fileA} <-> ${p.fileB}`);
+    }
+  }
+
+  const hasNear = nearClones.length > 0;
+  if (hasNear) {
+    lines.push(`     ${ANSI.GOLD}Harmonization Candidates: ${nearClones.length} structural clone(s)${ANSI.RESET}`);
+    for (const p of nearClones) {
+      const simPct = Math.round(p.similarity * 100);
+      lines.push(`       ${ANSI.GOLD}[${simPct}%]${ANSI.RESET} ${p.fileA} <-> ${p.fileB}`);
+    }
+  }
+
+  return lines.join('\n') + '\n';
+};

package/cli/audit/reporter-hotspot-graph.js

@@ -0,0 +1,34 @@
+import { ANSI } from '../theme.js';
+
+export const formatHotspotGraphReport = (graphResult) => {
+  const { count, hotspots = [] } = graphResult;
+  const hasHotspots = Array.isArray(hotspots) && hotspots.length > 0;
+  if (!hasHotspots) {
+    return `   ${ANSI.LIME}✔ Zero cascading violation hotspots detected.${ANSI.RESET}\n`;
+  }
+
+  const lines = [
+    `   ${ANSI.BOLD}${ANSI.PINK}Cascading Violation Hotspot Graph (${count} files with propagating debt)${ANSI.RESET}`
+  ];
+
+  for (let idx = 0; idx < hotspots.length; idx++) {
+    const h = hotspots[idx];
+    const rank = idx + 1;
+    const blast = h.blastRadius;
+    const critStr = h.criticalCount > 0 ? `${ANSI.RED}${h.criticalCount} crit${ANSI.RESET}, ` : '';
+    const highStr = h.highCount > 0 ? `${ANSI.GOLD}${h.highCount} high${ANSI.RESET}, ` : '';
+    const medStr = `${h.medCount} med`;
+
+    lines.push(
+      `     ${ANSI.BOLD}#${rank} ${ANSI.CYAN}${h.filePath}${ANSI.RESET} [${h.tier}, ${h.lines} LOC]`
+    );
+    lines.push(
+      `        ${ANSI.RED}Cascading Risk: ${h.cascadingRisk} pts${ANSI.RESET} (Violations: ${critStr}${highStr}${medStr})`
+    );
+    lines.push(
+      `        ${ANSI.DIM}Blast Radius: ${blast.totalImpact} consumers (${blast.directConsumers} direct, ${blast.impactedTests} tests across ${blast.depth} hops)${ANSI.RESET}`
+    );
+  }
+
+  return lines.join('\n') + '\n';
+};

package/cli/audit/rules-registry.js

@@ -117,9 +117,14 @@ export const RULE_REGISTRY = {
     directive: 'Extract related state and effects into dedicated domain hooks'
   },
   HOOK_RETURN_OVERLOAD: {
+    pillar: PILLARS.PILLAR_3,
+    severity: 'MEDIUM',
+    directive: 'Limit hook return values to 3 to 5 properties (Deprecated: use HOOK_SHAPE_CONTRACT)'
+  },
+  HOOK_SHAPE_CONTRACT: {
     pillar: PILLARS.PILLAR_3,
     severity: 'HIGH',
-    directive: 'Limit hook return values to 3 to 5 properties (State + Status + Actions)'
+    directive: 'Structure hook returns into flat State, Status, and verb-prefixed Actions buckets'
   },
   CONTROLLER_VIEW_MISMATCH: {
     pillar: PILLARS.PILLAR_3,

package/cli/audit/rules.js

@@ -19,8 +19,9 @@ import {
   createExtendedVisitors
 } from './extended-visitors.js';
 import { createPatternVisitors, recordTemplatePatterns } from './pattern-detector.js';
+import { createHookShapeRegistry } from './hook-shape-validator.js';
 
-export { PILLARS, RULE_REGISTRY };
+export { PILLARS, RULE_REGISTRY, createHookShapeRegistry };
 
 export const auditCode = (content, filePath, relativePath, options = {}) => {
   const violations = [];
@@ -145,7 +146,8 @@ export const auditCode = (content, filePath, relativePath, options = {}) => {
   }
 
   const traverseFn = traverse.default || traverse;
-  const visitors = createAstVisitors({ relativePath, violations });
+  const hookRegistry = options.hookRegistry || createHookShapeRegistry();
+  const visitors = createAstVisitors({ relativePath, violations, hookRegistry });
   const slopVisitors = createAiSlopVisitors({ relativePath, violations });
   const extendedVisitors = createExtendedVisitors({ relativePath, violations });
   const patternVisitors = options.patternRegistry
@@ -169,5 +171,11 @@ export const auditCode = (content, filePath, relativePath, options = {}) => {
 
   traverseFn(ast, mergedVisitors);
 
+  const shouldRunLocalConsistency = !options.hookRegistry;
+  if (shouldRunLocalConsistency) {
+    const consistencyViolations = hookRegistry.validateCrossHookConsistency();
+    violations.push(...consistencyViolations);
+  }
+
   return violations;
 };

package/cli/audit/rules.spec.js

@@ -203,3 +203,132 @@ export const debugCount = (itemCount: number) => {
   assert.strictEqual(violation, undefined);
 });
 
+test("Audit Hook Shape Contract: passes flat hook with 4 actions, 2 state fields, 1 status field (7 total)", () => {
+  const code = `
+export const useTodoList = () => {
+  const items = ref([]);
+  const filter = ref("all");
+  const isLoading = ref(false);
+
+  const addItem = (item) => { items.value.push(item); };
+  const toggleItem = (id) => { /* toggle */ };
+  const removeItem = (id) => { /* remove */ };
+  const setFilter = (next) => { filter.value = next; };
+
+  return {
+    items,
+    filter,
+    isLoading,
+    addItem,
+    toggleItem,
+    removeItem,
+    setFilter
+  };
+};
+`;
+  const violations = auditCode(code, "src/useTodoList.ts", "src/useTodoList.ts");
+  const shapeViolation = violations.find((v) => v.rule === "HOOK_SHAPE_CONTRACT");
+  assert.strictEqual(shapeViolation, undefined, "Expected HOOK_SHAPE_CONTRACT to pass for flat 7-property hook");
+
+  const overloadViolation = violations.find((v) => v.rule === "HOOK_RETURN_OVERLOAD");
+  assert.ok(overloadViolation, "Expected deprecated HOOK_RETURN_OVERLOAD warning");
+  assert.strictEqual(overloadViolation.severity, "MEDIUM", "Expected downgraded warning severity for HOOK_RETURN_OVERLOAD");
+});
+
+test("Audit Hook Shape Contract: fails hook with actions nested under actions wrapper", () => {
+  const code = `
+export const useTodoList = () => {
+  const items = ref([]);
+  const filter = ref("all");
+  const isLoading = ref(false);
+
+  const addItem = (item) => { items.value.push(item); };
+  const toggleItem = (id) => { /* toggle */ };
+  const removeItem = (id) => { /* remove */ };
+  const setFilter = (next) => { filter.value = next; };
+
+  return {
+    items,
+    filter,
+    isLoading,
+    actions: {
+      addItem,
+      toggleItem,
+      removeItem,
+      setFilter
+    }
+  };
+};
+`;
+  const violations = auditCode(code, "src/useTodoList.ts", "src/useTodoList.ts");
+  const shapeViolation = violations.find((v) => v.rule === "HOOK_SHAPE_CONTRACT");
+  assert.ok(shapeViolation, "Expected HOOK_SHAPE_CONTRACT failure for nested action wrapper");
+  assert.strictEqual(shapeViolation.severity, "HIGH");
+  assert.ok(shapeViolation.hazard.includes("actions"));
+});
+
+test("Audit Hook Shape Contract: flags raw DOM ref in hook return", () => {
+  const code = `
+export const useDropdown = () => {
+  const isOpen = ref(false);
+  const containerRef = ref(null);
+  const toggleDropdown = () => { isOpen.value = !isOpen.value; };
+
+  return {
+    isOpen,
+    containerRef,
+    toggleDropdown
+  };
+};
+`;
+  const violations = auditCode(code, "src/useDropdown.ts", "src/useDropdown.ts");
+  const shapeViolation = violations.find((v) => v.rule === "HOOK_SHAPE_CONTRACT");
+  assert.ok(shapeViolation, "Expected HOOK_SHAPE_CONTRACT failure for raw DOM ref");
+  assert.strictEqual(shapeViolation.severity, "HIGH");
+  assert.ok(shapeViolation.hazard.includes("containerRef"));
+});
+
+test("Audit Hook Shape Contract: flags non-verb action handler in hook return", () => {
+  const code = `
+export const useCounter = () => {
+  const count = ref(0);
+  const onToggle = () => { count.value += 1; };
+
+  return {
+    count,
+    onToggle
+  };
+};
+`;
+  const violations = auditCode(code, "src/useCounter.ts", "src/useCounter.ts");
+  const shapeViolation = violations.find((v) => v.rule === "HOOK_SHAPE_CONTRACT");
+  assert.ok(shapeViolation, "Expected HOOK_SHAPE_CONTRACT failure for onToggle");
+  assert.strictEqual(shapeViolation.severity, "HIGH");
+  assert.ok(shapeViolation.hazard.includes("onToggle"));
+});
+
+test("Audit Hook Shape Contract: flags cross-hook naming inconsistency for loading state", () => {
+  const code = `
+export const useFirst = () => {
+  const items = ref([]);
+  const isLoading = ref(false);
+  const fetchItems = () => {};
+  return { items, isLoading, fetchItems };
+};
+
+export const useSecond = () => {
+  const user = ref(null);
+  const loading = ref(false);
+  const fetchUser = () => {};
+  return { user, loading, fetchUser };
+};
+`;
+  const violations = auditCode(code, "src/useMulti.ts", "src/useMulti.ts");
+  const inconsistentViolation = violations.find(
+    (v) => v.rule === "HOOK_SHAPE_CONTRACT" && v.hazard.includes("loading")
+  );
+  assert.ok(inconsistentViolation, "Expected cross-hook naming inconsistency failure for loading vs isLoading");
+  assert.strictEqual(inconsistentViolation.severity, "HIGH");
+  assert.ok(inconsistentViolation.hazard.includes("isLoading"));
+});
+

package/cli/audit-stages.spec.js

@@ -0,0 +1,30 @@
+import test from 'node:test';
+import assert from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import { runAudit } from './audit.js';
+
+test('audit: options.stage tags the report as draft or strict', () => {
+  const tmpDir = path.resolve(process.cwd(), 'scratch/test-audit-stage');
+  if (fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
+  fs.mkdirSync(tmpDir, { recursive: true });
+
+  // Sample file with an inline multi-clause boolean (MEDIUM severity)
+  const code = `export const check = (a: number, b: number, c: number) => {
+  if (a > 0 && b > 0 && c > 0) return true;
+  return false;
+};`;
+  fs.writeFileSync(path.join(tmpDir, 'sample.ts'), code, 'utf-8');
+
+  const draftReport = runAudit(tmpDir, { stage: 'draft' });
+  assert.strictEqual(draftReport.stage, 'draft');
+  assert.ok(draftReport.totalViolations > 0);
+
+  const hasCritical = draftReport.violations.some((v) => v.severity === 'CRITICAL');
+  assert.strictEqual(hasCritical, false, 'Should have 0 critical violations');
+
+  const strictReport = runAudit(tmpDir, { stage: 'strict' });
+  assert.strictEqual(strictReport.stage, 'strict');
+
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});

package/cli/audit.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { auditCode, PILLARS, RULE_REGISTRY } from './audit/rules.js';
+import { auditCode, PILLARS, RULE_REGISTRY, createHookShapeRegistry } from './audit/rules.js';
 import { createPatternRegistry } from './audit/pattern-detector.js';
 import {
   buildRemediationRoadmap,
@@ -116,6 +116,7 @@ const auditFileEntry = (fullPath, relPath, scanOptions) => {
   const hookCount = hookMatches ? hookMatches.length : 0;
   const fileViolations = auditCode(content, fullPath, relPath, {
     patternRegistry: scanOptions.patternRegistry,
+    hookRegistry: scanOptions.hookRegistry,
     fast: scanOptions.fast
   });
 
@@ -174,15 +175,20 @@ export const scanDirectory = (targetDir, baseDir) => {
 };
 
 export const runAudit = (targetDir = 'src', options = {}) => {
-  const cwd = process.cwd();
-  const absoluteTarget = path.resolve(cwd, targetDir);
+  const cwd = options.cwd || process.cwd();
+  const absoluteTarget = path.isAbsolute(targetDir) ? targetDir : path.resolve(cwd, targetDir);
   const patternRegistry = createPatternRegistry();
+  const hookRegistry = createHookShapeRegistry();
   const { violations, fileStats, totalHooks } = scanTree(absoluteTarget, cwd, {
     patternRegistry,
+    hookRegistry,
     fast: Boolean(options.fast),
     fileList: options.fileList || null
   });
 
+  const crossHookViolations = hookRegistry.validateCrossHookConsistency();
+  violations.push(...crossHookViolations);
+
   const scannedFiles = fileStats.length;
   const totalLoc = fileStats.reduce((acc, f) => acc + f.lineCount, 0);
   const avgLoc = scannedFiles > 0 ? Math.round(totalLoc / scannedFiles) : 0;
@@ -226,8 +232,11 @@ export const runAudit = (targetDir = 'src', options = {}) => {
   const patterns = patternRegistry.resolveHarmonizationCandidates(hotspots);
   const roadmap = buildRemediationRoadmap({ hotspots, violations, patterns });
 
+  const stage = options.stage || (options.relax ? 'draft' : 'strict');
+
   const report = {
     targetDir,
+    stage,
     options,
     scannedFiles,
     totalViolations: violations.length,

package/cli/commands/cmd-audit.js

@@ -1,5 +1,5 @@
 /**
- * cmd-audit.js — Audit command orchestrator.
+ * cmd-audit.js: Audit command orchestrator.
  * Single responsibility: run the full AST audit pipeline given CLI args.
  * Extracted from cli/index.js per Directive 1.A (Monolith Decomposition).
  */
@@ -47,6 +47,19 @@ export const runAudit = async (customDir, isCli, rawArgs, loadProjectConfig) =>
   const isPromptOnFail = rawArgs.includes('--prompt-on-fail');
   const isCopyPrompt = rawArgs.includes('--copy-prompt');
 
+  const stageFlag = rawArgs.find((arg) => arg.startsWith('--stage='));
+  let stage = 'strict';
+  if (stageFlag) {
+    stage = stageFlag.split('=')[1];
+  } else if (rawArgs.includes('--relax') || rawArgs.includes('--draft')) {
+    stage = 'draft';
+  } else if (isStrict) {
+    stage = 'strict';
+  } else if (projectConfig.stage) {
+    stage = projectConfig.stage;
+  }
+  const isDraft = stage === 'draft';
+
   const dirFlag = rawArgs.find((arg) => arg.startsWith('--dir='));
   const outputFlag = rawArgs.find((arg) => arg.startsWith('--output=') || arg.startsWith('-o='));
   const outputFile = outputFlag ? outputFlag.split('=')[1] : null;
@@ -88,23 +101,53 @@ export const runAudit = async (customDir, isCli, rawArgs, loadProjectConfig) =>
     fileList = preflight.fileList;
   }
 
-  const auditOptions = { outputFile, model, costPerMillion, fast: isFast, fileList };
+  const auditOptions = { outputFile, model, costPerMillion, fast: isFast, fileList, stage };
   const report = executeAstAudit(targetDir, auditOptions);
   saveAuditSnapshot(report);
-  const syncRes = syncSearchIndex(targetDir, process.cwd());
-
-  if (syncRes?.db) {
-    syncViolationsIndex(syncRes.db, report.violations);
-    recordAuditSnapshot(syncRes.db, report);
-    if (rawArgs.includes('--triage')) {
-      const createdTasks = autoGenerateTasksFromAudit(syncRes.db, { cwd: process.cwd(), targetDir });
-      if (isCli && !isJson) {
-        process.stdout.write(`\x1b[32m✔\x1b[0m Auto-triage generated ${createdTasks.length} team task(s) from audit violations.\n`);
+  try {
+    const syncRes = syncSearchIndex(targetDir, process.cwd());
+
+    if (syncRes?.db) {
+      syncViolationsIndex(syncRes.db, report.violations);
+      const shouldTriage = !rawArgs.includes('--no-triage');
+      if (shouldTriage) {
+        const createdTasks = autoGenerateTasksFromAudit(syncRes.db, { cwd: process.cwd(), targetDir });
+        if (isCli && !isJson && createdTasks.length > 0) {
+          process.stdout.write(`\x1b[32m✔\x1b[0m Auto-triage synchronized ${createdTasks.length} team task(s) in SQLite backlog.\n`);
+        }
+      }
+      if (rawArgs.includes('--clones')) {
+        const { detectSemanticClones } = await import('../audit/clone-detector.js');
+        const { formatCloneReport } = await import('../audit/reporter-clones.js');
+        const cloneThresholdArg = rawArgs.find((a) => a.startsWith('--clone-threshold='));
+        const threshold = cloneThresholdArg ? parseFloat(cloneThresholdArg.split('=')[1]) : 0.85;
+        const clones = detectSemanticClones(syncRes.db, { threshold });
+        if (isJson) {
+          report.clones = clones;
+        } else {
+          process.stdout.write(formatCloneReport(clones));
+        }
+      }
+      if (rawArgs.includes('--hotspot-graph')) {
+        const { calculateCascadingHotspotGraph } = await import('../search-queries-hotspot-graph.js');
+        const { formatHotspotGraphReport } = await import('../audit/reporter-hotspot-graph.js');
+        const limitArg = rawArgs.find((a) => a.startsWith('--limit='));
+        const limit = limitArg ? parseInt(limitArg.split('=')[1], 10) : 10;
+        const graph = calculateCascadingHotspotGraph(syncRes.db, { limit });
+        if (isJson) {
+          report.hotspotGraph = graph;
+        } else {
+          process.stdout.write(formatHotspotGraphReport(graph));
+        }
       }
     }
+  } catch {
+    // Gracefully bypass indexing when database is readonly in sandboxed environment
   }
 
   // Stage 1: Atomic failure predicates
+  const isCriticalViolation = (v) => v.severity === 'CRITICAL';
+  const hasCritical = report.violations.some(isCriticalViolation);
   const isSevereViolation = (v) => v.severity === 'CRITICAL' || v.severity === 'HIGH';
   const hasCriticalOrHigh = report.violations.some(isSevereViolation);
   const hasViolations = report.violations.length > 0;
@@ -116,7 +159,8 @@ export const runAudit = async (customDir, isCli, rawArgs, loadProjectConfig) =>
   const isDefaultFail = !hasThreshold && !isStrict && hasCriticalOrHigh;
 
   // Stage 2: Unified failure decision
-  const hasFailingViolations = evaluateAuditFailure([isStrictFail, isDefaultFail, isGradeFail, isScoreFail]);
+  const hasStandardFailure = evaluateAuditFailure([isStrictFail, isDefaultFail, isGradeFail, isScoreFail]);
+  const hasFailingViolations = isDraft ? hasCritical : hasStandardFailure;
 
   if (isJson) {
     process.stdout.write(JSON.stringify(report, null, 2) + '\n');

package/cli/commands/cmd-project.js

@@ -0,0 +1,100 @@
+/**
+ * cmd-project.js: Persistent Coordinator and Projects CLI Handler
+ * Dispatches init, status, step, chat, pause, resume, and learnings
+ */
+
+import { openIndexDb } from '../search-db.js';
+import {
+  initProjectSession, getActiveProjectSession, getProjectSession,
+  postProjectMessage, getProjectMessages, updateProjectSession
+} from '../team/team-projects.js';
+import { queryRelevantLearnings, formatLearningsCard } from '../team/team-projects-memory.js';
+import { executeCoordinatorStep } from '../team/team-projects-coordinator.js';
+import { formatProjectStatusCard } from '../team/team-projects-format.js';
+import { listTasks } from '../team/team-db-tasks.js';
+
+export const runProjectCli = async (rawArgs = [], isCli = false, cwd = process.cwd()) => {
+  const db = openIndexDb(cwd);
+  if (!db) {
+    if (isCli) process.stderr.write('\x1b[31m✕ SQLite database unavailable.\x1b[0m\n');
+    return null;
+  }
+
+  const isJson = rawArgs.includes('--json');
+  const nonFlag = rawArgs.filter((a) => !a.startsWith('-'));
+  const subCommand = nonFlag[0] || 'status';
+  const restText = nonFlag.slice(1).join(' ');
+
+  if (subCommand === 'init' || subCommand === 'start') {
+    const goal = restText || 'Autonomous codebase optimization';
+    const session = initProjectSession(db, { goal, title: goal.slice(0, 40) });
+    if (isCli) {
+      if (isJson) process.stdout.write(`${JSON.stringify(session, null, 2)}\n`);
+      else process.stdout.write(`\x1b[32m✔\x1b[0m Initialized project session #${session.id}: "${session.title}"\n`);
+    }
+    return session;
+  }
+
+  if (subCommand === 'step' || subCommand === 'turn') {
+    const res = executeCoordinatorStep(db, { cwd });
+    if (isCli) {
+      if (isJson) process.stdout.write(`${JSON.stringify(res, null, 2)}\n`);
+      else process.stdout.write(`\x1b[36m⚡ [Turn ${res.turn || 0}]\x1b[0m ${res.action || res.status} - Status: ${res.status}\n`);
+    }
+    return res;
+  }
+
+  if (subCommand === 'chat' || subCommand === 'msg') {
+    const active = getActiveProjectSession(db);
+    if (!active) {
+      if (isCli) process.stderr.write('\x1b[31m✕ No active project. Run "chemx project init <goal>" first.\x1b[0m\n');
+      return { error: 'no_active_session' };
+    }
+    const msg = postProjectMessage(db, {
+      projectId: active.id,
+      turnIndex: active.current_turn,
+      authorId: '@user',
+      role: 'user',
+      message: restText || 'Status report'
+    });
+    if (isCli) {
+      if (isJson) process.stdout.write(`${JSON.stringify(msg, null, 2)}\n`);
+      else process.stdout.write(`\x1b[32m✔\x1b[0m Sent message to coordinator: "${msg.message}"\n`);
+    }
+    return msg;
+  }
+
+  if (subCommand === 'learnings' || subCommand === 'memory') {
+    const learnings = queryRelevantLearnings(db, { limit: 10 });
+    if (isCli) {
+      if (isJson) process.stdout.write(`${JSON.stringify(learnings, null, 2)}\n`);
+      else process.stdout.write(formatLearningsCard(learnings));
+    }
+    return learnings;
+  }
+
+  if (subCommand === 'pause' || subCommand === 'resume') {
+    const active = getActiveProjectSession(db);
+    if (!active) return null;
+    const newStatus = subCommand === 'pause' ? 'paused' : 'active';
+    const updated = updateProjectSession(db, active.id, { status: newStatus });
+    if (isCli) process.stdout.write(`\x1b[32m✔\x1b[0m Project #${active.id} status updated to: ${newStatus}\n`);
+    return updated;
+  }
+
+  // Default: status
+  const session = getActiveProjectSession(db);
+  const messages = session ? getProjectMessages(db, session.id, 5) : [];
+  const activeTasks = session ? listTasks(db, { status: 'in_progress' }) : [];
+  const learnings = queryRelevantLearnings(db, { limit: 5 });
+
+  if (isJson) {
+    const payload = { session, messages, activeTasks, learnings };
+    if (isCli) process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    return payload;
+  }
+
+  const card = formatProjectStatusCard({ session, messages, activeTasks, learnings });
+  if (isCli) process.stdout.write(card);
+  return { session, messages, activeTasks, learnings };
+};

package/cli/commands/cmd-router.js

@@ -1,5 +1,5 @@
 /**
- * cmd-router.js — CLI command dispatch table.
+ * cmd-router.js: CLI command dispatch table.
  * Single responsibility: map first-arg tokens to their lazy-loaded command handlers.
  * Extracted from cli/index.js per Directive 1.A (Monolith Decomposition).
  */
@@ -23,6 +23,25 @@ export const dispatchCommand = async (firstArg, rawArgs, runAudit, getPackageVer
       runTeamCli(rawArgs.slice(1), true);
       break;
     }
+    case 'project':
+    case 'coordinator': {
+      const { runProjectCli } = await import('./cmd-project.js');
+      await runProjectCli(rawArgs.slice(1), true);
+      break;
+    }
+    case 'tokens':
+    case 'telemetry': {
+      const { runTeamCli } = await import('../team/index.js');
+      runTeamCli(['tokens', ...rawArgs.slice(1)], true);
+      break;
+    }
+    case 'benchmark':
+    case 'ablation':
+    case 'memory': {
+      const { runTeamCli } = await import('../team/index.js');
+      runTeamCli(['benchmark', ...rawArgs.slice(1)], true);
+      break;
+    }
     case 'mcp':
     case 'mcp-server':
     case 'server': {
@@ -31,7 +50,8 @@ export const dispatchCommand = async (firstArg, rawArgs, runAudit, getPackageVer
       break;
     }
     case 'read':
-    case 'view': {
+    case 'view':
+    case 'r': {
       const { runReaderCli } = await import('../reader.js');
       runReaderCli(rawArgs.slice(1), true);
       break;
@@ -67,6 +87,12 @@ export const dispatchCommand = async (firstArg, rawArgs, runAudit, getPackageVer
       await runAudit(posDir, true);
       break;
     }
+    case 'trend':
+    case 'trends': {
+      const { runTrend } = await import('../trend.js');
+      runTrend(rawArgs.slice(1), process.cwd());
+      break;
+    }
     case 'init': {
       const { runInit } = await import('../scaffold.js');
       await runInit(rawArgs[1] || 'src/chemical-x', rawArgs, runAudit);
@@ -107,6 +133,12 @@ export const dispatchCommand = async (firstArg, rawArgs, runAudit, getPackageVer
       await runMutatorCli(rawArgs, true);
       break;
     }
+    case 'explode':
+    case 'unpack': {
+      const { runExplodeCli } = await import('../exploder.js');
+      await runExplodeCli(rawArgs.slice(1), true);
+      break;
+    }
     case 'add': {
       if (['prop', 'state', 'action'].includes(rawArgs[1])) {
         const { runMutatorCli } = await import('../mutators.js');
@@ -168,7 +200,24 @@ export const dispatchCommand = async (firstArg, rawArgs, runAudit, getPackageVer
       const { startUiServer } = await import('../ui-server.js');
       const portArg = rawArgs.find((a) => a.startsWith('--port='));
       const port = portArg ? parseInt(portArg.split('=')[1], 10) : 4173;
-      await startUiServer({ port, isCli: true, cwd: process.cwd() });
+      const hostArg = rawArgs.find((a) => a.startsWith('--host='));
+      const host = hostArg ? hostArg.split('=')[1] : '0.0.0.0';
+      const { server } = await startUiServer({ port, host, isCli: true, cwd: process.cwd() });
+      await new Promise((resolve) => {
+        const shutdown = () => {
+          server.close(() => resolve());
+        };
+        process.on('SIGINT', shutdown);
+        process.on('SIGTERM', shutdown);
+        server.on('close', resolve);
+      });
+      break;
+    }
+    case 'tesseract':
+    case 'cube':
+    case 'matrix': {
+      const { runTesseract } = await import('../tesseract.js');
+      await runTesseract(rawArgs.slice(1), true);
       break;
     }
     case 'help':

package/cli/commands-schema.js

@@ -194,5 +194,33 @@ export const COMMANDS_SCHEMA = [
       'npx chemx pillars --preset=recommended',
       'npx chemx pillars --preset=minimal --dry-run'
     ]
+  },
+  {
+    name: 'ui',
+    aliases: ['dashboard', 'preview'],
+    usage: 'npx chemx ui [options]',
+    summary: 'Launch the Chemical X interactive web dashboard.',
+    description: 'Provides real-time Kanban task boards, agent rails, live SQLite Database Studio, and codebase AST tree exploration.',
+    flags: [
+      { flag: '--port=<N>', desc: 'Server port (default: 4173)' }
+    ],
+    examples: [
+      'npx chemx ui',
+      'npx chemx dashboard --port=3000'
+    ]
+  },
+  {
+    name: 'tesseract',
+    aliases: ['cube', 'matrix'],
+    usage: 'npx chemx tesseract [options]',
+    summary: 'Autonomous AI Cognitive Bridge and Human-AI Symbiosis Interface.',
+    description: 'Deploys the full Chemical X cognitive lattice, AST topology, swarm telemetry, and Jarvis operational directives for instant AI onboarding.',
+    flags: [
+      { flag: '--json', desc: 'Output machine-readable JSON cognitive payload' }
+    ],
+    examples: [
+      'npx chemx tesseract',
+      'npx chemx tesseract --json'
+    ]
   }
 ];