@chemx/create-chemx 26.9.20-408 → 26.9.21-8

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/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/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/blast-radius.spec.js

@@ -0,0 +1,113 @@
+import test from "node:test";
+import assert from "node:assert";
+import { openIndexDb } from "./search-schema.js";
+import { upsertFileIndex } from "./search-db.js";
+import { calculateBlastRadius } from "./search-queries.js";
+
+test("calculateBlastRadius: traverses downstream multi-tier dependencies", () => {
+  const db = openIndexDb();
+  if (!db) return;
+
+  // Set up mock components in DB:
+  // a-test-btn (atom) <- m-test-grp (molecule) <- o-test-nav (organism)
+  upsertFileIndex(db, {
+    path: "src/ui/atoms/a-test-btn/a-test-btn.vue",
+    mtime: Date.now(),
+    size: 100,
+    tier: "atom",
+    lines: 20,
+    chars: 400,
+    symbols: [{ name: "AtomTestBtn", kind: "const", isExport: true, startLine: 1, endLine: 20 }],
+    imports: []
+  });
+
+  upsertFileIndex(db, {
+    path: "src/ui/molecules/m-test-grp/m-test-grp.vue",
+    mtime: Date.now(),
+    size: 200,
+    tier: "molecule",
+    lines: 40,
+    chars: 800,
+    symbols: [{ name: "MoleculeTestGrp", kind: "const", isExport: true, startLine: 1, endLine: 40 }],
+    imports: [
+      { importedSymbol: "AtomTestBtn", sourceModule: "../../atoms/a-test-btn/a-test-btn.vue", line: 2 }
+    ]
+  });
+
+  upsertFileIndex(db, {
+    path: "src/ui/organisms/o-test-nav/o-test-nav.vue",
+    mtime: Date.now(),
+    size: 300,
+    tier: "organism",
+    lines: 60,
+    chars: 1200,
+    symbols: [{ name: "OrganismTestNav", kind: "const", isExport: true, startLine: 1, endLine: 60 }],
+    imports: [
+      { importedSymbol: "MoleculeTestGrp", sourceModule: "../../molecules/m-test-grp/m-test-grp.vue", line: 3 }
+    ]
+  });
+
+  upsertFileIndex(db, {
+    path: "src/ui/molecules/m-test-grp/m-test-grp.spec.ts",
+    mtime: Date.now(),
+    size: 150,
+    tier: "utility",
+    lines: 30,
+    chars: 600,
+    symbols: [],
+    imports: [
+      { importedSymbol: "MoleculeTestGrp", sourceModule: "./m-test-grp.vue", line: 1 }
+    ]
+  });
+
+  const blast = calculateBlastRadius(db, "a-test-btn");
+
+  assert.strictEqual(blast.target, "a-test-btn");
+  assert.ok(blast.totalImpactCount >= 3, "Should detect at least 3 downstream files");
+  assert.strictEqual(blast.depth >= 2, true, "Should reach depth of at least 2");
+
+  // Verify direct consumers (m-test-grp)
+  const hasDirect = blast.directConsumers.some((c) => c.path.includes("m-test-grp.vue"));
+  assert.strictEqual(hasDirect, true, "m-test-grp.vue should be a direct consumer");
+
+  // Verify transitive consumers (o-test-nav)
+  const hasTransitive = blast.transitiveConsumers.some((c) => c.path.includes("o-test-nav.vue"));
+  assert.strictEqual(hasTransitive, true, "o-test-nav.vue should be a transitive consumer");
+
+  // Verify impacted test file detection
+  const hasTest = blast.impactedTests.some((t) => t.path.includes("m-test-grp.spec.ts"));
+  assert.strictEqual(hasTest, true, "m-test-grp.spec.ts should be flagged as impacted test");
+});
+
+test("calculateBlastRadius: safely terminates on circular dependency cycles", () => {
+  const db = openIndexDb();
+  if (!db) return;
+
+  // Cycle: circ-a -> circ-b -> circ-a
+  upsertFileIndex(db, {
+    path: "src/ui/circ-a.ts",
+    mtime: Date.now(),
+    size: 100,
+    tier: "utility",
+    lines: 10,
+    chars: 200,
+    symbols: [{ name: "CircA", kind: "const", isExport: true }],
+    imports: [{ importedSymbol: "CircB", sourceModule: "./circ-b", line: 1 }]
+  });
+
+  upsertFileIndex(db, {
+    path: "src/ui/circ-b.ts",
+    mtime: Date.now(),
+    size: 100,
+    tier: "utility",
+    lines: 10,
+    chars: 200,
+    symbols: [{ name: "CircB", kind: "const", isExport: true }],
+    imports: [{ importedSymbol: "CircA", sourceModule: "./circ-a", line: 1 }]
+  });
+
+  // Must not loop indefinitely or throw
+  const blast = calculateBlastRadius(db, "src/ui/circ-a.ts", { maxDepth: 4 });
+  assert.ok(blast.totalImpactCount > 0);
+  assert.ok(blast.depth <= 4);
+});

