@chemx/create-chemx 26.9.16-41 → 26.9.16-668

package/cli/audit/prompts.js

@@ -293,13 +293,12 @@ export const buildHotspotsPrompt = (report, options = {}) => {
   }
 
   lines.push('### STRICT EXECUTION RULES:');
-  lines.push('1. Branch First: Change to a new branch prefixed with `chem-x/NAMEOFIMPROVEMENT` before making changes, then commit the branch and create a PR to main.');
-  lines.push('2. Pre-Split Pattern Discovery: Audit recurring UI layouts, state machines, and predicates across monoliths first; extract canonical shared capsules before slicing to prevent bespoke pattern duplication.');
-  lines.push('3. Molecular Limits: Molecule capsules must strictly remain under 100 lines per file.');
-  lines.push('4. Table-of-Contents Views: Top-level page views must be 10 to 20 line declarative Table of Contents assembling molecules via named slots.');
-  lines.push('5. Composable Return Contracts: Custom hooks/composables must strictly limit returns to 3 to 5 properties (State + Status + Actions).');
-  lines.push('6. Type Co-location: Co-locate granular types/*.d.ts files inside each feature capsule (< 100 lines per type file) instead of creating type monoliths.');
-  lines.push('7. Zero breaking changes to external component APIs, route exports, or existing props.');
+  lines.push('1. Pre-Split Pattern Discovery: Audit recurring UI layouts, state machines, and predicates across monoliths first; extract canonical shared capsules before slicing to prevent bespoke pattern duplication.');
+  lines.push('2. Molecular Limits: Molecule capsules must strictly remain under 100 lines per file.');
+  lines.push('3. Table-of-Contents Views: Top-level page views must be 10 to 20 line declarative Table of Contents assembling molecules via named slots.');
+  lines.push('4. Composable Return Contracts: Custom hooks/composables must strictly limit returns to 3 to 5 properties (State + Status + Actions).');
+  lines.push('5. Type Co-location: Co-locate granular types/*.d.ts files inside each feature capsule (< 100 lines per type file) instead of creating type monoliths.');
+  lines.push('6. Zero breaking changes to external component APIs, route exports, or existing props.');
   if (!isSubSection) {
     lines.push('');
     lines.push(buildAgentCommandsSection());
@@ -340,11 +339,10 @@ export const buildPillarPrompt = (report, pillarName, options = {}) => {
   }
 
   lines.push('### STRICT EXECUTION RULES:');
-  lines.push('1. Branch First: Change to a new branch prefixed with `chem-x/NAMEOFIMPROVEMENT` before making changes.');
-  lines.push('2. Pre-Split Pattern Discovery: Survey cross-file patterns before slicing; extract canonical shared capsules first.');
-  lines.push('3. Molecular Capsule Limit: Maximum 100 lines per molecule capsule file.');
-  lines.push('4. Table-of-Contents Views: Top-level page views must be 10 to 20 line declarative templates assembling components via named slots.');
-  lines.push('5. Zero breaking changes to external component APIs, route exports, or existing props.');
+  lines.push('1. Pre-Split Pattern Discovery: Survey cross-file patterns before slicing; extract canonical shared capsules first.');
+  lines.push('2. Molecular Capsule Limit: Maximum 100 lines per molecule capsule file.');
+  lines.push('3. Table-of-Contents Views: Top-level page views must be 10 to 20 line declarative templates assembling components via named slots.');
+  lines.push('4. Zero breaking changes to external component APIs, route exports, or existing props.');
   if (!isSubSection) {
     lines.push('');
     lines.push(buildAgentCommandsSection());

package/cli/audit/roadmap.js

@@ -128,12 +128,6 @@ export const buildRemediationRoadmap = (report) => {
         target: '.git/hooks/pre-commit & .github/workflows/',
         action: 'Run npx chemx install to lock in line budgets and prevent future monolith regressions.',
         locations: []
-      },
-      {
-        title: 'Branch, Commit & Pull Request Workflow',
-        target: 'git checkout -b chem-x/NAMEOFIMPROVEMENT',
-        action: 'Change to a branch prefixed with chem-x/NAMEOFIMPROVEMENT to make changes, commit the branch, and create a PR to main.',
-        locations: []
       }
     ]
   });
