@chemx/starter-kit 26.9.14-1358 → 26.9.16-1249

package/cli/audit/autofix.js

@@ -0,0 +1,176 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const IGNORED_DIRS = new Set([
+  'node_modules',
+  'dist',
+  'build',
+  'vendor',
+  '.git',
+  '.next',
+  '.turbo',
+  '.cache'
+]);
+
+const FIXABLE_EXTENSIONS = new Set(['.tsx', '.ts', '.jsx', '.js', '.vue', '.md', '.scss', '.css']);
+
+const RESIDUE_PATTERNS = [
+  ['hope this', 'helps'].join(' '),
+  ['feel free', 'to tweak'].join(' '),
+  ['let me know', 'if you need'].join(' '),
+  ['as an ai', 'language model'].join(' ')
+];
+
+const RESIDUE_REGEX = new RegExp(`\\b(?:${RESIDUE_PATTERNS.join('|')})\\b`, 'i');
+const PREAMBLE_REGEX = /\b(?:here(?:'s| is) the (?:complete|updated|refactored|full) (?:code|implementation|file|component|version))\b/i;
+const TRUNCATION_REGEX = /^\s*\/\/\s*\.\.\.\s*(?:existing|rest of|remaining)\s+(?:code|implementation|logic|imports)/i;
+const MARKDOWN_FENCE_REGEX = /^\s*```(?:typescript|javascript|tsx|jsx|vue|js|ts|html|css|scss)?\s*$/;
+
+export const autofixContent = (content, options = {}) => {
+  const allowedRules = options.rules ? new Set(options.rules) : null;
+  const shouldFix = (rule) => !allowedRules || allowedRules.has(rule);
+
+  const lines = content.split('\n');
+  const fixes = [];
+  const resultLines = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    let line = lines[i];
+    const lineNumber = i + 1;
+    let shouldDropLine = false;
+
+    // 1. Leaked markdown fence removal
+    if (shouldFix('AI_SLOP_CONVERSATIONAL_ARTIFACT') && MARKDOWN_FENCE_REGEX.test(line)) {
+      fixes.push({
+        line: lineNumber,
+        rule: 'AI_SLOP_CONVERSATIONAL_ARTIFACT',
+        action: 'Removed leaked markdown code fence'
+      });
+      shouldDropLine = true;
+    }
+
+    // 2. Pure conversational preamble or residue comment removal
+    if (!shouldDropLine && shouldFix('AI_SLOP_CONVERSATIONAL_ARTIFACT')) {
+      const isComment = /^\s*(?:\/\/|\/\*|<!--)/.test(line);
+      if (isComment && (PREAMBLE_REGEX.test(line) || RESIDUE_REGEX.test(line))) {
+        fixes.push({
+          line: lineNumber,
+          rule: 'AI_SLOP_CONVERSATIONAL_ARTIFACT',
+          action: 'Removed AI conversational residue comment'
+        });
+        shouldDropLine = true;
+      }
+    }
+
+    // 3. AI lazy placeholder comment removal
+    if (!shouldDropLine && shouldFix('AI_SLOP_LAZY_PLACEHOLDER') && TRUNCATION_REGEX.test(line)) {
+      fixes.push({
+        line: lineNumber,
+        rule: 'AI_SLOP_LAZY_PLACEHOLDER',
+        action: 'Removed lazy AI truncation placeholder comment'
+      });
+      shouldDropLine = true;
+    }
+
+    if (!shouldDropLine && shouldFix('TYPOGRAPHY_EM_DASH') && line.includes('\u2014')) {
+      line = line.replace(/\u2014/g, '-');
+      fixes.push({
+        line: lineNumber,
+        rule: 'TYPOGRAPHY_EM_DASH',
+        action: 'Replaced em dash with standard hyphen'
+      });
+    }
+
+    if (!shouldDropLine) {
+      resultLines.push(line);
+    }
+  }
+
+  return {
+    fixedContent: resultLines.join('\n'),
+    fixes
+  };
+};
+
+const collectFiles = (targetPath, baseDir) => {
+  const stat = fs.statSync(targetPath);
+  if (stat.isFile()) {
+    return [targetPath];
+  }
+
+  let files = [];
+  const entries = fs.readdirSync(targetPath, { withFileTypes: true });
+  for (const entry of entries) {
+    if (IGNORED_DIRS.has(entry.name)) continue;
+    const fullPath = path.join(targetPath, entry.name);
+    if (entry.isDirectory()) {
+      files = files.concat(collectFiles(fullPath, baseDir));
+    } else if (FIXABLE_EXTENSIONS.has(path.extname(entry.name))) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+};
+
+export const runAutofix = (targetPath, options = {}) => {
+  const cwd = options.cwd || process.cwd();
+  const resolvedTarget = path.resolve(cwd, targetPath || 'src');
+  const dryRun = Boolean(options.dryRun);
+
+  if (!fs.existsSync(resolvedTarget)) {
+    return {
+      target: targetPath || 'src',
+      dryRun,
+      filesScanned: 0,
+      filesChanged: 0,
+      totalFixes: 0,
+      fixes: []
+    };
+  }
+
+  const files = collectFiles(resolvedTarget, cwd);
+  const allFixes = [];
+  let filesChanged = 0;
+
+  for (const filePath of files) {
+    const relPath = path.relative(cwd, filePath);
+    const originalContent = fs.readFileSync(filePath, 'utf-8');
+    const { fixedContent, fixes } = autofixContent(originalContent, options);
+
+    if (fixes.length > 0) {
+      filesChanged += 1;
+      for (const fix of fixes) {
+        allFixes.push({
+          file: relPath,
+          line: fix.line,
+          rule: fix.rule,
+          action: fix.action
+        });
+      }
+
+      if (!dryRun) {
+        fs.writeFileSync(filePath, fixedContent, 'utf-8');
+      }
+    }
+  }
+
+  // Token optimization: cap fixes list to top 15 samples if very large
+  const MAX_REPORTED_FIXES = 15;
+  const isCapped = allFixes.length > MAX_REPORTED_FIXES;
+  const reportedFixes = isCapped ? allFixes.slice(0, MAX_REPORTED_FIXES) : allFixes;
+
+  const result = {
+    target: targetPath || 'src',
+    dryRun,
+    filesScanned: files.length,
+    filesChanged,
+    totalFixes: allFixes.length,
+    fixes: reportedFixes
+  };
+
+  if (isCapped) {
+    result.omittedFixesCount = allFixes.length - MAX_REPORTED_FIXES;
+  }
+
+  return result;
+};

package/cli/audit/autofix.spec.js

@@ -0,0 +1,85 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { autofixContent, runAutofix } from './autofix.js';
+
+test('autofixContent: replaces em dash with standard hyphen', () => {
+  const input = 'const title = "Welcome — User Dashboard";\n// Notes — see section 3';
+  const { fixedContent, fixes } = autofixContent(input);
+
+  assert.equal(fixes.length, 2);
+  assert.equal(fixes[0].rule, 'TYPOGRAPHY_EM_DASH');
+  assert.equal(fixedContent, 'const title = "Welcome - User Dashboard";\n// Notes - see section 3');
+});
+
+test('autofixContent: removes leaked markdown code fences', () => {
+  const input = '```typescript\nimport { ref } from "vue";\n```';
+  const { fixedContent, fixes } = autofixContent(input);
+
+  assert.equal(fixes.length, 2);
+  assert.equal(fixes[0].rule, 'AI_SLOP_CONVERSATIONAL_ARTIFACT');
+  assert.equal(fixes[1].rule, 'AI_SLOP_CONVERSATIONAL_ARTIFACT');
+  assert.equal(fixedContent, 'import { ref } from "vue";');
+});
+
+test('autofixContent: removes conversational residue comments and preambles', () => {
+  const input = [
+    '// Here is the complete code:',
+    'export const add = (a, b) => a + b;',
+    '// Hope this helps! Feel free to tweak as needed.'
+  ].join('\n');
+
+  const { fixedContent, fixes } = autofixContent(input);
+  assert.equal(fixes.length, 2);
+  assert.equal(fixes[0].rule, 'AI_SLOP_CONVERSATIONAL_ARTIFACT');
+  assert.equal(fixes[1].rule, 'AI_SLOP_CONVERSATIONAL_ARTIFACT');
+  assert.equal(fixedContent, 'export const add = (a, b) => a + b;');
+});
+
+test('autofixContent: removes lazy truncation comments', () => {
+  const input = [
+    'export const config = {',
+    '  // ... existing code',
+    '  timeout: 5000',
+    '};'
+  ].join('\n');
+
+  const { fixedContent, fixes } = autofixContent(input);
+  assert.equal(fixes.length, 1);
+  assert.equal(fixes[0].rule, 'AI_SLOP_LAZY_PLACEHOLDER');
+  assert.equal(fixedContent, 'export const config = {\n  timeout: 5000\n};');
+});
+
+test('autofixContent: respects rule filtering', () => {
+  const input = '```\nconst x = "foo — bar";';
+  const { fixedContent, fixes } = autofixContent(input, { rules: ['TYPOGRAPHY_EM_DASH'] });
+
+  assert.equal(fixes.length, 1);
+  assert.equal(fixes[0].rule, 'TYPOGRAPHY_EM_DASH');
+  assert.ok(fixedContent.includes('```'));
+  assert.ok(fixedContent.includes('foo - bar'));
+});
+
+test('runAutofix: handles dryRun and file write correctly', () => {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'chemx-autofix-test-'));
+  const testFile = path.join(tempDir, 'test.ts');
+  fs.writeFileSync(testFile, 'const msg = "test — em dash";\n// hope this helps', 'utf-8');
+
+  // Dry run: reports fixes without modifying file
+  const dryResult = runAutofix(testFile, { dryRun: true, cwd: tempDir });
+  assert.equal(dryResult.filesChanged, 1);
+  assert.equal(dryResult.totalFixes, 2);
+  assert.equal(dryResult.dryRun, true);
+  assert.equal(fs.readFileSync(testFile, 'utf-8'), 'const msg = "test — em dash";\n// hope this helps');
+
+  // Live run: writes changes
+  const liveResult = runAutofix(testFile, { dryRun: false, cwd: tempDir });
+  assert.equal(liveResult.filesChanged, 1);
+  assert.equal(liveResult.totalFixes, 2);
+  assert.equal(liveResult.dryRun, false);
+  assert.equal(fs.readFileSync(testFile, 'utf-8'), 'const msg = "test - em dash";');
+
+  fs.rmSync(tempDir, { recursive: true, force: true });
+});

