@chemx/starter-kit 26.9.12-93 → 26.9.13-272

package/cli/audit/prompts.js

@@ -1,74 +1,132 @@
-const CYAN = '\x1b[38;2;98;201;255m';
-const BOLD = '\x1b[1m';
-const DIM = '\x1b[2m';
-const RESET = '\x1b[0m';
-
-export const buildGradeFPrompt = (report) => {
-  const { violations, hotspots } = report;
-  const critical = violations.filter((v) => v.severity === 'CRITICAL');
+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) => {
+  const lines = [];
+  const indent = '   ' + '  '.repeat(depth);
+
+  const sortedDirs = Array.from(node.dirs.entries()).sort((a, b) => a[0].localeCompare(b[0]));
+  for (const [dirName, childNode] of sortedDirs) {
+    lines.push(`${indent}📁 ${BOLD}${dirName}${RESET}`);
+    const childLines = renderTreeLines(childNode, depth + 1);
+    lines.push(...childLines);
+  }
+
+  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}- \`${YELLOW}${fileName}:${uniqueLocs}${RESET}\``);
+  }
+
+  return lines;
+};
+
+export const formatGroupedPromptViolations = (violations = []) => {
+  const hasNoViolations = violations.length === 0;
+  if (hasNoViolations) return [];
+
+  const ruleGroups = groupViolationsByRule(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}. ${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);
+    const treeLines = renderTreeLines(tree, 0);
+    lines.push(...treeLines);
+    lines.push('');
+  });
+
+  return lines;
+};
+
+export const buildGradeFPrompt = (report, options = {}) => {
+  const { excludeAiSlop = false } = options;
+  const { violations = [], hotspots = [] } = report;
+  const critical = violations
+    .filter((v) => v.severity === 'CRITICAL')
+    .filter((v) => (excludeAiSlop ? !v.isAiSlop : true));
   const extremeMonoliths = hotspots.filter((h) => h.lineCount >= 2000);
 
-  if (critical.length === 0 && extremeMonoliths.length === 0) return '';
+  const hasNoCritical = critical.length === 0;
+  const hasNoMonoliths = extremeMonoliths.length === 0;
+  if (hasNoCritical && hasNoMonoliths) return '';
 
   const lines = [];
   lines.push('Act as a Principal Systems Architect. Surgically refactor the following Grade F Critical Context Hazards in our codebase according to Chemical X Molecular Architecture Standards:\n');
 
   if (extremeMonoliths.length > 0) {
     lines.push('### EXTREME MONOLITHS (>= 2,000 lines of code) : MONOLITH DECOMPOSITION');
+    lines.push('Action: Decompose into crystalline single-responsibility capsules (< 100 lines per molecule). Convert top-level view into a declarative Table-of-Contents view.\n');
     extremeMonoliths.forEach((h, i) => {
       lines.push(`${i + 1}. File: \`${h.filePath}\` (${h.lineCount} lines)`);
-      lines.push('   Action: Decompose this monolith into crystalline single-responsibility capsules (< 100 lines per molecule). Convert top-level view into a declarative Table-of-Contents view.');
     });
     lines.push('');
   }
 
   if (critical.length > 0) {
     lines.push('### CRITICAL AST VIOLATIONS');
-    critical.forEach((v, i) => {
-      lines.push(`${i + 1}. \`${v.filePath}:${v.line}:${v.column}\` [${v.rule}]`);
-      lines.push(`   Hazard: ${v.hazard}`);
-      lines.push(`   Directive: ${v.directive}`);
-    });
-    lines.push('');
+    lines.push(...formatGroupedPromptViolations(critical));
   }
 
   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');
 };
 
