@chemx/starter-kit 26.9.26-253 → 26.9.28-1234

package/cli/audit/metrics.js

@@ -1,5 +1,7 @@
 import { PILLARS } from './rules.js';
 
+export const isSlopViolation = (v) => Boolean(v.isAiSlop || (v.rule && v.rule.startsWith('AI_SLOP_')));
+
 export const calculateMolecularHealthScore = (violations, totalFiles) => {
   if (totalFiles === 0) {
     return { score: 100, grade: 'A+', label: 'Crystalline Molecular' };
@@ -7,7 +9,7 @@ export const calculateMolecularHealthScore = (violations, totalFiles) => {
 
   let penalty = 0;
   for (const v of violations) {
-    if (v.isAiSlop) continue;
+    if (isSlopViolation(v)) continue;
     if (v.severity === 'CRITICAL') penalty += 8;
     else if (v.severity === 'HIGH') penalty += 4;
     else if (v.severity === 'MEDIUM') penalty += 2;
@@ -57,7 +59,7 @@ export const calculatePillarBreakdown = (violations) => {
   }
 
   for (const v of violations) {
-    if (v.isAiSlop) continue;
+    if (isSlopViolation(v)) continue;
     const pillarName = v.pillar || PILLARS.PILLAR_1;
     if (!breakdown[pillarName]) {
       breakdown[pillarName] = {
@@ -181,7 +183,7 @@ export const calculateHotspots = (violations, fileStats, limit = 5) => {
 export const calculateQuantumHealthScore = calculateMolecularHealthScore;
 
 export const calculateAiSlopScore = (violations, totalFiles) => {
-  const slopViolations = violations.filter((v) => v.isAiSlop);
+  const slopViolations = violations.filter(isSlopViolation);
   if (totalFiles === 0) {
     return {
       score: 100,

package/cli/audit/reporter-markdown.js

@@ -128,7 +128,7 @@ export const generateMarkdownReport = (report) => {
     }
   }
 
-  const slopViolations = violations.filter((v) => v.isAiSlop);
+  const slopViolations = violations.filter((v) => v.isAiSlop || (v.rule && v.rule.startsWith('AI_SLOP_')));
   lines.push('---');
   lines.push('');
   lines.push('## 5. AI Slop & Code Authenticity Audit');

package/cli/audit/reporter-sections.js

@@ -27,7 +27,7 @@ import {
 } from './prompts.js';
 import { resolveFirstDefined } from './rules-predicates.js';
 
-const isSlopViolation = (v) => Boolean(v.isAiSlop);
+const isSlopViolation = (v) => Boolean(v.isAiSlop || (v.rule && v.rule.startsWith('AI_SLOP_')));
 
 const formatHotspotItem = (h, idx) => {
   const monolithBadge = resolveHotspotBadge(h.lineCount);

package/cli/audit/rules-helpers.js

@@ -17,7 +17,13 @@ export const countLogicalOperators = (node) => {
 export const extractParseableCode = (content, ext) => {
   if (ext === '.vue') {
     const scriptMatch = content.match(/<script\b[^>]*>([\s\S]*?)<\/script>/i);
-    return scriptMatch ? scriptMatch[1] : '';
+    if (!scriptMatch) return '';
+    const scriptStartIndex = scriptMatch.index || 0;
+    const preScript = content.slice(0, scriptStartIndex);
+    const openTag = scriptMatch[0].match(/<script\b[^>]*>/i)?.[0] || '';
+    const preContent = preScript + openTag;
+    const leadingNewlines = preContent.split('\n').length - 1;
+    return '\n'.repeat(leadingNewlines) + scriptMatch[1];
   }
   return content;
 };

package/cli/audit/rules-registry.js

@@ -242,5 +242,15 @@ export const RULE_REGISTRY = {
     pillar: PILLARS.PILLAR_4,
     severity: 'MEDIUM',
     directive: 'Encapsulate flat primitive props into a cohesive domain type or composable'
+  },
+  LAYER_VIOLATION_CONTROLLER: {
+    pillar: PILLARS.PILLAR_4,
+    severity: 'CRITICAL',
+    directive: 'Do not inject DbContext or raw persistence into presentation controllers; route through MediatR/CQRS handlers'
+  },
+  COUPLING_EXCESSIVE_INJECTION: {
+    pillar: PILLARS.PILLAR_1,
+    severity: 'HIGH',
+    directive: 'Decompose high-coupling controllers; reduce injected services or route via MediatR'
   }
 };

package/cli/audit/rules.js

@@ -107,11 +107,11 @@ export const auditCode = (content, filePath, relativePath, options = {}) => {
   checkSlopTextPatterns(content, lines, relativePath, violations);
 
   // Pillars 8-11: Extended Fast Checks (A11y, Security secrets, Fake tests, Co-located specs)
-  checkExtendedTextPatterns(content, lines, relativePath, filePath, violations);
+  checkExtendedTextPatterns(content, lines, relativePath, filePath, violations, config);
 
   const lang = getLanguageForFile(filePath);
   if (lang?.id === 'csharp') {
-    analyzeCSharpCode(content, relativePath, violations);
+    analyzeCSharpCode(content, relativePath, violations, config);
   }
 
   if (options.fast || !isBabelParsable(filePath)) {

package/cli/audit.js

@@ -84,12 +84,12 @@ const IGNORED_DIRS = new Set([
   'out'
 ]);
 
-const isSourceFile = (name) => {
-  return isPolyglotSourceFile(name, { includeTests: false });
+const isSourceFile = (name, options = {}) => {
+  return isPolyglotSourceFile(name, { includeTests: false, ...options });
 };
 
 export const auditFile = (filePath, relativePath) => {
-  if (!isSourceFile(path.basename(filePath))) return [];
+  if (!isSourceFile(path.basename(filePath), { includeTests: true })) return [];
   const content = fs.readFileSync(filePath, 'utf-8');
   return auditCode(content, filePath, relativePath);
 };
@@ -125,12 +125,18 @@ export const scanTree = (targetDir, baseDir, scanOptions = {}) => {
   let fileStats = [];
   let totalHooks = 0;
 
+  const targetRel = path.relative(baseDir, targetDir);
+  const isTargetingTests = /(?:^|[\\/])(?:tests?|specs?)(?:[\\/]|$)/i.test(targetRel) ||
+    /(?:^|[\\/])(?:tests?|specs?)(?:[\\/]|$)/i.test(targetDir);
+  const includeTests = Boolean(scanOptions.includeTests || isTargetingTests);
+  const effectiveScanOptions = { ...scanOptions, includeTests };
+
   if (scanOptions.fileList && scanOptions.fileList.length > 0) {
     for (const item of scanOptions.fileList) {
       const fullPath = path.isAbsolute(item) ? item : path.resolve(baseDir, item);
       const relPath = path.relative(baseDir, fullPath);
-      if (fs.existsSync(fullPath) && isSourceFile(path.basename(fullPath))) {
-        const result = auditFileEntry(fullPath, relPath, scanOptions);
+      if (fs.existsSync(fullPath) && isSourceFile(path.basename(fullPath), { includeTests: true })) {
+        const result = auditFileEntry(fullPath, relPath, effectiveScanOptions);
         violations = violations.concat(result.fileViolations);
         fileStats.push(result.fileStat);
         totalHooks += result.hookCount;
@@ -150,13 +156,13 @@ export const scanTree = (targetDir, baseDir, scanOptions = {}) => {
 
     if (entry.isDirectory()) {
       if (!IGNORED_DIRS.has(entry.name)) {
-        const sub = scanTree(fullPath, baseDir, scanOptions);
+        const sub = scanTree(fullPath, baseDir, effectiveScanOptions);
         violations = violations.concat(sub.violations);
         fileStats = fileStats.concat(sub.fileStats);
         totalHooks += sub.totalHooks;
       }
-    } else if (isSourceFile(entry.name)) {
-      const result = auditFileEntry(fullPath, relPath, scanOptions);
+    } else if (isSourceFile(entry.name, { includeTests })) {
+      const result = auditFileEntry(fullPath, relPath, effectiveScanOptions);
       violations = violations.concat(result.fileViolations);
       fileStats.push(result.fileStat);
       totalHooks += result.hookCount;
@@ -177,11 +183,13 @@ export const runAudit = (targetDir = 'src', options = {}) => {
   const patternRegistry = createPatternRegistry();
   const hookRegistry = createHookShapeRegistry();
   const config = options.config || loadProjectConfig(cwd);
+  const includeTests = Boolean(options.includeTests);
   const { violations, fileStats, totalHooks } = scanTree(absoluteTarget, cwd, {
     patternRegistry,
     hookRegistry,
     fast: Boolean(options.fast),
     fileList: options.fileList || null,
+    includeTests,
     config
   });
 

package/cli/commands/cmd-audit.js

@@ -101,7 +101,8 @@ export const runAudit = async (customDir, isCli, rawArgs, loadProjectConfig) =>
     fileList = preflight.fileList;
   }
 
-  const auditOptions = { outputFile, model, costPerMillion, fast: isFast, fileList, stage, config: projectConfig };
+  const includeTests = rawArgs.includes('--include-tests') || rawArgs.includes('--tests');
+  const auditOptions = { outputFile, model, costPerMillion, fast: isFast, fileList, stage, config: projectConfig, includeTests };
   const report = executeAstAudit(targetDir, auditOptions);
   saveAuditSnapshot(report);
   try {
@@ -112,7 +113,8 @@ export const runAudit = async (customDir, isCli, rawArgs, loadProjectConfig) =>
       const shouldTriage = !rawArgs.includes('--no-triage');
       if (shouldTriage) {
         const createdTasks = autoGenerateTasksFromAudit(syncRes.db, { cwd: process.cwd(), targetDir });
-        if (isCli && !isJson && createdTasks.length > 0) {
+        const shouldLogTriage = isCli && !isJson && createdTasks.length > 0;
+        if (shouldLogTriage) {
           process.stdout.write(`\x1b[32m✔\x1b[0m Auto-triage synchronized ${createdTasks.length} team task(s) in SQLite backlog.\n`);
         }
       }
@@ -141,8 +143,8 @@ export const runAudit = async (customDir, isCli, rawArgs, loadProjectConfig) =>
         }
       }
     }
-  } catch {
-    // Gracefully bypass indexing when database is readonly in sandboxed environment
+  } catch (err) {
+    if (process.env.DEBUG) process.stderr.write(`[debug] Indexing bypassed: ${err?.message}\n`);
   }
 
   // Stage 1: Atomic failure predicates

package/cli/config/loader.js

@@ -25,6 +25,7 @@ const normalizeRuleKeys = (rules = {}) => {
     'max-prop-count': 'maxPropCount',
     'prefer-design-tokens': 'preferDesignTokens',
     'enforce-file-length': 'enforceFileLength',
+    'enforce-colocated-tests': 'enforceColocatedTests',
     'rule-of-three-abstractions': 'ruleOfThreeAbstractions',
     'ai-slop-detection': 'aiSlopDetection',
     'max-line-count-warning': 'maxLineCountWarning'

package/cli/config/profiles.js

@@ -14,6 +14,7 @@ export const PROFILES = {
     maxPropCount: 7,
     preferDesignTokens: 'warning',
     enforceFileLength: false,
+    enforceColocatedTests: false,
     ruleOfThreeAbstractions: true,
     aiSlopDetection: 'critical',
     maxLineCountWarning: 250
@@ -28,6 +29,7 @@ export const PROFILES = {
     maxPropCount: 5,
     preferDesignTokens: 'error',
     enforceFileLength: true,
+    enforceColocatedTests: true,
     ruleOfThreeAbstractions: false,
     aiSlopDetection: 'critical',
     maxLineCountWarning: 100
@@ -42,6 +44,7 @@ export const PROFILES = {
     maxPropCount: 12,
     preferDesignTokens: 'off',
     enforceFileLength: false,
+    enforceColocatedTests: false,
     ruleOfThreeAbstractions: true,
     aiSlopDetection: 'medium',
     maxLineCountWarning: 500

package/cli/friction-fixes.spec.js

@@ -0,0 +1,96 @@
+import test from 'node:test';
+import assert from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import { handleChemx } from './mcp/tools.js';
+import { auditCode } from './audit/rules.js';
+
+test('Friction 1: team_task add and team task add persist task rows', async () => {
+  const resCmd = await handleChemx({ command: 'team task add CLI Task Test' });
+  assert.ok(resCmd && resCmd.id, 'Expected task object with id from team task add');
+  assert.strictEqual(resCmd.title, 'CLI Task Test');
+
+  const resCmd2 = await handleChemx({ command: 'team_task add Direct SubCmd Task' });
+  assert.ok(resCmd2 && resCmd2.id, 'Expected task object with id from team_task add');
+  assert.strictEqual(resCmd2.title, 'Direct SubCmd Task');
+
+  const resInfer = await handleChemx({ action: 'team_task', params: { title: 'Inferred Add Task' } });
+  assert.ok(resInfer && resInfer.id, 'Expected task object with id when title is given');
+  assert.strictEqual(resInfer.title, 'Inferred Add Task');
+});
+
+test('Friction 2: patch handles all parameter aliases and command strings', async () => {
+  const testFile = path.resolve('test-patch-spec.txt');
+  fs.writeFileSync(testFile, 'line 1\nOLD_STRING\nline 3\n');
+
+  try {
+    await handleChemx({ action: 'patch', params: { path: 'test-patch-spec.txt', target: 'OLD_STRING', replace: 'NEW_STRING_1' } });
+    assert.strictEqual(fs.readFileSync(testFile, 'utf8'), 'line 1\nNEW_STRING_1\nline 3\n');
+
+    await handleChemx({ action: 'patch', params: { path: 'test-patch-spec.txt', search: 'NEW_STRING_1', replacement: 'NEW_STRING_2' } });
+    assert.strictEqual(fs.readFileSync(testFile, 'utf8'), 'line 1\nNEW_STRING_2\nline 3\n');
+
+    await handleChemx({ action: 'patch', params: { path: 'test-patch-spec.txt', targetContent: 'NEW_STRING_2', replacementContent: 'FINAL_STRING' } });
+    assert.strictEqual(fs.readFileSync(testFile, 'utf8'), 'line 1\nFINAL_STRING\nline 3\n');
+  } finally {
+    if (fs.existsSync(testFile)) fs.unlinkSync(testFile);
+  }
+});
+
+test('Friction 3: Vue file AST line numbers match file line numbers exactly', () => {
+  const vueContent = [
+    '<template>',
+    '  <div>',
+    '    <p>Line 3</p>',
+    '    <p>Line 4</p>',
+    '    <p>Line 5</p>',
+    '    <p>Line 6</p>',
+    '    <p>Line 7</p>',
+    '    <p>Line 8</p>',
+    '    <p>Line 9</p>',
+    '    <p>Line 10</p>',
+    '  </div>',
+    '</template>',
+    '',
+    '<script setup lang="ts">',
+    'const cond = a && b && c;',
+    '</script>'
+  ].join('\n');
+
+  const recorded = [];
+  const fakeReg = { record: (type, sig, loc) => recorded.push({ type, sig, loc }) };
+  auditCode(vueContent, 'SampleVue.vue', 'SampleVue.vue', { patternRegistry: fakeReg });
+
+  const condRec = recorded.find((r) => r.type === 'PREDICATE_LOGIC');
+  assert.ok(condRec, 'Expected PREDICATE_LOGIC recorded');
+  assert.strictEqual(condRec.loc.line, 15, 'Expected condition on line 15');
+});
+
+test('Friction 4: HOOK_SATURATION excludes canonical controller return wrappers', () => {
+  const hookCode = [
+    'export function useMyComposable() {',
+    '  const a = useA();',
+    '  const b = useB();',
+    '  const c = useC();',
+    '  const d = useD();',
+    '  const e = useE();',
+    '  return useSharedStatusController({ a, b, c, d, e });',
+    '}'
+  ].join('\n');
+
+  const hookViolations = auditCode(hookCode, 'useMyComposable.ts', 'src/useMyComposable.ts');
+  const hookSat = hookViolations.filter((v) => v.rule === 'HOOK_SATURATION');
+  assert.strictEqual(hookSat.length, 0, 'useSharedStatusController should not trigger HOOK_SATURATION');
+});
+
+test('Friction 5: TEST_MISSING_COLOCATED is gated by profile', () => {
+  const compCode = '<template><button>Click</button></template>';
+
+  const defaultViolations = auditCode(compCode, 'src/components/molecules/m-button.vue', 'src/components/molecules/m-button.vue', { config: { profile: 'pragmatic' } });
+  const testMissingDefault = defaultViolations.filter((v) => v.rule === 'TEST_MISSING_COLOCATED');
+  assert.strictEqual(testMissingDefault.length, 0, 'Pragmatic profile should not flag TEST_MISSING_COLOCATED');
+
+  const strictViolations = auditCode(compCode, 'src/components/molecules/m-button.vue', 'src/components/molecules/m-button.vue', { config: { profile: 'atomic-strict' } });
+  const testMissingStrict = strictViolations.filter((v) => v.rule === 'TEST_MISSING_COLOCATED');
+  assert.strictEqual(testMissingStrict.length, 1, 'Atomic-strict profile should flag TEST_MISSING_COLOCATED');
+});

package/cli/installer-templates.js

@@ -62,27 +62,47 @@ MIN_SCORE="\${CHEMX_MIN_SCORE:-\${CONF_MIN_SCORE:-${minScore}}}"
 MAX_LINES="\${CHEMX_MAX_LINES:-\${CONF_MAX_LINES:-500}}"
 MAX_MOLECULE_LINES="\${CHEMX_MAX_MOLECULE_LINES:-\${CONF_MAX_MOL:-100}}"
 
-STAGED_FILES=\$(git diff --cached --name-only --diff-filter=ACM | grep -E '\\.(jsx?|tsx?|vue|svelte)\$' | grep -vE '(\\.(d\\.ts|min\\.|test\\.|spec\\.))')
+STAGED_FILES=\$(git diff --cached --name-only --diff-filter=ACM | grep -E '\\.(jsx?|tsx?|vue|svelte|cs|py|go)\$' | grep -vE '(\\.(d\\.ts|min\\.|test\\.|spec\\.))')
 [ -z "\$STAGED_FILES" ] && exit 0
 
 FAILED=0
 ERRORS=""
+EXCEEDED_FILES=""
 for F in \$STAGED_FILES; do
   [ ! -f "\$F" ] && continue
   L=\$(wc -l < "\$F" | tr -d ' ')
   case "\$F" in
     *molecules*|*/m-*|m-*)
-      [ "\$L" -gt "\$MAX_MOLECULE_LINES" ] && FAILED=1 && ERRORS="\${ERRORS}\\n  \${C_RED}✕\${C_RESET} \$F (\$L LOC > \$MAX_MOLECULE_LINES molecule limit)" ;;
+      if [ "\$L" -gt "\$MAX_MOLECULE_LINES" ]; then
+        FAILED=1
+        ERRORS="\${ERRORS}\\n  \${C_RED}✕\${C_RESET} \$F (\$L LOC > \$MAX_MOLECULE_LINES molecule limit)"
+        EXCEEDED_FILES="\${EXCEEDED_FILES}\\n- \$F (\$L LOC > \$MAX_MOLECULE_LINES limit)"
+      fi
+      ;;
     *)
-      [ "\$L" -gt "\$MAX_LINES" ] && FAILED=1 && ERRORS="\${ERRORS}\\n  \${C_RED}✕\${C_RESET} \$F (\$L LOC > \$MAX_LINES file budget)" ;;
+      if [ "\$L" -gt "\$MAX_LINES" ]; then
+        FAILED=1
+        ERRORS="\${ERRORS}\\n  \${C_RED}✕\${C_RESET} \$F (\$L LOC > \$MAX_LINES file budget)"
+        EXCEEDED_FILES="\${EXCEEDED_FILES}\\n- \$F (\$L LOC > \$MAX_LINES limit)"
+      fi
+      ;;
   esac
 done
 
 if [ "\$FAILED" -eq 1 ]; then
   printf "\\n%s%s[Chemical X] Commit Blocked: Staged files exceed architectural line budgets%s\\n" "\$C_BOLD" "\$C_RED" "\$C_RESET"
   printf "%b\\n\\n" "\$ERRORS"
-  printf "%sMonolithic files degrade AI context windows and cause hallucination loops.%s\\n" "\$C_YELLOW" "\$C_RESET"
-  printf "Decompose large files into single-purpose crystalline capsules or configure thresholds in .chemx/config.json before committing.\\n\\n"
+  printf "%s╭──────────────────────────────────────────────────────────────────────────╮%s\\n" "\$C_CYAN" "\$C_RESET"
+  printf "%s│ 🤖 AI REFACTOR PROMPT (Copy & paste into your AI assistant):            │%s\\n" "\$C_CYAN" "\$C_RESET"
+  printf "%s╰──────────────────────────────────────────────────────────────────────────╯%s\\n" "\$C_CYAN" "\$C_RESET"
+  printf "Please refactor the following files that exceed Chemical X line budgets:%b\\n\\n" "\$EXCEEDED_FILES"
+  printf "Refactor Directives:\\n"
+  printf "1. Decompose monolithic logic into crystalline single-purpose modules (< %s lines for files, < %s lines for molecules).\\n" "\$MAX_LINES" "\$MAX_MOLECULE_LINES"
+  printf "2. Extract presentation into Table-of-Contents views and business state into composables/services.\\n"
+  printf "3. Preserve all existing symbols, exports, and public API contracts.\\n"
+  printf "4. Decompose complex inline booleans and flatten nested control flow.\\n"
+  printf "%s────────────────────────────────────────────────────────────────────────────%s\\n\\n" "\$C_CYAN" "\$C_RESET"
+  printf "%s💡 Tip: To bypass line budgets temporarily: CHEMX_SKIP_PRECOMMIT=1 git commit%s\\n\\n" "\$C_YELLOW" "\$C_RESET"
   exit 1
 fi
 
@@ -104,7 +124,18 @@ if [ -n "\$AUDIT_BIN" ]; then
   if ! AUDIT_OUT=\$(eval "\$AUDIT_BIN audit --git --min-grade=\$MIN_GRADE --min-score=\$MIN_SCORE --non-interactive" < /dev/null 2>&1); then
     printf "\\n%s%s[Chemical X] Commit Blocked: Architectural health verification failed%s\\n" "\$C_BOLD" "\$C_RED" "\$C_RESET"
     printf "%s\\n\\n" "\$AUDIT_OUT"
-    printf "%s💡 Tip: Want crystalline drop-in templates? Run 'npm create chemx' or sponsor at https://github.com/sponsors/Chemical-X-Protocol%s\\n\\n" "\$C_CYAN" "\$C_RESET"
+    printf "%s╭──────────────────────────────────────────────────────────────────────────╮%s\\n" "\$C_CYAN" "\$C_RESET"
+    printf "%s│ 🤖 AI REFACTOR PROMPT (Copy & paste into your AI assistant):            │%s\\n" "\$C_CYAN" "\$C_RESET"
+    printf "%s╰──────────────────────────────────────────────────────────────────────────╯%s\\n" "\$C_CYAN" "\$C_RESET"
+    printf "Please fix the Chemical X architectural hazards reported above in staged files.\\n\\n"
+    printf "Refactor Directives:\\n"
+    printf "1. Surgically resolve each flagged Critical and High severity hazard.\\n"
+    printf "2. Decompose monoliths into single-purpose crystalline capsules.\\n"
+    printf "3. Preserve all existing symbols, exports, and test contracts.\\n"
+    printf "4. Verify with 'chemx audit' after making changes.\\n"
+    printf "%s────────────────────────────────────────────────────────────────────────────%s\\n\\n" "\$C_CYAN" "\$C_RESET"
+    printf "%s💡 Tip: Run 'chemx audit' locally to inspect details or run autofixes.%s\\n" "\$C_CYAN" "\$C_RESET"
+    printf "   To bypass this check temporarily: CHEMX_SKIP_PRECOMMIT=1 git commit\\n\\n"
     exit 1
   fi
 fi

package/cli/mcp/manifests.js

@@ -303,10 +303,15 @@ export const SUB_TOOLS = [
       properties: {
         path: { type: 'string', description: 'Target file path' },
         targetContent: { type: 'string', description: 'Exact string chunk to replace' },
+        target: { type: 'string', description: 'Alias for target text chunk to replace' },
+        search: { type: 'string', description: 'Alias for target text chunk to replace' },
         replacementContent: { type: 'string', description: 'New replacement content' },
-        allowMultiple: { type: 'boolean', description: 'Allow multiple replacements' }
+        replacement: { type: 'string', description: 'Alias for replacement content' },
+        replace: { type: 'string', description: 'Alias for replacement content' },
+        allowMultiple: { type: 'boolean', description: 'Allow multiple replacements' },
+        multiple: { type: 'boolean', description: 'Alias for allowMultiple' }
       },
-      required: ['path', 'targetContent', 'replacementContent']
+      required: ['path']
     }
   },
   {

package/cli/mcp/tools-patch.js

@@ -2,6 +2,7 @@ import path from 'node:path';
 import { syncSingleFileIndex } from '../search.js';
 import { patchFile } from '../patcher.js';
 import { handleCheckCommand } from '../search-commands.js';
+import { resolveSafePath } from '../path-scope.js';
 
 export const isSevereViolation = (v) => {
   const isCritical = v.severity === 'CRITICAL';
@@ -36,10 +37,10 @@ export const handleChemxPatch = (args = {}, cwd = process.cwd()) => {
   const hasRequiredArgs = hasPath && hasTargetContent && hasReplacementContent;
 
   if (!hasRequiredArgs) {
-    throw new Error('chemx_patch requires "path", "targetContent", and "replacementContent" arguments.');
+    throw new Error('chemx_patch requires "path", target content ("targetContent", "target", or "search"), and replacement content ("replacementContent", "replacement", or "replace").');
   }
 
-  const targetPath = path.isAbsolute(args.path) ? args.path : path.resolve(cwd, args.path);
+  const targetPath = resolveSafePath(args.path, cwd);
   const result = patchFile(targetPath, {
     targetContent,
     replacementContent,
@@ -69,6 +70,6 @@ export const handleChemxCheck = (args = {}, cwd = process.cwd()) => {
   if (!args.path) {
     throw new Error('chemx_check requires "path" argument.');
   }
-  const targetPath = path.isAbsolute(args.path) ? args.path : path.resolve(cwd, args.path);
+  const targetPath = resolveSafePath(args.path, cwd);
   return handleCheckCommand(targetPath, { isJson: true, isCli: false });
 };

package/cli/mcp/tools-read.js

@@ -6,6 +6,7 @@ import {
 } from '../search-queries.js';
 import { findSimilarSymbols } from '../search-queries-similar.js';
 import { readTokenOptimized } from '../reader.js';
+import { resolveSafePath } from '../path-scope.js';
 import { EXT_LANG_MAP, resolveTargetCwd } from './tools-search-util.js';
 
 const buildConnectionCard = (db, symbol, targetPath) => {
@@ -72,8 +73,9 @@ export const handleChemxRead = (args = {}, cwd = process.cwd()) => {
     if (endLine === undefined && colonMatch[3]) endLine = parseInt(colonMatch[3], 10);
   }
 
-  const targetPath = path.isAbsolute(rawPath) ? rawPath : path.resolve(targetCwd, rawPath);
+  const targetPath = resolveSafePath(rawPath, targetCwd);
   const res = readTokenOptimized(targetPath, {
+    cwd: targetCwd,
     outline: args.outline,
     logic: args.logic,
     template: args.template,

package/cli/mcp/tools-team-locks.js

@@ -6,23 +6,30 @@ import {
   getFileLockStatus
 } from '../team/team-db.js';
 import { handleError } from '../errors/index.js';
+import { isPathTraversal } from '../path-scope.js';
 
 export const handleChemxTeamLock = async (args = {}, cwd = process.cwd()) => {
   const db = openIndexDb(cwd);
   if (!db) return { error: 'sqlite_unavailable' };
   const action = args.action || 'status';
 
+  if (args.filePath && isPathTraversal(args.filePath, cwd)) {
+    return { error: 'path_traversal' };
+  }
+
   if (action === 'acquire') {
     return requestFileLock(db, args.filePath, args.agentId, {
       purpose: args.purpose,
-      ttlMs: args.ttlMs
+      ttlMs: args.ttlMs,
+      cwd
     });
   }
   if (action === 'release') {
-    return releaseFileLock(db, args.filePath, args.agentId);
+    return releaseFileLock(db, args.filePath, args.agentId, { cwd });
   }
   if (action === 'status') {
-    const status = getFileLockStatus(db, args.filePath);
+    const status = getFileLockStatus(db, args.filePath, { cwd });
+    if (!status) return null;
     return {
       lease: status.lease,
       waiters: toColumnar(status.waiters, ['id', 'agent_id', 'priority', 'status', 'requested_at'])

package/cli/mcp/tools-team-tasks.js

@@ -12,7 +12,10 @@ import { freezeReleaseTrain } from '../team/team-release-train.js';
 export const handleChemxTeamTask = async (args = {}, cwd = process.cwd()) => {
   const db = openIndexDb(cwd);
   if (!db) return { error: 'sqlite_unavailable' };
-  const action = args.action || args.subAction || 'list';
+  let action = args.action || args.subAction;
+  if (!action) {
+    action = Boolean(args.title) ? 'add' : 'list';
+  }
 
   if (action === 'list') {
     const parentId = args.parentId !== undefined ? args.parentId : args.parent;
@@ -53,7 +56,7 @@ export const handleChemxTeamTask = async (args = {}, cwd = process.cwd()) => {
     const parentId = args.parentId !== undefined ? args.parentId : args.parent;
     const task = createTask(db, {
       title: args.title,
-      target_path: args.targetPath,
+      target_path: args.targetPath || args.target,
       tier: args.tier || 'molecule',
       priority: args.priority || 2,
       assigned_agent_id: args.assignedAgentId || null,

package/cli/mcp/tools-write.js

@@ -2,6 +2,7 @@ import path from 'node:path';
 import { syncSingleFileIndex } from '../search.js';
 import { writeFile } from '../patcher.js';
 import { formatPatchWarnings } from './tools-patch.js';
+import { resolveSafePath } from '../path-scope.js';
 
 export const handleChemxWrite = (args = {}, cwd = process.cwd()) => {
   const hasPath = Boolean(args.path);
@@ -12,7 +13,7 @@ export const handleChemxWrite = (args = {}, cwd = process.cwd()) => {
     throw new Error('chemx_write requires "path" and "content" arguments.');
   }
 
-  const targetPath = path.isAbsolute(args.path) ? args.path : path.resolve(cwd, args.path);
+  const targetPath = resolveSafePath(args.path, cwd);
   const result = writeFile(targetPath, {
     content: args.content,
     cwd

package/cli/mcp/tools.js

@@ -76,10 +76,53 @@ const parseCommand = (command, params) => {
       }
     };
   }
+  if (subCmd === 'patch') {
+    return {
+      action: 'patch',
+      params: {
+        path: parts[1] || params?.path,
+        target: params?.target || params?.targetContent || params?.search,
+        replacement: params?.replacement || params?.replacementContent || params?.replace,
+        ...params
+      }
+    };
+  }
   if (subCmd === 'q' || subCmd === 'search') return { action: 'q', params: { query: parts.slice(1).join(' '), ...params } };
   if (subCmd === 'team') {
     const TEAM_ACTIONS = { status: 'team_status', feed: 'team_feed', task: 'team_task', lock: 'team_lock', inbox: 'team_inbox', dm: 'team_dm' };
-    return { action: TEAM_ACTIONS[parts[1] || 'status'] || 'team_task', params };
+    const sub = parts[1] || 'status';
+    const action = TEAM_ACTIONS[sub] || 'team_task';
+    const parsedParams = { ...params };
+    const isTaskSub = sub === 'task' || !TEAM_ACTIONS[parts[1]];
+    if (isTaskSub) {
+      const taskSub = TEAM_ACTIONS[parts[1]] ? parts[2] : parts[1];
+      const isCreate = ['add', 'create', 'new'].includes(taskSub);
+      if (isCreate) {
+        parsedParams.subAction = 'add';
+        const titleTokens = parts.slice(TEAM_ACTIONS[parts[1]] ? 3 : 2);
+        if (titleTokens.length > 0 && !parsedParams.title) {
+          parsedParams.title = titleTokens.join(' ').replace(/^["']|["']$/g, '');
+        }
+      } else if (taskSub) {
+        parsedParams.subAction = taskSub;
+      }
+    }
+    return { action, params: parsedParams };
+  }
+  if (subCmd === 'team_task') {
+    const parsedParams = { ...params };
+    const taskSub = parts[1];
+    const isCreate = ['add', 'create', 'new'].includes(taskSub);
+    if (isCreate) {
+      parsedParams.subAction = 'add';
+      const titleTokens = parts.slice(2);
+      if (titleTokens.length > 0 && !parsedParams.title) {
+        parsedParams.title = titleTokens.join(' ').replace(/^["']|["']$/g, '');
+      }
+    } else if (taskSub) {
+      parsedParams.subAction = taskSub;
+    }
+    return { action: 'team_task', params: parsedParams };
   }
   if (subCmd === 'project' || subCmd === 'coordinator') {
     const subAction = parts[1] || 'status';

package/cli/patcher.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { ANSI } from './theme.js';
 import { syncSingleFileIndex } from './search.js';
 import { auditFile } from './audit.js';
+import { resolveSafePath } from './path-scope.js';
 
 /**
  * Surgically applies a search-and-replace block to a file.
@@ -37,7 +38,7 @@ export const patchFile = (targetPath, params = {}) => {
     throw new Error('replacementContent is required for patching');
   }
 
-  const resolvedPath = path.resolve(cwd, targetPath);
+  const resolvedPath = resolveSafePath(targetPath, cwd);
   if (!fs.existsSync(resolvedPath)) {
     throw new Error(`File not found: ${targetPath}`);
   }
@@ -253,7 +254,7 @@ export const writeFile = (targetPath, params = {}) => {
     throw new Error('content is required for writeFile');
   }
 
-  const resolvedPath = path.resolve(cwd, targetPath);
+  const resolvedPath = resolveSafePath(targetPath, cwd);
   const dir = path.dirname(resolvedPath);
   if (!fs.existsSync(dir)) {
     fs.mkdirSync(dir, { recursive: true });