@chemx/starter-kit 26.9.20-390 → 26.9.21-227

package/README.md

@@ -18,6 +18,47 @@ Access the interactive book, prompt generator, and asset vault at [https://chemi
 
 ---
 
+## Quickstart: Scaffolding a New Project
+
+Create a brand new molecular architecture project in seconds using your preferred package manager:
+
+```bash
+# npm (interactive or pass project directory)
+npm create chemx my-molecular-app
+
+# Automated / Agent / Headless mode (skips prompts, scaffolds Community Edition immediately)
+npm create chemx my-molecular-app -- --yes
+
+# npx
+npx create-chemx my-molecular-app --yes
+
+# pnpm / yarn / bun
+pnpm create chemx my-molecular-app
+yarn create chemx my-molecular-app
+bun create chemx my-molecular-app
+```
+
+### Headless & Autonomous Agent Mode
+When running in unattended environments (CI/CD pipelines, Cursor Agent, Windsurf, Claude Code, Antigravity), pass `--yes` (or `-y`, `--ci`, `--headless`) to bypass interactive terminal menus and immediately scaffold the free Community Edition with recommended architectural pillars:
+
+```bash
+npx create-chemx my-molecular-app --yes
+```
+
+### Package Architecture: Scaffolder vs Command Engine
+Chemical X provides two coordinated packages:
+- **`create-chemx`**: Dedicated zero-dependency project scaffolder (`npm create chemx`). Directly provisions project templates, test suites, and architectural configurations.
+- **`chemx`**: The full Molecular Architecture CLI & AST Query Engine. Manages audits, verifications, AST query lookups, code patching, and multi-agent swarm task coordination.
+
+```bash
+# Install chemx CLI globally or in your project:
+npm install -g chemx
+# or run on-demand:
+npx chemx --help
+```
+
+---
+
 ## Structure
 
 ```
@@ -138,6 +179,106 @@ $ npx chemx verify --dir=blueprints
 
 ---
 
+## CLI Command Reference & Workflow
+
+The `chemx` command suite is specifically tailored for token conservation, instant feedback, and zero terminal clutter:
+
+### 1. Verification & Quality
+```bash
+# Full verification pipeline (AST Audit + Typecheck + Tests) -> ~45 token status card
+chemx verify
+chemx verify --json
+
+# Run 7-Pillar static AST audit
+chemx audit
+chemx audit --unroll        # Inspect individual hazard lines and explanations
+chemx audit --strict        # Fail on any violation, including minor style warnings
+chemx audit --json          # Machine-readable format for agent pipelines
+
+# Silent TypeScript compilation check (suppresses passing noise, returns error lines)
+chemx typecheck
+chemx typecheck --json
+
+# Silent test runner (suppresses passing tests, extracts only failing assertions & stack diffs)
+chemx test
+chemx test --json
+
+# Silent build audit (categorizes diagnostics into TypeScript, Rollup, and style budgets)
+chemx build
+chemx build --json
+```
+
+### 2. AST Query Engine & Surgical Inspection
+```bash
+# Hybrid search (BM25 keyword + cosine vector similarity via Reciprocal Rank Fusion)
+chemx q "useAttentionCardController" --hybrid --json
+
+# Transitive blast radius analysis before refactoring foundational capsules
+chemx q "a-button" --blast-radius --json
+
+# Inspect component props, hooks, and types without reading entire files
+chemx q "m-task-list" --inspect
+
+# Surgical token-optimized file reader (AST outlines, stripped comments, specific symbols)
+chemx read src/components/m-card.vue --symbol=useCardController
+chemx read src/components/m-card.vue --outline
+chemx read src/components/m-card.vue --start=10 --end=40
+
+# Surgical file patching without full-file rewrites
+chemx patch <file> --target="oldCode" --replacement="newCode"
+```
+
+### 3. Crystalline Capsule Generator
+Scaffold production-ready component capsules matching strict zero-raw-DOM standards:
+```bash
+# Molecule capsule (component, controller, glass styling, types, spec)
+chemx m-task-card
+
+# Atom foundation (the only tier permitted raw HTML elements)
+chemx a-status-pill
+
+# Organism module (complex grouping of molecules and atoms)
+chemx o-workspace-header
+
+# Pure reactive hook / domain composable
+chemx use-task-filter
+```
+
+### 4. Database-Driven Multi-Agent Swarm Coordination
+Coordinate multi-agent swarms using the local SQLite store (`.chemx/index.db`) without multi-thousand-token markdown specification bloat:
+```bash
+# Auto-triage: convert AST audit hazards directly into assignable team tasks
+chemx team task triage
+
+# List tasks assigned to a specific agent
+chemx team task list --agent=@agent-alpha
+
+# Claim an open task
+chemx team task claim 1 --as=@agent-alpha
+
+# Mark task complete (automatically re-audits target file on disk to guarantee zero hazards)
+chemx team task done 1 --as=@agent-alpha
+
+# Inspect multi-agent swarm status and lock queues
+chemx team status
+```
+
+---
+
+## The 7 Molecular Architecture Pillars
+
+Chemical X enforces seven core architectural directives configured via `chemx pillars`:
+
+1. **Strict Molecular Line Budgets (< 100 Lines)**: Single-purpose files. Approaching 100 lines is a decomposition trigger. Eliminates context rot and cuts token ingestion costs.
+2. **Strict Component Tiers & Zero-Raw-DOM**: Raw HTML elements (`<button>`, `<input>`, `<div>`) are strictly isolated inside foundational **Atoms** (`a-*`). Molecules, Organisms, Templates, and Views assemble atoms and never contain raw tags.
+3. **Table-of-Contents Views**: Top-level page views are clean, 10–20 line declarative blueprints assembling self-contained molecules and organisms via named slots (`#header`, `#default`, `#modals`).
+4. **Molecular Composable Contracts**: Composables return plain destructurable objects with a strict 3-to-5 property limit (State + Status + Actions). Domain types use discriminated unions (zero impossible states).
+5. **Silent Verification Pipeline**: Verification tools suppress passing checkmarks and compiler banners, returning token-compact summaries (~45 tokens) to protect AI agent context windows.
+6. **AST Codebase Query Engine**: In-band AST symbol graph lookups, blast radius calculations, and outline extraction eliminate blind full-file context dumps.
+7. **Database-First Swarm Coordination**: Task backlogs, file locks, and agent communications live in local SQLite (`.chemx/index.db`) rather than monolithic markdown specifications.
+
+---
+
 ## Model Context Protocol (MCP) Server
 
 Chemical X includes a high-performance, zero-dependency JSON-RPC 2.0 Stdio MCP server that connects directly to AI agent hosts (Cursor, Claude Desktop, Windsurf, Antigravity, VS Code).
@@ -215,6 +356,11 @@ npx chemx --version
 # create-chemx v26.9.17-606
 ```
 
+### Package Pairing & npm Registry Propagation
+
+- **Package Pairing**: `@chemx/create-chemx` and `chemx` publish together under synchronized minute-precision CalVer timestamps (`YY.M.D-minute`). For consistent behavior, install or pin the matching release versions.
+- **npm Registry Propagation Note**: Newly published releases on npm can take 2–5 minutes to propagate across all edge CDN mirrors after `npm view` lists them. If `npm install` intermittently fails with a 404 on an exact newly published version, wait a few minutes and retry.
+
 Because autonomous coding agent models update frequently, this package is continuously integrated and deployed via automated CI whenever new agent directives, AST checks, or framework rules are tuned. Rapid version iterations reflect active, daily alignment rather than breaking SemVer shifts.
 
 > [!NOTE]

package/blueprints/_package.json

@@ -10,8 +10,10 @@
     "verify": "chemx verify"
   },
   "devDependencies": {
+    "@vue/test-utils": "^2.4.6",
     "create-chemx": "latest",
     "typescript": "^5.4.0",
-    "vitest": "^1.6.0"
+    "vitest": "^1.6.0",
+    "vue": "^3.4.0"
   }
 }

package/blueprints/workflows/chemx-audit.yml

@@ -47,7 +47,7 @@ jobs:
           path: AUDIT_REPORT.md
 
       - name: Post Architectural Audit Comment on PR
-        if: always() && github.event_name == 'pull_request' && hashFiles('AUDIT_REPORT.md') != ''
+        if: always() && github.event_name == 'pull_request' && hashFiles('AUDIT_REPORT.md') != '' && vars.CHEMX_ENABLE_PR_COMMENTS == 'true'
         continue-on-error: true
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/cli/audit/autofix.js

@@ -63,7 +63,9 @@ export const autofixContent = (content, options = {}) => {
     }
 
     // 3. AI lazy placeholder comment removal
-    if (!shouldDropLine && shouldFix('AI_SLOP_LAZY_PLACEHOLDER') && TRUNCATION_REGEX.test(line)) {
+    const hasLazyTruncation = TRUNCATION_REGEX.test(line);
+    const isLazyTruncationEligible = !shouldDropLine && shouldFix('AI_SLOP_LAZY_PLACEHOLDER');
+    if (isLazyTruncationEligible && hasLazyTruncation) {
       fixes.push({
         line: lineNumber,
         rule: 'AI_SLOP_LAZY_PLACEHOLDER',
@@ -72,7 +74,9 @@ export const autofixContent = (content, options = {}) => {
       shouldDropLine = true;
     }
 
-    if (!shouldDropLine && shouldFix('TYPOGRAPHY_EM_DASH') && line.includes('\u2014')) {
+    const hasEmDash = line.includes('\u2014');
+    const isEmDashEligible = !shouldDropLine && shouldFix('TYPOGRAPHY_EM_DASH');
+    if (isEmDashEligible && hasEmDash) {
       line = line.replace(/\u2014/g, '-');
       fixes.push({
         line: lineNumber,
@@ -81,6 +85,17 @@ export const autofixContent = (content, options = {}) => {
       });
     }
 
+    const hasTimeoutMacro = /setTimeout\([^,]+,\s*0\)/.test(line);
+    const isTimeoutEligible = !shouldDropLine && shouldFix('MACRO_TASK_OVER_MICRO_TASK');
+    if (isTimeoutEligible && hasTimeoutMacro) {
+      line = line.replace(/setTimeout\(([^,]+),\s*0\)/g, 'queueMicrotask($1)');
+      fixes.push({
+        line: lineNumber,
+        rule: 'MACRO_TASK_OVER_MICRO_TASK',
+        action: 'Replaced setTimeout(fn, 0) with queueMicrotask(fn)'
+      });
+    }
+
     if (!shouldDropLine) {
       resultLines.push(line);
     }

package/cli/audit/clone-detector.js

@@ -0,0 +1,64 @@
+import path from 'node:path';
+import { deserializeVector, cosineSimilarity } from '../embeddings/vectorizer.js';
+
+const isSpecOrTest = (filePath) => {
+  if (!filePath || typeof filePath !== 'string') return false;
+  return filePath.includes('.spec.') || filePath.includes('.test.') || filePath.includes('__tests__');
+};
+
+export const detectSemanticClones = (db, options = {}) => {
+  const isValidDb = Boolean(db);
+  if (!isValidDb) return { count: 0, threshold: 0.85, pairs: [] };
+
+  const threshold = typeof options.threshold === 'number' ? options.threshold : 0.85;
+  const limit = options.limit || 50;
+
+  const rows = db.prepare(
+    "SELECT file_path, target_name, vector FROM embeddings WHERE target_type = 'file'"
+  ).all();
+
+  const entries = rows
+    .filter((r) => !isSpecOrTest(r.file_path))
+    .map((r) => ({
+      filePath: r.file_path,
+      name: r.target_name,
+      vec: deserializeVector(r.vector)
+    }));
+
+  const pairs = [];
+
+  for (let i = 0; i < entries.length; i++) {
+    for (let j = i + 1; j < entries.length; j++) {
+      const a = entries[i];
+      const b = entries[j];
+
+      const isSameFile = a.filePath === b.filePath;
+      if (isSameFile) continue;
+
+      const sim = cosineSimilarity(a.vec, b.vec);
+      const isClone = sim >= threshold;
+
+      if (isClone) {
+        pairs.push({
+          fileA: a.filePath,
+          fileB: b.filePath,
+          nameA: a.name,
+          nameB: b.name,
+          similarity: Number(sim.toFixed(4)),
+          isExact: sim >= 0.95
+        });
+      }
+    }
+  }
+
+  pairs.sort((p1, p2) => p2.similarity - p1.similarity);
+  const cappedPairs = pairs.slice(0, limit);
+
+  return {
+    count: pairs.length,
+    threshold,
+    exactClones: cappedPairs.filter((p) => p.isExact),
+    nearClones: cappedPairs.filter((p) => !p.isExact),
+    pairs: cappedPairs
+  };
+};

package/cli/audit/clone-detector.spec.js

@@ -0,0 +1,46 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { DatabaseSync } from 'node:sqlite';
+import { generateEmbedding, serializeVector } from '../embeddings/vectorizer.js';
+import { detectSemanticClones } from './clone-detector.js';
+import { formatCloneReport } from './reporter-clones.js';
+
+test('clone-detector: detects high-similarity clones while ignoring spec companion files', () => {
+  const db = new DatabaseSync(':memory:');
+  db.exec(`
+    CREATE TABLE embeddings (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      file_path TEXT NOT NULL,
+      target_type TEXT NOT NULL,
+      target_name TEXT NOT NULL,
+      vector BLOB NOT NULL
+    );
+  `);
+
+  const insert = db.prepare('INSERT INTO embeddings (file_path, target_type, target_name, vector) VALUES (?, ?, ?, ?)');
+  const vecA = serializeVector(generateEmbedding('modal window popup backdrop blur close cancel confirm'));
+  const vecB = serializeVector(generateEmbedding('modal dialog popup backdrop blur cancel confirm close'));
+  const vecTest = serializeVector(generateEmbedding('modal window popup backdrop blur close cancel confirm spec test'));
+  const vecDiff = serializeVector(generateEmbedding('database sqlite migration column index'));
+
+  insert.run('src/ui/m-modal-a/m-modal-a.vue', 'file', 'm-modal-a.vue', vecA);
+  insert.run('src/ui/m-modal-b/m-modal-b.vue', 'file', 'm-modal-b.vue', vecB);
+  insert.run('src/ui/m-modal-a/m-modal-a.spec.ts', 'file', 'm-modal-a.spec.ts', vecTest);
+  insert.run('src/db/storage.ts', 'file', 'storage.ts', vecDiff);
+
+  const res = detectSemanticClones(db, { threshold: 0.8 });
+  assert.equal(res.count, 1);
+  assert.equal(res.pairs[0].fileA, 'src/ui/m-modal-a/m-modal-a.vue');
+  assert.equal(res.pairs[0].fileB, 'src/ui/m-modal-b/m-modal-b.vue');
+  assert.ok(res.pairs[0].similarity > 0.85);
+
+  const report = formatCloneReport(res);
+  assert.match(report, /Semantic Clone Detection/);
+  assert.match(report, /m-modal-a\.vue <-> src\/ui\/m-modal-b\/m-modal-b\.vue/);
+});
+
+test('clone-detector: handles empty or invalid db gracefully', () => {
+  assert.equal(detectSemanticClones(null).count, 0);
+  const emptyReport = formatCloneReport({ count: 0, threshold: 0.85, pairs: [] });
+  assert.match(emptyReport, /Zero duplicate clone hazards detected/);
+});

package/cli/audit/extended-text-patterns.js

@@ -66,8 +66,131 @@ export const checkMoleculeCoLocatedTest = (filePath, relativePath, violations) =
   });
 };
 
+/**
+ * Pillar 3: Return-shape diff check to ensure view only references identifiers
+ * present in the co-located controller's return object.
+ */
+export const checkControllerViewContract = (filePath, relativePath, content, violations) => {
+  const baseName = path.basename(filePath);
+  const ext = path.extname(filePath);
+
+  const isMoleculePath = relativePath.includes('molecules') || baseName.startsWith('m-') || baseName.startsWith('o-');
+  const isComponentExt = isComponentExtension(ext);
+  const isTestOrSpecFile = baseName.includes('.spec.') || baseName.includes('.test.');
+
+  const isComponent = isMoleculePath && isComponentExt && !isTestOrSpecFile;
+  if (!isComponent) return;
+
+  const controllerImportMatch = content.match(/from\s+['"]\.\/([a-zA-Z0-9_-]+\.controller)(?:\.ts)?['"]/);
+  if (!controllerImportMatch) return;
+
+  const controllerRel = controllerImportMatch[1];
+  const dir = path.dirname(filePath);
+  const controllerFullPath = path.join(dir, `${controllerRel}.ts`);
+
+  const [controllerContent, readErr] = toResultSync(() => {
+    if (fs.existsSync(controllerFullPath)) {
+      return fs.readFileSync(controllerFullPath, 'utf-8');
+    }
+    return null;
+  });
+
+  if (readErr || !controllerContent) return;
+
+  // Locate the last `return {` in the controller (handles early-return guards).
+  // Use a brace-depth-aware scan to find the matching closing brace so that
+  // nested object literals (e.g. `filter: { current, set }`) do not truncate
+  // the extraction prematurely — the non-greedy `[\s\S]*?` regex stops at the
+  // first `}` it sees, which is wrong for controllers with nested return props.
+  const returnStartIdx = controllerContent.lastIndexOf('return {');
+  if (returnStartIdx === -1) return;
+
+  const openIdx = controllerContent.indexOf('{', returnStartIdx);
+  if (openIdx === -1) return;
+
+  let depth = 0;
+  let closeIdx = -1;
+  for (let i = openIdx; i < controllerContent.length; i++) {
+    if (controllerContent[i] === '{') depth++;
+    else if (controllerContent[i] === '}') {
+      depth--;
+      if (depth === 0) { closeIdx = i; break; }
+    }
+  }
+  if (closeIdx === -1) return;
+
+  const returnBody = controllerContent.slice(openIdx + 1, closeIdx);
+  const returnedKeys = new Set();
+
+  // Walk the return body character-by-character to extract only TOP-LEVEL keys
+  // (depth-0 identifiers immediately followed by `:` or end-of-entry `,`/`}`).
+  // This correctly ignores property names nested inside sub-objects.
+  let scanDepth = 0;
+  let currentToken = '';
+  const flushToken = () => {
+    const trimmed = currentToken.trim();
+    currentToken = '';
+    if (!trimmed) return;
+    const getterMatch = trimmed.match(/^get\s+([a-zA-Z0-9_]+)\s*\(/);
+    if (getterMatch) { returnedKeys.add(getterMatch[1]); return; }
+    const keyMatch = trimmed.match(/^([a-zA-Z0-9_]+)/);
+    if (keyMatch) returnedKeys.add(keyMatch[1]);
+  };
+  for (let i = 0; i < returnBody.length; i++) {
+    const ch = returnBody[i];
+    if (ch === '{' || ch === '[' || ch === '(') { scanDepth++; currentToken += ch; }
+    else if (ch === '}' || ch === ']' || ch === ')') { scanDepth--; currentToken += ch; }
+    else if (ch === ',' && scanDepth === 0) { flushToken(); }
+    else { currentToken += ch; }
+  }
+  flushToken();
+
+  const destructuredMatches = content.matchAll(/(?:const|let)\s*\{([\s\S]*?)\}\s*=\s*(?:\{[^}]*\}\s*,\s*|\{\s*\.\.\.props\s*,\s*\.\.\.)?(?:use|create)[A-Z0-9]\w*Controller/g);
+  const destructuredKeys = new Set();
+  for (const match of destructuredMatches) {
+    const keysStr = match[1];
+    const rawKeys = keysStr.split(',').map((k) => k.trim()).filter(Boolean);
+    for (const rawKey of rawKeys) {
+      const cleanKey = rawKey.split(':')[0].trim();
+      if (cleanKey && !cleanKey.startsWith('...')) {
+        destructuredKeys.add(cleanKey);
+      }
+    }
+  }
+
+  const controllerVarMatch = content.match(/(?:const|let)\s+([a-zA-Z0-9_]+)\s*=\s*(?:use|create)[A-Z0-9]\w*Controller/);
+  if (controllerVarMatch) {
+    const varName = controllerVarMatch[1];
+    const propAccesses = content.matchAll(new RegExp(`\\b${varName}\\.([a-zA-Z0-9_]+)`, 'g'));
+    for (const pa of propAccesses) {
+      destructuredKeys.add(pa[1]);
+    }
+  }
+
+  const missing = [];
+  for (const key of destructuredKeys) {
+    if (!returnedKeys.has(key)) {
+      missing.push(key);
+    }
+  }
+
+  if (missing.length > 0) {
+    violations.push({
+      filePath: relativePath,
+      line: 1,
+      column: 1,
+      hazard: `View references undefined controller exports: ${missing.join(', ')} (controller returns: ${[...returnedKeys].join(', ')})`,
+      rule: 'CONTROLLER_VIEW_MISMATCH',
+      severity: 'CRITICAL',
+      pillar: 'Reactivity & Composable Contracts',
+      directive: 'Ensure view destructuring matches properties returned by the co-located controller'
+    });
+  }
+};
+
 export const checkExtendedTextPatterns = (content, lines, relativePath, filePath, violations) => {
   checkMoleculeCoLocatedTest(filePath, relativePath, violations);
+  checkControllerViewContract(filePath, relativePath, content, violations);
 
   const isTestFile = /\.(test|spec)\.[jt]sx?$/.test(filePath);
   const ext = path.extname(filePath);

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

@@ -121,6 +121,11 @@ export const RULE_REGISTRY = {
     severity: 'HIGH',
     directive: 'Limit hook return values to 3 to 5 properties (State + Status + Actions)'
   },
+  CONTROLLER_VIEW_MISMATCH: {
+    pillar: PILLARS.PILLAR_3,
+    severity: 'CRITICAL',
+    directive: 'Ensure view destructuring matches properties returned by the co-located controller'
+  },
   TIMER_DISCIPLINE: {
     pillar: PILLARS.PILLAR_6,
     severity: 'CRITICAL',

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

@@ -226,8 +226,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,