package/cli/audit/pattern-detector.js

@@ -73,6 +73,7 @@ export const createPatternRegistry = () => {
         totalHits: bucket.occurrences.length,
         hasHotspot,
         impactScore,
+        uniqueFiles,
         occurrences: bucket.occurrences
       });
     }
@@ -83,6 +84,150 @@ export const createPatternRegistry = () => {
   return { record, resolveHarmonizationCandidates };
 };
 
+const VOID_ELEMENTS = new Set([
+  'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr'
+]);
+
+export const extractTemplateTokens = (html) => {
+  const tokens = [];
+  let i = 0;
+  let line = 1;
+
+  while (i < html.length) {
+    if (html[i] === '\n') {
+      line++;
+      i++;
+      continue;
+    }
+
+    if (html.startsWith('<!--', i)) {
+      const endComment = html.indexOf('-->', i + 4);
+      if (endComment === -1) break;
+      for (let c = i; c < endComment + 3; c++) {
+        if (html[c] === '\n') line++;
+      }
+      i = endComment + 3;
+      continue;
+    }
+
+    if (html[i] === '<') {
+      const tagLine = line;
+      let j = i + 1;
+      const isClosing = html[j] === '/';
+      if (isClosing) j++;
+
+      const nameStart = j;
+      while (j < html.length && /[a-zA-Z0-9_-]/.test(html[j])) {
+        j++;
+      }
+      const tagName = html.slice(nameStart, j);
+
+      if (tagName) {
+        let isSelfClosing = false;
+        let inQuote = null;
+
+        while (j < html.length) {
+          const ch = html[j];
+          if (ch === '\n') line++;
+
+          if (inQuote) {
+            if (ch === inQuote && html[j - 1] !== '\\') {
+              inQuote = null;
+            }
+          } else {
+            if (ch === '"' || ch === "'") {
+              inQuote = ch;
+            } else if (ch === '/' && html[j + 1] === '>') {
+              isSelfClosing = true;
+              j += 2;
+              break;
+            } else if (ch === '>') {
+              j++;
+              break;
+            }
+          }
+          j++;
+        }
+
+        const isVoid = VOID_ELEMENTS.has(tagName.toLowerCase());
+        tokens.push({
+          tag: tagName,
+          isClosing,
+          isSelfClosing: isSelfClosing || isVoid,
+          line: tagLine
+        });
+
+        i = j;
+        continue;
+      }
+    }
+
+    i++;
+  }
+
+  return tokens;
+};
+
+export const buildTagTree = (tokens) => {
+  const root = { tag: 'ROOT', line: 1, children: [] };
+  const stack = [root];
+
+  for (const token of tokens) {
+    if (token.isClosing) {
+      for (let s = stack.length - 1; s > 0; s--) {
+        if (stack[s].tag === token.tag) {
+          stack.length = s;
+          break;
+        }
+      }
+    } else {
+      const node = { tag: token.tag, line: token.line, children: [] };
+      stack[stack.length - 1].children.push(node);
+      if (!token.isSelfClosing) {
+        stack.push(node);
+      }
+    }
+  }
+
+  return root.children;
+};
+
+const getHierarchy = (node, depth = 0) => {
+  if (depth > 2 || !node) return '';
+  const childHierarchy = (node.children || [])
+    .map((c) => getHierarchy(c, depth + 1))
+    .filter(Boolean);
+  if (childHierarchy.length === 0) return node.tag;
+  return `${node.tag}>(${childHierarchy.join('+')})`;
+};
+
+export const recordTemplatePatterns = (registry, templateHtml, relativePath, startLineOffset = 0) => {
+  if (!registry || !templateHtml) return;
+  const tokens = extractTemplateTokens(templateHtml);
+  const nodes = buildTagTree(tokens);
+
+  const traverseNodes = (nodeList) => {
+    for (const node of nodeList) {
+      if (node.children && node.children.length >= MIN_CHILD_NODES) {
+        const hierarchy = getHierarchy(node);
+        if (hierarchy && hierarchy.includes('>')) {
+          registry.record('UI_STRUCTURE', hierarchy, {
+            filePath: relativePath,
+            line: node.line + startLineOffset,
+            detail: hierarchy
+          });
+        }
+      }
+      if (node.children && node.children.length > 0) {
+        traverseNodes(node.children);
+      }
+    }
+  };
+
+  traverseNodes(nodes);
+};
+
+
 export const createPatternVisitors = (registry, relativePath) => {
   if (!registry) return {};
 

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

@@ -0,0 +1,61 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  createPatternRegistry,
+  extractTemplateTokens,
+  buildTagTree,
+  recordTemplatePatterns
+} from './pattern-detector.js';
+
+test('extractTemplateTokens: extracts tags, ignoring comments and handling quotes', () => {
+  const html = `
+    <!-- comment -->
+    <v-card class="elevation-2" :title="count > 0 ? 'yes' : 'no'">
+      <v-card-title>Title</v-card-title>
+      <x-btn />
+    </v-card>
+  `;
+
+  const tokens = extractTemplateTokens(html);
+  assert.equal(tokens[0].tag, 'v-card');
+  assert.equal(tokens[0].isClosing, false);
+  assert.equal(tokens[1].tag, 'v-card-title');
+  assert.equal(tokens[2].tag, 'v-card-title');
+  assert.equal(tokens[2].isClosing, true);
+  assert.equal(tokens[3].tag, 'x-btn');
+  assert.equal(tokens[3].isSelfClosing, true);
+  assert.equal(tokens[4].tag, 'v-card');
+  assert.equal(tokens[4].isClosing, true);
+});
+
+test('buildTagTree and recordTemplatePatterns: captures UI_STRUCTURE from Vue template', () => {
+  const registry = createPatternRegistry();
+  const template1 = `
+    <template>
+      <v-sheet class="panel">
+        <x-btn color="primary">Save</x-btn>
+        <x-btn color="secondary">Cancel</x-btn>
+      </v-sheet>
+    </template>
+  `;
+
+  const template2 = `
+    <template>
+      <v-sheet class="controls">
+        <x-btn color="error">Delete</x-btn>
+        <x-btn color="warning">Reset</x-btn>
+      </v-sheet>
+    </template>
+  `;
+
+  recordTemplatePatterns(registry, template1, 'src/components/A.vue');
+  recordTemplatePatterns(registry, template2, 'src/components/B.vue');
+
+  const candidates = registry.resolveHarmonizationCandidates();
+  const uiCandidate = candidates.find((c) => c.type === 'UI_STRUCTURE');
+
+  assert.ok(uiCandidate, 'Expected UI_STRUCTURE candidate to be found');
+  assert.equal(uiCandidate.detail, 'v-sheet>(x-btn+x-btn)');
+  assert.equal(uiCandidate.fileCount, 2);
+  assert.deepEqual(uiCandidate.uniqueFiles.sort(), ['src/components/A.vue', 'src/components/B.vue']);
+});

