@chemx/starter-kit 26.9.21-227 → 26.9.21-432

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/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|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)([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/rules-registry.js

@@ -117,9 +117,14 @@ export const RULE_REGISTRY = {
     directive: 'Extract related state and effects into dedicated domain hooks'
   },
   HOOK_RETURN_OVERLOAD: {
+    pillar: PILLARS.PILLAR_3,
+    severity: 'MEDIUM',
+    directive: 'Limit hook return values to 3 to 5 properties (Deprecated: use HOOK_SHAPE_CONTRACT)'
+  },
+  HOOK_SHAPE_CONTRACT: {
     pillar: PILLARS.PILLAR_3,
     severity: 'HIGH',
-    directive: 'Limit hook return values to 3 to 5 properties (State + Status + Actions)'
+    directive: 'Structure hook returns into flat State, Status, and verb-prefixed Actions buckets'
   },
   CONTROLLER_VIEW_MISMATCH: {
     pillar: PILLARS.PILLAR_3,

package/cli/audit/rules.js

@@ -19,8 +19,9 @@ import {
   createExtendedVisitors
 } from './extended-visitors.js';
 import { createPatternVisitors, recordTemplatePatterns } from './pattern-detector.js';
+import { createHookShapeRegistry } from './hook-shape-validator.js';
 
-export { PILLARS, RULE_REGISTRY };
+export { PILLARS, RULE_REGISTRY, createHookShapeRegistry };
 
 export const auditCode = (content, filePath, relativePath, options = {}) => {
   const violations = [];
@@ -145,7 +146,8 @@ export const auditCode = (content, filePath, relativePath, options = {}) => {
   }
 
   const traverseFn = traverse.default || traverse;
-  const visitors = createAstVisitors({ relativePath, violations });
+  const hookRegistry = options.hookRegistry || createHookShapeRegistry();
+  const visitors = createAstVisitors({ relativePath, violations, hookRegistry });
   const slopVisitors = createAiSlopVisitors({ relativePath, violations });
   const extendedVisitors = createExtendedVisitors({ relativePath, violations });
   const patternVisitors = options.patternRegistry
@@ -169,5 +171,11 @@ export const auditCode = (content, filePath, relativePath, options = {}) => {
 
   traverseFn(ast, mergedVisitors);
 
+  const shouldRunLocalConsistency = !options.hookRegistry;
+  if (shouldRunLocalConsistency) {
+    const consistencyViolations = hookRegistry.validateCrossHookConsistency();
+    violations.push(...consistencyViolations);
+  }
+
   return violations;
 };

package/cli/audit/rules.spec.js

@@ -203,3 +203,132 @@ export const debugCount = (itemCount: number) => {
   assert.strictEqual(violation, undefined);
 });
 
+test("Audit Hook Shape Contract: passes flat hook with 4 actions, 2 state fields, 1 status field (7 total)", () => {
+  const code = `
+export const useTodoList = () => {
+  const items = ref([]);
+  const filter = ref("all");
+  const isLoading = ref(false);
+
+  const addItem = (item) => { items.value.push(item); };
+  const toggleItem = (id) => { /* toggle */ };
+  const removeItem = (id) => { /* remove */ };
+  const setFilter = (next) => { filter.value = next; };
+
+  return {
+    items,
+    filter,
+    isLoading,
+    addItem,
+    toggleItem,
+    removeItem,
+    setFilter
+  };
+};
+`;
+  const violations = auditCode(code, "src/useTodoList.ts", "src/useTodoList.ts");
+  const shapeViolation = violations.find((v) => v.rule === "HOOK_SHAPE_CONTRACT");
+  assert.strictEqual(shapeViolation, undefined, "Expected HOOK_SHAPE_CONTRACT to pass for flat 7-property hook");
+
+  const overloadViolation = violations.find((v) => v.rule === "HOOK_RETURN_OVERLOAD");
+  assert.ok(overloadViolation, "Expected deprecated HOOK_RETURN_OVERLOAD warning");
+  assert.strictEqual(overloadViolation.severity, "MEDIUM", "Expected downgraded warning severity for HOOK_RETURN_OVERLOAD");
+});
+
+test("Audit Hook Shape Contract: fails hook with actions nested under actions wrapper", () => {
+  const code = `
+export const useTodoList = () => {
+  const items = ref([]);
+  const filter = ref("all");
+  const isLoading = ref(false);
+
+  const addItem = (item) => { items.value.push(item); };
+  const toggleItem = (id) => { /* toggle */ };
+  const removeItem = (id) => { /* remove */ };
+  const setFilter = (next) => { filter.value = next; };
+
+  return {
+    items,
+    filter,
+    isLoading,
+    actions: {
+      addItem,
+      toggleItem,
+      removeItem,
+      setFilter
+    }
+  };
+};
+`;
+  const violations = auditCode(code, "src/useTodoList.ts", "src/useTodoList.ts");
+  const shapeViolation = violations.find((v) => v.rule === "HOOK_SHAPE_CONTRACT");
+  assert.ok(shapeViolation, "Expected HOOK_SHAPE_CONTRACT failure for nested action wrapper");
+  assert.strictEqual(shapeViolation.severity, "HIGH");
+  assert.ok(shapeViolation.hazard.includes("actions"));
+});
+
+test("Audit Hook Shape Contract: flags raw DOM ref in hook return", () => {
+  const code = `
+export const useDropdown = () => {
+  const isOpen = ref(false);
+  const containerRef = ref(null);
+  const toggleDropdown = () => { isOpen.value = !isOpen.value; };
+
+  return {
+    isOpen,
+    containerRef,
+    toggleDropdown
+  };
+};
+`;
+  const violations = auditCode(code, "src/useDropdown.ts", "src/useDropdown.ts");
+  const shapeViolation = violations.find((v) => v.rule === "HOOK_SHAPE_CONTRACT");
+  assert.ok(shapeViolation, "Expected HOOK_SHAPE_CONTRACT failure for raw DOM ref");
+  assert.strictEqual(shapeViolation.severity, "HIGH");
+  assert.ok(shapeViolation.hazard.includes("containerRef"));
+});
+
+test("Audit Hook Shape Contract: flags non-verb action handler in hook return", () => {
+  const code = `
+export const useCounter = () => {
+  const count = ref(0);
+  const onToggle = () => { count.value += 1; };
+
+  return {
+    count,
+    onToggle
+  };
+};
+`;
+  const violations = auditCode(code, "src/useCounter.ts", "src/useCounter.ts");
+  const shapeViolation = violations.find((v) => v.rule === "HOOK_SHAPE_CONTRACT");
+  assert.ok(shapeViolation, "Expected HOOK_SHAPE_CONTRACT failure for onToggle");
+  assert.strictEqual(shapeViolation.severity, "HIGH");
+  assert.ok(shapeViolation.hazard.includes("onToggle"));
+});
+
+test("Audit Hook Shape Contract: flags cross-hook naming inconsistency for loading state", () => {
+  const code = `
+export const useFirst = () => {
+  const items = ref([]);
+  const isLoading = ref(false);
+  const fetchItems = () => {};
+  return { items, isLoading, fetchItems };
+};
+
+export const useSecond = () => {
+  const user = ref(null);
+  const loading = ref(false);
+  const fetchUser = () => {};
+  return { user, loading, fetchUser };
+};
+`;
+  const violations = auditCode(code, "src/useMulti.ts", "src/useMulti.ts");
+  const inconsistentViolation = violations.find(
+    (v) => v.rule === "HOOK_SHAPE_CONTRACT" && v.hazard.includes("loading")
+  );
+  assert.ok(inconsistentViolation, "Expected cross-hook naming inconsistency failure for loading vs isLoading");
+  assert.strictEqual(inconsistentViolation.severity, "HIGH");
+  assert.ok(inconsistentViolation.hazard.includes("isLoading"));
+});
+

package/cli/audit.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { auditCode, PILLARS, RULE_REGISTRY } from './audit/rules.js';
+import { auditCode, PILLARS, RULE_REGISTRY, createHookShapeRegistry } from './audit/rules.js';
 import { createPatternRegistry } from './audit/pattern-detector.js';
 import {
   buildRemediationRoadmap,
@@ -116,6 +116,7 @@ const auditFileEntry = (fullPath, relPath, scanOptions) => {
   const hookCount = hookMatches ? hookMatches.length : 0;
   const fileViolations = auditCode(content, fullPath, relPath, {
     patternRegistry: scanOptions.patternRegistry,
+    hookRegistry: scanOptions.hookRegistry,
     fast: scanOptions.fast
   });
 
@@ -174,15 +175,20 @@ export const scanDirectory = (targetDir, baseDir) => {
 };
 
 export const runAudit = (targetDir = 'src', options = {}) => {
-  const cwd = process.cwd();
-  const absoluteTarget = path.resolve(cwd, targetDir);
+  const cwd = options.cwd || process.cwd();
+  const absoluteTarget = path.isAbsolute(targetDir) ? targetDir : path.resolve(cwd, targetDir);
   const patternRegistry = createPatternRegistry();
+  const hookRegistry = createHookShapeRegistry();
   const { violations, fileStats, totalHooks } = scanTree(absoluteTarget, cwd, {
     patternRegistry,
+    hookRegistry,
     fast: Boolean(options.fast),
     fileList: options.fileList || null
   });
 
+  const crossHookViolations = hookRegistry.validateCrossHookConsistency();
+  violations.push(...crossHookViolations);
+
   const scannedFiles = fileStats.length;
   const totalLoc = fileStats.reduce((acc, f) => acc + f.lineCount, 0);
   const avgLoc = scannedFiles > 0 ? Math.round(totalLoc / scannedFiles) : 0;

package/cli/mcp/tools.js

@@ -52,8 +52,10 @@ export {
 };
 
 const handleQueryPatterns = (args = {}, cwd = process.cwd()) => {
-  const targetDir = args.dir || (fs.existsSync(path.resolve(cwd, 'src')) ? 'src' : '.');
-  const report = executeAstAudit(targetDir, {});
+  const baseCwd = resolveTargetCwd(cwd);
+  const targetDir = args.dir || (fs.existsSync(path.resolve(baseCwd, 'src')) ? 'src' : '.');
+  const resolvedTarget = path.isAbsolute(targetDir) ? targetDir : path.resolve(baseCwd, targetDir);
+  const report = executeAstAudit(resolvedTarget, { cwd: baseCwd });
   const rawPatterns = report.patterns || [];
   const filterType = args.type || 'ALL';
   const minOccurrences = typeof args.minOccurrences === 'number' ? args.minOccurrences : 2;
@@ -113,12 +115,13 @@ const handleQueryPatterns = (args = {}, cwd = process.cwd()) => {
 };
 
 const handleAudit = (args = {}, cwd = process.cwd()) => {
-  const rawTarget = args.path || (fs.existsSync(path.resolve(cwd, 'src')) ? 'src' : '.');
-  const resolvedTarget = path.resolve(cwd, rawTarget);
+  const baseCwd = resolveTargetCwd(cwd);
+  const rawTarget = args.path || args.dir || (fs.existsSync(path.resolve(baseCwd, 'src')) ? 'src' : '.');
+  const resolvedTarget = path.isAbsolute(rawTarget) ? rawTarget : path.resolve(baseCwd, rawTarget);
   const isFile = fs.existsSync(resolvedTarget) && fs.statSync(resolvedTarget).isFile();
 
   if (isFile) {
-    const relPath = path.relative(cwd, resolvedTarget);
+    const relPath = path.relative(baseCwd, resolvedTarget);
     const violations = auditFile(resolvedTarget, relPath);
     return {
       type: 'file',
@@ -129,21 +132,22 @@ const handleAudit = (args = {}, cwd = process.cwd()) => {
   }
 
   const options = {
+    cwd: baseCwd,
     model: args.model || 'blended',
     outputFile: null
   };
 
-  const report = executeAstAudit(rawTarget, options);
+  const report = executeAstAudit(resolvedTarget, options);
 
   // Sync AST audit results to SQLite index database
   try {
-    const syncRes = syncSearchIndex(rawTarget, cwd);
+    const syncRes = syncSearchIndex(resolvedTarget, baseCwd);
     if (syncRes?.db) {
       syncViolationsIndex(syncRes.db, report.violations);
       recordAuditSnapshot(syncRes.db, report);
     }
-  } catch {
-    // Continue if SQLite synchronization fails
+  } catch (syncError) {
+    process.stderr.write(`[chemx] Search index sync bypassed: ${syncError?.message || String(syncError)}\n`);
   }
 
   const isSevereViolation = (v) => {
@@ -239,7 +243,8 @@ const handleGetRefactorPrompt = (args = {}, cwd = process.cwd()) => {
 };
 
 const handleAuditBuild = async (args = {}, cwd = process.cwd()) => {
-  const targetCwd = args.dir ? path.resolve(cwd, args.dir) : cwd;
+  const baseCwd = resolveTargetCwd(cwd);
+  const targetCwd = args.dir ? path.resolve(baseCwd, args.dir) : baseCwd;
   const rawArgs = ['--json'];
   if (args.command) {
     rawArgs.push('--', args.command);
@@ -248,10 +253,13 @@ const handleAuditBuild = async (args = {}, cwd = process.cwd()) => {
 };
 
 const handleAutofix = (args = {}, cwd = process.cwd()) => {
-  return runAutofix(args.path, {
+  const baseCwd = resolveTargetCwd(cwd);
+  const rawTarget = args.path || args.dir || (fs.existsSync(path.resolve(baseCwd, 'src')) ? 'src' : '.');
+  const targetDir = path.isAbsolute(rawTarget) ? rawTarget : path.resolve(baseCwd, rawTarget);
+  return runAutofix(targetDir, {
     dryRun: Boolean(args.dryRun),
     rules: args.rules,
-    cwd
+    cwd: baseCwd
   });
 };
 

package/cli/team/team-db-task-helpers.js

@@ -15,7 +15,9 @@ export const parseTaskRow = (row) => {
   return {
     ...row,
     dependencies: JSON.parse(row.dependencies || '[]'),
-    result_payload: JSON.parse(row.result_payload || '{}')
+    result_payload: JSON.parse(row.result_payload || '{}'),
+    violation_snapshot: typeof row.violation_snapshot === 'string' ? JSON.parse(row.violation_snapshot || '{}') : (row.violation_snapshot || {}),
+    diff_receipt: typeof row.diff_receipt === 'string' ? JSON.parse(row.diff_receipt || '{}') : (row.diff_receipt || {})
   };
 };
 
@@ -59,8 +61,10 @@ export const executeStatusUpdate = (db, taskId, status, options, task) => {
   const payloadStr = options.resultPayload
     ? JSON.stringify(options.resultPayload)
     : JSON.stringify(task.result_payload);
-  db.prepare('UPDATE agent_tasks SET status = ?, blocked_reason = ?, result_payload = ?, updated_at = ? WHERE id = ?')
-    .run(status, options.blockedReason || '', payloadStr, now, Number(taskId));
+  const receiptObj = options.diffReceipt || options.resultPayload?.receipt || task.diff_receipt || {};
+  const diffReceiptStr = JSON.stringify(receiptObj);
+  db.prepare('UPDATE agent_tasks SET status = ?, blocked_reason = ?, result_payload = ?, diff_receipt = ?, updated_at = ? WHERE id = ?')
+    .run(status, options.blockedReason || '', payloadStr, diffReceiptStr, now, Number(taskId));
 
   const isTerminal = ['done', 'failed', 'queued'].includes(status);
   const hasAgent = Boolean(task.assigned_agent_id);