@chem-x/starter-kit 26.9.13-632 → 26.9.14-1358

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xopher Pollard / Chemical X Protocol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -30,9 +30,21 @@ starter-kit/
     └── index.js                # Interactive capsule generator
 ```
 
+## Release Versioning: Minute-Precision CalVer
+
+This package adheres to **Minute-Precision Calendar Versioning** (`YY.MM.DD-MMMM`):
+- `YY.MM.DD`: Release date (e.g. `26.9.14` for Sept 14, 2026).
+- `MMMM`: Minute of the day (0 to 1439).
+
+Because autonomous coding agent models update frequently, this package is continuously integrated and deployed via automated CI whenever new agent directives, AST checks, or framework rules are tuned. Rapid version iterations reflect active, daily alignment rather than breaking SemVer shifts.
+
+> [!NOTE]
+> Download statistics on npm reflect continuous automated test matrix verification and test runner execution across automated environments.
+
 ---
 
-## Licensing & Access
+## License
 
-Unlocked for verified GitHub Sponsors and VIP license key holders of `chemical-x-protocol`.  
-Explore activation details at [https://chemicalx.xophz.com/#starter-kit](https://chemicalx.xophz.com/#starter-kit).
+Core CLI tools and capsule generators are distributed under the **MIT License**.  
+Private production monorepos and extended starter suites are unlocked for verified GitHub Sponsors.  
+Explore sponsorship details at [https://chemicalx.xophz.com](https://chemicalx.xophz.com).

package/cli/audit/prompts.js

@@ -60,8 +60,16 @@ export const formatGroupedPromptViolations = (violations = []) => {
   return lines;
 };
 
+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.'
+].join('\n');
+
 export const buildGradeFPrompt = (report, options = {}) => {
-  const { excludeAiSlop = false } = options;
+  const { excludeAiSlop = false, isSubSection = false } = options;
   const { violations = [], hotspots = [] } = report;
   const critical = violations
     .filter((v) => v.severity === 'CRITICAL')
@@ -73,7 +81,10 @@ export const buildGradeFPrompt = (report, options = {}) => {
   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');
+  const preamble = isSubSection
+    ? 'Surgically refactor the following Grade F Critical Context Hazards in our codebase according to Chemical X Molecular Architecture Standards:\n'
+    : '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';
+  lines.push(preamble);
 
   if (extremeMonoliths.length > 0) {
     lines.push('### EXTREME MONOLITHS (>= 2,000 lines of code) : MONOLITH DECOMPOSITION');
@@ -96,12 +107,14 @@ export const buildGradeFPrompt = (report, options = {}) => {
   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.');
+  lines.push('');
+  lines.push(buildAgentCommandsSection());
 
   return lines.join('\n');
 };
 
 export const buildGradeDPrompt = (report, options = {}) => {
-  const { excludeAiSlop = false } = options;
+  const { excludeAiSlop = false, isSubSection = false } = options;
   const { violations = [], hotspots = [] } = report;
   const high = violations
     .filter((v) => v.severity === 'HIGH')
@@ -113,7 +126,10 @@ export const buildGradeDPrompt = (report, options = {}) => {
   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');
+  const preamble = isSubSection
+    ? 'Refactor the following Grade D High-Severity Architectural Debts according to Chemical X Molecular Architecture Standards:\n'
+    : 'Act as a Principal Systems Architect. Refactor the following Grade D High-Severity Architectural Debts according to Chemical X Molecular Architecture Standards:\n';
+  lines.push(preamble);
 
   if (severeMonoliths.length > 0) {
     lines.push('### SEVERE MONOLITHS (1,000 - 1,999 lines of code)');
@@ -133,12 +149,14 @@ export const buildGradeDPrompt = (report, options = {}) => {
   lines.push('1. Hook Saturation: Extract component hooks into dedicated domain composables adhering to the 3-5 property return limit (State + Status + Actions).');
   lines.push('2. Complex Control Flow: Break multi-clause conditionals into 2-stage atomic boolean variables with early-return guard clauses.');
   lines.push('3. Zero breaking changes to caller APIs or existing props.');
+  lines.push('');
+  lines.push(buildAgentCommandsSection());
 
   return lines.join('\n');
 };
 
 export const buildGradeCPrompt = (report, options = {}) => {
-  const { excludeAiSlop = false } = options;
+  const { excludeAiSlop = false, isSubSection = false } = options;
   const { violations = [], hotspots = [] } = report;
   const medium = violations
     .filter((v) => v.severity === 'MEDIUM')
@@ -150,7 +168,10 @@ export const buildGradeCPrompt = (report, options = {}) => {
   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');
+  const preamble = isSubSection
+    ? 'Refactor the following Grade C Medium-Severity Technical Debts according to Chemical X Molecular Architecture Standards:\n'
+    : 'Act as a Senior Frontend Engineer. Refactor the following Grade C Medium-Severity Technical Debts according to Chemical X Molecular Architecture Standards:\n';
+  lines.push(preamble);
 
   if (warningMonoliths.length > 0) {
     lines.push('### WARNING MONOLITHS (500 - 999 lines of code)');
@@ -170,12 +191,14 @@ export const buildGradeCPrompt = (report, options = {}) => {
   lines.push('1. Zero raw inline styles: Replace style={{...}} with atom props, SCSS mixins (@include glass), or scoped BEM classes.');
   lines.push('2. Extract anonymous inline callbacks into named functions before passing as props.');
   lines.push('3. Co-locate granular types (*.d.ts) inside feature capsules (< 100 lines of code). Avoid type monoliths.');
+  lines.push('');
+  lines.push(buildAgentCommandsSection());
 
   return lines.join('\n');
 };
 
 export const buildGradeBPrompt = (report, options = {}) => {
-  const { excludeAiSlop = false } = options;
+  const { excludeAiSlop = false, isSubSection = false } = options;
   const { violations = [] } = report;
   const low = violations
     .filter((v) => v.severity === 'LOW')
@@ -185,7 +208,10 @@ export const buildGradeBPrompt = (report, options = {}) => {
   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');
+  const preamble = isSubSection
+    ? 'Clean up the following Grade B Low-Severity Hygiene Issues according to Chemical X standards:\n'
+    : 'Act as a Clean Code Specialist. Clean up the following Grade B Low-Severity Hygiene Issues according to Chemical X standards:\n';
+  lines.push(preamble);
 
   lines.push('### LOW HYGIENE VIOLATIONS');
   lines.push(...formatGroupedPromptViolations(low));
@@ -194,11 +220,14 @@ export const buildGradeBPrompt = (report, options = {}) => {
   lines.push('1. Typography Hygiene: Replace all em dashes with standard hyphens (-) or colons (:).');
   lines.push('2. Logging Hygiene: Remove unguarded console.log calls or route through central debug proxy.');
   lines.push('3. FontAwesome Compliance: Remove text-* utility classes from icons; use :color prop or inline CSS.');
+  lines.push('');
+  lines.push(buildAgentCommandsSection());
 
   return lines.join('\n');
 };
 
-export const buildAiSlopPrompt = (report) => {
+export const buildAiSlopPrompt = (report, options = {}) => {
+  const { isSubSection = false } = options;
   const { violations = [] } = report;
   const slopViolations = violations.filter((v) => Boolean(v.isAiSlop));
 
@@ -206,10 +235,15 @@ export const buildAiSlopPrompt = (report) => {
   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');
-  lines.push(...formatGroupedPromptViolations(slopViolations));
+  const preamble = isSubSection
+    ? 'Eliminate the following AI Slop and conversational artifacts from our codebase according to Chemical X standards:\n'
+    : '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(preamble);
+
+  if (slopViolations.length > 0) {
+    lines.push('### AI SLOP & CODE AUTHENTICITY VIOLATIONS');
+    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.');
@@ -218,11 +252,14 @@ export const buildAiSlopPrompt = (report) => {
   lines.push('4. Paranoia Catch Wrappers: Replace shallow or empty catch blocks with intentional error propagation or ResultTuple ([data, error]).');
   lines.push('5. Inline Utility Reinventions: Replace reinvented inline helper utilities with shared project utilities or native methods.');
   lines.push('6. Type Widening: Eliminate lazy "any" type casts on error parameters or variables; enforce strict typing.');
+  lines.push('');
+  lines.push(buildAgentCommandsSection());
 
   return lines.join('\n');
 };
 
-export const buildHotspotsPrompt = (report) => {
+export const buildHotspotsPrompt = (report, options = {}) => {
+  const { isSubSection = false } = options;
   const { hotspots = [] } = report;
   const monolithHotspots = hotspots.filter((h) => h.isMonolith || h.lineCount > 500);
 
@@ -230,15 +267,20 @@ export const buildHotspotsPrompt = (report) => {
   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');
+  const preamble = isSubSection
+    ? 'Surgically decompose the following monolithic hotspot files according to Chemical X Molecular Architecture Standards:\n'
+    : 'Act as a Principal Systems Architect. Surgically decompose the following monolithic hotspot files according to Chemical X Molecular Architecture Standards:\n';
+  lines.push(preamble);
 
-  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('');
+  if (monolithHotspots.length > 0) {
+    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('');
+  }
 
   lines.push('### STRICT EXECUTION RULES:');
   lines.push('1. Branch First: Change to a new branch prefixed with `chem-x/NAMEOFIMPROVEMENT` before making changes, then commit the branch and create a PR to main.');
@@ -248,11 +290,14 @@ export const buildHotspotsPrompt = (report) => {
   lines.push('5. Composable Return Contracts: Custom hooks/composables must strictly limit returns to 3 to 5 properties (State + Status + Actions).');
   lines.push('6. Type Co-location: Co-locate granular types/*.d.ts files inside each feature capsule (< 100 lines per type file) instead of creating type monoliths.');
   lines.push('7. Zero breaking changes to external component APIs, route exports, or existing props.');
+  lines.push('');
+  lines.push(buildAgentCommandsSection());
 
   return lines.join('\n');
 };
 
-export const buildPillarPrompt = (report, pillarName) => {
+export const buildPillarPrompt = (report, pillarName, options = {}) => {
+  const { isSubSection = false } = options;
   const { violations = [], hotspots = [] } = report;
   const pillarViolations = violations.filter((v) => v.pillar === pillarName);
   const isPillar1 = pillarName === 'Line Budgets & Monolith Decomposition';
@@ -263,7 +308,10 @@ export const buildPillarPrompt = (report, pillarName) => {
   if (hasNoViolations && hasNoHotspots) return '';
 
   const lines = [];
-  lines.push(`Act as a Principal Systems Architect. Surgically refactor the following ${pillarName} violations according to Chemical X Molecular Architecture Standards:\n`);
+  const preamble = isSubSection
+    ? `Surgically refactor the following ${pillarName} violations according to Chemical X Molecular Architecture Standards:\n`
+    : `Act as a Principal Systems Architect. Surgically refactor the following ${pillarName} violations according to Chemical X Molecular Architecture Standards:\n`;
+  lines.push(preamble);
 
   if (relevantHotspots.length > 0) {
     lines.push('### MONOLITHIC REFACTORING HOTSPOTS');
@@ -285,25 +333,53 @@ export const buildPillarPrompt = (report, pillarName) => {
   lines.push('3. Molecular Capsule Limit: Maximum 100 lines per molecule capsule file.');
   lines.push('4. Table-of-Contents Views: Top-level page views must be 10 to 20 line declarative templates assembling components via named slots.');
   lines.push('5. Zero breaking changes to external component APIs, route exports, or existing props.');
+  lines.push('');
+  lines.push(buildAgentCommandsSection());
 
   return lines.join('\n');
 };
 
+export const deduplicateRolePreambles = (promptText, options = {}) => {
+  if (typeof promptText !== 'string' || !promptText) return '';
+  const { onlyIdentical = false } = options;
+  let firstRole = null;
+  const seenRoles = new Set();
+
+  return promptText.replace(/(^|\n\s*)Act as (?:an?|the)\s+([^.\n]+?)\.\s+(?=[A-Z])/gi, (match, prefix, role) => {
+    const normalizedRole = role.trim().toLowerCase();
+    if (!firstRole) {
+      firstRole = normalizedRole;
+      seenRoles.add(normalizedRole);
+      return match;
+    }
+
+    if (onlyIdentical) {
+      if (seenRoles.has(normalizedRole)) {
+        return prefix;
+      }
+      return match;
+    }
+
+    return prefix;
+  });
+};
+
 export const buildMasterPrompt = (report) => {
   const sections = [
-    buildGradeFPrompt(report, { excludeAiSlop: true }),
-    buildGradeDPrompt(report, { excludeAiSlop: true }),
-    buildGradeCPrompt(report, { excludeAiSlop: true }),
-    buildGradeBPrompt(report, { excludeAiSlop: true }),
-    buildAiSlopPrompt(report),
-    buildHotspotsPrompt(report)
+    buildGradeFPrompt(report, { excludeAiSlop: true, isSubSection: true }),
+    buildGradeDPrompt(report, { excludeAiSlop: true, isSubSection: true }),
+    buildGradeCPrompt(report, { excludeAiSlop: true, isSubSection: true }),
+    buildGradeBPrompt(report, { excludeAiSlop: true, isSubSection: true }),
+    buildAiSlopPrompt(report, { isSubSection: true }),
+    buildHotspotsPrompt(report, { isSubSection: true })
   ].filter(Boolean);
 
   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');
+  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';
+  const rawPrompt = header + sections.join('\n\n---\n\n');
+  return deduplicateRolePreambles(rawPrompt);
 };
 
 export const formatPromptBox = (title, promptText) => {

package/cli/audit/prompts.spec.js

@@ -0,0 +1,291 @@
+import test from 'node:test';
+import assert from 'node:assert';
+import {
+  deduplicateRolePreambles,
+  buildGradeFPrompt,
+  buildGradeDPrompt,
+  buildGradeCPrompt,
+  buildGradeBPrompt,
+  buildAiSlopPrompt,
+  buildHotspotsPrompt,
+  buildPillarPrompt,
+  buildMasterPrompt
+} from './prompts.js';
+
+test('deduplicateRolePreambles: handles invalid and empty inputs', () => {
+  assert.strictEqual(deduplicateRolePreambles(''), '');
+  assert.strictEqual(deduplicateRolePreambles(null), '');
+  assert.strictEqual(deduplicateRolePreambles(undefined), '');
+  assert.strictEqual(deduplicateRolePreambles(123), '');
+});
+
+test('deduplicateRolePreambles: leaves single role preamble untouched', () => {
+  const single = 'Act as a Principal Systems Architect. Execute a phased architectural refactoring.';
+  assert.strictEqual(deduplicateRolePreambles(single), single);
+});
+
+test('deduplicateRolePreambles: removes repeated identical role preambles', () => {
+  const input = [
+    'Act as a Principal Systems Architect. Execute a phased architectural refactoring of our codebase according to Chemical X Molecular Architecture Standards.',
+    '',
+    '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:'
+  ].join('\n');
+
+  const expected = [
+    'Act as a Principal Systems Architect. Execute a phased architectural refactoring of our codebase according to Chemical X Molecular Architecture Standards.',
+    '',
+    'Surgically refactor the following Grade F Critical Context Hazards in our codebase according to Chemical X Molecular Architecture Standards:'
+  ].join('\n');
+
+  assert.strictEqual(deduplicateRolePreambles(input), expected);
+});
+
+test('deduplicateRolePreambles: removes subsequent different role preambles by default', () => {
+  const input = [
+    'Act as a Principal Systems Architect. Execute a phased refactor.',
+    '',
+    'Act as a Senior Frontend Engineer. Refactor the following Grade C Medium-Severity Technical Debts:',
+    '',
+    'Act as a Clean Code Specialist. Clean up the following Grade B Low-Severity Hygiene Issues:'
+  ].join('\n');
+
+  const expected = [
+    'Act as a Principal Systems Architect. Execute a phased refactor.',
+    '',
+    'Refactor the following Grade C Medium-Severity Technical Debts:',
+    '',
+    'Clean up the following Grade B Low-Severity Hygiene Issues:'
+  ].join('\n');
+
+  assert.strictEqual(deduplicateRolePreambles(input), expected);
+});
+
+test('deduplicateRolePreambles: respects onlyIdentical option', () => {
+  const input = [
+    'Act as a Principal Systems Architect. Execute step 1.',
+    '',
+    'Act as a Senior Frontend Engineer. Refactor step 2.',
+    '',
+    'Act as a Principal Systems Architect. Decompose step 3.'
+  ].join('\n');
+
+  const result = deduplicateRolePreambles(input, { onlyIdentical: true });
+  assert.ok(result.includes('Act as a Principal Systems Architect. Execute step 1.'));
+  assert.ok(result.includes('Act as a Senior Frontend Engineer. Refactor step 2.'));
+  assert.ok(result.includes('\n\nDecompose step 3.'));
+  assert.ok(!result.includes('Act as a Principal Systems Architect. Decompose step 3.'));
+});
+
+test('buildGradeFPrompt: respects isSubSection option', () => {
+  const mockReport = {
+    violations: [
+      {
+        severity: 'CRITICAL',
+        pillar: 'Test Pillar',
+        message: 'Critical issue',
+        filePath: 'src/heavy.ts',
+        line: 10
+      }
+    ],
+    hotspots: []
+  };
+
+  const standalone = buildGradeFPrompt(mockReport);
+  assert.ok(standalone.startsWith('Act as a Principal Systems Architect. Surgically refactor'));
+
+  const subSection = buildGradeFPrompt(mockReport, { isSubSection: true });
+  assert.ok(subSection.startsWith('Surgically refactor'));
+  assert.ok(!subSection.includes('Act as a Principal Systems Architect.'));
+});
+
+test('buildGradeDPrompt: respects isSubSection option', () => {
+  const mockReport = {
+    violations: [
+      {
+        severity: 'HIGH',
+        pillar: 'Test Pillar',
+        message: 'High severity issue',
+        filePath: 'src/high.ts',
+        line: 20
+      }
+    ],
+    hotspots: []
+  };
+
+  const standalone = buildGradeDPrompt(mockReport);
+  assert.ok(standalone.startsWith('Act as a Principal Systems Architect. Refactor'));
+
+  const subSection = buildGradeDPrompt(mockReport, { isSubSection: true });
+  assert.ok(subSection.startsWith('Refactor'));
+  assert.ok(!subSection.includes('Act as a Principal Systems Architect.'));
+});
+
+test('buildGradeCPrompt: respects isSubSection option', () => {
+  const mockReport = {
+    violations: [
+      {
+        severity: 'MEDIUM',
+        pillar: 'Test Pillar',
+        message: 'Medium severity issue',
+        filePath: 'src/medium.ts',
+        line: 30
+      }
+    ],
+    hotspots: []
+  };
+
+  const standalone = buildGradeCPrompt(mockReport);
+  assert.ok(standalone.startsWith('Act as a Senior Frontend Engineer. Refactor'));
+
+  const subSection = buildGradeCPrompt(mockReport, { isSubSection: true });
+  assert.ok(subSection.startsWith('Refactor'));
+  assert.ok(!subSection.includes('Act as a Senior Frontend Engineer.'));
+});
+
+test('buildGradeBPrompt: respects isSubSection option', () => {
+  const mockReport = {
+    violations: [
+      {
+        severity: 'LOW',
+        pillar: 'Test Pillar',
+        message: 'Low severity issue',
+        filePath: 'src/low.ts',
+        line: 40
+      }
+    ],
+    hotspots: []
+  };
+
+  const standalone = buildGradeBPrompt(mockReport);
+  assert.ok(standalone.startsWith('Act as a Clean Code Specialist. Clean up'));
+
+  const subSection = buildGradeBPrompt(mockReport, { isSubSection: true });
+  assert.ok(subSection.startsWith('Clean up'));
+  assert.ok(!subSection.includes('Act as a Clean Code Specialist.'));
+});
+
+test('buildAiSlopPrompt: respects isSubSection option', () => {
+  const mockReport = {
+    violations: [
+      {
+        severity: 'LOW',
+        pillar: 'Code Authenticity & Anti-Slop',
+        message: 'Echo comment',
+        filePath: 'src/slop.ts',
+        line: 5,
+        isAiSlop: true
+      }
+    ],
+    hotspots: []
+  };
+
+  const standalone = buildAiSlopPrompt(mockReport);
+  assert.ok(standalone.startsWith('Act as a Clean Code Specialist and Code Authenticity Guardian. Eliminate'));
+
+  const subSection = buildAiSlopPrompt(mockReport, { isSubSection: true });
+  assert.ok(subSection.startsWith('Eliminate'));
+  assert.ok(!subSection.includes('Act as a Clean Code Specialist'));
+});
+
+test('buildHotspotsPrompt: respects isSubSection option', () => {
+  const mockReport = {
+    violations: [],
+    hotspots: [
+      {
+        filePath: 'src/monolith.ts',
+        lineCount: 1200,
+        violationCount: 10,
+        isMonolith: true,
+        monolithTier: 'SEVERE'
+      }
+    ]
+  };
+
+  const standalone = buildHotspotsPrompt(mockReport);
+  assert.ok(standalone.startsWith('Act as a Principal Systems Architect. Surgically decompose'));
+
+  const subSection = buildHotspotsPrompt(mockReport, { isSubSection: true });
+  assert.ok(subSection.startsWith('Surgically decompose'));
+  assert.ok(!subSection.includes('Act as a Principal Systems Architect.'));
+});
+
+test('buildPillarPrompt: respects isSubSection option', () => {
+  const mockReport = {
+    violations: [
+      {
+        severity: 'HIGH',
+        pillar: 'Control Flow & Self-Documenting Logic',
+        message: 'Complex conditional',
+        filePath: 'src/flow.ts',
+        line: 15
+      }
+    ],
+    hotspots: []
+  };
+
+  const standalone = buildPillarPrompt(mockReport, 'Control Flow & Self-Documenting Logic');
+  assert.ok(standalone.startsWith('Act as a Principal Systems Architect. Surgically refactor'));
+
+  const subSection = buildPillarPrompt(mockReport, 'Control Flow & Self-Documenting Logic', { isSubSection: true });
+  assert.ok(subSection.startsWith('Surgically refactor'));
+  assert.ok(!subSection.includes('Act as a Principal Systems Architect.'));
+});
+
+test('buildMasterPrompt: has single top-level role preamble and no repeated Act as persona statements', () => {
+  const mockReport = {
+    violations: [
+      {
+        severity: 'CRITICAL',
+        pillar: 'Pillar 1',
+        message: 'Critical error',
+        filePath: 'src/critical.ts',
+        line: 1
+      },
+      {
+        severity: 'HIGH',
+        pillar: 'Pillar 2',
+        message: 'High error',
+        filePath: 'src/high.ts',
+        line: 2
+      },
+      {
+        severity: 'MEDIUM',
+        pillar: 'Pillar 3',
+        message: 'Medium error',
+        filePath: 'src/medium.ts',
+        line: 3
+      },
+      {
+        severity: 'LOW',
+        pillar: 'Pillar 4',
+        message: 'Low error',
+        filePath: 'src/low.ts',
+        line: 4
+      },
+      {
+        severity: 'LOW',
+        pillar: 'Pillar 5',
+        message: 'AI slop echo',
+        filePath: 'src/slop.ts',
+        line: 5,
+        isAiSlop: true
+      }
+    ],
+    hotspots: [
+      {
+        filePath: 'src/monolith.ts',
+        lineCount: 2200,
+        violationCount: 15,
+        isMonolith: true,
+        monolithTier: 'EXTREME'
+      }
+    ]
+  };
+
+  const prompt = buildMasterPrompt(mockReport);
+  assert.ok(prompt.startsWith('Act as a Principal Systems Architect. Execute a phased architectural refactoring'));
+
+  // Ensure "Act as" occurs exactly once in the entire composite prompt
+  const matches = prompt.match(/Act as\b/g) || [];
+  assert.strictEqual(matches.length, 1, `Expected exactly 1 "Act as", found ${matches.length}`);
+});

package/cli/audit/roadmap.js

@@ -209,6 +209,12 @@ export const buildSelfHealingRoadmapPrompt = (report) => {
   lines.push('3. Commit the branch with atomic, intention-revealing commit messages.');
   lines.push('4. Create a Pull Request (PR) to `main` upon completing the remediation phases.\n');
 
+  lines.push('### AI AGENT DISCOVERY & REFACTORING COMMANDS:');
+  lines.push('- Discovery & Inspect: Run `pnpm q "<target>" --inspect` (or `npx chemx search "<target>" --inspect`) to inspect component props and hooks before editing.');
+  lines.push('- Tier Filter: Run `pnpm q "<query>" --tier=molecule` (or `atom`, `organism`, `hook`) to find related capsules.');
+  lines.push('- Zero-Overhead JSON: Run `pnpm q "<query>" --json` for minified AST metadata without burning context tokens on whole files.');
+  lines.push('- Re-Verify Score: Run `npx chemx audit` after completing each phase to verify health score improvements.\n');
+
   phases.forEach((p) => {
     lines.push(`### STEP ${p.step}: ${p.phase}`);
     lines.push(`Goal: ${p.rationale}\n`);
@@ -219,6 +225,10 @@ export const buildSelfHealingRoadmapPrompt = (report) => {
       if (item.locations.length > 0) {
         lines.push(`   Files: ${item.locations.join(', ')}`);
       }
+      const rawTarget = item.target.split(' ')[0].replace(/->.*/, '').trim();
+      if (rawTarget && !rawTarget.includes('*')) {
+        lines.push(`   Command: pnpm q "${rawTarget}" --inspect`);
+      }
     });
     lines.push('');
   });