@chemx/starter-kit 26.9.12-107 → 26.9.12-1140

package/cli/audit/ai-slop-detector.js

@@ -1,5 +1,12 @@
 import * as t from '@babel/types';
 import { RULE_REGISTRY } from './rules-registry.js';
+import {
+  isComponentPath,
+  isCodeLine,
+  isShallowCatchBody,
+  hasAnyTypeAnnotation,
+  isRedundantPassthroughReturn
+} from './rules-predicates.js';
 
 const RESIDUE_PATTERNS = [
   ['hope this', 'helps'].join(' '),
@@ -95,7 +102,7 @@ export const checkSlopTextPatterns = (content, lines, relativePath, violations)
         let nextIdx = idx + 1;
         while (nextIdx < lines.length) {
           const nextTrim = lines[nextIdx].trim();
-          if (nextTrim && !nextTrim.startsWith('//') && !nextTrim.startsWith('/*')) {
+          if (isCodeLine(nextTrim)) {
             const nextWords = new Set(normalizeWords(nextTrim));
             let matchCount = 0;
             for (const cw of commentWords) {
@@ -126,25 +133,12 @@ export const checkSlopTextPatterns = (content, lines, relativePath, violations)
 };
 
 export const createAiSlopVisitors = ({ relativePath, violations }) => {
-  const isComponentFile = (
-    relativePath.includes('molecules') ||
-    relativePath.includes('components') ||
-    relativePath.includes('/m-') ||
-    relativePath.includes('/views/') ||
-    relativePath.includes('/pages/')
-  );
+  const isComponentFile = isComponentPath(relativePath);
 
   return {
     CatchClause(astPath) {
       const body = astPath.node.body?.body || [];
-      const isShallowCatch = (
-        body.length === 0 ||
-        (body.length === 1 &&
-          t.isExpressionStatement(body[0]) &&
-          t.isCallExpression(body[0].expression) &&
-          t.isMemberExpression(body[0].expression.callee) &&
-          t.isIdentifier(body[0].expression.callee.object, { name: 'console' }))
-      );
+      const isShallowCatch = isShallowCatchBody(body, t);
 
       if (isShallowCatch) {
         const line = astPath.node.loc?.start.line || 1;
@@ -162,23 +156,20 @@ export const createAiSlopVisitors = ({ relativePath, violations }) => {
         });
       }
 
-      const param = astPath.node.param;
-      if (param && t.isIdentifier(param) && param.typeAnnotation) {
-        if (t.isTSTypeAnnotation(param.typeAnnotation) && t.isTSAnyKeyword(param.typeAnnotation.typeAnnotation)) {
-          const line = astPath.node.loc?.start.line || 1;
-          const meta = RULE_REGISTRY.AI_SLOP_LAZY_ANY;
-          violations.push({
-            filePath: relativePath,
-            line,
-            column: astPath.node.loc?.start.column || 1,
-            hazard: 'Lazy any catch parameter widening detected',
-            rule: 'AI_SLOP_LAZY_ANY',
-            severity: meta.severity,
-            pillar: meta.pillar,
-            directive: meta.directive,
-            isAiSlop: true
-          });
-        }
+      if (hasAnyTypeAnnotation(astPath.node.param, t)) {
+        const line = astPath.node.loc?.start.line || 1;
+        const meta = RULE_REGISTRY.AI_SLOP_LAZY_ANY;
+        violations.push({
+          filePath: relativePath,
+          line,
+          column: astPath.node.loc?.start.column || 1,
+          hazard: 'Lazy any catch parameter widening detected',
+          rule: 'AI_SLOP_LAZY_ANY',
+          severity: meta.severity,
+          pillar: meta.pillar,
+          directive: meta.directive,
+          isAiSlop: true
+        });
       }
     },
 
@@ -188,14 +179,7 @@ export const createAiSlopVisitors = ({ relativePath, violations }) => {
         for (let i = 0; i < stmts.length - 1; i++) {
           const curr = stmts[i];
           const next = stmts[i + 1];
-          if (
-            t.isVariableDeclaration(curr) &&
-            curr.declarations.length === 1 &&
-            t.isIdentifier(curr.declarations[0].id) &&
-            t.isReturnStatement(next) &&
-            t.isIdentifier(next.argument) &&
-            curr.declarations[0].id.name === next.argument.name
-          ) {
+          if (isRedundantPassthroughReturn(curr, next, t)) {
             const varName = curr.declarations[0].id.name;
             const line = curr.loc?.start.line || 1;
             const meta = RULE_REGISTRY.AI_SLOP_REDUNDANT_PASSTHROUGH;

package/cli/audit/ast-visitors.js

@@ -1,14 +1,17 @@
 import * as t from '@babel/types';
 import { RULE_REGISTRY } from './rules-registry.js';
 import { countLogicalOperators } from './rules-helpers.js';
+import {
+  isCustomHookFunction,
+  resolveStartLine,
+  isZeroDelayTimeout,
+  isUnguardedConsoleCall
+} from './rules-predicates.js';
 
 export const createAstVisitors = ({ relativePath, violations }) => {
   return {
     Function(astPath) {
-      const isCustomHook = (
-        (astPath.node.id && /^use[A-Z0-9]/.test(astPath.node.id.name)) ||
-        (astPath.parentPath?.node?.id && /^use[A-Z0-9]/.test(astPath.parentPath.node.id.name))
-      );
+      const isCustomHook = isCustomHookFunction(astPath);
 
       // Pillar 3: Hook Saturation
       let hookCount = 0;
@@ -70,7 +73,7 @@ export const createAstVisitors = ({ relativePath, violations }) => {
       if (t.isLogicalExpression(expr) || t.isUnaryExpression(expr)) {
         const opCount = countLogicalOperators(expr);
         if (opCount > 2) {
-          const line = expr.loc?.start.line || astPath.node.loc?.start.line || 1;
+          const line = resolveStartLine(expr, astPath.node, 1);
           const meta = RULE_REGISTRY.CONTROL_FLOW_INLINE_BOOLEAN;
           violations.push({
             filePath: relativePath,
@@ -154,7 +157,7 @@ export const createAstVisitors = ({ relativePath, violations }) => {
         const delayArg = args[1];
 
         // Render-hack check: setTimeout(fn, 0)
-        if (callee.name === 'setTimeout' && delayArg && t.isNumericLiteral(delayArg) && delayArg.value === 0) {
+        if (isZeroDelayTimeout(callee, delayArg, t)) {
           const line = astPath.node.loc?.start.line || 1;
           const meta = RULE_REGISTRY.RENDER_HACK_TIMEOUT;
           violations.push({
@@ -198,13 +201,7 @@ export const createAstVisitors = ({ relativePath, violations }) => {
       }
 
       // Unguarded Logging
-      if (
-        t.isMemberExpression(callee) &&
-        t.isIdentifier(callee.object) &&
-        callee.object.name === 'console' &&
-        t.isIdentifier(callee.property) &&
-        ['log', 'info', 'warn'].includes(callee.property.name)
-      ) {
+      if (isUnguardedConsoleCall(callee, t)) {
         const line = astPath.node.loc?.start.line || 1;
         const meta = RULE_REGISTRY.UNGUARDED_LOGGING;
         violations.push({

package/cli/audit/history.js

@@ -126,18 +126,39 @@ export const getAuditHistory = (cwd = process.cwd()) => {
 };
 
 export const getAuditBaseline = (cwd = process.cwd()) => {
+  const history = getAuditHistory(cwd);
   const baselinePath = path.resolve(cwd, '.chemx', 'baseline.json');
+  let explicitBaseline = null;
   if (fs.existsSync(baselinePath)) {
     try {
       const raw = fs.readFileSync(baselinePath, 'utf-8');
-      return JSON.parse(raw);
+      explicitBaseline = JSON.parse(raw);
     } catch (err) {
       const error = err instanceof Error ? err : new Error(String(err));
-      return null;
+      explicitBaseline = null;
     }
   }
-  const history = getAuditHistory(cwd);
-  return history.length > 0 ? history[0] : null;
+
+  if (history.length === 0) {
+    return explicitBaseline;
+  }
+
+  // Find the lowest scoring snapshot in history (the true debt floor)
+  let lowestSnapshot = history[0];
+  for (const s of history) {
+    const currentScore = s.health?.score ?? 100;
+    const lowestScore = lowestSnapshot.health?.score ?? 100;
+    if (currentScore < lowestScore) {
+      lowestSnapshot = s;
+    }
+  }
+
+  if (!explicitBaseline) return lowestSnapshot;
+
+  // Use the lowest score between explicit baseline and history floor
+  const explicitScore = explicitBaseline.health?.score ?? 100;
+  const minScore = lowestSnapshot.health?.score ?? 100;
+  return minScore < explicitScore ? lowestSnapshot : explicitBaseline;
 };
 
 export const setAuditBaseline = (snapshot, cwd = process.cwd()) => {
@@ -179,10 +200,14 @@ export const saveAuditSnapshot = (report, cwd = process.cwd()) => {
   const historyPath = path.resolve(cwd, '.chemx', 'history.json');
   fs.writeFileSync(historyPath, JSON.stringify(trimmed, null, 2), 'utf-8');
 
-  // Auto-establish first run as baseline if none exists
+  // Auto-establish first run or lower score as baseline floor
   const baselinePath = path.resolve(cwd, '.chemx', 'baseline.json');
   let isNewBaseline = false;
-  if (!fs.existsSync(baselinePath)) {
+  const currentBaseline = getAuditBaseline(cwd);
+  const currentScore = snapshot.health?.score ?? 100;
+  const baselineScore = currentBaseline?.health?.score ?? 101;
+
+  if (!currentBaseline || currentScore < baselineScore) {
     fs.writeFileSync(baselinePath, JSON.stringify(snapshot, null, 2), 'utf-8');
     isNewBaseline = true;
   }
@@ -275,7 +300,8 @@ export const calculateTransformationDelta = (beforeSnapshot, afterSnapshot) => {
   };
 };
 
-export const formatTransformationTerminal = (beforeSnapshot, afterSnapshot) => {
+export const formatTransformationTerminal = (beforeSnapshot, afterSnapshot, options = {}) => {
+  const { isStepDelta = false } = options;
   const delta = calculateTransformationDelta(beforeSnapshot, afterSnapshot);
   const lines = [];
 
@@ -295,18 +321,26 @@ export const formatTransformationTerminal = (beforeSnapshot, afterSnapshot) => {
     return `${color}${BOLD}${sign}${perUnit}${RESET}`;
   };
 
+  const title = isStepDelta
+    ? 'STEP PROGRESSION : INCREMENTAL CHECKPOINT DELTA'
+    : 'ARCHITECTURAL TRANSFORMATION : BEFORE & AFTER PROGRESSION';
+  const subtitle = isStepDelta
+    ? 'Comparing immediately preceding audit vs. latest refactored audit'
+    : 'Comparing baseline floor snapshot vs. latest refactored audit';
+  const beforeLabel = isStepDelta ? 'Previous Audit:' : 'Baseline Floor:';
+
   lines.push('');
   lines.push(`${CYAN}======================================================================${RESET}`);
-  lines.push(`${BOLD}${CYAN}   ARCHITECTURAL TRANSFORMATION : BEFORE & AFTER PROGRESSION${RESET}`);
-  lines.push(`${DIM}   Comparing baseline snapshot vs. latest refactored audit${RESET}`);
+  lines.push(`${BOLD}${CYAN}   ${title}${RESET}`);
+  lines.push(`${DIM}   ${subtitle}${RESET}`);
   lines.push(`${CYAN}======================================================================${RESET}`);
   lines.push('');
 
   const dateBefore = new Date(beforeSnapshot.timestamp).toLocaleDateString();
   const dateAfter = new Date(afterSnapshot.timestamp).toLocaleDateString();
 
-  lines.push(`   ${BOLD}Baseline Audit:${RESET}    ${DIM}${dateBefore} [${beforeSnapshot.id}]${RESET}`);
-  lines.push(`   ${BOLD}Latest Audit:${RESET}      ${GREEN}${dateAfter} [${afterSnapshot.id}]${RESET}`);
+  lines.push(`   ${BOLD}${beforeLabel.padEnd(18)}${RESET} ${DIM}${dateBefore} [${beforeSnapshot.id}]${RESET}`);
+  lines.push(`   ${BOLD}${'Latest Audit:'.padEnd(18)}${RESET} ${GREEN}${dateAfter} [${afterSnapshot.id}]${RESET}`);
   lines.push('');
 
   lines.push(`${BOLD}   METRIC COMPARISON TABLE${RESET}`);

package/cli/audit/pattern-detector.js

@@ -0,0 +1,182 @@
+/**
+ * Chemical X Protocol: Structural Pattern Harmonization Detector
+ * Single-pass AST fingerprinting to discover cross-file clones and extraction candidates.
+ */
+
+const MIN_UNION_MEMBERS = 3;
+const MIN_CHILD_NODES = 2;
+
+export const createPatternRegistry = () => {
+  const buckets = new Map();
+
+  const record = (type, signature, location) => {
+    if (!signature) return;
+    const key = `${type}::${signature}`;
+    let bucket = buckets.get(key);
+    if (!bucket) {
+      bucket = {
+        type,
+        signature,
+        detail: location.detail || signature,
+        occurrences: []
+      };
+      buckets.set(key, bucket);
+    }
+    bucket.occurrences.push({
+      filePath: location.filePath,
+      line: location.line || 1,
+      column: location.column || 1
+    });
+  };
+
+  const resolveHarmonizationCandidates = (hotspots = []) => {
+    const hotspotFiles = new Set(hotspots.map((h) => h.filePath));
+    const candidates = [];
+
+    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 impactScore = uniqueFiles.length * (hasHotspot ? 3 : 1.5) + bucket.occurrences.length;
+
+      let label = 'Recurring Pattern';
+      let suggestedCapsule = 'm-shared-capsule';
+      let recommendation = 'Extract canonical capsule before decomposing consumers';
+
+      if (bucket.type === 'STATE_UNION') {
+        label = `Shared State Machine (${bucket.detail})`;
+        suggestedCapsule = 'types/state.d.ts';
+        recommendation = 'Extract shared discriminated union into domain types to eliminate duplicate definitions';
+      } else if (bucket.type === 'UI_STRUCTURE') {
+        label = `Shared UI Layout Structure (${bucket.detail})`;
+        suggestedCapsule = 'm-feature-card';
+        recommendation = 'Extract canonical molecule capsule before slicing consumer monoliths';
+      } else if (bucket.type === 'PREDICATE_LOGIC') {
+        label = `Duplicated Boolean Predicate Topology (${bucket.detail})`;
+        suggestedCapsule = 'usePredicateFilter.ts';
+        recommendation = 'Extract named predicate callback or higher-order filter function';
+      } else if (bucket.type === 'HOOK_SIGNATURE') {
+        label = `Parallel State Controller Return (${bucket.detail})`;
+        suggestedCapsule = 'useSharedController.ts';
+        recommendation = 'Unify ad-hoc local state returns into a canonical domain composable';
+      }
+
+      candidates.push({
+        id: key,
+        type: bucket.type,
+        label,
+        detail: bucket.detail,
+        suggestedCapsule,
+        recommendation,
+        fileCount: uniqueFiles.length,
+        totalHits: bucket.occurrences.length,
+        hasHotspot,
+        impactScore,
+        occurrences: bucket.occurrences
+      });
+    }
+
+    return candidates.sort((a, b) => b.impactScore - a.impactScore).slice(0, 12);
+  };
+
+  return { record, resolveHarmonizationCandidates };
+};
+
+export const createPatternVisitors = (registry, relativePath) => {
+  if (!registry) return {};
+
+  const getJsxTagName = (node) => {
+    if (!node || !node.openingElement) return null;
+    const nameNode = node.openingElement.name;
+    if (nameNode.type === 'JSXIdentifier') return nameNode.name;
+    if (nameNode.type === 'JSXMemberExpression') return `${nameNode.object.name}.${nameNode.property.name}`;
+    return null;
+  };
+
+  const getJsxHierarchy = (node, depth = 0) => {
+    if (depth > 2 || !node || node.type !== 'JSXElement') return '';
+    const tag = getJsxTagName(node);
+    if (!tag) return '';
+
+    const elementChildren = (node.children || [])
+      .filter((c) => c.type === 'JSXElement')
+      .map((c) => getJsxHierarchy(c, depth + 1))
+      .filter(Boolean);
+
+    if (elementChildren.length === 0) return tag;
+    return `${tag}>(${elementChildren.join('+')})`;
+  };
+
+  return {
+    TSTypeAliasDeclaration(path) {
+      const typeAnnotation = path.node.typeAnnotation;
+      if (typeAnnotation && typeAnnotation.type === 'TSUnionType') {
+        const literals = (typeAnnotation.types || [])
+          .filter((t) => t.type === 'TSLiteralType' && typeof t.literal?.value === 'string')
+          .map((t) => `'${t.literal.value}'`);
+
+        if (literals.length >= MIN_UNION_MEMBERS) {
+          const sorted = Array.from(new Set(literals)).sort().join(' | ');
+          registry.record('STATE_UNION', sorted, {
+            filePath: relativePath,
+            line: path.node.loc?.start?.line,
+            detail: sorted
+          });
+        }
+      }
+    },
+
+    JSXElement(path) {
+      const directElementChildren = (path.node.children || []).filter((c) => c.type === 'JSXElement');
+      if (directElementChildren.length >= MIN_CHILD_NODES) {
+        const hierarchy = getJsxHierarchy(path.node);
+        if (hierarchy && hierarchy.includes('>')) {
+          registry.record('UI_STRUCTURE', hierarchy, {
+            filePath: relativePath,
+            line: path.node.loc?.start?.line,
+            detail: hierarchy
+          });
+        }
+      }
+    },
+
+    LogicalExpression(path) {
+      let clauseCount = 1;
+      let curr = path.node;
+      while (curr && curr.type === 'LogicalExpression') {
+        clauseCount++;
+        curr = curr.left;
+      }
+      if (clauseCount >= 3) {
+        const sig = `CLAUSES_${clauseCount}_OP_${path.node.operator}`;
+        registry.record('PREDICATE_LOGIC', sig, {
+          filePath: relativePath,
+          line: path.node.loc?.start?.line,
+          detail: `${clauseCount}-clause ${path.node.operator} condition`
+        });
+      }
+    },
+
+    ReturnStatement(path) {
+      const functionParent = path.getFunctionParent();
+      const fnName = functionParent?.node?.id?.name;
+      const isHook = fnName && /^use[A-Z]/.test(fnName);
+
+      if (isHook && path.node.argument && path.node.argument.type === 'ObjectExpression') {
+        const props = (path.node.argument.properties || [])
+          .filter((p) => p.type === 'ObjectProperty' && p.key?.name)
+          .map((p) => p.key.name);
+
+        if (props.length >= 3) {
+          const sorted = props.sort().join(',');
+          registry.record('HOOK_SIGNATURE', sorted, {
+            filePath: relativePath,
+            line: path.node.loc?.start?.line,
+            detail: `{ ${sorted.replace(/,/g, ', ')} }`
+          });
+        }
+      }
+    }
+  };
+};

package/cli/audit/prompts.js

@@ -1,36 +1,19 @@
-import { groupViolationsByRule } from './reporter-grouping.js';
-
-const CYAN = '\x1b[38;2;98;201;255m';
-const BOLD = '\x1b[1m';
-const DIM = '\x1b[2m';
-const RESET = '\x1b[0m';
-
-const buildPathTree = (violations) => {
-  const root = { dirs: new Map(), files: new Map() };
-
-  for (const v of violations) {
-    const rawPath = v.filePath || '';
-    const normalized = rawPath.replace(/\\/g, '/').replace(/^\.\//, '');
-    const segments = normalized.split('/');
-    const fileName = segments.pop();
-
-    let current = root;
-    for (const seg of segments) {
-      const segName = seg.endsWith('/') ? seg : `${seg}/`;
-      if (!current.dirs.has(segName)) {
-        current.dirs.set(segName, { dirs: new Map(), files: new Map() });
-      }
-      current = current.dirs.get(segName);
-    }
-
-    if (!current.files.has(fileName)) {
-      current.files.set(fileName, []);
-    }
-    const loc = v.column ? `${v.line}:${v.column}` : `${v.line}`;
-    current.files.get(fileName).push(loc);
-  }
-
-  return root;
+import { groupViolationsByRule, buildPathTree } from './reporter-grouping.js';
+import {
+  CYAN,
+  YELLOW,
+  RED,
+  ORANGE,
+  DIM,
+  BOLD,
+  RESET
+} from './reporter-utils.js';
+
+const SEVERITY_COLORS = {
+  CRITICAL: RED,
+  HIGH: ORANGE,
+  MEDIUM: YELLOW,
+  LOW: DIM
 };
 
 const renderTreeLines = (node, depth = 0) => {
@@ -39,7 +22,7 @@ const renderTreeLines = (node, depth = 0) => {
 
   const sortedDirs = Array.from(node.dirs.entries()).sort((a, b) => a[0].localeCompare(b[0]));
   for (const [dirName, childNode] of sortedDirs) {
-    lines.push(`${indent}* ${dirName}`);
+    lines.push(`${indent}📁 ${BOLD}${dirName}${RESET}`);
     const childLines = renderTreeLines(childNode, depth + 1);
     lines.push(...childLines);
   }
@@ -47,7 +30,7 @@ const renderTreeLines = (node, depth = 0) => {
   const sortedFiles = Array.from(node.files.entries()).sort((a, b) => a[0].localeCompare(b[0]));
   for (const [fileName, locs] of sortedFiles) {
     const uniqueLocs = Array.from(new Set(locs)).join(', ');
-    lines.push(`${indent}- \`${fileName}:${uniqueLocs}\``);
+    lines.push(`${indent}- \`${YELLOW}${fileName}:${uniqueLocs}${RESET}\``);
   }
 
   return lines;
@@ -61,10 +44,11 @@ export const formatGroupedPromptViolations = (violations = []) => {
   const lines = [];
 
   ruleGroups.forEach((rg, idx) => {
+    const sevColor = SEVERITY_COLORS[rg.severity] || YELLOW;
     const countLabel = rg.total === 1 ? '1 item' : `${rg.total} items`;
-    lines.push(`${idx + 1}. [${rg.rule}] (${countLabel})`);
-    lines.push(`   Hazard: ${rg.hazard}`);
-    lines.push(`   Directive: ${rg.directive}`);
+    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:');
 
     const tree = buildPathTree(rg.violations);
@@ -106,11 +90,12 @@ export const buildGradeFPrompt = (report, options = {}) => {
   }
 
   lines.push('### STRICT EXECUTION RULES:');
-  lines.push('1. Every new molecule component must stay under 100 lines.');
-  lines.push('2. Top-level page views must be 10-20 line declarative Table-of-Contents templates assembling components via named slots.');
-  lines.push('3. Zero synthetic or mock data: return live data or explicit empty states.');
-  lines.push('4. Zero render-hack setTimeout: replace with await nextTick() or flush: post.');
-  lines.push('5. Output surgical diffs or modular replacements. Preserve existing external exports.');
+  lines.push('1. Pre-Split Pattern Discovery: Survey cross-file patterns before slicing; extract canonical shared capsules first to avoid proliferating duplicate one-off patterns.');
+  lines.push('2. Every new molecule component must stay under 100 lines.');
+  lines.push('3. Top-level page views must be 10-20 line declarative Table-of-Contents templates assembling components via named slots.');
+  lines.push('4. Zero synthetic or mock data: return live data or explicit empty states.');
+  lines.push('5. Zero render-hack setTimeout: replace with await nextTick() or flush: post.');
+  lines.push('6. Output surgical diffs or modular replacements. Preserve existing external exports.');
 
   return lines.join('\n');
 };
@@ -256,11 +241,13 @@ export const buildHotspotsPrompt = (report) => {
   lines.push('');
 
   lines.push('### STRICT EXECUTION RULES:');
-  lines.push('1. Molecular Limits: Molecule capsules must strictly remain under 100 lines per file.');
-  lines.push('2. 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('3. Composable Return Contracts: Custom hooks/composables must strictly limit returns to 3 to 5 properties (State + Status + Actions).');
-  lines.push('4. 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('5. Zero breaking changes to external component APIs, route exports, or existing props.');
+  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.');
 
   return lines.join('\n');
 };

package/cli/audit/reporter-banner.js

@@ -1,5 +1,6 @@
 import { resolveGradeColor } from './reporter-utils.js';
 import { getAsciiGradeLines } from './reporter-ascii.js';
+import { getChemicalXGradientColor, ANSI } from '../theme.js';
 
 const BANNER_ART = [
   ' ██████╗██╗  ██╗███████╗███╗   ███╗██╗ ██████╗ █████╗ ██╗         ██╗  ██╗',
@@ -18,7 +19,7 @@ export const getChemicalXAsciiBanner = (gradeOrReport = null) => {
     : gradeOrReport;
 
   const lines = [];
-  lines.push('                     \x1b[1m\x1b[37mThe Secret Sauce to \x1b[38;2;98;201;255mVibe Coding\x1b[0m');
+  lines.push(`                     ${ANSI.BOLD}${ANSI.GOLD}The Secret Sauce to Vibe Coding!${ANSI.RESET}`);
 
   const gColor = grade ? resolveGradeColor(grade) : '';
   const gradeLines = grade ? getAsciiGradeLines(grade, gColor, true) : [];
@@ -35,21 +36,8 @@ export const getChemicalXAsciiBanner = (gradeOrReport = null) => {
         continue;
       }
       const t = i / (MAX_BANNER_LEN - 1);
-      let r;
-      let g;
-      let b;
-      if (t < 0.5) {
-        const factor = t * 2;
-        r = Math.round(244 * (1 - factor) + 192 * factor);
-        g = Math.round(114 * (1 - factor) + 132 * factor);
-        b = Math.round(182 * (1 - factor) + 252 * factor);
-      } else {
-        const factor = (t - 0.5) * 2;
-        r = Math.round(192 * (1 - factor) + 129 * factor);
-        g = Math.round(132 * (1 - factor) + 140 * factor);
-        b = Math.round(252 * (1 - factor) + 248 * factor);
-      }
-      out += `\x1b[38;2;${r};${g};${b}m\x1b[1m${ch}\x1b[0m`;
+      const { ansi } = getChemicalXGradientColor(t);
+      out += `${ansi}${ANSI.BOLD}${ch}${ANSI.RESET}`;
     }
 
     if (isSideBySide && gradeLines.length > lineIdx) {