package/cli/audit/prompts.js

@@ -107,8 +107,10 @@ 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());
+  if (!isSubSection) {
+    lines.push('');
+    lines.push(buildAgentCommandsSection());
+  }
 
   return lines.join('\n');
 };
@@ -149,8 +151,10 @@ 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());
+  if (!isSubSection) {
+    lines.push('');
+    lines.push(buildAgentCommandsSection());
+  }
 
   return lines.join('\n');
 };
@@ -191,8 +195,10 @@ 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());
+  if (!isSubSection) {
+    lines.push('');
+    lines.push(buildAgentCommandsSection());
+  }
 
   return lines.join('\n');
 };
@@ -220,8 +226,10 @@ 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());
+  if (!isSubSection) {
+    lines.push('');
+    lines.push(buildAgentCommandsSection());
+  }
 
   return lines.join('\n');
 };
@@ -252,8 +260,10 @@ export const buildAiSlopPrompt = (report, options = {}) => {
   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());
+  if (!isSubSection) {
+    lines.push('');
+    lines.push(buildAgentCommandsSection());
+  }
 
   return lines.join('\n');
 };
@@ -283,15 +293,16 @@ export const buildHotspotsPrompt = (report, options = {}) => {
   }
 
   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.');
-  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.');
-  lines.push('');
-  lines.push(buildAgentCommandsSection());
+  lines.push('1. 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('2. Molecular Limits: Molecule capsules must strictly remain under 100 lines per file.');
+  lines.push('3. 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('4. Composable Return Contracts: Custom hooks/composables must strictly limit returns to 3 to 5 properties (State + Status + Actions).');
+  lines.push('5. 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('6. Zero breaking changes to external component APIs, route exports, or existing props.');
+  if (!isSubSection) {
+    lines.push('');
+    lines.push(buildAgentCommandsSection());
+  }
 
   return lines.join('\n');
 };
@@ -328,17 +339,29 @@ export const buildPillarPrompt = (report, pillarName, options = {}) => {
   }
 
   lines.push('### STRICT EXECUTION RULES:');
-  lines.push('1. Branch First: Change to a new branch prefixed with `chem-x/NAMEOFIMPROVEMENT` before making changes.');
-  lines.push('2. Pre-Split Pattern Discovery: Survey cross-file patterns before slicing; extract canonical shared capsules first.');
-  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());
+  lines.push('1. Pre-Split Pattern Discovery: Survey cross-file patterns before slicing; extract canonical shared capsules first.');
+  lines.push('2. Molecular Capsule Limit: Maximum 100 lines per molecule capsule file.');
+  lines.push('3. Table-of-Contents Views: Top-level page views must be 10 to 20 line declarative templates assembling components via named slots.');
+  lines.push('4. Zero breaking changes to external component APIs, route exports, or existing props.');
+  if (!isSubSection) {
+    lines.push('');
+    lines.push(buildAgentCommandsSection());
+  }
 
   return lines.join('\n');
 };
 
