@chemx/starter-kit 26.9.23-1269 → 26.9.25-747

package/cli/audit/hook-shape-validator.js

@@ -1,7 +1,7 @@
 import * as t from '@babel/types';
 import { RULE_REGISTRY } from './rules-registry.js';
 
-const VERB_PREFIX_REGEX = /^(add|remove|toggle|set|get|fetch|load|save|delete|clear|reset|refresh|update|create|edit|send|sync|init|dispose|trigger|post|put|patch|apply|dismiss|select|deselect|filter|sort|search|open|close|show|hide|start|stop|cancel|execute|run|retry|submit|validate|mutate|next|prev|step|increment|decrement|insert|upsert|drop|enable|disable|register|unregister|login|logout|checkout|publish|archive|discard|confirm|undo|redo|claim|complete|acquire|release|download|upload|export|import|handle)([A-Z0-9_].*)?$/;
+const VERB_PREFIX_REGEX = /^(add|remove|toggle|set|get|fetch|load|save|delete|clear|reset|refresh|update|create|edit|send|sync|init|setup|dispose|trigger|post|put|patch|apply|dismiss|select|deselect|filter|sort|search|open|close|show|hide|start|stop|cancel|execute|run|retry|submit|validate|mutate|next|prev|step|increment|decrement|insert|upsert|drop|enable|disable|register|unregister|login|logout|checkout|publish|archive|discard|confirm|undo|redo|claim|complete|acquire|release|download|upload|export|import|handle|play|pause|resume|seek|unlock|restore|advance|focus|notify|broadcast|copy|format)([A-Z0-9_].*)?$/;
 
 const STATUS_HEURISTIC_REGEX = /^(is[A-Z]|has[A-Z]|can[A-Z]|should[A-Z])|.*(Error|Status)$/;
 const STATUS_EXACT_NAMES = new Set(['status', 'error', 'loading', 'pending', 'ready']);

package/cli/audit/pattern-detector.js

@@ -29,15 +29,17 @@ export const createPatternRegistry = () => {
     });
   };
 
