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

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) {

package/cli/audit/reporter-sections.js

@@ -13,7 +13,9 @@ import {
   resolveHealthHearts,
   resolveRiskColor,
   resolveHotspotBadge,
-  resolveTopSectionColor
+  resolveTopSectionColor,
+  PILLAR_EMOJIS,
+  formatPillarReactionBadgesTerminal
 } from './reporter-utils.js';
 import { getAsciiGradeLines, getReportCardAsciiLines } from './reporter-ascii.js';
 import { renderGroupedViolationsTerminal } from './reporter-grouping.js';
@@ -153,10 +155,18 @@ export const formatPillarsSection = (report, themeColor = null) => {
   lines.push(`${sectionColor}======================================================================${RESET}`);
   lines.push(`${BOLD}${sectionColor}   7-PILLAR ARCHITECTURAL COMPLIANCE MATRIX${RESET}`);
   lines.push(`${sectionColor}======================================================================${RESET}`);
-  lines.push(`   ${DIM}Pillar Name                                   Status     Violations${RESET}`);
-  lines.push(`   ${DIM}------------------------------------------------------------------${RESET}`);
+
+  const reactionStrip = formatPillarReactionBadgesTerminal(pillars);
+  if (reactionStrip) {
+    lines.push(`   ${BOLD}Reaction Badges:${RESET} ${reactionStrip}`);
+    lines.push(`${sectionColor}----------------------------------------------------------------------${RESET}`);
+  }
+
+  lines.push(`   ${DIM}Pillar Name                                         Status     Violations${RESET}`);
+  lines.push(`   ${DIM}------------------------------------------------------------------------${RESET}`);
   for (const [pillarName, data] of Object.entries(pillars)) {
-    const padName = pillarName.padEnd(45, ' ');
+    const icon = PILLAR_EMOJIS[pillarName] || '🏛️';
+    const padName = `[ ${icon} ] ${pillarName}`.padEnd(51, ' ');
     const badge = getStatusBadge(data.status).padEnd(16, ' ');
     const countStr = data.violations === 0 ? `${GREEN}0${RESET}` : `${RED}${data.violations}${RESET}`;
     lines.push(`   ${padName} ${badge} ${countStr}`);

package/cli/audit/reporter-utils.js

@@ -129,6 +129,49 @@ export const PILLAR_EMOJIS = {
   'Naming Conventions': '🏷️'
 };
 
+export const PILLAR_SHORT_NAMES = {
+  'Line Budgets & Monolith Decomposition': 'Monoliths',
+  'Control Flow & Boolean Logic': 'Logic',
+  'Reactivity & Composable Contracts': 'Reactivity',
+  'Type Architecture & Data Integrity': 'Types',
+  'Design System & Styling Hygiene': 'Styling',
+  'Timers & Macro-Task Discipline': 'Timers',
+  'Global Hygiene & Typography': 'Hygiene',
+  'Accessibility & Semantic Integrity': 'A11y',
+  'Security & Content Safety': 'Security',
+  'Testing Discipline': 'Testing',
+  'Naming Conventions': 'Naming'
+};
+
+export const resolveBadgeColor = (score) => {
+  if (score >= 90) return '06b6d4';
+  if (score >= 70) return 'f59e0b';
+  return 'ef4444';
+};
+
+export const formatPillarShieldBadges = (pillars = {}) => {
+  const badges = [];
+  for (const [pillarName, data] of Object.entries(pillars)) {
+    const icon = PILLAR_EMOJIS[pillarName] || '🏛️';
+    const shortName = PILLAR_SHORT_NAMES[pillarName] || pillarName.split(' ')[0];
+    const rawLabel = `${icon} ${shortName}`.replace(/-/g, '--').replace(/ /g, '_');
+    const label = encodeURIComponent(rawLabel);
+    let statusText = 'PASS';
+    let color = '06b6d4';
+    if (data?.status === 'WARN') {
+      const v = data?.violations || 0;
+      statusText = encodeURIComponent(`WARN ${v}`.replace(/-/g, '--').replace(/ /g, '_'));
+      color = 'f59e0b';
+    } else if (data?.status === 'FAILED') {
+      const v = data?.violations || 0;
+      statusText = encodeURIComponent(`FAIL ${v}`.replace(/-/g, '--').replace(/ /g, '_'));
+      color = 'ef4444';
+    }
+    badges.push(`[![${shortName}](https://img.shields.io/badge/${label}-${statusText}-${color}?style=for-the-badge)](https://chemicalx.xophz.com)`);
+  }
+  return badges.join(' ');
+};
+
 export const NUMBER_EMOJIS = ['1️⃣', '2️⃣', '3️⃣', '4️⃣', '5️⃣', '6️⃣', '7️⃣', '8️⃣', '9️⃣', '🔟'];
 
 export const resolvePriorityBadge = (idx) => {
@@ -147,3 +190,35 @@ export const resolveMarkdownMonolithText = (lineCount) => {
   if (lineCount > 500) return '🟡 **WARNING (> 500 lines of code)**';
   return '🟢 Compliant';
 };
+
+export const formatPillarReactionBadgesTerminal = (pillars = {}) => {
+  const badges = [];
+  for (const [pillarName, data] of Object.entries(pillars)) {
+    const icon = PILLAR_EMOJIS[pillarName] || '🏛️';
+    const violations = data?.violations || 0;
+    if (data?.status === 'PASSED') {
+      badges.push(`${GREEN}[ ${icon} PASS ]${RESET}`);
+    } else if (data?.status === 'WARN') {
+      badges.push(`${YELLOW}[ ${icon} WARN (${violations}) ]${RESET}`);
+    } else {
+      badges.push(`${RED}[ ${icon} FAIL (${violations}) ]${RESET}`);
+    }
+  }
+  return badges.join(' ');
+};
+
+export const formatPillarReactionBadgesMarkdown = (pillars = {}) => {
+  const badges = [];
+  for (const [pillarName, data] of Object.entries(pillars)) {
+    const icon = PILLAR_EMOJIS[pillarName] || '🏛️';
+    const violations = data?.violations || 0;
+    if (data?.status === 'PASSED') {
+      badges.push(`\`[ ${icon} PASS ]\``);
+    } else if (data?.status === 'WARN') {
+      badges.push(`\`[ ${icon} WARN: ${violations} ]\``);
+    } else {
+      badges.push(`\`[ ${icon} FAIL: ${violations} ]\``);
+    }
+  }
+  return badges.join(' ');
+};

package/cli/audit/reporter.d.ts

@@ -6,11 +6,20 @@ export * from './reporter-sections';
 export * from './reporter-summary';
 export * from './reporter-grouping';
 
+export interface FormatGradeOptions {
+  readonly includePrompt?: boolean;
+}
+
 export declare function formatTerminalReport(report: AuditReport): string;
 export declare function generateMarkdownReport(report: AuditReport): string;
 export declare function resolveTopSectionColor(report: AuditReport): string;
-export declare function formatGradeFSection(report: AuditReport): string;
-export declare function formatGradeDSection(report: AuditReport): string;
-export declare function formatGradeCSection(report: AuditReport): string;
-export declare function formatGradeBSection(report: AuditReport): string;
+export declare function formatGradeFSection(report: AuditReport, options?: FormatGradeOptions): string;
+export declare function formatGradeDSection(report: AuditReport, options?: FormatGradeOptions): string;
+export declare function formatGradeCSection(report: AuditReport, options?: FormatGradeOptions): string;
+export declare function formatGradeBSection(report: AuditReport, options?: FormatGradeOptions): string;
 export declare function formatGradeASection(report: AuditReport): string;
+export declare function formatPillarReactionBadgesTerminal(pillars?: Record<string, unknown>): string;
+export declare function formatPillarReactionBadgesMarkdown(pillars?: Record<string, unknown>): string;
+export declare const PILLAR_SHORT_NAMES: Record<string, string>;
+export declare function resolveBadgeColor(score: number): string;
+export declare function formatPillarShieldBadges(pillars?: Record<string, unknown>): string;

package/cli/audit/reporter.js

@@ -20,6 +20,24 @@ import {
   formatContextAnalysisSection,
   formatAiSlopSection
 } from './reporter-sections.js';
+import {
+  formatRoadmapSection,
+  formatRoadmapMarkdown,
+  buildSelfHealingRoadmapPrompt
+} from './roadmap.js';
+import {
+  formatGradeASection,
+  formatGradeBSection,
+  formatGradeCSection,
+  formatGradeDSection,
+  formatGradeFSection
+} from './reporter-grades.js';
+
+export {
+  formatRoadmapSection,
+  formatRoadmapMarkdown,
+  buildSelfHealingRoadmapPrompt
+};
 
 export {
   groupViolationsBySeverity,
@@ -32,7 +50,12 @@ export {
   resolveTopSectionColor,
   resolveMarkdownStatusIcon,
   resolveMarkdownMonolithText,
+  formatPillarReactionBadgesTerminal,
+  formatPillarReactionBadgesMarkdown,
+  formatPillarShieldBadges,
+  resolveBadgeColor,
   PILLAR_EMOJIS,
+  PILLAR_SHORT_NAMES,
   NUMBER_EMOJIS,
   resolvePriorityBadge,
   CYAN,
@@ -112,9 +135,12 @@ export const formatTerminalReport = (report) => {
   lines.push(formatHotspotsSection(report, topColor, { includePrompt: false }));
   lines.push(formatDirectoryDistributionSection(report, topColor));
   lines.push(formatAiSlopSection(report, topColor, { includePrompt: false }));
-  lines.push(formatCriticalSection(report));
-  lines.push(formatHighMediumSection(report));
-  lines.push(formatLowSection(report));
+  lines.push(formatRoadmapSection(report, topColor));
+  lines.push(formatGradeASection(report));
+  lines.push(formatGradeBSection(report, { includePrompt: false }));
+  lines.push(formatGradeCSection(report, { includePrompt: false }));
+  lines.push(formatGradeDSection(report, { includePrompt: false }));
+  lines.push(formatGradeFSection(report, { includePrompt: false }));
 
   const masterPrompt = buildMasterPrompt(report);
   if (masterPrompt) {

package/cli/audit/roadmap.js

@@ -0,0 +1,236 @@
+/**
+ * Chemical X Protocol: Self-Healing Remediation Roadmap
+ * Calculates and formats the optimal sequence of architectural fixes.
+ */
+
+import {
+  CYAN,
+  GREEN,
+  YELLOW,
+  RED,
+  ORANGE,
+  DIM,
+  BOLD,
+  RESET,
+  resolveTopSectionColor,
+  groupViolationsBySeverity
+} from './reporter-utils.js';
+
+export const buildRemediationRoadmap = (report) => {
+  const { hotspots = [], violations = [], patterns = [] } = report;
+  const { critical, high, medium, low } = groupViolationsBySeverity(violations);
+
+  const extremeMonoliths = hotspots.filter((h) => h.lineCount >= 2000);
+  const severeMonoliths = hotspots.filter((h) => h.lineCount >= 1000 && h.lineCount < 2000);
+  const warningMonoliths = hotspots.filter((h) => h.lineCount >= 500 && h.lineCount < 1000);
+
+  const phases = [];
+
+  // Phase 1: Pattern Recognition & Canonical Harvesting
+  phases.push({
+    step: 1,
+    phase: 'PHASE 1: PATTERN HARVESTING & CANONICAL EXTRACTION',
+    roi: 'MAXIMUM (Compounding Reuse)',
+    rationale: 'Extract reusable UI structures and shared domain types before slicing monoliths to eliminate redundant bespoke code.',
+    items: patterns.length > 0
+      ? patterns.map((p) => ({
+          title: p.label,
+          target: p.suggestedCapsule,
+          action: p.recommendation,
+          locations: p.occurrences.slice(0, 3).map((o) => `${o.filePath}:${o.line}`)
+        }))
+      : [
+          {
+            title: 'Cross-Monolith Pattern Survey',
+            target: 'src/components/molecules/',
+            action: 'Audit shared card layouts, common status unions, and repeated filter predicates across candidate files before code splitting.',
+            locations: []
+          }
+        ]
+  });
+
+  // Phase 2: Domain Foundations & Type Architecture
+  const typeViolations = violations.filter((v) => v.rule === 'TYPE_MONOLITH' || v.pillar?.includes('Pillar 4'));
+  phases.push({
+    step: 2,
+    phase: 'PHASE 2: DOMAIN FOUNDATIONS & TYPE INTEGRITY',
+    roi: 'HIGH (Compile-Time Guardrails)',
+    rationale: 'Co-locate granular types/*.d.ts capsules to provide strict discriminated unions for decomposing components.',
+    items: typeViolations.length > 0
+      ? typeViolations.slice(0, 5).map((v) => ({
+          title: v.hazard,
+          target: `${v.filePath} -> types/*.d.ts`,
+          action: v.directive,
+          locations: [`${v.filePath}:${v.line}`]
+        }))
+      : [
+          {
+            title: 'Domain Type Co-location',
+            target: 'types/*.d.ts',
+            action: 'Ensure molecule capsules own co-located type declarations (< 100 lines each) with zero root type dumping.',
+            locations: []
+          }
+        ]
+  });
+
+  // Phase 3: Monolith Decomposition (Grade F & D)
+  const topMonoliths = [...extremeMonoliths, ...severeMonoliths, ...warningMonoliths].slice(0, 6);
+  phases.push({
+    step: 3,
+    phase: 'PHASE 3: MONOLITH DECOMPOSITION (HOTSPOTS)',
+    roi: 'VERY HIGH (Context Window Unlocking)',
+    rationale: 'Decompose giant views into 10-20 line Table-of-Contents templates by importing canonical capsules harvested in Phase 1.',
+    items: topMonoliths.map((m) => ({
+      title: `${m.filePath} (${m.lineCount} lines, ${m.violationCount} hazards)`,
+      target: m.filePath,
+      action: 'Decompose into crystalline single-responsibility capsules (< 100 lines per molecule) reusing Phase 1 components.',
+      locations: [`${m.filePath}:1`]
+    }))
+  });
+
+  // Phase 4: Component Hygiene & Polish (Grade C & B)
+  phases.push({
+    step: 4,
+    phase: 'PHASE 4: COMPONENT HYGIENE & DESIGN SYSTEM POLISH',
+    roi: 'MEDIUM (Visual & Syntax Standardization)',
+    rationale: 'Clean up inline styles into mixins (@include glass), two-stage booleans, typography, and logging on the newly lean capsules.',
+    items: [
+      {
+        title: `Medium Severity Debts (${medium.length} items)`,
+        target: 'Component stylesheets & logic',
+        action: 'Replace raw inline styles with atom props or SCSS mixins (@include glass); extract anonymous callbacks into named handlers.',
+        locations: []
+      },
+      {
+        title: `Hygiene & Typography Debts (${low.length} items)`,
+        target: 'Copy, comments & logs',
+        action: 'Eliminate em dashes (use hyphens or colons), route console logs through debug proxy, and ensure FontAwesome SVG compliance.',
+        locations: []
+      }
+    ]
+  });
+
+  // Phase 5: Verification & Gatekeeping
+  phases.push({
+    step: 5,
+    phase: 'PHASE 5: AUTOMATED GATEKEEPING & CI ENFORCEMENT',
+    roi: 'PERMANENT (Zero-Entropy Protection)',
+    rationale: 'Verify the newly refactored codebase passes with Grade A / Score >= 90 and install pre-commit guardrails.',
+    items: [
+      {
+        title: 'Run Architectural Re-Audit',
+        target: 'chemx audit',
+        action: 'Execute npx chemx audit --strict to confirm zero monolith hazards remain.',
+        locations: []
+      },
+      {
+        title: 'Install Pre-Commit & CI Gatekeepers',
+        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: []
+      }
+    ]
+  });
+
+  return phases;
+};
+
+export const formatRoadmapSection = (report, themeColor = null) => {
+  const sectionColor = themeColor || resolveTopSectionColor(report);
+  const phases = buildRemediationRoadmap(report);
+  const lines = [];
+
+  lines.push('');
+  lines.push(`${sectionColor}======================================================================${RESET}`);
+  lines.push(`${BOLD}${sectionColor}   SELF-HEALING REMEDIATION ROADMAP (OPTIMAL FIX SEQUENCE)${RESET}`);
+  lines.push(`${DIM}   Fix in this sequence to harvest patterns first and compound code reuse${RESET}`);
+  lines.push(`${sectionColor}======================================================================${RESET}`);
+
+  phases.forEach((p) => {
+    lines.push(`\n   ${CYAN}${BOLD}[STEP ${p.step}] ${p.phase}${RESET}`);
+    lines.push(`   ${DIM}ROI: ${p.roi}${RESET}`);
+    lines.push(`   ${YELLOW}Strategy: ${p.rationale}${RESET}`);
+
+    p.items.forEach((item, idx) => {
+      lines.push(`     ${idx + 1}. ${BOLD}${item.title}${RESET}`);
+      lines.push(`        Target: ${CYAN}${item.target}${RESET}`);
+      lines.push(`        Action: ${item.action}`);
+      if (item.locations.length > 0) {
+        lines.push(`        Locations: ${DIM}${item.locations.join(', ')}${RESET}`);
+      }
+    });
+  });
+
+  lines.push(`\n${sectionColor}======================================================================${RESET}\n`);
+  return lines.join('\n');
+};
+
+export const formatRoadmapMarkdown = (report) => {
+  const phases = buildRemediationRoadmap(report);
+  const lines = [];
+
+  lines.push('## 🗺 Recommended Remediation Sequence (Self-Healing Roadmap)\n');
+  lines.push('> Follow this sequence strictly: harvesting patterns first creates reusable building blocks that eliminate duplicate work during subsequent monolith slicing.\n');
+
+  phases.forEach((p) => {
+    lines.push(`### Step ${p.step}: ${p.phase}`);
+    lines.push(`**ROI**: ${p.roi} | **Strategy**: ${p.rationale}\n`);
+
+    p.items.forEach((item) => {
+      lines.push(`- [ ] **${item.title}**`);
+      lines.push(`  - **Target**: \`${item.target}\``);
+      lines.push(`  - **Action**: ${item.action}`);
+      if (item.locations.length > 0) {
+        lines.push(`  - **Locations**: \`${item.locations.join('`, `')}\``);
+      }
+    });
+    lines.push('');
+  });
+
+  return lines.join('\n');
+};
+
+export const buildSelfHealingRoadmapPrompt = (report) => {
+  const phases = buildRemediationRoadmap(report);
+  const lines = [];
+
+  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');
+
+  phases.forEach((p) => {
+    lines.push(`### STEP ${p.step}: ${p.phase}`);
+    lines.push(`Goal: ${p.rationale}\n`);
+    p.items.forEach((item, idx) => {
+      lines.push(`${idx + 1}. Task: ${item.title}`);
+      lines.push(`   Target: ${item.target}`);
+      lines.push(`   Execution: ${item.action}`);
+      if (item.locations.length > 0) {
+        lines.push(`   Files: ${item.locations.join(', ')}`);
+      }
+    });
+    lines.push('');
+  });
+
+  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.');
+
+  return lines.join('\n');
+};

package/cli/audit/rules-predicates.d.ts

@@ -0,0 +1,17 @@
+import type * as babelTypes from '@babel/types';
+
+export declare function isComponentPath(path: string): boolean;
+export declare function isCodeLine(line: string): boolean;
+export declare function isConsoleCallStatement(stmt: unknown, t: typeof babelTypes): boolean;
+export declare function isShallowCatchBody(body: readonly unknown[], t: typeof babelTypes): boolean;
+export declare function hasAnyTypeAnnotation(param: unknown, t: typeof babelTypes): boolean;
+export declare function isRedundantPassthroughReturn(curr: unknown, next: unknown, t: typeof babelTypes): boolean;
+export declare function isHookIdentifier(idNode: unknown): boolean;
+export declare function isCustomHookFunction(astPath: unknown): boolean;
+export declare function resolveStartLine(primaryNode?: unknown, fallbackNode?: unknown, defaultLine?: number): number;
+export declare function isZeroDelayTimeout(callee: unknown, delayArg: unknown, t: typeof babelTypes): boolean;
+export declare function isUnguardedConsoleCall(callee: unknown, t: typeof babelTypes): boolean;
+export declare function matchesDiscussionTitle(titleLower: string, targetLower: string): boolean;
+export declare function isGradeBelowMinimum(currentGrade: string, minGrade?: string | null): boolean;
+export declare function evaluateAuditFailure(conditions?: readonly boolean[]): boolean;
+export declare function isNonInteractiveSession(rawArgs: readonly string[], env?: Record<string, string | undefined>): boolean;

package/cli/audit/rules-predicates.js

@@ -0,0 +1,107 @@
+/**
+ * Chemical X Protocol: Canonical Predicates for AST & CLI Control Flow
+ * Reusable single-concept booleans and higher-order predicate helpers.
+ */
+
+const COMPONENT_PATH_SEGMENTS = ['molecules', 'components', '/m-', '/views/', '/pages/'];
+const CONSOLE_LOG_METHODS = ['log', 'info', 'warn'];
+const NON_INTERACTIVE_FLAGS = ['--non-interactive', '--no-interactive', '--ci'];
+const GRADE_RANKS = { 'A+': 5, 'A': 4, 'B': 3, 'C': 2, 'D': 1, 'F': 0 };
+
+export const isComponentPath = (path) => {
+  return COMPONENT_PATH_SEGMENTS.some((segment) => path.includes(segment));
+};
+
+export const isCodeLine = (line) => {
+  if (!line) return false;
+  const isLineComment = line.startsWith('//');
+  const isBlockComment = line.startsWith('/*');
+  return !isLineComment && !isBlockComment;
+};
+
+export const isConsoleCallStatement = (stmt, t) => {
+  if (!t.isExpressionStatement(stmt)) return false;
+  const expr = stmt.expression;
+  if (!t.isCallExpression(expr)) return false;
+  const callee = expr.callee;
+  if (!t.isMemberExpression(callee)) return false;
+  return t.isIdentifier(callee.object, { name: 'console' });
+};
+
+export const isShallowCatchBody = (body, t) => {
+  if (body.length === 0) return true;
+  if (body.length === 1) return isConsoleCallStatement(body[0], t);
+  return false;
+};
+
+export const hasAnyTypeAnnotation = (param, t) => {
+  if (!param || !t.isIdentifier(param)) return false;
+  const typeAnn = param.typeAnnotation;
+  if (!typeAnn || !t.isTSTypeAnnotation(typeAnn)) return false;
+  return t.isTSAnyKeyword(typeAnn.typeAnnotation);
+};
+
+export const isRedundantPassthroughReturn = (curr, next, t) => {
+  if (!t.isVariableDeclaration(curr) || curr.declarations.length !== 1) return false;
+  const decl = curr.declarations[0];
+  if (!t.isIdentifier(decl.id)) return false;
+  if (!t.isReturnStatement(next) || !t.isIdentifier(next.argument)) return false;
+  return decl.id.name === next.argument.name;
+};
+
+export const isHookIdentifier = (idNode) => {
+  return Boolean(idNode?.name && /^use[A-Z0-9]/.test(idNode.name));
+};
+
+export const isCustomHookFunction = (astPath) => {
+  const hasHookId = isHookIdentifier(astPath.node.id);
+  const hasParentHookId = isHookIdentifier(astPath.parentPath?.node?.id);
+  return hasHookId || hasParentHookId;
+};
+
+export const resolveStartLine = (primaryNode, fallbackNode, defaultLine = 1) => {
+  return primaryNode?.loc?.start?.line ?? fallbackNode?.loc?.start?.line ?? defaultLine;
+};
+
+export const isZeroDelayTimeout = (callee, delayArg, t) => {
+  const isTimeoutId = t.isIdentifier(callee, { name: 'setTimeout' });
+  const isZeroNumeric = t.isNumericLiteral(delayArg) && delayArg.value === 0;
+  return isTimeoutId && isZeroNumeric;
+};
+
+export const isUnguardedConsoleCall = (callee, t) => {
+  if (!t.isMemberExpression(callee)) return false;
+  if (!t.isIdentifier(callee.object, { name: 'console' })) return false;
+  if (!t.isIdentifier(callee.property)) return false;
+  return CONSOLE_LOG_METHODS.includes(callee.property.name);
+};
+
+export const matchesDiscussionTitle = (titleLower, targetLower) => {
+  const patterns = [
+    ` ${targetLower} :`,
+    ` ${targetLower} [`,
+    `: ${targetLower}`,
+    `${targetLower} audit`
+  ];
+  return patterns.some((p) => titleLower.includes(p));
+};
+
+export const isGradeBelowMinimum = (currentGrade, minGrade) => {
+  if (!minGrade) return false;
+  const currentRank = GRADE_RANKS[currentGrade];
+  const minRank = GRADE_RANKS[minGrade];
+  const hasValidRanks = currentRank !== undefined && minRank !== undefined;
+  return hasValidRanks && currentRank < minRank;
+};
+
+export const evaluateAuditFailure = (conditions = []) => {
+  return conditions.some(Boolean);
+};
+
+export const isNonInteractiveSession = (rawArgs, env = process.env) => {
+  const hasCliFlag = NON_INTERACTIVE_FLAGS.some((flag) => rawArgs.includes(flag));
+  const hasOutputFlag = rawArgs.some((arg) => arg.startsWith('--output=') || arg.startsWith('-o='));
+  const hasFormatFlag = rawArgs.includes('--markdown') || rawArgs.includes('--md') || rawArgs.includes('--json');
+  const hasCiEnv = Boolean(env.CI || env.GIT_DIR);
+  return hasCliFlag || hasOutputFlag || hasFormatFlag || hasCiEnv;
+};