@chemx/create-chemx 26.9.21-8 → 26.9.24-393

package/cli/audit/ast-visitors.js

@@ -7,8 +7,9 @@ import {
   isZeroDelayTimeout,
   isUnguardedConsoleCall
 } from './rules-predicates.js';
+import { validateHookReturnShape } from './hook-shape-validator.js';
 
-export const createAstVisitors = ({ relativePath, violations }) => {
+export const createAstVisitors = ({ relativePath, violations, hookRegistry }) => {
   return {
     Function(astPath) {
       const isCustomHook = isCustomHookFunction(astPath);
@@ -45,22 +46,14 @@ export const createAstVisitors = ({ relativePath, violations }) => {
       if (isCustomHook) {
         astPath.traverse({
           ReturnStatement(retPath) {
-            if (retPath.getFunctionParent() === astPath && t.isObjectExpression(retPath.node.argument)) {
-              const propCount = retPath.node.argument.properties.length;
-              if (propCount > 5) {
-                const line = retPath.node.loc?.start.line || 1;
-                const meta = RULE_REGISTRY.HOOK_RETURN_OVERLOAD;
-                violations.push({
-                  filePath: relativePath,
-                  line,
-                  column: retPath.node.loc?.start.column || 1,
-                  hazard: `Hook return saturation (${propCount} properties > 5 limit)`,
-                  rule: 'HOOK_RETURN_OVERLOAD',
-                  severity: meta.severity,
-                  pillar: meta.pillar,
-                  directive: meta.directive
-                });
-              }
+            if (retPath.getFunctionParent() === astPath) {
+              validateHookReturnShape({
+                retPath,
+                astPath,
+                relativePath,
+                violations,
+                hookRegistry
+              });
             }
           }
         });

package/cli/audit/autofix.js

@@ -63,7 +63,9 @@ export const autofixContent = (content, options = {}) => {
     }
 
     // 3. AI lazy placeholder comment removal
-    if (!shouldDropLine && shouldFix('AI_SLOP_LAZY_PLACEHOLDER') && TRUNCATION_REGEX.test(line)) {
+    const hasLazyTruncation = TRUNCATION_REGEX.test(line);
+    const isLazyTruncationEligible = !shouldDropLine && shouldFix('AI_SLOP_LAZY_PLACEHOLDER');
+    if (isLazyTruncationEligible && hasLazyTruncation) {
       fixes.push({
         line: lineNumber,
         rule: 'AI_SLOP_LAZY_PLACEHOLDER',
@@ -72,7 +74,9 @@ export const autofixContent = (content, options = {}) => {
       shouldDropLine = true;
     }
 
-    if (!shouldDropLine && shouldFix('TYPOGRAPHY_EM_DASH') && line.includes('\u2014')) {
+    const hasEmDash = line.includes('\u2014');
+    const isEmDashEligible = !shouldDropLine && shouldFix('TYPOGRAPHY_EM_DASH');
+    if (isEmDashEligible && hasEmDash) {
       line = line.replace(/\u2014/g, '-');
       fixes.push({
         line: lineNumber,
@@ -81,6 +85,17 @@ export const autofixContent = (content, options = {}) => {
       });
     }
 
+    const hasTimeoutMacro = /setTimeout\([^,]+,\s*0\)/.test(line);
+    const isTimeoutEligible = !shouldDropLine && shouldFix('MACRO_TASK_OVER_MICRO_TASK');
+    if (isTimeoutEligible && hasTimeoutMacro) {
+      line = line.replace(/setTimeout\(([^,]+),\s*0\)/g, 'queueMicrotask($1)');
+      fixes.push({
+        line: lineNumber,
+        rule: 'MACRO_TASK_OVER_MICRO_TASK',
+        action: 'Replaced setTimeout(fn, 0) with queueMicrotask(fn)'
+      });
+    }
+
     if (!shouldDropLine) {
       resultLines.push(line);
     }

package/cli/audit/clone-detector.js

@@ -0,0 +1,64 @@
+import path from 'node:path';
+import { deserializeVector, cosineSimilarity } from '../embeddings/vectorizer.js';
+
+const isSpecOrTest = (filePath) => {
+  if (!filePath || typeof filePath !== 'string') return false;
+  return filePath.includes('.spec.') || filePath.includes('.test.') || filePath.includes('__tests__');
+};
+
+export const detectSemanticClones = (db, options = {}) => {
+  const isValidDb = Boolean(db);
+  if (!isValidDb) return { count: 0, threshold: 0.85, pairs: [] };
+
+  const threshold = typeof options.threshold === 'number' ? options.threshold : 0.85;
+  const limit = options.limit || 50;
+
+  const rows = db.prepare(
+    "SELECT file_path, target_name, vector FROM embeddings WHERE target_type = 'file'"
+  ).all();
+
+  const entries = rows
+    .filter((r) => !isSpecOrTest(r.file_path))
+    .map((r) => ({
+      filePath: r.file_path,
+      name: r.target_name,
+      vec: deserializeVector(r.vector)
+    }));
+
+  const pairs = [];
+
+  for (let i = 0; i < entries.length; i++) {
+    for (let j = i + 1; j < entries.length; j++) {
+      const a = entries[i];
+      const b = entries[j];
+
+      const isSameFile = a.filePath === b.filePath;
+      if (isSameFile) continue;
+
+      const sim = cosineSimilarity(a.vec, b.vec);
+      const isClone = sim >= threshold;
+
+      if (isClone) {
+        pairs.push({
+          fileA: a.filePath,
+          fileB: b.filePath,
+          nameA: a.name,
+          nameB: b.name,
+          similarity: Number(sim.toFixed(4)),
+          isExact: sim >= 0.95
+        });
+      }
+    }
+  }
+
+  pairs.sort((p1, p2) => p2.similarity - p1.similarity);
+  const cappedPairs = pairs.slice(0, limit);
+
+  return {
+    count: pairs.length,
+    threshold,
+    exactClones: cappedPairs.filter((p) => p.isExact),
+    nearClones: cappedPairs.filter((p) => !p.isExact),
+    pairs: cappedPairs
+  };
+};

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

@@ -0,0 +1,46 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { DatabaseSync } from 'node:sqlite';
+import { generateEmbedding, serializeVector } from '../embeddings/vectorizer.js';
+import { detectSemanticClones } from './clone-detector.js';
+import { formatCloneReport } from './reporter-clones.js';
+
+test('clone-detector: detects high-similarity clones while ignoring spec companion files', () => {
+  const db = new DatabaseSync(':memory:');
+  db.exec(`
+    CREATE TABLE embeddings (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      file_path TEXT NOT NULL,
+      target_type TEXT NOT NULL,
+      target_name TEXT NOT NULL,
+      vector BLOB NOT NULL
+    );
+  `);
+
+  const insert = db.prepare('INSERT INTO embeddings (file_path, target_type, target_name, vector) VALUES (?, ?, ?, ?)');
+  const vecA = serializeVector(generateEmbedding('modal window popup backdrop blur close cancel confirm'));
+  const vecB = serializeVector(generateEmbedding('modal dialog popup backdrop blur cancel confirm close'));
+  const vecTest = serializeVector(generateEmbedding('modal window popup backdrop blur close cancel confirm spec test'));
+  const vecDiff = serializeVector(generateEmbedding('database sqlite migration column index'));
+
+  insert.run('src/ui/m-modal-a/m-modal-a.vue', 'file', 'm-modal-a.vue', vecA);
+  insert.run('src/ui/m-modal-b/m-modal-b.vue', 'file', 'm-modal-b.vue', vecB);
+  insert.run('src/ui/m-modal-a/m-modal-a.spec.ts', 'file', 'm-modal-a.spec.ts', vecTest);
+  insert.run('src/db/storage.ts', 'file', 'storage.ts', vecDiff);
+
+  const res = detectSemanticClones(db, { threshold: 0.8 });
+  assert.equal(res.count, 1);
+  assert.equal(res.pairs[0].fileA, 'src/ui/m-modal-a/m-modal-a.vue');
+  assert.equal(res.pairs[0].fileB, 'src/ui/m-modal-b/m-modal-b.vue');
+  assert.ok(res.pairs[0].similarity > 0.85);
+
+  const report = formatCloneReport(res);
+  assert.match(report, /Semantic Clone Detection/);
+  assert.match(report, /m-modal-a\.vue <-> src\/ui\/m-modal-b\/m-modal-b\.vue/);
+});
+
+test('clone-detector: handles empty or invalid db gracefully', () => {
+  assert.equal(detectSemanticClones(null).count, 0);
+  const emptyReport = formatCloneReport({ count: 0, threshold: 0.85, pairs: [] });
+  assert.match(emptyReport, /Zero duplicate clone hazards detected/);
+});

package/cli/audit/history.js

@@ -13,8 +13,12 @@ const RED = '\x1b[31m';
 
 export const ensureChemxDir = (cwd = process.cwd()) => {
   const dir = path.resolve(cwd, '.chemx');
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
+  try {
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+  } catch {
+    return dir;
   }
 
   // Ensure .chemx is gitignored if git repo exists
@@ -165,7 +169,11 @@ export const getAuditBaseline = (cwd = process.cwd()) => {
 export const setAuditBaseline = (snapshot, cwd = process.cwd()) => {
   ensureChemxDir(cwd);
   const baselinePath = path.resolve(cwd, '.chemx', 'baseline.json');
-  fs.writeFileSync(baselinePath, JSON.stringify(snapshot, null, 2), 'utf-8');
+  try {
+    fs.writeFileSync(baselinePath, JSON.stringify(snapshot, null, 2), 'utf-8');
+  } catch {
+    // Read-only filesystem in sandbox
+  }
   return snapshot;
 };
 
@@ -196,7 +204,11 @@ export const saveAuditSnapshot = (report, cwd = process.cwd()) => {
   // Keep last 50 snapshots
   const trimmed = history.slice(-50);
   const historyPath = path.resolve(cwd, '.chemx', 'history.json');
-  fs.writeFileSync(historyPath, JSON.stringify(trimmed, null, 2), 'utf-8');
+  try {
+    fs.writeFileSync(historyPath, JSON.stringify(trimmed, null, 2), 'utf-8');
+  } catch {
+    // Read-only filesystem in sandbox
+  }
 
   // Auto-establish first run or lower score as baseline floor
   const baselinePath = path.resolve(cwd, '.chemx', 'baseline.json');
@@ -206,8 +218,12 @@ export const saveAuditSnapshot = (report, cwd = process.cwd()) => {
   const baselineScore = currentBaseline?.health?.score ?? 101;
 
   if (!currentBaseline || currentScore < baselineScore) {
-    fs.writeFileSync(baselinePath, JSON.stringify(snapshot, null, 2), 'utf-8');
-    isNewBaseline = true;
+    try {
+      fs.writeFileSync(baselinePath, JSON.stringify(snapshot, null, 2), 'utf-8');
+      isNewBaseline = true;
+    } catch {
+      // Read-only filesystem in sandbox
+    }
   }
 
   const baseline = getAuditBaseline(cwd);

package/cli/audit/hook-shape-validator.js

@@ -0,0 +1,312 @@
+import * as t from '@babel/types';
+import { RULE_REGISTRY } from './rules-registry.js';
+
+const VERB_PREFIX_REGEX = /^(add|remove|toggle|set|get|fetch|load|save|delete|clear|reset|refresh|update|create|edit|send|sync|init|setup|dispose|trigger|post|put|patch|apply|dismiss|select|deselect|filter|sort|search|open|close|show|hide|start|stop|cancel|execute|run|retry|submit|validate|mutate|next|prev|step|increment|decrement|insert|upsert|drop|enable|disable|register|unregister|login|logout|checkout|publish|archive|discard|confirm|undo|redo|claim|complete|acquire|release|download|upload|export|import|handle|play|pause|resume|seek|unlock|restore|advance|focus|notify|broadcast|copy|format)([A-Z0-9_].*)?$/;
+
+const STATUS_HEURISTIC_REGEX = /^(is[A-Z]|has[A-Z]|can[A-Z]|should[A-Z])|.*(Error|Status)$/;
+const STATUS_EXACT_NAMES = new Set(['status', 'error', 'loading', 'pending', 'ready']);
+const ACTION_WRAPPER_KEYS = new Set(['actions', 'handlers', 'methods', 'operations']);
+
+const RAW_DOM_REF_REGEX = /^(dom|element|container|input|button|target|root|node)?Ref$|.*(Element|Node|Dom)Ref$/i;
+const INTERMEDIATE_VAL_REGEX = /^(temp|draft|raw|partial|interim|scratch|memoized)([A-Z_].*)?$/i;
+const UNGROUPED_CALLBACK_REGEX = /^(on[A-Z]|callback$|.*Callback$)/;
+
+const MUTUALLY_EXCLUSIVE_STATUSES = new Set([
+  'isloading', 'issuccess', 'iserror', 'isidle', 'isloaded', 'isfetching', 'ispending',
+  'loading', 'success', 'idle'
+]);
+
+export const SEMANTIC_STATUS_CLUSTERS = {
+  LOADING: {
+    canonical: 'isLoading',
+    variants: new Set(['isloading', 'loading', 'ispending', 'pending', 'isfetching', 'fetching'])
+  },
+  ERROR: {
+    canonical: 'error',
+    variants: new Set(['error', 'iserror', 'haserror', 'err', 'errormessage'])
+  },
+  READY: {
+    canonical: 'isReady',
+    variants: new Set(['isready', 'ready', 'isinitialized', 'initialized'])
+  },
+  STATUS: {
+    canonical: 'status',
+    variants: new Set(['status', 'state', 'phase', 'stage'])
+  }
+};
+
+const resolvePropKey = (prop) => {
+  if (t.isIdentifier(prop.key)) return prop.key.name;
+  if (t.isStringLiteral(prop.key)) return prop.key.value;
+  return null;
+};
+
+const isFunctionNode = (node, scope) => {
+  const isDirectFunction = t.isArrowFunctionExpression(node) || t.isFunctionExpression(node);
+  if (isDirectFunction) return true;
+
+  const isIdentifierNode = t.isIdentifier(node);
+  const canInspectScope = isIdentifierNode && Boolean(scope);
+  if (!canInspectScope) return false;
+
+  const binding = scope.getBinding(node.name);
+  if (!binding) return false;
+
+  if (binding.path.isFunctionDeclaration()) return true;
+
+  if (binding.path.isVariableDeclarator()) {
+    const init = binding.path.node.init;
+    const isInitFunction = t.isArrowFunctionExpression(init) || t.isFunctionExpression(init);
+    if (isInitFunction) return true;
+    const isCallbackHook = t.isCallExpression(init) && t.isIdentifier(init.callee, { name: 'useCallback' });
+    if (isCallbackHook) return true;
+  }
+
+  return false;
+};
+
+const hasNestedActions = (objectExpr, scope) => {
+  if (!t.isObjectExpression(objectExpr)) return false;
+  return objectExpr.properties.some((p) => {
+    if (t.isObjectMethod(p)) return true;
+    if (t.isObjectProperty(p)) {
+      const name = resolvePropKey(p);
+      const isVerbNamed = Boolean(name && VERB_PREFIX_REGEX.test(name));
+      if (isVerbNamed) return true;
+      if (isFunctionNode(p.value, scope)) return true;
+    }
+    return false;
+  });
+};
+
+export const createHookShapeRegistry = () => {
+  const entries = [];
+
+  const recordHook = (hookInfo) => {
+    entries.push(hookInfo);
+  };
+
+  const validateCrossHookConsistency = () => {
+    const consistencyViolations = [];
+    if (entries.length < 2) return consistencyViolations;
+
+    for (const [clusterKey, cluster] of Object.entries(SEMANTIC_STATUS_CLUSTERS)) {
+      const occurrences = [];
+      for (const entry of entries) {
+        for (const prop of entry.statusProps) {
+          const lower = prop.name.toLowerCase();
+          if (cluster.variants.has(lower)) {
+            occurrences.push({ ...prop, hookName: entry.hookName, filePath: entry.filePath });
+          }
+        }
+      }
+
+      const uniqueNames = Array.from(new Set(occurrences.map((o) => o.name)));
+      if (uniqueNames.length > 1) {
+        for (const occ of occurrences) {
+          if (occ.name !== cluster.canonical) {
+            const meta = RULE_REGISTRY.HOOK_SHAPE_CONTRACT;
+            consistencyViolations.push({
+              filePath: occ.filePath,
+              line: occ.line,
+              column: occ.column,
+              hazard: `Inconsistent ${clusterKey.toLowerCase()} status property "${occ.name}". Rename to "${cluster.canonical}" to match hook shape conventions.`,
+              rule: 'HOOK_SHAPE_CONTRACT',
+              severity: meta.severity,
+              pillar: meta.pillar,
+              directive: meta.directive
+            });
+          }
+        }
+      }
+    }
+
+    return consistencyViolations;
+  };
+
+  return { recordHook, validateCrossHookConsistency, entries };
+};
+
+export const validateHookReturnShape = ({ retPath, astPath, relativePath, violations, hookRegistry }) => {
+  if (!t.isObjectExpression(retPath.node.argument)) return;
+
+  const properties = retPath.node.argument.properties;
+  const propCount = properties.length;
+  const hookName = astPath.node.id?.name || astPath.parentPath?.node?.id?.name || 'anonymousHook';
+  const meta = RULE_REGISTRY.HOOK_SHAPE_CONTRACT;
+  const overloadMeta = RULE_REGISTRY.HOOK_RETURN_OVERLOAD;
+
+  if (propCount > 5) {
+    violations.push({
+      filePath: relativePath,
+      line: retPath.node.loc?.start.line || 1,
+      column: retPath.node.loc?.start.column || 1,
+      hazard: `Hook return saturation (${propCount} properties > 5 limit; deprecated rule: migrate to HOOK_SHAPE_CONTRACT)`,
+      rule: 'HOOK_RETURN_OVERLOAD',
+      severity: overloadMeta.severity,
+      pillar: overloadMeta.pillar,
+      directive: overloadMeta.directive
+    });
+  }
+
+  const statusProps = [];
+  const mutualStatuses = [];
+
+  for (const prop of properties) {
+    if (t.isSpreadElement(prop)) continue;
+
+    const keyName = resolvePropKey(prop);
+    if (!keyName) continue;
+
+    const line = prop.loc?.start.line || retPath.node.loc?.start.line || 1;
+    const column = prop.loc?.start.column || retPath.node.loc?.start.column || 1;
+
+    const isActionWrapperKey = ACTION_WRAPPER_KEYS.has(keyName);
+    if (isActionWrapperKey) {
+      violations.push({
+        filePath: relativePath,
+        line,
+        column,
+        hazard: `Nested action wrapper detected in hook return ("${keyName}"). Actions must be flat at top level per HOOK_SHAPE_CONTRACT.`,
+        rule: 'HOOK_SHAPE_CONTRACT',
+        severity: meta.severity,
+        pillar: meta.pillar,
+        directive: meta.directive
+      });
+      continue;
+    }
+
+    const isPropObject = t.isObjectProperty(prop) && hasNestedActions(prop.value, astPath.scope);
+    if (isPropObject) {
+      violations.push({
+        filePath: relativePath,
+        line,
+        column,
+        hazard: `Action wrapper detected in property "${keyName}". Actions must be flat at top level per HOOK_SHAPE_CONTRACT.`,
+        rule: 'HOOK_SHAPE_CONTRACT',
+        severity: meta.severity,
+        pillar: meta.pillar,
+        directive: meta.directive
+      });
+      continue;
+    }
+
+    const isMethod = t.isObjectMethod(prop);
+    const isPropFunc = t.isObjectProperty(prop) && isFunctionNode(prop.value, astPath.scope);
+    const isFunction = isMethod || isPropFunc;
+
+    if (isFunction) {
+      const isStatusPredicate = STATUS_HEURISTIC_REGEX.test(keyName);
+      if (isStatusPredicate) {
+        statusProps.push({ name: keyName, line, column });
+        if (MUTUALLY_EXCLUSIVE_STATUSES.has(keyName.toLowerCase())) {
+          mutualStatuses.push(keyName);
+        }
+        continue;
+      }
+
+      const isUngrouped = UNGROUPED_CALLBACK_REGEX.test(keyName);
+      if (isUngrouped) {
+        violations.push({
+          filePath: relativePath,
+          line,
+          column,
+          hazard: `Property "${keyName}" is an invalid hook action. Actions must be verb-prefixed (e.g. addItem, toggleItem) rather than event handlers or callbacks.`,
+          rule: 'HOOK_SHAPE_CONTRACT',
+          severity: meta.severity,
+          pillar: meta.pillar,
+          directive: meta.directive
+        });
+      } else {
+        const isVerbPrefixed = VERB_PREFIX_REGEX.test(keyName);
+        if (!isVerbPrefixed) {
+          violations.push({
+            filePath: relativePath,
+            line,
+            column,
+            hazard: `Function "${keyName}" in hook return is missing an action verb prefix (e.g. addItem, toggleItem).`,
+            rule: 'HOOK_SHAPE_CONTRACT',
+            severity: meta.severity,
+            pillar: meta.pillar,
+            directive: meta.directive
+          });
+        }
+      }
+      continue;
+    }
+
+    const isDomRef = RAW_DOM_REF_REGEX.test(keyName) || keyName === 'ref';
+    if (isDomRef) {
+      violations.push({
+        filePath: relativePath,
+        line,
+        column,
+        hazard: `Property "${keyName}" is a raw DOM ref. Hooks must not return raw DOM element refs.`,
+        rule: 'HOOK_SHAPE_CONTRACT',
+        severity: meta.severity,
+        pillar: meta.pillar,
+        directive: meta.directive
+      });
+      continue;
+    }
+
+    const isIntermediate = INTERMEDIATE_VAL_REGEX.test(keyName);
+    if (isIntermediate) {
+      violations.push({
+        filePath: relativePath,
+        line,
+        column,
+        hazard: `Property "${keyName}" is an intermediate or temporary value. Hooks must return finished domain state.`,
+        rule: 'HOOK_SHAPE_CONTRACT',
+        severity: meta.severity,
+        pillar: meta.pillar,
+        directive: meta.directive
+      });
+      continue;
+    }
+
+    const isCallback = UNGROUPED_CALLBACK_REGEX.test(keyName);
+    if (isCallback) {
+      violations.push({
+        filePath: relativePath,
+        line,
+        column,
+        hazard: `Property "${keyName}" is an ungrouped callback or handler. Actions must be verb-prefixed (e.g. addItem).`,
+        rule: 'HOOK_SHAPE_CONTRACT',
+        severity: meta.severity,
+        pillar: meta.pillar,
+        directive: meta.directive
+      });
+      continue;
+    }
+
+    const isStatus = STATUS_HEURISTIC_REGEX.test(keyName) || STATUS_EXACT_NAMES.has(keyName.toLowerCase());
+    if (isStatus) {
+      statusProps.push({ name: keyName, line, column });
+      if (MUTUALLY_EXCLUSIVE_STATUSES.has(keyName.toLowerCase())) {
+        mutualStatuses.push(keyName);
+      }
+    }
+  }
+
+  if (mutualStatuses.length >= 3) {
+    violations.push({
+      filePath: relativePath,
+      line: retPath.node.loc?.start.line || 1,
+      column: retPath.node.loc?.start.column || 1,
+      hazard: `Mutually exclusive lifecycle states returned as multiple independent booleans (${mutualStatuses.join(', ')}). Prefer a single discriminated status field per Directive 2.B.`,
+      rule: 'HOOK_SHAPE_CONTRACT',
+      severity: meta.severity,
+      pillar: meta.pillar,
+      directive: meta.directive
+    });
+  }
+
+  if (hookRegistry) {
+    hookRegistry.recordHook({
+      hookName,
+      filePath: relativePath,
+      statusProps
+    });
+  }
+};

package/cli/audit/prompts.js

@@ -36,7 +36,7 @@ const renderTreeLines = (node, depth = 0) => {
   return lines;
 };
 
-export const formatGroupedPromptViolations = (violations = []) => {
+export const formatGroupedPromptViolations = (violations = [], options = {}) => {
   const hasNoViolations = violations.length === 0;
   if (hasNoViolations) return [];
 
@@ -49,11 +49,14 @@ export const formatGroupedPromptViolations = (violations = []) => {
     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:');
+    lines.push(`   Action:    chemx team task list --rule=${rg.rule}`);
 
-    const tree = buildPathTree(rg.violations);
-    const treeLines = renderTreeLines(tree, 0);
-    lines.push(...treeLines);
+    if (options.detailedLocations) {
+      lines.push('   Locations:');
+      const tree = buildPathTree(rg.violations);
+      const treeLines = renderTreeLines(tree, 0);
+      lines.push(...treeLines);
+    }
     lines.push('');
   });
 
@@ -62,10 +65,10 @@ export const formatGroupedPromptViolations = (violations = []) => {
 
 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.'
+  '- Claim Work: Run `chemx team task list --status=queued` and claim via `chemx team task claim <id> --as=@coder`.',
+  '- Inspect Target: Run `chemx read <target_path> --outline` to inspect AST signatures without token bloat.',
+  '- Verify & Auto-Resolve: Run `chemx verify`. Clean files auto-reconcile tasks to done in SQLite.',
+  '- MCP Invocations: If invoking via MCP, pass command string directly via `chemx({ command: "..." })`.'
 ].join('\n');
 
 export const buildGradeFPrompt = (report, options = {}) => {
@@ -296,7 +299,7 @@ export const buildHotspotsPrompt = (report, options = {}) => {
   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('4. Composable Return Contracts: Custom hooks/composables must classify returns into flat State, Status, and verb-prefixed Actions buckets (Directive 4.A).');
   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) {

package/cli/audit/prompts.spec.js

@@ -10,7 +10,8 @@ import {
   buildAiSlopPrompt,
   buildHotspotsPrompt,
   buildPillarPrompt,
-  buildMasterPrompt
+  buildMasterPrompt,
+  formatGroupedPromptViolations
 } from './prompts.js';
 
 test('deduplicateRolePreambles: handles invalid and empty inputs', () => {
@@ -314,3 +315,53 @@ test('deduplicateRefactoringCommands: collapses multiple occurrences to single b
   assert.ok(result.includes('Section 2 content'));
   assert.ok(result.includes('- Command B'));
 });
+
+test('formatGroupedPromptViolations: outputs token-compact task action by default', () => {
+  const violations = [
+    {
+      rule: 'SECURITY_RAW_HTML_INJECTION',
+      severity: 'CRITICAL',
+      hazard: 'Unsanitized HTML injection',
+      directive: 'Sanitize dynamic HTML via DOMPurify',
+      filePath: 'src/view-a.vue',
+      line: 10
+    },
+    {
+      rule: 'SECURITY_RAW_HTML_INJECTION',
+      severity: 'CRITICAL',
+      hazard: 'Unsanitized HTML injection',
+      directive: 'Sanitize dynamic HTML via DOMPurify',
+      filePath: 'src/view-b.vue',
+      line: 25
+    }
+  ];
+
+  const lines = formatGroupedPromptViolations(violations);
+  const text = lines.join('\n');
+
+  assert.ok(text.includes('[SECURITY_RAW_HTML_INJECTION]'));
+  assert.ok(text.includes('(2 items)'));
+  assert.ok(text.includes('Action:    chemx team task list --rule=SECURITY_RAW_HTML_INJECTION'));
+  // Does not dump file locations tree by default
+  assert.ok(!text.includes('Locations:'));
+  assert.ok(!text.includes('view-a.vue:10'));
+});
+
+test('formatGroupedPromptViolations: renders file tree when detailedLocations is enabled', () => {
+  const violations = [
+    {
+      rule: 'SECURITY_RAW_HTML_INJECTION',
+      severity: 'CRITICAL',
+      hazard: 'Unsanitized HTML injection',
+      directive: 'Sanitize dynamic HTML via DOMPurify',
+      filePath: 'src/view-a.vue',
+      line: 10
+    }
+  ];
+
+  const lines = formatGroupedPromptViolations(violations, { detailedLocations: true });
+  const text = lines.join('\n');
+
+  assert.ok(text.includes('Locations:'));
+  assert.ok(text.includes('view-a.vue:10'));
+});