-  const resolveHarmonizationCandidates = (hotspots = []) => {
+  const resolveHarmonizationCandidates = (hotspots = [], options = {}) => {
     const hotspotFiles = new Set(hotspots.map((h) => h.filePath));
     const candidates = [];
+    const minFiles = options.ruleOfThree ? 3 : 2;
 
     for (const [key, bucket] of buckets.entries()) {
       const uniqueFiles = Array.from(new Set(bucket.occurrences.map((o) => o.filePath)));
-      if (uniqueFiles.length < 2) continue;
-
       const hasHotspot = uniqueFiles.some((f) => hotspotFiles.has(f));
+      const isCandidateEligible = hasHotspot ? uniqueFiles.length >= 2 : uniqueFiles.length >= minFiles;
+      if (!isCandidateEligible) continue;
+
       const impactScore = uniqueFiles.length * (hasHotspot ? 3 : 1.5) + bucket.occurrences.length;
 
       let label = 'Recurring Pattern';

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

@@ -94,3 +94,20 @@ test('categorizeUiStructure: maps semantic AST topologies to specialized capsule
   assert.equal(fallbackRes.suggestedCapsule, 'm-feature-card');
 });
 
+test('Rule of Three: requires pattern across 3+ files unless a hotspot is involved', () => {
+  const registry = createPatternRegistry();
+  const template = `<template><v-sheet><x-btn>1</x-btn><x-btn>2</x-btn></v-sheet></template>`;
+
+  recordTemplatePatterns(registry, template, 'src/components/A.vue');
+  recordTemplatePatterns(registry, template, 'src/components/B.vue');
+
+  // With Rule of Three enabled and no hotspots, 2 files do not trigger premature abstraction
+  const strictCandidates = registry.resolveHarmonizationCandidates([], { ruleOfThree: true });
+  assert.equal(strictCandidates.length, 0, '2 occurrences without hotspot should not trigger premature abstraction');
+
+  // When a 3rd file adopts the pattern, Rule of Three threshold is satisfied
+  recordTemplatePatterns(registry, template, 'src/components/C.vue');
+  const satisfiedCandidates = registry.resolveHarmonizationCandidates([], { ruleOfThree: true });
+  assert.equal(satisfiedCandidates.length, 1, '3 occurrences should satisfy Rule of Three threshold');
+});
+

package/cli/audit/prompts.js

@@ -36,7 +36,7 @@ const renderTreeLines = (node, depth = 0) => {
   return lines;
 };
 
-export const formatGroupedPromptViolations = (violations = []) => {
+export const formatGroupedPromptViolations = (violations = [], options = {}) => {
   const hasNoViolations = violations.length === 0;
   if (hasNoViolations) return [];
 
@@ -49,11 +49,14 @@ export const formatGroupedPromptViolations = (violations = []) => {
     lines.push(`${idx + 1}. ${sevColor}[${rg.rule}]${RESET} ${BOLD}(${countLabel})${RESET}`);
     lines.push(`   Hazard:    ${rg.hazard}`);
     lines.push(`   Directive: ${CYAN}${rg.directive}${RESET}`);
-    lines.push('   Locations:');
+    lines.push(`   Action:    chemx team task list --rule=${rg.rule}`);
 
-    const tree = buildPathTree(rg.violations);
-    const treeLines = renderTreeLines(tree, 0);
-    lines.push(...treeLines);
+    if (options.detailedLocations) {
+      lines.push('   Locations:');
+      const tree = buildPathTree(rg.violations);
+      const treeLines = renderTreeLines(tree, 0);
+      lines.push(...treeLines);
+    }
     lines.push('');
   });
 
@@ -62,10 +65,10 @@ export const formatGroupedPromptViolations = (violations = []) => {
 
 export const buildAgentCommandsSection = () => [
   '### AI AGENT DISCOVERY & REFACTORING COMMANDS:',
-  '- Query & Inspect: Run `pnpm q "<target>" --inspect` (or `npx chemx search "<target>" --inspect`) to inspect component props, symbols, and hooks before editing.',
-  '- Tier Filter: Run `pnpm q "<query>" --tier=molecule` (or `atom`, `organism`, `hook`) to find related capsules.',
-  '- Zero-Overhead JSON: Run `pnpm q "<query>" --json` for minified AST metadata without burning context tokens on whole files.',
-  '- Re-Verify Score: Run `npx chemx audit` after refactoring to ensure Molecular Health Index (MHI) and letter grades improve.'
+  '- Claim Work: Run `chemx team task list --status=queued` and claim via `chemx team task claim <id> --as=@coder`.',
+  '- Inspect Target: Run `chemx read <target_path> --outline` to inspect AST signatures without token bloat.',
+  '- Verify & Auto-Resolve: Run `chemx verify`. Clean files auto-reconcile tasks to done in SQLite.',
+  '- MCP Invocations: If invoking via MCP, pass command string directly via `chemx({ command: "..." })`.'
 ].join('\n');
 
 export const buildGradeFPrompt = (report, options = {}) => {

package/cli/audit/prompts.spec.js

@@ -10,7 +10,8 @@ import {
   buildAiSlopPrompt,
   buildHotspotsPrompt,
   buildPillarPrompt,
-  buildMasterPrompt
+  buildMasterPrompt,
+  formatGroupedPromptViolations
 } from './prompts.js';
 
 test('deduplicateRolePreambles: handles invalid and empty inputs', () => {
@@ -314,3 +315,53 @@ test('deduplicateRefactoringCommands: collapses multiple occurrences to single b
   assert.ok(result.includes('Section 2 content'));
   assert.ok(result.includes('- Command B'));
 });
+
+test('formatGroupedPromptViolations: outputs token-compact task action by default', () => {
+  const violations = [
+    {
+      rule: 'SECURITY_RAW_HTML_INJECTION',
+      severity: 'CRITICAL',
+      hazard: 'Unsanitized HTML injection',
+      directive: 'Sanitize dynamic HTML via DOMPurify',
+      filePath: 'src/view-a.vue',
+      line: 10
+    },
+    {
+      rule: 'SECURITY_RAW_HTML_INJECTION',
+      severity: 'CRITICAL',
+      hazard: 'Unsanitized HTML injection',
+      directive: 'Sanitize dynamic HTML via DOMPurify',
+      filePath: 'src/view-b.vue',
+      line: 25
+    }
+  ];
+
+  const lines = formatGroupedPromptViolations(violations);
+  const text = lines.join('\n');
+
+  assert.ok(text.includes('[SECURITY_RAW_HTML_INJECTION]'));
+  assert.ok(text.includes('(2 items)'));
+  assert.ok(text.includes('Action:    chemx team task list --rule=SECURITY_RAW_HTML_INJECTION'));
+  // Does not dump file locations tree by default
+  assert.ok(!text.includes('Locations:'));
+  assert.ok(!text.includes('view-a.vue:10'));
+});
+
+test('formatGroupedPromptViolations: renders file tree when detailedLocations is enabled', () => {
+  const violations = [
+    {
+      rule: 'SECURITY_RAW_HTML_INJECTION',
+      severity: 'CRITICAL',
+      hazard: 'Unsanitized HTML injection',
+      directive: 'Sanitize dynamic HTML via DOMPurify',
+      filePath: 'src/view-a.vue',
+      line: 10
+    }
+  ];
+
+  const lines = formatGroupedPromptViolations(violations, { detailedLocations: true });
+  const text = lines.join('\n');
+
+  assert.ok(text.includes('Locations:'));
+  assert.ok(text.includes('view-a.vue:10'));
+});

package/cli/audit/reporter-grades.js

@@ -267,6 +267,7 @@ export const formatGradeASection = (report) => {
     lines.push(`   ${GREEN}✔${RESET} Low Context Hazard & Token Burn Risk`);
   }
 
+  lines.push(`\n   ${DIM}ℹ Notice: Architectural grade measures AST rules only. Run chemx verify for full typecheck and test verification.${RESET}`);
   lines.push(`\n${GREEN}======================================================================${RESET}\n`);
   return lines.join('\n');
 };

package/cli/audit/reporter-markdown.js

@@ -39,6 +39,8 @@ export const generateMarkdownReport = (report) => {
     lines.push('');
   }
   lines.push('> *Comprehensive static analysis report enforcing Chemical X Molecular Architecture standards.*');
+  lines.push('> ');
+  lines.push('> **Notice**: Architectural grades measure AST rule compliance only. Run `chemx verify` for full production readiness (typecheck + test suite).');
   lines.push('');
   lines.push('## 1. Executive Summary & Scorecard');
   lines.push('');

package/cli/audit/reporter-sections.js

@@ -72,6 +72,9 @@ export const formatScorecardSection = (report, themeColor = null) => {
   lines.push(`   Largest File:        ${BOLD}${metrics.largestFile.filePath || 'None'}${RESET} (${metrics.largestFile.lineCount} lines)`);
   lines.push(`   Molecule Capsules:   ${metrics.moleculeCount} found (${metrics.moleculeCompliantPct}% compliant < 100 lines of code)`);
   lines.push(`   Custom Hooks:        ${metrics.hookCount} detected`);
+  lines.push(`   ${sectionColor}----------------------------------------------------------------------${RESET}`);
+  lines.push(`   ${DIM}ℹ Notice: Architectural grade measures AST rules only.${RESET}`);
+  lines.push(`   ${DIM}  Run ${RESET}${BOLD}chemx verify${RESET}${DIM} for full typecheck and test verification.${RESET}`);
   lines.push(`${sectionColor}======================================================================${RESET}\n`);
 
   return lines.join('\n');

package/cli/audit/rules-registry.js

@@ -215,5 +215,32 @@ export const RULE_REGISTRY = {
     pillar: 'AI Slop & Code Authenticity',
     severity: 'LOW',
     directive: 'Inline redundant single-use passthrough assignments directly into return expressions'
+  },
+
+  // Greybeard Pragmatic: Structural Weight & Bounded Context
+  STRUCTURAL_WEIGHT_EXCEEDED: {
+    pillar: PILLARS.PILLAR_1,
+    severity: 'HIGH',
+    directive: 'Reduce component responsibility density: extract domain hooks, decompose branching, or flatten render tree'
+  },
+  COMPLEXITY_CYCLOMATIC_HIGH: {
+    pillar: PILLARS.PILLAR_2,
+    severity: 'HIGH',
+    directive: 'Decompose high cyclomatic complexity into pure helper functions or table dispatch'
+  },
+  HOOK_STATE_SATURATION: {
+    pillar: PILLARS.PILLAR_3,
+    severity: 'HIGH',
+    directive: 'Extract co-located state and effects into a dedicated domain hook or reducer'
+  },
+  RENDER_TREE_DEPTH_EXCEEDED: {
+    pillar: PILLARS.PILLAR_2,
+    severity: 'HIGH',
+    directive: 'Extract nested JSX ternaries into computed descriptor objects or early returns'
+  },
+  PROP_SURFACE_BLOAT: {
+    pillar: PILLARS.PILLAR_4,
+    severity: 'MEDIUM',
+    directive: 'Encapsulate flat primitive props into a cohesive domain type or composable'
   }
 };

package/cli/audit/rules.js

@@ -20,6 +20,8 @@ import {
 } from './extended-visitors.js';
 import { createPatternVisitors, recordTemplatePatterns } from './pattern-detector.js';
 import { createHookShapeRegistry } from './hook-shape-validator.js';
+import { isBabelParsable, getLanguageForFile } from '../languages.js';
+import { analyzeCSharpCode } from './csharp-analyzer.js';
 
 export { PILLARS, RULE_REGISTRY, createHookShapeRegistry };
 
@@ -34,7 +36,11 @@ export const auditCode = (content, filePath, relativePath, options = {}) => {
   const isView = relativePath.includes('/views/') || relativePath.includes('/pages/') || /View\.[tj]sx?$/.test(baseName);
   const isRootTypeFile = baseName === 'types.ts' || baseName === 'global.d.ts';
 
+  const config = options.config?.rules || options.config || {};
+  const enforceFileLength = config.enforceFileLength === true || config.profile === 'atomic-strict';
+
   // Pillar 1: Sliding Scale Monolith Detection
+  const moleculeLimit = enforceFileLength ? 100 : (config.maxLineCountWarning || 250);
   if (lineCount > 500) {
     const tier = resolveMonolithTier(lineCount);
     violations.push({
@@ -47,7 +53,7 @@ export const auditCode = (content, filePath, relativePath, options = {}) => {
       pillar: PILLARS.PILLAR_1,
       directive: tier.directive
     });
-  } else if (isMolecule && lineCount > 100) {
+  } else if (isMolecule && lineCount > moleculeLimit) {
     const tier = resolveMoleculeTier(lineCount);
     violations.push({
       filePath: relativePath,
@@ -103,7 +109,12 @@ 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) {
+  const lang = getLanguageForFile(filePath);
+  if (lang?.id === 'csharp') {
+    analyzeCSharpCode(content, relativePath, violations);
+  }
+
+  if (options.fast || !isBabelParsable(filePath)) {
     return violations;
   }
 
@@ -147,7 +158,7 @@ export const auditCode = (content, filePath, relativePath, options = {}) => {
 
   const traverseFn = traverse.default || traverse;
   const hookRegistry = options.hookRegistry || createHookShapeRegistry();
-  const visitors = createAstVisitors({ relativePath, violations, hookRegistry });
+  const visitors = createAstVisitors({ relativePath, violations, hookRegistry, config });
   const slopVisitors = createAiSlopVisitors({ relativePath, violations });
   const extendedVisitors = createExtendedVisitors({ relativePath, violations });
   const patternVisitors = options.patternRegistry

package/cli/audit/rules.spec.js

@@ -1,6 +1,9 @@
 import test from "node:test";
 import assert from "node:assert";
 import { auditCode } from "./rules.js";
+import { formatScorecardSection } from './reporter-sections.js';
+import { formatGradeASection } from './reporter-grades.js';
+import { generateMarkdownReport } from './reporter-markdown.js';
 
 test("Audit Rules: flags repetitive dispatch switch statement as CONTROL_FLOW_DISPATCH_SWITCH", () => {
   const code = `
@@ -332,3 +335,27 @@ export const useSecond = () => {
   assert.ok(inconsistentViolation.hazard.includes("isLoading"));
 });
 
+test("Audit Reporter: includes explicit architectural health notice distinguishing from production readiness", () => {
+  const mockReport = {
+    metrics: { scannedFiles: 5, totalLoc: 200, avgLoc: 40, largestFile: { filePath: 'src/a.ts', lineCount: 50 }, moleculeCount: 2, moleculeCompliantPct: 100, hookCount: 1 },
+    health: { score: 100, grade: 'A+', label: 'Pristine' },
+    pillars: { 'Pillar 1': { status: 'PASSED', violations: 0, critical: 0, high: 0, medium: 0, low: 0 } },
+    hotspots: [],
+    contextAnalysis: { riskLevel: 'LOW', estimatedTokens: 1000, estimatedExcessTokens: 0, potentialSavingsPct: 0 },
+    violations: [],
+    aiSlop: { score: 100, grade: 'A+', label: 'Pure Artisanal' }
+  };
+
+  const scorecard = formatScorecardSection(mockReport);
+  assert.ok(scorecard.includes('Architectural grade measures AST rules only'));
+  assert.ok(scorecard.includes('chemx verify'));
+
+  const gradeA = formatGradeASection(mockReport);
+  assert.ok(gradeA.includes('Architectural grade measures AST rules only'));
+  assert.ok(gradeA.includes('chemx verify'));
+
+  const markdown = generateMarkdownReport(mockReport);
+  assert.ok(markdown.includes('Architectural grades measure AST rule compliance only'));
+  assert.ok(markdown.includes('chemx verify'));
+});
+

package/cli/audit/structural-weight-evaluator.js

@@ -0,0 +1,121 @@
+import * as t from '@babel/types';
+import { RULE_REGISTRY } from './rules-registry.js';
+import {
+  countBranchingDecisions,
+  countHookCalls,
+  findNestedTernary,
+  countDestructuredProps
+} from './structural-weight.js';
+
+const isComponentOrHook = (funcPath, relativePath = '') => {
+  const isComponentFile = /\.(jsx|tsx|vue|svelte)$/.test(relativePath) ||
+    relativePath.includes('/components/') ||
+    relativePath.includes('/molecules/') ||
+    relativePath.includes('/atoms/') ||
+    relativePath.includes('/organisms/') ||
+    relativePath.includes('/views/') ||
+    relativePath.includes('/hooks/') ||
+    relativePath.includes('/composables/');
+
+  if (isComponentFile) return true;
+
+  const id = funcPath.node.id;
+  if (id && t.isIdentifier(id)) {
+    if (/^[A-Z]/.test(id.name) || /^use[A-Z0-9]/.test(id.name)) {
+      return true;
+    }
+  }
+
+  let returnsJsx = false;
+  funcPath.traverse({
+    ReturnStatement(ret) {
+      if (ret.getFunctionParent() === funcPath) {
+        const arg = ret.node.argument;
+        if (t.isJSXElement(arg) || t.isJSXFragment(arg)) {
+          returnsJsx = true;
+        }
+      }
+    }
+  });
+
+  return returnsJsx;
+};
+
+export const evaluateComponentStructuralWeight = ({
+  funcPath,
+  relativePath,
+  violations,
+  config = {}
+}) => {
+  if (!isComponentOrHook(funcPath, relativePath)) return null;
+
+  const maxComplexity = config.maxCyclomaticComplexity || 12;
+  const maxHooks = config.maxHookDensity || 4;
+  const maxProps = config.maxPropCount || 7;
+
+  const complexity = countBranchingDecisions(funcPath);
+  const hooks = countHookCalls(funcPath);
+  const propCount = countDestructuredProps(funcPath);
+  const startLoc = funcPath.node.loc?.start;
+  const line = startLoc?.line || 1;
+  const column = startLoc?.column || 1;
+
+  if (complexity > maxComplexity) {
+    const meta = RULE_REGISTRY.COMPLEXITY_CYCLOMATIC_HIGH;
+    violations.push({
+      filePath: relativePath,
+      line,
+      column,
+      hazard: `High cyclomatic complexity (${complexity} > ${maxComplexity} threshold)`,
+      rule: 'COMPLEXITY_CYCLOMATIC_HIGH',
+      severity: meta.severity,
+      pillar: meta.pillar,
+      directive: meta.directive
+    });
+  }
+
+  if (hooks > maxHooks) {
+    const meta = RULE_REGISTRY.HOOK_STATE_SATURATION;
+    violations.push({
+      filePath: relativePath,
+      line,
+      column,
+      hazard: `Excessive hook & state density (${hooks} hooks > ${maxHooks} threshold)`,
+      rule: 'HOOK_STATE_SATURATION',
+      severity: meta.severity,
+      pillar: meta.pillar,
+      directive: meta.directive
+    });
+  }
+
+  if (propCount > maxProps) {
+    const meta = RULE_REGISTRY.PROP_SURFACE_BLOAT;
+    violations.push({
+      filePath: relativePath,
+      line,
+      column,
+      hazard: `Prop surface area bloat (${propCount} props > ${maxProps} threshold)`,
+      rule: 'PROP_SURFACE_BLOAT',
+      severity: meta.severity,
+      pillar: meta.pillar,
+      directive: meta.directive
+    });
+  }
+
+  const nestedTernary = findNestedTernary(funcPath);
+  if (nestedTernary) {
+    const meta = RULE_REGISTRY.CONTROL_FLOW_NESTED_TERNARY;
+    violations.push({
+      filePath: relativePath,
+      line: nestedTernary.loc?.start.line || line,
+      column: nestedTernary.loc?.start.column || column,
+      hazard: 'Nested ternary expression detected in component logic',
+      rule: 'CONTROL_FLOW_NESTED_TERNARY',
+      severity: meta.severity,
+      pillar: meta.pillar,
+      directive: meta.directive
+    });
+  }
+
+  return { complexity, hooks, propCount };
+};

package/cli/audit/structural-weight.js

@@ -0,0 +1,92 @@
+import * as t from '@babel/types';
+
+export const countBranchingDecisions = (funcPath) => {
+  let complexity = 1;
+  funcPath.traverse({
+    IfStatement(p) {
+      if (p.getFunctionParent() === funcPath) complexity += 1;
+    },
+    ConditionalExpression(p) {
+      if (p.getFunctionParent() === funcPath) complexity += 1;
+    },
+    SwitchCase(p) {
+      if (p.getFunctionParent() === funcPath && p.node.test !== null) complexity += 1;
+    },
+    LogicalExpression(p) {
+      if (p.getFunctionParent() === funcPath) complexity += 1;
+    },
+    ForStatement(p) {
+      if (p.getFunctionParent() === funcPath) complexity += 1;
+    },
+    ForInStatement(p) {
+      if (p.getFunctionParent() === funcPath) complexity += 1;
+    },
+    ForOfStatement(p) {
+      if (p.getFunctionParent() === funcPath) complexity += 1;
+    },
+    WhileStatement(p) {
+      if (p.getFunctionParent() === funcPath) complexity += 1;
+    },
+    CatchClause(p) {
+      if (p.getFunctionParent() === funcPath) complexity += 1;
+    }
+  });
+  return complexity;
+};
+
+export const countHookCalls = (funcPath) => {
+  let hooks = 0;
+  funcPath.traverse({
+    CallExpression(p) {
+      if (p.getFunctionParent() !== funcPath) return;
+      const callee = p.node.callee;
+      const isHookIdentifier = t.isIdentifier(callee) && /^use[A-Z0-9]/.test(callee.name);
+      if (isHookIdentifier) {
+        hooks += 1;
+      }
+    }
+  });
+  return hooks;
+};
+
+export const findNestedTernary = (astPath) => {
+  let nested = null;
+  astPath.traverse({
+    ConditionalExpression(p) {
+      if (nested) return;
+      const parentCond = p.findParent((parent) => t.isConditionalExpression(parent.node));
+      if (parentCond) {
+        nested = p.node;
+      }
+    }
+  });
+  return nested;
+};
+
+export const countDestructuredProps = (funcPath) => {
+  const firstParam = funcPath.node.params?.[0];
+  const isObjectPattern = t.isObjectPattern(firstParam);
+  if (isObjectPattern) {
+    return firstParam.properties.length;
+  }
+  return 0;
+};
+
+export const measureJsxDepth = (jsxElementPath) => {
+  let maxDepth = 1;
+  const walk = (node, depth) => {
+    if (depth > maxDepth) maxDepth = depth;
+    const isJsxContainer = t.isJSXElement(node) || t.isJSXFragment(node);
+    if (isJsxContainer) {
+      const children = node.children || [];
+      for (const child of children) {
+        const isChildElement = t.isJSXElement(child) || t.isJSXFragment(child);
+        if (isChildElement) {
+          walk(child, depth + 1);
+        }
+      }
+    }
+  };
+  walk(jsxElementPath.node, 1);
+  return maxDepth;
+};

package/cli/audit/structural-weight.spec.js

@@ -0,0 +1,116 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { auditCode } from './rules.js';
+
+describe('AST Structural Weight & Pragmatic Profile Audit', () => {
+  it('does NOT flag a 120-line cohesive molecule in default pragmatic mode', () => {
+    // Generate a cohesive 115-line component with low complexity
+    const staticRows = Array.from({ length: 100 }, (_, i) => `    { id: ${i}, label: 'Item ${i}' },`).join('\n');
+    const code = `
+export const SimpleTable = () => {
+  const items = [
+${staticRows}
+  ];
+  return items.length;
+};
+`;
+    const violations = auditCode(code, 'src/components/molecules/m-table.js', 'src/components/molecules/m-table.js', {
+      config: { profile: 'pragmatic', enforceFileLength: false }
+    });
+
+    const moleculeLineViolation = violations.find((v) => v.rule === 'LINE_BUDGET_MOLECULE');
+    assert.strictEqual(moleculeLineViolation, undefined, 'Pragmatic mode should not flag a cohesive molecule under 250 lines');
+  });
+
+  it('strictly flags a 105-line molecule when profile is atomic-strict', () => {
+    const staticRows = Array.from({ length: 102 }, (_, i) => `    { id: ${i} },`).join('\n');
+    const code = `
+export const StrictCard = () => {
+  const rows = [
+${staticRows}
+  ];
+  return rows.length;
+};
+`;
+    const violations = auditCode(code, 'src/components/molecules/m-card.js', 'src/components/molecules/m-card.js', {
+      config: { profile: 'atomic-strict', enforceFileLength: true }
+    });
+
+    const moleculeLineViolation = violations.find((v) => v.rule === 'LINE_BUDGET_MOLECULE');
+    assert.ok(moleculeLineViolation, 'Atomic-strict mode should enforce 100-line molecule cap');
+  });
+
+  it('detects high cyclomatic complexity (CC > 12) via COMPLEXITY_CYCLOMATIC_HIGH', () => {
+    const code = `
+export function ComplexComponent(a, b, c, d, e, f, g) {
+  if (a === 1) return 1;
+  if (b === 2) return 2;
+  if (c === 3) return 3;
+  if (d === 4) return 4;
+  if (e === 5) return 5;
+  if (f === 6) return 6;
+  if (g === 7) return 7;
+  if (a && b) return 8;
+  if (c && d) return 9;
+  if (e && f) return 10;
+  if (a || g) return 11;
+  if (b || c) return 12;
+  if (d || e) return 13;
+  return 0;
+}
+`;
+    const violations = auditCode(code, 'src/components/ComplexComponent.jsx', 'src/components/ComplexComponent.jsx', {
+      config: { maxCyclomaticComplexity: 12 }
+    });
+
+    const complexityViolation = violations.find((v) => v.rule === 'COMPLEXITY_CYCLOMATIC_HIGH');
+    assert.ok(complexityViolation, 'Should detect cyclomatic complexity exceeding threshold');
+    assert.strictEqual(complexityViolation.severity, 'HIGH');
+  });
+
+  it('detects hook & state saturation (hooks > 4) via HOOK_STATE_SATURATION', () => {
+    const code = `
+import { useState, useEffect, useMemo, useCallback, useRef } from 'react';
+
+export function MonolithicComponent() {
+  const [s1, setS1] = useState(1);
+  const [s2, setS2] = useState(2);
+  const [s3, setS3] = useState(3);
+  useEffect(() => {}, []);
+  const m1 = useMemo(() => s1 + s2, [s1, s2]);
+  return null;
+}
+`;
+    const violations = auditCode(code, 'src/Component.jsx', 'src/Component.jsx', {
+      config: { maxHookDensity: 4 }
+    });
+
+    const hookViolation = violations.find((v) => v.rule === 'HOOK_STATE_SATURATION');
+    assert.ok(hookViolation, 'Should detect excessive hook density without domain encapsulation');
+  });
+
+  it('detects nested ternaries via CONTROL_FLOW_NESTED_TERNARY', () => {
+    const code = `
+export const BadTernary = (props) => {
+  return props.a ? (props.b ? 'X' : 'Y') : 'Z';
+};
+`;
+    const violations = auditCode(code, 'src/Ternary.jsx', 'src/Ternary.jsx');
+    const ternaryViolation = violations.find((v) => v.rule === 'CONTROL_FLOW_NESTED_TERNARY');
+    assert.ok(ternaryViolation, 'Should detect nested ternary expression');
+  });
+
+  it('detects prop surface area bloat (props > 7) via PROP_SURFACE_BLOAT', () => {
+    const code = `
+export const BloatedProps = ({ p1, p2, p3, p4, p5, p6, p7, p8, p9 }) => {
+  return p1;
+};
+`;
+    const violations = auditCode(code, 'src/Props.jsx', 'src/Props.jsx', {
+      config: { maxPropCount: 7 }
+    });
+
+    const propViolation = violations.find((v) => v.rule === 'PROP_SURFACE_BLOAT');
+    assert.ok(propViolation, 'Should detect prop count exceeding threshold');
+  });
+});

package/cli/audit-preflight-scope.js

@@ -3,7 +3,10 @@ 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'];
+const CANDIDATE_NAMES = [
+  'src', 'app', 'cli', 'components', 'lib', 'packages', 'modules',
+  'server', 'backend', 'api', 'Services', 'Controllers', 'Handlers', 'Domain', 'pkg', 'cmd', 'internal'
+];
 
 export const detectCandidateDirectories = (cwd = process.cwd()) => {
   return CANDIDATE_NAMES.filter((name) => {