@@ -202,13 +196,6 @@ export const buildSelfHealingRoadmapPrompt = (report) => {
 
   lines.push('Act as a Principal Systems Architect. Execute a self-healing architectural remediation of our codebase by following this strict multi-phase sequence in order:\n');
 
-  lines.push('### MANDATORY GIT BRANCHING & PR WORKFLOW:');
-  lines.push('1. Before modifying any files, change to a dedicated feature branch prefixed with `chem-x/NAMEOFIMPROVEMENT`:');
-  lines.push('   `git checkout -b chem-x/NAMEOFIMPROVEMENT`');
-  lines.push('2. Execute each remediation phase sequentially on this branch.');
-  lines.push('3. Commit the branch with atomic, intention-revealing commit messages.');
-  lines.push('4. Create a Pull Request (PR) to `main` upon completing the remediation phases.\n');
-
   lines.push('### AI AGENT DISCOVERY & REFACTORING COMMANDS:');
   lines.push('- Discovery & Inspect: Run `pnpm q "<target>" --inspect` (or `npx chemx search "<target>" --inspect`) to inspect component props and hooks before editing.');
   lines.push('- Tier Filter: Run `pnpm q "<query>" --tier=molecule` (or `atom`, `organism`, `hook`) to find related capsules.');
@@ -234,13 +221,11 @@ export const buildSelfHealingRoadmapPrompt = (report) => {
   });
 
   lines.push('### EXECUTION DISCIPLINE:');
-  lines.push('1. Branch First: Change to a new branch prefixed with `chem-x/NAMEOFIMPROVEMENT` (e.g. `git checkout -b chem-x/<name-of-improvement>`) before making any changes.');
-  lines.push('2. Complete Step 1 (Pattern Harvesting) completely before touching any monolithic file in Step 3.');
-  lines.push('3. Spliced views in Step 3 must directly import and bind to the canonical capsules created in Step 1.');
-  lines.push('4. Every new molecule component must stay under 100 lines.');
-  lines.push('5. Top-level page views must be 10-20 line declarative Table-of-Contents templates assembling molecules via named slots.');
-  lines.push('6. Zero synthetic or mock data; zero em dashes (use hyphens or colons).');
-  lines.push('7. PR to Main: Commit the branch and create a Pull Request to main.');
+  lines.push('1. Complete Step 1 (Pattern Harvesting) completely before touching any monolithic file in Step 3.');
+  lines.push('2. Spliced views in Step 3 must directly import and bind to the canonical capsules created in Step 1.');
+  lines.push('3. Every new molecule component must stay under 100 lines.');
+  lines.push('4. Top-level page views must be 10-20 line declarative Table-of-Contents templates assembling molecules via named slots.');
+  lines.push('5. Zero synthetic or mock data; zero em dashes (use hyphens or colons).');
 
   return lines.join('\n');
 };

package/cli/audit/rules.js