-export const buildGradeDPrompt = (report) => {
-  const { violations, hotspots } = report;
-  const high = violations.filter((v) => v.severity === 'HIGH');
+export const buildGradeDPrompt = (report, options = {}) => {
+  const { excludeAiSlop = false } = options;
+  const { violations = [], hotspots = [] } = report;
+  const high = violations
+    .filter((v) => v.severity === 'HIGH')
+    .filter((v) => (excludeAiSlop ? !v.isAiSlop : true));
   const severeMonoliths = hotspots.filter((h) => h.lineCount >= 1000 && h.lineCount < 2000);
 
-  if (high.length === 0 && severeMonoliths.length === 0) return '';
+  const hasNoHigh = high.length === 0;
+  const hasNoMonoliths = severeMonoliths.length === 0;
+  if (hasNoHigh && hasNoMonoliths) return '';
 
   const lines = [];
   lines.push('Act as a Principal Systems Architect. Refactor the following Grade D High-Severity Architectural Debts according to Chemical X Molecular Architecture Standards:\n');
 
   if (severeMonoliths.length > 0) {
     lines.push('### SEVERE MONOLITHS (1,000 - 1,999 lines of code)');
+    lines.push('Action: Extract sub-features into isolated molecule capsules (< 100 lines of code) and domain composables.\n');
     severeMonoliths.forEach((h, i) => {
       lines.push(`${i + 1}. File: \`${h.filePath}\` (${h.lineCount} lines)`);
-      lines.push('   Action: Extract sub-features into isolated molecule capsules (< 100 lines of code) and domain composables.');
     });
     lines.push('');
   }
 
   if (high.length > 0) {
     lines.push('### HIGH SEVERITY VIOLATIONS');
-    high.forEach((v, i) => {
-      lines.push(`${i + 1}. \`${v.filePath}:${v.line}:${v.column}\` [${v.rule}]`);
-      lines.push(`   Hazard: ${v.hazard}`);
-      lines.push(`   Directive: ${v.directive}`);
-    });
-    lines.push('');
+    lines.push(...formatGroupedPromptViolations(high));
   }
 
   lines.push('### STRICT EXECUTION RULES:');
@@ -79,33 +137,33 @@ export const buildGradeDPrompt = (report) => {
   return lines.join('\n');
 };
 
-export const buildGradeCPrompt = (report) => {
-  const { violations, hotspots } = report;
-  const medium = violations.filter((v) => v.severity === 'MEDIUM');
+export const buildGradeCPrompt = (report, options = {}) => {
+  const { excludeAiSlop = false } = options;
+  const { violations = [], hotspots = [] } = report;
+  const medium = violations
+    .filter((v) => v.severity === 'MEDIUM')
+    .filter((v) => (excludeAiSlop ? !v.isAiSlop : true));
   const warningMonoliths = hotspots.filter((h) => h.lineCount >= 500 && h.lineCount < 1000);
 
-  if (medium.length === 0 && warningMonoliths.length === 0) return '';
+  const hasNoMedium = medium.length === 0;
+  const hasNoMonoliths = warningMonoliths.length === 0;
+  if (hasNoMedium && hasNoMonoliths) return '';
 
   const lines = [];
   lines.push('Act as a Senior Frontend Engineer. Refactor the following Grade C Medium-Severity Technical Debts according to Chemical X Molecular Architecture Standards:\n');
 
   if (warningMonoliths.length > 0) {
     lines.push('### WARNING MONOLITHS (500 - 999 lines of code)');
+    lines.push('Action: Bring file under 500 line budget by extracting helper functions, types, and child molecules.\n');
     warningMonoliths.forEach((h, i) => {
       lines.push(`${i + 1}. File: \`${h.filePath}\` (${h.lineCount} lines)`);
-      lines.push('   Action: Bring file under 500 line budget by extracting helper functions, types, and child molecules.');
     });
     lines.push('');
   }
 
   if (medium.length > 0) {
     lines.push('### MEDIUM SEVERITY VIOLATIONS');
-    medium.forEach((v, i) => {
-      lines.push(`${i + 1}. \`${v.filePath}:${v.line}:${v.column}\` [${v.rule}]`);
-      lines.push(`   Hazard: ${v.hazard}`);
-      lines.push(`   Directive: ${v.directive}`);
-    });
-    lines.push('');
+    lines.push(...formatGroupedPromptViolations(medium));
   }
 
   lines.push('### STRICT EXECUTION RULES:');
@@ -116,22 +174,21 @@ export const buildGradeCPrompt = (report) => {
   return lines.join('\n');
 };
 
-export const buildGradeBPrompt = (report) => {
-  const { violations } = report;
-  const low = violations.filter((v) => v.severity === 'LOW');
+export const buildGradeBPrompt = (report, options = {}) => {
+  const { excludeAiSlop = false } = options;
+  const { violations = [] } = report;
+  const low = violations
+    .filter((v) => v.severity === 'LOW')
+    .filter((v) => (excludeAiSlop ? !v.isAiSlop : true));
 
-  if (low.length === 0) return '';
+  const hasNoLow = low.length === 0;
+  if (hasNoLow) return '';
 
   const lines = [];
   lines.push('Act as a Clean Code Specialist. Clean up the following Grade B Low-Severity Hygiene Issues according to Chemical X standards:\n');
 
   lines.push('### LOW HYGIENE VIOLATIONS');
-  low.forEach((v, i) => {
-    lines.push(`${i + 1}. \`${v.filePath}:${v.line}:${v.column}\` [${v.rule}]`);
-    lines.push(`   Hazard: ${v.hazard}`);
-    lines.push(`   Directive: ${v.directive}`);
-  });
-  lines.push('');
+  lines.push(...formatGroupedPromptViolations(low));
 
   lines.push('### STRICT EXECUTION RULES:');
   lines.push('1. Typography Hygiene: Replace all em dashes with standard hyphens (-) or colons (:).');
@@ -145,18 +202,14 @@ export const buildAiSlopPrompt = (report) => {
   const { violations = [] } = report;
   const slopViolations = violations.filter((v) => Boolean(v.isAiSlop));
 
-  if (slopViolations.length === 0) return '';
+  const hasNoSlop = slopViolations.length === 0;
+  if (hasNoSlop) return '';
 
   const lines = [];
   lines.push('Act as a Clean Code Specialist and Code Authenticity Guardian. Eliminate the following AI Slop and conversational artifacts from our codebase according to Chemical X standards:\n');
 
   lines.push('### AI SLOP & CODE AUTHENTICITY VIOLATIONS');
-  slopViolations.forEach((v, i) => {
-    lines.push(`${i + 1}. \`${v.filePath}:${v.line}:${v.column}\` [${v.rule}]`);
-    lines.push(`   Hazard: ${v.hazard}`);
-    lines.push(`   Directive: ${v.directive}`);
-  });
-  lines.push('');
+  lines.push(...formatGroupedPromptViolations(slopViolations));
 
   lines.push('### STRICT EXECUTION RULES:');
   lines.push('1. Conversational Residue: Completely remove leaked AI conversational preambles, assistant markdown code fences, and pleasantry comments.');
@@ -173,40 +226,44 @@ export const buildHotspotsPrompt = (report) => {
   const { hotspots = [] } = report;
   const monolithHotspots = hotspots.filter((h) => h.isMonolith || h.lineCount > 500);
 
-  if (monolithHotspots.length === 0) return '';
+  const hasNoMonoliths = monolithHotspots.length === 0;
+  if (hasNoMonoliths) return '';
 
   const lines = [];
   lines.push('Act as a Principal Systems Architect. Surgically decompose the following monolithic hotspot files according to Chemical X Molecular Architecture Standards:\n');
 
   lines.push('### MONOLITHIC REFACTORING HOTSPOTS');
+  lines.push('Action: Decompose into single-responsibility crystalline molecule capsules (< 100 lines) and dedicated domain composables.\n');
   monolithHotspots.forEach((h, i) => {
     const tier = h.monolithTier ? `[${h.monolithTier} MONOLITH]` : '[MONOLITH]';
     lines.push(`${i + 1}. File: \`${h.filePath}\` (${h.lineCount} lines, ${h.violationCount} hazards) ${tier}`);
-    lines.push('   Action: Decompose into single-responsibility crystalline molecule capsules (< 100 lines) and dedicated domain composables.');
   });
   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');
 };
 
 export const buildMasterPrompt = (report) => {
   const sections = [
-    buildGradeFPrompt(report),
-    buildGradeDPrompt(report),
-    buildGradeCPrompt(report),
-    buildGradeBPrompt(report),
+    buildGradeFPrompt(report, { excludeAiSlop: true }),
+    buildGradeDPrompt(report, { excludeAiSlop: true }),
+    buildGradeCPrompt(report, { excludeAiSlop: true }),
+    buildGradeBPrompt(report, { excludeAiSlop: true }),
     buildAiSlopPrompt(report),
     buildHotspotsPrompt(report)
   ].filter(Boolean);
 
-  if (sections.length === 0) return '';
+  const hasNoSections = sections.length === 0;
+  if (hasNoSections) return '';
 
   const header = `Act as a Principal Systems Architect. Execute a phased architectural refactoring of our codebase according to Chemical X Molecular Architecture Standards.\n\n`;
   return header + sections.join('\n\n---\n\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) {

package/cli/audit/reporter-grades.js

@@ -19,7 +19,8 @@ import {
 import { getReportCardAsciiLines } from './reporter-ascii.js';
 import { renderGroupedViolationsTerminal } from './reporter-grouping.js';
 
-export const formatGradeFSection = (report) => {
+export const formatGradeFSection = (report, options = {}) => {
+  const { includePrompt = true } = options;
   const { violations, hotspots, pillars } = report;
   const { critical } = groupViolationsBySeverity(violations);
   const extremeMonoliths = hotspots.filter((h) => h.lineCount >= 2000);
@@ -67,16 +68,19 @@ export const formatGradeFSection = (report) => {
     }
   }
 
-  const promptF = buildGradeFPrompt(report);
-  if (promptF) {
-    lines.push(formatPromptBox('🤖 AI AGENT REFACTORING PROMPT (GRADE F HAZARDS)', promptF));
+  if (includePrompt) {
+    const promptF = buildGradeFPrompt(report);
+    if (promptF) {
+      lines.push(formatPromptBox('🤖 AI AGENT REFACTORING PROMPT (GRADE F HAZARDS)', promptF));
+    }
   }
 
   lines.push(`${RED}======================================================================${RESET}\n`);
   return lines.join('\n');
 };
 
-export const formatGradeDSection = (report) => {
+export const formatGradeDSection = (report, options = {}) => {
+  const { includePrompt = true } = options;
   const { violations, hotspots, pillars } = report;
   const { high } = groupViolationsBySeverity(violations);
   const severeMonoliths = hotspots.filter((h) => h.lineCount >= 1000 && h.lineCount < 2000);
@@ -123,16 +127,19 @@ export const formatGradeDSection = (report) => {
     }
   }
 
-  const promptD = buildGradeDPrompt(report);
-  if (promptD) {
-    lines.push(formatPromptBox('🤖 AI AGENT REFACTORING PROMPT (GRADE D DEBTS)', promptD));
+  if (includePrompt) {
+    const promptD = buildGradeDPrompt(report);
+    if (promptD) {
+      lines.push(formatPromptBox('🤖 AI AGENT REFACTORING PROMPT (GRADE D DEBTS)', promptD));
+    }
   }
 
   lines.push(`${ORANGE}======================================================================${RESET}\n`);
   return lines.join('\n');
 };
 
-export const formatGradeCSection = (report) => {
+export const formatGradeCSection = (report, options = {}) => {
+  const { includePrompt = true } = options;
   const { violations, hotspots } = report;
   const { medium } = groupViolationsBySeverity(violations);
   const warningMonoliths = hotspots.filter((h) => h.lineCount >= 500 && h.lineCount < 1000);
@@ -169,16 +176,19 @@ export const formatGradeCSection = (report) => {
     }
   }
 
-  const promptC = buildGradeCPrompt(report);
-  if (promptC) {
-    lines.push(formatPromptBox('🤖 AI AGENT REFACTORING PROMPT (GRADE C DEBTS)', promptC));
+  if (includePrompt) {
+    const promptC = buildGradeCPrompt(report);
+    if (promptC) {
+      lines.push(formatPromptBox('🤖 AI AGENT REFACTORING PROMPT (GRADE C DEBTS)', promptC));
+    }
   }
 
   lines.push(`${CYAN}======================================================================${RESET}\n`);
   return lines.join('\n');
 };
 
-export const formatGradeBSection = (report) => {
+export const formatGradeBSection = (report, options = {}) => {
+  const { includePrompt = true } = options;
   const { violations } = report;
   const { low } = groupViolationsBySeverity(violations);
   const lines = [];
@@ -202,9 +212,11 @@ export const formatGradeBSection = (report) => {
     lines.push(renderGroupedViolationsTerminal(low));
   }
 
-  const promptB = buildGradeBPrompt(report);
-  if (promptB) {
-    lines.push(formatPromptBox('🤖 AI AGENT REFACTORING PROMPT (GRADE B HYGIENE)', promptB));
+  if (includePrompt) {
+    const promptB = buildGradeBPrompt(report);
+    if (promptB) {
+      lines.push(formatPromptBox('🤖 AI AGENT REFACTORING PROMPT (GRADE B HYGIENE)', promptB));
+    }
   }
 
   lines.push(`${YELLOW}======================================================================${RESET}\n`);

package/cli/audit/reporter-grouping.d.ts

@@ -29,9 +29,15 @@ export interface RuleHazardSummary {
   readonly directories: readonly RuleDirectoryOccurrence[];
 }
 
+export interface PathTreeNode {
+  readonly dirs: Map<string, PathTreeNode>;
+  readonly files: Map<string, string[]>;
+}
+
 export declare function resolveDirectory(filePath?: string): string;
 export declare function groupViolationsByDirectory(violations?: readonly HazardViolation[]): readonly DirectoryHazardSummary[];
 export declare function groupViolationsByRule(violations?: readonly HazardViolation[]): readonly RuleHazardSummary[];
+export declare function buildPathTree(violations?: readonly HazardViolation[]): PathTreeNode;
 export declare function formatCompactLocations(violations: readonly HazardViolation[], maxShown?: number): string;
 export declare function renderGroupedViolationsTerminal(violations: readonly HazardViolation[]): string;
 export declare function formatDirectoryDistributionSection(report: AuditReport, themeColor?: string | null): string;

package/cli/audit/reporter-grouping.js

@@ -157,6 +157,34 @@ const resolveSeverityColor = (severity) => {
   return DIM;
 };
 
+export 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;
+};
+
 export const formatCompactLocations = (violations, maxShown = 4) => {
   const formatLocationItem = (v) => {
     const base = path.basename(v.filePath);
@@ -186,7 +214,8 @@ export const renderGroupedViolationsTerminal = (violations) => {
 
     if (isSingleOccurrence) {
       const v = rg.violations[0];
-      lines.push(`   ${sevColor}[#${idx + 1} ${rg.severity}]${RESET} [${rg.rule}] ${YELLOW}${v.filePath}:${v.line}:${v.column}${RESET}`);
+      const colStr = v.column ? `:${v.column}` : '';
+      lines.push(`   ${sevColor}[#${idx + 1} ${rg.severity}]${RESET} [${rg.rule}] ${YELLOW}${v.filePath}:${v.line}${colStr}${RESET}`);
       lines.push(`      Hazard:    ${rg.hazard}`);
       lines.push(`      Directive: ${CYAN}${rg.directive}${RESET}\n`);
       return;
@@ -199,10 +228,24 @@ export const renderGroupedViolationsTerminal = (violations) => {
     lines.push(`      Directive: ${CYAN}${rg.directive}${RESET}`);
     lines.push(`      Locations:`);
 
-    for (const d of rg.directories) {
-      const locs = formatCompactLocations(d.violations, 4);
-      lines.push(`        📁 ${d.directory} (${d.count}): ${locs}`);
-    }
+    const tree = buildPathTree(rg.violations);
+    const renderTerminalTree = (node, depth = 0) => {
+      const indent = '        ' + '  '.repeat(depth);
+
+      const sortedDirs = Array.from(node.dirs.entries()).sort((a, b) => a[0].localeCompare(b[0]));
+      for (const [dirName, childNode] of sortedDirs) {
+        lines.push(`${indent}📁 ${BOLD}${dirName}${RESET}`);
+        renderTerminalTree(childNode, depth + 1);
+      }
+
+      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}- ${YELLOW}${fileName}:${uniqueLocs}${RESET}`);
+      }
+    };
+
+    renderTerminalTree(tree, 0);
     lines.push('');
   });
 

package/cli/audit/reporter-markdown.js

@@ -4,6 +4,9 @@ import {
   resolveHealthHearts,
   resolveMarkdownStatusIcon,
   resolveMarkdownMonolithText,
+  formatPillarReactionBadgesMarkdown,
+  formatPillarShieldBadges,
+  resolveBadgeColor,
   PILLAR_EMOJIS,
   NUMBER_EMOJIS
 } from './reporter-utils.js';
@@ -11,14 +14,30 @@ import {
   formatDirectoryRollupMarkdown,
   renderGroupedViolationsMarkdown
 } from './reporter-grouping-markdown.js';
+import { formatRoadmapMarkdown } from './roadmap.js';
 
 export const generateMarkdownReport = (report) => {
   const { metrics, health, pillars, contextAnalysis, hotspots, violations, aiSlop } = report;
   const { critical, high, medium, low } = groupViolationsBySeverity(violations);
   const lines = [];
 
+  const badgeColor = resolveBadgeColor(health.score);
+  const encodedGrade = encodeURIComponent(`${health.score}/100 (${health.grade})`);
+  const slopScore = aiSlop?.score ?? 100;
+  const slopGrade = aiSlop?.grade ?? 'A+';
+  const slopLabel = aiSlop?.label ?? 'Pure Artisanal';
+  const slopBadgeColor = resolveBadgeColor(slopScore);
+  const encodedSlop = encodeURIComponent(`${slopScore}/100 (${slopGrade})`);
+
   lines.push('# Chemical X Protocol: Architectural Audit Report');
   lines.push('');
+  lines.push(`[![Chemical X Protocol](https://img.shields.io/badge/Chemical%20X-Architecture%20Audit-62c9ff?style=for-the-badge)](https://chemicalx.xophz.com) [![Chemical X MHI](https://img.shields.io/badge/Chemical%20X%20MHI-${encodedGrade}-${badgeColor}?style=for-the-badge)](https://chemicalx.xophz.com) [![AI Slop Index](https://img.shields.io/badge/AI%20Slop%20Index-${encodedSlop}-${slopBadgeColor}?style=for-the-badge)](https://chemicalx.xophz.com)`);
+  lines.push('');
+  const pillarShields = formatPillarShieldBadges(pillars);
+  if (pillarShields) {
+    lines.push(pillarShields);
+    lines.push('');
+  }
   lines.push('> *Comprehensive static analysis report enforcing Chemical X Molecular Architecture standards.*');
   lines.push('');
   lines.push('## 1. Executive Summary & Scorecard');
@@ -28,9 +47,6 @@ export const generateMarkdownReport = (report) => {
   const hearts = resolveHealthHearts(health?.grade, health?.score, false);
   lines.push(`| **Life / Health Meter** | ${hearts} (Grade **${health.grade}**) | ${health.score} / 100 (${health.label}) |`);
   lines.push(`| **Molecular Health Index** | **${health.score} / 100** | Grade: **${health.grade}** (${health.label}) |`);
-  const slopScore = aiSlop?.score ?? 100;
-  const slopGrade = aiSlop?.grade ?? 'A+';
-  const slopLabel = aiSlop?.label ?? 'Pure Artisanal';
   lines.push(`| **AI Slop Index (ASI)** | **${slopScore} / 100** | Grade: **${slopGrade}** (${slopLabel}) |`);
   lines.push(`| **Scanned Files** | ${metrics.scannedFiles} source files | Verified |`);
   lines.push(`| **Total Lines of Code** | ${metrics.totalLoc} lines of code | Avg ${metrics.avgLoc} lines/file |`);
@@ -86,19 +102,25 @@ export const generateMarkdownReport = (report) => {
     lines.push(formatDirectoryRollupMarkdown(violations));
 
     if (critical.length > 0) {
-      lines.push('### Critical Hazards (Immediate Action Required)');
+      lines.push('### Grade F: Critical Hazards & Extreme Monoliths (Immediate Action Required)');
       lines.push('');
       lines.push(renderGroupedViolationsMarkdown(critical, { showSeverity: false }));
     }
 
-    if (high.length > 0 || medium.length > 0) {
-      lines.push('### High & Medium Hazards (Architecture Debts)');
+    if (high.length > 0) {
+      lines.push('### Grade D: High Severity Debts & Severe Monoliths');
       lines.push('');
-      lines.push(renderGroupedViolationsMarkdown([...high, ...medium], { showSeverity: true }));
+      lines.push(renderGroupedViolationsMarkdown(high, { showSeverity: false }));
+    }
+
+    if (medium.length > 0) {
+      lines.push('### Grade C: Medium Severity Debts & Monolithic Drift');
+      lines.push('');
+      lines.push(renderGroupedViolationsMarkdown(medium, { showSeverity: false }));
     }
 
     if (low.length > 0) {
-      lines.push('### Low & Hygiene Issues (Typography & Logging)');
+      lines.push('### Grade B: Low Severity Hygiene & Minor Debts');
       lines.push('');
       lines.push(renderGroupedViolationsMarkdown(low, { showSeverity: false }));
     }
@@ -122,14 +144,7 @@ export const generateMarkdownReport = (report) => {
 
   lines.push('---');
   lines.push('');
-  lines.push('## 6. Remediation Roadmap');
-  lines.push('');
-  lines.push('1. **Decompose Monoliths**: Break down any file exceeding 500 lines into single-responsibility capsules.');
-  lines.push('2. **Cap Molecule Size**: Ensure all molecule components (`m-*`) remain strictly under 100 lines.');
-  lines.push('3. **Two-Stage Boolean Logic**: Replace complex multi-clause expressions with atomic boolean variables.');
-  lines.push('4. **Lifecycle-Safe Timers**: Migrate raw `setInterval` and `setTimeout` calls to self-cleaning composables.');
-  lines.push('5. **Purge AI Slop**: Remove conversational residue, eliminate echo comments, and inline single-use passthrough assignments.');
-  lines.push('');
+  lines.push(formatRoadmapMarkdown(report));
 
   const masterPrompt = buildMasterPrompt(report);
   if (masterPrompt) {