+export const deduplicateRefactoringCommands = (promptText) => {
+  if (typeof promptText !== 'string' || !promptText) return '';
+  const headerMarker = '### AI AGENT DISCOVERY & REFACTORING COMMANDS:';
+  const parts = promptText.split(headerMarker);
+  if (parts.length <= 2) return promptText;
+
+  const prefix = parts.slice(0, -1).join('').replace(/---\s*\n\s*---\s*\n/g, '---\n').trimEnd();
+  const lastSection = parts[parts.length - 1];
+  return `${prefix}\n\n${headerMarker}${lastSection}`;
+};
+
 export const deduplicateRolePreambles = (promptText, options = {}) => {
   if (typeof promptText !== 'string' || !promptText) return '';
   const { onlyIdentical = false } = options;
@@ -378,8 +401,9 @@ export const buildMasterPrompt = (report) => {
   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';
-  const rawPrompt = header + sections.join('\n\n---\n\n');
-  return deduplicateRolePreambles(rawPrompt);
+  const rawPrompt = `${header}${sections.join('\n\n---\n\n')}\n\n---\n\n${buildAgentCommandsSection()}`;
+  const dedupedRoles = deduplicateRolePreambles(rawPrompt);
+  return deduplicateRefactoringCommands(dedupedRoles);
 };
 
 export const formatPromptBox = (title, promptText) => {

package/cli/audit/prompts.spec.js

@@ -2,6 +2,7 @@ import test from 'node:test';
 import assert from 'node:assert';
 import {
   deduplicateRolePreambles,
+  deduplicateRefactoringCommands,
   buildGradeFPrompt,
   buildGradeDPrompt,
   buildGradeCPrompt,
@@ -288,4 +289,28 @@ test('buildMasterPrompt: has single top-level role preamble and no repeated Act
   // 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}`);
+
+  // Ensure refactoring commands section occurs exactly once
+  const commandMatches = prompt.match(/### AI AGENT DISCOVERY & REFACTORING COMMANDS:/g) || [];
+  assert.strictEqual(commandMatches.length, 1, `Expected exactly 1 refactoring commands section, found ${commandMatches.length}`);
+});
+
+test('deduplicateRefactoringCommands: collapses multiple occurrences to single block', () => {
+  const header = '### AI AGENT DISCOVERY & REFACTORING COMMANDS:';
+  const input = [
+    'Section 1 content',
+    header,
+    '- Command A',
+    '---',
+    'Section 2 content',
+    header,
+    '- Command B'
+  ].join('\n');
+
+  const result = deduplicateRefactoringCommands(input);
+  const matches = result.match(/### AI AGENT DISCOVERY & REFACTORING COMMANDS:/g) || [];
+  assert.strictEqual(matches.length, 1);
+  assert.ok(result.includes('Section 1 content'));
+  assert.ok(result.includes('Section 2 content'));
+  assert.ok(result.includes('- Command B'));
 });