@@ -102,6 +102,10 @@ export const auditCode = (content, filePath, relativePath, options = {}) => {
   // Pillars 8-11: Extended Fast Checks (A11y, Security secrets, Fake tests, Co-located specs)
   checkExtendedTextPatterns(content, lines, relativePath, filePath, violations);
 
+  if (options.fast) {
+    return violations;
+  }
+
   // Vue template structural pattern discovery
   if (ext === '.vue' && options.patternRegistry) {
     const templateMatch = content.match(/<template\b[^>]*>([\s\S]*?)<\/template>/i);

package/cli/audit-preflight-git.js

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
+
+const SOURCE_FILE_PATTERN = /\.(tsx|ts|jsx|js|vue|svelte)$/;
+const EXCLUDED_PATTERNS = ['.test.', '.spec.', '.min.', '.d.ts'];
+
+export const isSourceFilePath = (filePath) => {
+  const isExtensionValid = SOURCE_FILE_PATTERN.test(filePath);
+  if (!isExtensionValid) return false;
+  const isExcluded = EXCLUDED_PATTERNS.some((pat) => filePath.includes(pat));
+  return !isExcluded;
+};
+
+export const parseGitStatusOutput = (output) => {
+  const lines = output.split('\n');
+  const files = [];
+
+  for (const rawLine of lines) {
+    const trimmed = rawLine.trim();
+    if (!trimmed) continue;
+    const cleanPath = trimmed.replace(/^[MADRCU?! ]+\s+/, '').trim().replace(/^"|"$/g, '');
+    if (cleanPath) {
+      files.push(cleanPath);
+    }
+  }
+
+  return files;
+};
+
+export const getGitChangedFiles = (cwd = process.cwd()) => {
+  try {
+    const result = spawnSync('git', ['status', '--porcelain', '-u'], { cwd, encoding: 'utf-8' });
+    const isSuccess = result.status === 0;
+    if (!isSuccess || !result.stdout) return [];
+    return parseGitStatusOutput(result.stdout);
+  } catch {
+    return [];
+  }
+};
+
+export const resolveGitAuditScope = (cwd = process.cwd()) => {
+  const rawFiles = getGitChangedFiles(cwd);
+  const existingSourceFiles = rawFiles.filter((relPath) => {
+    const isSource = isSourceFilePath(relPath);
+    const exists = fs.existsSync(relPath);
+    return isSource && exists;
+  });
+
+  const hasChangedFiles = existingSourceFiles.length > 0;
+  return {
+    ok: hasChangedFiles,
+    files: existingSourceFiles
+  };
+};

package/cli/audit-preflight-scope.js

@@ -0,0 +1,87 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { hasGum, gumChoose, gumInput, promptQuestion } from './terminal.js';
+import { resolveGitAuditScope } from './audit-preflight-git.js';
+
+const CANDIDATE_NAMES = ['src', 'app', 'cli', 'components', 'lib', 'packages', 'modules'];
+
+export const detectCandidateDirectories = (cwd = process.cwd()) => {
+  return CANDIDATE_NAMES.filter((name) => {
+    const fullPath = path.resolve(cwd, name);
+    return fs.existsSync(fullPath) && fs.statSync(fullPath).isDirectory();
+  });
+};
+
+const promptSpecificDirectory = async (cwd) => {
+  const candidates = detectCandidateDirectories(cwd);
+  const options = [...candidates.map((dir) => `📂 ${dir}`), '✏️  Custom directory path...'];
+
+  let choice = '';
+  if (hasGum()) {
+    choice = gumChoose(options, 'Select Target Directory:');
+  } else {
+    process.stdout.write('\n' + options.map((opt, i) => ` ${i + 1}. ${opt}`).join('\n') + '\n\n');
+    const ans = await promptQuestion(`Select directory [1-${options.length}]: `);
+    const index = parseInt(ans, 10) - 1;
+    choice = options[index] || '';
+  }
+
+  const isCustomPath = !choice || choice.includes('Custom');
+  if (isCustomPath) {
+    if (hasGum()) {
+      return gumInput('Target directory path:', 'src') || 'src';
+    }
+    const entered = await promptQuestion('Target directory path [src]: ');
+    return entered || 'src';
+  }
+
+  const matched = candidates.find((dir) => choice.includes(dir));
+  return matched || 'src';
+};
+
+export const promptAuditScope = async (defaultDir, rawArgs, cwd = process.cwd()) => {
+  const hasGitFlag = rawArgs.includes('--git') || rawArgs.includes('--changed');
+  if (hasGitFlag) {
+    const gitScope = resolveGitAuditScope(cwd);
+    return { targetDir: defaultDir, fileList: gitScope.ok ? gitScope.files : null };
+  }
+
+  const scopeOptions = [
+    '📁 Whole Project (Scan entire workspace)',
+    '📂 Specific Directory (Select target folder)',
+    '🌿 Git Changed Files (Scan modified or staged files only)'
+  ];
+
+  let scopeChoice = '';
+  if (hasGum()) {
+    scopeChoice = gumChoose(scopeOptions, 'Select Audit Scope:');
+  } else {
+    process.stdout.write('\n' + scopeOptions.map((opt, i) => ` ${i + 1}. ${opt}`).join('\n') + '\n\n');
+    const ans = await promptQuestion(`Select audit scope [1-${scopeOptions.length}]: `);
+    const index = parseInt(ans, 10) - 1;
+    scopeChoice = scopeOptions[index] || '';
+  }
+
+  const isCancelled = !scopeChoice;
+  if (isCancelled) return null;
+
+  const isGit = scopeChoice.includes('Git');
+  if (isGit) {
+    const gitScope = resolveGitAuditScope(cwd);
+    const hasFiles = gitScope.ok;
+    if (!hasFiles) {
+      process.stdout.write('\n\x1b[33m⚠ No git modified or staged source files found. Auditing whole project.\x1b[0m\n');
+      return { targetDir: defaultDir, fileList: null };
+    }
+    process.stdout.write(`\n\x1b[32m✔ Focused on ${gitScope.files.length} git modified/staged file(s).\x1b[0m\n`);
+    return { targetDir: defaultDir, fileList: gitScope.files };
+  }
+
+  const isSpecific = scopeChoice.includes('Specific');
+  if (isSpecific) {
+    const chosenDir = await promptSpecificDirectory(cwd);
+    return { targetDir: chosenDir, fileList: null };
+  }
+
+  return { targetDir: defaultDir, fileList: null };
+};

package/cli/audit-preflight.d.ts

@@ -0,0 +1,16 @@
+export interface PreflightResult {
+  readonly targetDir: string;
+  readonly fast: boolean;
+  readonly fileList: readonly string[] | null;
+}
+
+export interface PreflightOptions {
+  readonly customDir?: string | null;
+  readonly defaultDir?: string;
+  readonly cwd?: string;
+}
+
+export declare function detectCandidateDirectories(cwd?: string): string[];
+export declare function resolveGitAuditScope(cwd?: string): { ok: boolean; files: string[] };
+export declare function getGitChangedFiles(cwd?: string): string[];
+export declare function runAuditPreflight(rawArgs: readonly string[], options?: PreflightOptions): Promise<PreflightResult>;

package/cli/audit-preflight.js

@@ -0,0 +1,85 @@
+import { hasGum, gumChoose, promptQuestion } from './terminal.js';
+import { promptAuditScope } from './audit-preflight-scope.js';
+import { isNonInteractiveSession } from './audit/rules-predicates.js';
+import { resolveGitAuditScope } from './audit-preflight-git.js';
+
+export { detectCandidateDirectories } from './audit-preflight-scope.js';
+export { resolveGitAuditScope, getGitChangedFiles } from './audit-preflight-git.js';
+
+const DEPTH_OPTIONS = [
+  '🔬 Full AST Audit (Deep molecular analysis, AST visitors, slop, patterns)',
+  '⚡ Fast Scan (Instant line-budget, token burn, and file metrics)'
+];
+
+const promptAuditDepth = async (rawArgs) => {
+  const hasFastFlag = rawArgs.includes('--fast') || rawArgs.includes('--quick');
+  const hasFullFlag = rawArgs.includes('--full') || rawArgs.includes('--deep');
+
+  if (hasFastFlag) return true;
+  if (hasFullFlag) return false;
+
+  let depthChoice = '';
+  if (hasGum()) {
+    depthChoice = gumChoose(DEPTH_OPTIONS, 'Select Audit Depth:');
+  } else {
+    process.stdout.write('\n' + DEPTH_OPTIONS.map((opt, i) => ` ${i + 1}. ${opt}`).join('\n') + '\n\n');
+    const ans = await promptQuestion(`Select audit depth [1-${DEPTH_OPTIONS.length}]: `);
+    const index = parseInt(ans, 10) - 1;
+    depthChoice = DEPTH_OPTIONS[index] || '';
+  }
+
+  const isCancelled = !depthChoice;
+  if (isCancelled) return null;
+
+  return depthChoice.includes('Fast');
+};
+
+export const runAuditPreflight = async (rawArgs, options = {}) => {
+  const { customDir = null, defaultDir = 'src', cwd = process.cwd() } = options;
+
+  const isNonInteractive = isNonInteractiveSession(rawArgs);
+  const hasTty = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  const hasYesFlag = rawArgs.includes('-y') || rawArgs.includes('--yes');
+  const isInteractive = !isNonInteractive && hasTty && !hasYesFlag;
+
+  const hasExplicitDir = Boolean(customDir) || rawArgs.some((arg) => arg.startsWith('--dir='));
+  const hasExplicitGit = rawArgs.includes('--git') || rawArgs.includes('--changed');
+  const hasExplicitFast = rawArgs.includes('--fast') || rawArgs.includes('--quick');
+  const hasExplicitFull = rawArgs.includes('--full') || rawArgs.includes('--deep');
+  const isFullySpecified = (hasExplicitDir || hasExplicitGit) && (hasExplicitFast || hasExplicitFull);
+
+  if (!isInteractive || isFullySpecified) {
+    const fast = hasExplicitFast;
+    const fileList = hasExplicitGit ? resolveGitAuditScope(cwd).files : null;
+    return { targetDir: customDir || defaultDir, fast, fileList };
+  }
+
+  process.stdout.write('\n\x1b[1m\x1b[38;5;45m⚡ Chemical X Protocol\x1b[0m \x1b[38;5;220mInteractive Pre-Flight\x1b[0m\n\n');
+
+  let targetDir = customDir || defaultDir;
+  let fileList = null;
+
+  const needsScopePrompt = !hasExplicitDir && !hasExplicitGit;
+  if (needsScopePrompt) {
+    const scopeResult = await promptAuditScope(defaultDir, rawArgs, cwd);
+    if (!scopeResult) {
+      process.exit(0);
+    }
+    targetDir = scopeResult.targetDir;
+    fileList = scopeResult.fileList;
+  } else if (hasExplicitGit) {
+    fileList = resolveGitAuditScope(cwd).files;
+  }
+
+  const depthResult = await promptAuditDepth(rawArgs);
+  if (depthResult === null) {
+    process.exit(0);
+  }
+  const fast = depthResult;
+
+  const modeLabel = fast ? 'Fast line-budget scan' : 'Full molecular AST audit';
+  const targetLabel = fileList ? `${fileList.length} git modified file(s)` : targetDir;
+  process.stdout.write(`\n\x1b[36m⚡ Starting ${modeLabel} for ${targetLabel}...\x1b[0m\n\n`);
+
+  return { targetDir, fast, fileList };
+};

package/cli/audit-preflight.spec.js

@@ -0,0 +1,104 @@
+import test from 'node:test';
+import assert from 'node:assert';
+import { isSourceFilePath, parseGitStatusOutput } from './audit-preflight-git.js';
+import { detectCandidateDirectories } from './audit-preflight-scope.js';
+import { runAuditPreflight } from './audit-preflight.js';
+import { scanTree, runAudit } from './audit.js';
+import { auditCode } from './audit/rules.js';
+
+test('isSourceFilePath: correctly validates source files and excludes tests', () => {
+  assert.strictEqual(isSourceFilePath('src/app.tsx'), true);
+  assert.strictEqual(isSourceFilePath('cli/index.js'), true);
+  assert.strictEqual(isSourceFilePath('components/card.vue'), true);
+  assert.strictEqual(isSourceFilePath('ui/button.svelte'), true);
+  assert.strictEqual(isSourceFilePath('src/app.test.tsx'), false);
+  assert.strictEqual(isSourceFilePath('src/app.spec.js'), false);
+  assert.strictEqual(isSourceFilePath('dist/bundle.min.js'), false);
+  assert.strictEqual(isSourceFilePath('types/index.d.ts'), false);
+  assert.strictEqual(isSourceFilePath('README.md'), false);
+});
+
+test('parseGitStatusOutput: extracts clean file paths from git porcelain output', () => {
+  const output = [
+    ' M src/components/card.tsx',
+    'A  cli/new-command.js',
+    '?? scripts/scratch.ts',
+    ' D old-file.js',
+    '"quoted/path/with space.ts"'
+  ].join('\n');
+
+  const parsed = parseGitStatusOutput(output);
+  assert.strictEqual(parsed.length, 5);
+  assert.strictEqual(parsed[0], 'src/components/card.tsx');
+  assert.strictEqual(parsed[1], 'cli/new-command.js');
+  assert.strictEqual(parsed[2], 'scripts/scratch.ts');
+  assert.strictEqual(parsed[3], 'old-file.js');
+  assert.strictEqual(parsed[4], 'quoted/path/with space.ts');
+});
+
+test('detectCandidateDirectories: identifies existing directory targets', () => {
+  const detected = detectCandidateDirectories(process.cwd());
+  assert.ok(Array.isArray(detected));
+  assert.ok(detected.includes('cli'));
+});
+
+test('runAuditPreflight: non-interactive mode resolves immediately without questions', async () => {
+  const result = await runAuditPreflight(['--ci'], {
+    defaultDir: 'cli',
+    cwd: process.cwd()
+  });
+
+  assert.strictEqual(result.targetDir, 'cli');
+  assert.strictEqual(result.fast, false);
+  assert.strictEqual(result.fileList, null);
+});
+
+test('runAuditPreflight: explicit fast and customDir flags bypass questions', async () => {
+  const result = await runAuditPreflight(['--fast', '--dir=cli'], {
+    customDir: 'cli',
+    defaultDir: 'src',
+    cwd: process.cwd()
+  });
+
+  assert.strictEqual(result.targetDir, 'cli');
+  assert.strictEqual(result.fast, true);
+  assert.strictEqual(result.fileList, null);
+});
+
+test('runAuditPreflight: yes flag accepts defaults immediately', async () => {
+  const result = await runAuditPreflight(['-y'], {
+    defaultDir: 'cli',
+    cwd: process.cwd()
+  });
+
+  assert.strictEqual(result.targetDir, 'cli');
+  assert.strictEqual(result.fast, false);
+  assert.strictEqual(result.fileList, null);
+});
+
+test('auditCode: fast mode executes line checks and bypasses AST parser', () => {
+  const longFile = 'const a = 1;\n'.repeat(600);
+  const violations = auditCode(longFile, 'src/monolith.ts', 'src/monolith.ts', { fast: true });
+
+  assert.ok(violations.length > 0);
+  const hasLineBudget = violations.some((v) => v.rule === 'LINE_BUDGET_FILE');
+  assert.strictEqual(hasLineBudget, true);
+});
+
+test('scanTree: fileList restricts scanning strictly to specified files', () => {
+  const result = scanTree('cli', process.cwd(), {
+    fileList: ['cli/installer-templates.js']
+  });
+
+  assert.strictEqual(result.fileStats.length, 1);
+  assert.strictEqual(result.fileStats[0].relativePath, 'cli/installer-templates.js');
+});
+
+test('runAudit: fast mode returns valid health metrics with zero AST traversal', () => {
+  const report = runAudit('cli', { fast: true });
+
+  assert.ok(report.scannedFiles > 0);
+  assert.ok(report.health);
+  assert.ok(typeof report.health.score === 'number');
+  assert.ok(typeof report.health.grade === 'string');
+});

package/cli/audit.js

@@ -97,11 +97,48 @@ export const auditFile = (filePath, relativePath) => {
   return auditCode(content, filePath, relativePath);
 };
 
+const auditFileEntry = (fullPath, relPath, scanOptions) => {
+  const content = fs.readFileSync(fullPath, 'utf-8');
+  const lines = content.split('\n');
+  const baseName = path.basename(fullPath);
+  const isMolecule = relPath.includes('molecules') || relPath.includes('/m-') || baseName.startsWith('m-');
+
+  const fileStat = {
+    fullPath,
+    relativePath: relPath,
+    lineCount: lines.length,
+    charCount: content.length,
+    isMolecule
+  };
+
+  const hookMatches = content.match(/\buse[A-Z0-9]\w*\b/g);
+  const hookCount = hookMatches ? hookMatches.length : 0;
+  const fileViolations = auditCode(content, fullPath, relPath, {
+    patternRegistry: scanOptions.patternRegistry,
+    fast: scanOptions.fast
+  });
+
+  return { fileStat, hookCount, fileViolations };
+};
+
 export const scanTree = (targetDir, baseDir, scanOptions = {}) => {
   let violations = [];
   let fileStats = [];
   let totalHooks = 0;
-  const { patternRegistry } = scanOptions;
+
+  if (scanOptions.fileList && scanOptions.fileList.length > 0) {
+    for (const item of scanOptions.fileList) {
+      const fullPath = path.isAbsolute(item) ? item : path.resolve(baseDir, item);
+      const relPath = path.relative(baseDir, fullPath);
+      if (fs.existsSync(fullPath) && isSourceFile(path.basename(fullPath))) {
+        const result = auditFileEntry(fullPath, relPath, scanOptions);
+        violations = violations.concat(result.fileViolations);
+        fileStats.push(result.fileStat);
+        totalHooks += result.hookCount;
+      }
+    }
+    return { violations, fileStats, totalHooks };
+  }
 
   if (!fs.existsSync(targetDir)) {
     return { violations, fileStats, totalHooks };
@@ -120,26 +157,10 @@ export const scanTree = (targetDir, baseDir, scanOptions = {}) => {
         totalHooks += sub.totalHooks;
       }
     } else if (isSourceFile(entry.name)) {
-      const content = fs.readFileSync(fullPath, 'utf-8');
-      const lines = content.split('\n');
-      const isMolecule = relPath.includes('molecules') || relPath.includes('/m-') || entry.name.startsWith('m-');
-
-      fileStats.push({
-        fullPath,
-        relativePath: relPath,
-        lineCount: lines.length,
-        charCount: content.length,
-        isMolecule
-      });
-
-      // Count hook declarations / invocations for metric
-      const hookMatches = content.match(/\buse[A-Z0-9]\w*\b/g);
-      if (hookMatches) {
-        totalHooks += hookMatches.length;
-      }
-
-      const fileViolations = auditCode(content, fullPath, relPath, { patternRegistry });
-      violations = violations.concat(fileViolations);
+      const result = auditFileEntry(fullPath, relPath, scanOptions);
+      violations = violations.concat(result.fileViolations);
+      fileStats.push(result.fileStat);
+      totalHooks += result.hookCount;
     }
   }
 
@@ -155,7 +176,11 @@ export const runAudit = (targetDir = 'src', options = {}) => {
   const cwd = process.cwd();
   const absoluteTarget = path.resolve(cwd, targetDir);
   const patternRegistry = createPatternRegistry();
-  const { violations, fileStats, totalHooks } = scanTree(absoluteTarget, cwd, { patternRegistry });
+  const { violations, fileStats, totalHooks } = scanTree(absoluteTarget, cwd, {
+    patternRegistry,
+    fast: Boolean(options.fast),
+    fileList: options.fileList || null
+  });
 
   const scannedFiles = fileStats.length;
   const totalLoc = fileStats.reduce((acc, f) => acc + f.lineCount, 0);

package/cli/help.js

@@ -111,6 +111,15 @@ export const printHelp = () => {
     `      Display this comprehensive CLI documentation and options guide.`,
     '',
     `${BOLD}AUDIT OPTIONS & FLAGS${RESET}`,
+    `  ${CYAN}--fast${RESET}, ${CYAN}--quick${RESET}`,
+    `      Fast scan: verify line budgets, token burn, and file metrics, bypassing deep AST traversal.`,
+    '',
+    `  ${CYAN}--git${RESET}, ${CYAN}--changed${RESET}`,
+    `      Scope audit strictly to modified, staged, or untracked source files in git.`,
+    '',
+    `  ${CYAN}-y${RESET}, ${CYAN}--yes${RESET}`,
+    `      Accept defaults and bypass interactive pre-flight wizard questions.`,
+    '',
     `  ${CYAN}--dir=<path>${RESET}`,
     `      Directory to analyze. Defaults to ${CYAN}src${RESET} if present, else current working directory.`,
     `      Example: ${CYAN}npx chemx audit --dir=apps/web/src${RESET}`,

package/cli/index.js

@@ -30,6 +30,7 @@ import {
   evaluateAuditFailure,
   isNonInteractiveSession
 } from './audit/rules-predicates.js';
+import { runAuditPreflight, resolveGitAuditScope } from './audit-preflight.js';
 import { runInstallWizard } from './installer.js';
 import { runBadgeCommand } from './badge.js';
 import { runBuildAudit } from './build.js';
@@ -84,8 +85,42 @@ export const runAudit = async (customDir = null, isCli = false) => {
   const costFlag = rawArgs.find((arg) => arg.startsWith('--cost-per-million='));
   const costPerMillion = costFlag ? parseFloat(costFlag.split('=')[1]) : null;
 
-  const targetDir = resolveTargetDir(customDir, dirFlag);
-  const report = executeAstAudit(targetDir, { outputFile, model, costPerMillion });
+  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) {
@@ -120,12 +155,9 @@ export const runAudit = async (customDir = null, isCli = false) => {
       process.exit(0);
     }
 
-    const isNonInteractive = isNonInteractiveSession(rawArgs);
-    const isInteractive = !isNonInteractive && Boolean(process.stdin.isTTY && process.stdout.isTTY);
-
     if (isInteractive && !isUnroll) {
       const handleReAudit = () => {
-        const refreshed = executeAstAudit(targetDir, { outputFile, model, costPerMillion });
+        const refreshed = executeAstAudit(targetDir, auditOptions);
         saveAuditSnapshot(refreshed);
         return refreshed;
       };
@@ -198,7 +230,9 @@ export {
   runBuildAudit,
   runSearch,
   syncSearchIndex,
-  startMcpServer,
+  runMcpServer,
+  runMcpServer as startMcpServer,
+  runMcpInstaller,
   runReaderCli,
   readTokenOptimized,
   runPatcherCli,

package/cli/installer-templates.js

@@ -2,15 +2,46 @@ export const buildPreCommitHookScript = (minGrade = 'B', minScore = 80) => `#!/b
 # Chemical X Protocol: Pre-Commit Line Budget & Architecture Gatekeeper
 # Free architectural guardrail preventing context bloat and monolith sprawl.
 
-MIN_GRADE="\${CHEMX_MIN_GRADE:-${minGrade}}"
-MIN_SCORE="\${CHEMX_MIN_SCORE:-${minScore}}"
-MAX_LINES="\${CHEMX_MAX_LINES:-500}"
-MAX_MOLECULE_LINES="\${CHEMX_MAX_MOLECULE_LINES:-100}"
-
 REPO_ROOT="\$(git rev-parse --show-toplevel 2>/dev/null)"
 [ -z "\$REPO_ROOT" ] && exit 0
 cd "\$REPO_ROOT" || exit 1
 
+# Delegate to version-controlled script if present
+if [ -f "\$REPO_ROOT/scripts/pre-commit.sh" ]; then
+  exec "\$REPO_ROOT/scripts/pre-commit.sh" "\$@"
+fi
+
+# Load thresholds from .chemx/config.json if available
+CONF_MAX_LINES=""
+CONF_MAX_MOL=""
+CONF_MIN_GRADE=""
+CONF_MIN_SCORE=""
+CONFIG_FILE="\$REPO_ROOT/.chemx/config.json"
+
+if [ -f "\$CONFIG_FILE" ]; then
+  if command -v node >/dev/null 2>&1; then
+    eval \$(node -e "
+      try {
+        const c = JSON.parse(require('fs').readFileSync('\$CONFIG_FILE', 'utf8'));
+        if (c.maxLineCount || c.maxLines) console.log('CONF_MAX_LINES=' + (c.maxLineCount || c.maxLines));
+        if (c.maxMoleculeLineCount || c.maxMoleculeLines) console.log('CONF_MAX_MOL=' + (c.maxMoleculeLineCount || c.maxMoleculeLines));
+        if (c.minGrade) console.log('CONF_MIN_GRADE=' + c.minGrade);
+        if (c.minScore) console.log('CONF_MIN_SCORE=' + c.minScore);
+      } catch (e) {}
+    ")
+  else
+    CONF_MAX_LINES=\$(grep -o '"maxLineCount"[[:space:]]*:[[:space:]]*[0-9]*' "\$CONFIG_FILE" 2>/dev/null | grep -o '[0-9]*\$')
+    CONF_MAX_MOL=\$(grep -o '"maxMoleculeLineCount"[[:space:]]*:[[:space:]]*[0-9]*' "\$CONFIG_FILE" 2>/dev/null | grep -o '[0-9]*\$')
+    CONF_MIN_GRADE=\$(grep -o '"minGrade"[[:space:]]*:[[:space:]]*"[^"]*"' "\$CONFIG_FILE" 2>/dev/null | sed 's/.*"minGrade"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\\1/')
+    CONF_MIN_SCORE=\$(grep -o '"minScore"[[:space:]]*:[[:space:]]*[0-9]*' "\$CONFIG_FILE" 2>/dev/null | grep -o '[0-9]*\$')
+  fi
+fi
+
+MIN_GRADE="\${CHEMX_MIN_GRADE:-\${CONF_MIN_GRADE:-${minGrade}}}"
+MIN_SCORE="\${CHEMX_MIN_SCORE:-\${CONF_MIN_SCORE:-${minScore}}}"
+MAX_LINES="\${CHEMX_MAX_LINES:-\${CONF_MAX_LINES:-500}}"
+MAX_MOLECULE_LINES="\${CHEMX_MAX_MOLECULE_LINES:-\${CONF_MAX_MOL:-100}}"
+
 STAGED_FILES=\$(git diff --cached --name-only --diff-filter=ACM | grep -E '\\.(jsx?|tsx?|vue|svelte)\$' | grep -vE '(\\.(d\\.ts|min\\.|test\\.|spec\\.))')
 [ -z "\$STAGED_FILES" ] && exit 0
 
@@ -29,6 +60,9 @@ done
 
 if [ "\$FAILED" -eq 1 ]; then
   printf "\\n\\033[1m\\033[31m[Chemical X] Commit Blocked: Staged files exceed architectural line budgets\\033[0m\\n\$ERRORS\\n\\n"
+  printf "\\033[33mMonolithic files degrade AI context windows and cause hallucination loops.\\033[0m\\n"
+  printf "Decompose large files into single-purpose crystalline capsules or configure thresholds in .chemx/config.json before committing.\\n\\n"
+  exit 1
 fi
 
 AUDIT_BIN=""
@@ -51,7 +85,6 @@ if [ -n "\$AUDIT_BIN" ]; then
   fi
 fi
 
-[ "\$FAILED" -eq 1 ] && exit 1
 printf "\\033[32m✔ [Chemical X] Pre-commit architectural guardrails passed.\\033[0m\\n"
 exit 0
 `;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chemx/create-chemx",
-  "version": "26.9.16-41",
+  "version": "26.9.16-668",
   "description": "Chemical X Protocol: Private drop-in architecture starter kit and capsule generator",
   "type": "module",
   "bin": {