package/cli/commands/cmd-audit.js

@@ -0,0 +1,201 @@
+/**
+ * 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).
+ */
+
+import { printHelp } from '../help.js';
+
+/**
+ * @param {string|null} customDir
+ * @param {boolean} isCli
+ * @param {string[]} rawArgs  - process.argv slice already resolved by the caller
+ * @param {() => object} loadProjectConfig
+ */
+export const runAudit = async (customDir, isCli, rawArgs, loadProjectConfig) => {
+  const {
+    runAudit: executeAstAudit,
+    formatTerminalReport,
+    generateMarkdownReport,
+    saveAuditSnapshot,
+    copyToClipboard,
+    buildMasterPrompt,
+    groupViolationsBySeverity
+  } = await import('../audit.js');
+  const {
+    runInteractiveAuditNavigator,
+    showConversionMenu,
+    handleShareToDiscussions
+  } = await import('../navigator.js');
+  const { renderDashboardBanner } = await import('../navigator-banner.js');
+  const {
+    isGradeBelowMinimum,
+    evaluateAuditFailure,
+    isNonInteractiveSession
+  } = await import('../audit/rules-predicates.js');
+  const { runAuditPreflight, resolveGitAuditScope } = await import('../audit-preflight.js');
+  const { syncSearchIndex, resolveTargetDir, syncViolationsIndex, recordAuditSnapshot } = await import('../search.js');
+  const { autoGenerateTasksFromAudit } = await import('../team/index.js');
+  const { runScaffold } = await import('../scaffold.js');
+
+  const projectConfig = loadProjectConfig();
+  const isJson = rawArgs.includes('--json');
+  const isMarkdown = rawArgs.includes('--markdown') || rawArgs.includes('--md');
+  const isUnroll = rawArgs.includes('--unroll') || rawArgs.includes('--all');
+  const isShare = rawArgs.includes('--share') || rawArgs.includes('--post');
+  const isStrict = rawArgs.includes('--strict');
+  const isPromptOnFail = rawArgs.includes('--prompt-on-fail');
+  const isCopyPrompt = rawArgs.includes('--copy-prompt');
+
+  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;
+
+  const minGradeFlag = rawArgs.find((arg) => arg.startsWith('--min-grade='));
+  const minGrade = (minGradeFlag ? minGradeFlag.split('=')[1] : (process.env.CHEMX_MIN_GRADE || projectConfig.minGrade || '')).toUpperCase();
+
+  const minScoreFlag = rawArgs.find((arg) => arg.startsWith('--min-score='));
+  const minScoreRaw = minScoreFlag ? minScoreFlag.split('=')[1] : (process.env.CHEMX_MIN_SCORE || projectConfig.minScore || null);
+  const minScore = minScoreRaw !== null && minScoreRaw !== undefined ? parseInt(String(minScoreRaw), 10) : null;
+
+  const modelFlag = rawArgs.find((arg) => arg.startsWith('--model='));
+  const model = modelFlag ? modelFlag.split('=')[1] : (projectConfig.model || 'blended');
+  const costFlag = rawArgs.find((arg) => arg.startsWith('--cost-per-million='));
+  const costPerMillion = costFlag ? parseFloat(costFlag.split('=')[1]) : null;
+
+  const isNonInteractive = isNonInteractiveSession(rawArgs);
+  const isInteractive = !isNonInteractive && Boolean(process.stdin.isTTY && process.stdout.isTTY);
+
+  let targetDir = resolveTargetDir(customDir, dirFlag);
+  let isFast = rawArgs.includes('--fast') || rawArgs.includes('--quick');
+  let fileList = null;
+
+  const hasGitFlag = rawArgs.includes('--git') || rawArgs.includes('--changed');
+  if (hasGitFlag) {
+    const gitScope = resolveGitAuditScope(process.cwd());
+    if (gitScope.ok) fileList = gitScope.files;
+  }
+
+  const shouldRunPreflight = isCli && isInteractive && !isJson && !isMarkdown && !isShare;
+  if (shouldRunPreflight) {
+    const preflight = await runAuditPreflight(rawArgs, {
+      customDir,
+      defaultDir: targetDir,
+      cwd: process.cwd()
+    });
+    targetDir = preflight.targetDir;
+    isFast = preflight.fast;
+    fileList = preflight.fileList;
+  }
+
+  const auditOptions = { outputFile, model, costPerMillion, fast: isFast, fileList };
+  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`);
+      }
+    }
+  }
+
+  // Stage 1: Atomic failure predicates
+  const isSevereViolation = (v) => v.severity === 'CRITICAL' || v.severity === 'HIGH';
+  const hasCriticalOrHigh = report.violations.some(isSevereViolation);
+  const hasViolations = report.violations.length > 0;
+  const isStrictFail = isStrict && hasViolations;
+  const isGradeFail = isGradeBelowMinimum(report.health.grade, minGrade);
+  const hasMinScore = minScore !== null && !isNaN(minScore);
+  const isScoreFail = hasMinScore && report.health.score < minScore;
+  const hasThreshold = Boolean(minGrade) || hasMinScore;
+  const isDefaultFail = !hasThreshold && !isStrict && hasCriticalOrHigh;
+
+  // Stage 2: Unified failure decision
+  const hasFailingViolations = evaluateAuditFailure([isStrictFail, isDefaultFail, isGradeFail, isScoreFail]);
+
+  if (isJson) {
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    if (isCli) process.exit(hasFailingViolations ? 1 : 0);
+    return report;
+  }
+
+  if (isMarkdown && !outputFile) {
+    const md = generateMarkdownReport(report);
+    process.stdout.write(md + '\n');
+    if (isCli) process.exit(hasFailingViolations ? 1 : 0);
+    return report;
+  }
+
+  if (isCli) {
+    if (isShare) {
+      await handleShareToDiscussions(report);
+      process.exit(0);
+    }
+
+    if (isInteractive && !isUnroll) {
+      const handleReAudit = () => {
+        const refreshed = executeAstAudit(targetDir, auditOptions);
+        saveAuditSnapshot(refreshed);
+        return refreshed;
+      };
+      await runInteractiveAuditNavigator(
+        report,
+        () => runScaffold(undefined, rawArgs, (d, cli) => runAudit(d, cli, rawArgs, loadProjectConfig)),
+        handleReAudit
+      );
+    } else {
+      if (isUnroll) {
+        process.stdout.write(formatTerminalReport(report));
+        if (isInteractive) {
+          await showConversionMenu(() => runScaffold(undefined, rawArgs, (d, cli) => runAudit(d, cli, rawArgs, loadProjectConfig)));
+        }
+      } else {
+        const { critical, high, medium, low } = groupViolationsBySeverity(report.violations);
+        const highMediumCount = high.length + medium.length;
+        renderDashboardBanner(
+          report.health,
+          report.metrics,
+          report.violations,
+          critical,
+          highMediumCount,
+          low,
+          report.contextAnalysis,
+          report.aiSlop,
+          { clear: false }
+        );
+
+        if (hasFailingViolations && !isInteractive) {
+          process.stdout.write('\n\x1b[1m\x1b[31m✕ [Chemical X] Architectural health verification failed:\x1b[0m\n');
+          if (isGradeFail) process.stdout.write(`  \x1b[31m•\x1b[0m Grade ${report.health.grade} is below required minimum tier ${minGrade}\n`);
+          if (isScoreFail) process.stdout.write(`  \x1b[31m•\x1b[0m Score ${report.health.score}/100 is below required minimum score ${minScore}/100\n`);
+          if (isDefaultFail) process.stdout.write(`  \x1b[31m•\x1b[0m Unresolved hazards: ${critical.length} Critical, ${high.length} High (run 'chemx audit --unroll' to inspect)\n`);
+          if (isStrictFail) process.stdout.write(`  \x1b[31m•\x1b[0m Strict mode: ${report.violations.length} total violation(s) detected\n`);
+          process.stdout.write('  \x1b[36m💡 Convert hazards into team tasks: chemx team task triage\x1b[0m\n');
+        }
+      }
+    }
+
+    if (hasFailingViolations && (isPromptOnFail || isCopyPrompt)) {
+      const prompt = buildMasterPrompt(report);
+      if (prompt) {
+        const copied = copyToClipboard(prompt);
+        if (copied) {
+          process.stdout.write('\n\x1b[1m\x1b[32m✔ AI Agent refactoring prompt copied to clipboard!\x1b[0m\n');
+          process.stdout.write('\x1b[36mPaste directly into Cursor, Claude, or Windsurf to resolve architectural hazards.\x1b[0m\n\n');
+        } else if (isCopyPrompt) {
+          process.stdout.write('\n\x1b[33m⚠ Could not access system clipboard.\x1b[0m\n\n');
+        }
+      }
+    }
+
+    process.exit(hasFailingViolations ? 1 : 0);
+  }
+
+  process.stdout.write(formatTerminalReport(report));
+  return report;
+};