@chemx/starter-kit 26.9.17-309 → 26.9.17-606

package/cli/audit/rules.spec.js

@@ -0,0 +1,205 @@
+import test from "node:test";
+import assert from "node:assert";
+import { auditCode } from "./rules.js";
+
+test("Audit Rules: flags repetitive dispatch switch statement as CONTROL_FLOW_DISPATCH_SWITCH", () => {
+  const code = `
+export const resolveColor = (type) => {
+  switch (type) {
+    case "primary":
+      return "blue";
+    case "secondary":
+      return "gray";
+    case "danger":
+      return "red";
+    case "warning":
+      return "yellow";
+    default:
+      return "white";
+  }
+};
+`;
+
+  const violations = auditCode(code, "src/utils/colors.js", "src/utils/colors.js");
+  const dispatchViolation = violations.find((v) => v.rule === "CONTROL_FLOW_DISPATCH_SWITCH");
+  assert.ok(dispatchViolation, "Expected CONTROL_FLOW_DISPATCH_SWITCH violation");
+  assert.strictEqual(dispatchViolation.severity, "MEDIUM");
+  assert.ok(dispatchViolation.hazard.includes("Dispatch switch smell detected"));
+});
+
+test("Audit Rules: does NOT flag non-dispatch complex switch statements", () => {
+  const code = `
+export const processOrder = (status, order) => {
+  switch (status) {
+    case "pending": {
+      validatePayment(order);
+      sendNotification(order.userId);
+      return queueForFulfillment(order);
+    }
+    case "completed": {
+      archiveOrder(order);
+      emitAnalytics("order_completed", order);
+      break;
+    }
+    default:
+      throw new Error("Invalid status");
+  }
+};
+`;
+
+  const violations = auditCode(code, "src/order.js", "src/order.js");
+  const dispatchViolation = violations.find((v) => v.rule === "CONTROL_FLOW_DISPATCH_SWITCH");
+  assert.strictEqual(dispatchViolation, undefined, "Complex switch should not be flagged as dispatch smell");
+});
+
+test("Audit Rules: clean keyed map implementation produces 0 violations", () => {
+  const code = `
+const COLOR_MAP = {
+  primary: "blue",
+  secondary: "gray",
+  danger: "red",
+  warning: "yellow"
+};
+
+export const resolveColor = (type) => {
+  return Object.prototype.hasOwnProperty.call(COLOR_MAP, type) ? COLOR_MAP[type] : "white";
+};
+`;
+
+  const violations = auditCode(code, "src/utils/colors.js", "src/utils/colors.js");
+  const dispatchViolation = violations.find((v) => v.rule === "CONTROL_FLOW_DISPATCH_SWITCH");
+  assert.strictEqual(dispatchViolation, undefined);
+});
+
+test("Audit Security: flags external link target=_blank missing rel=noopener noreferrer in JSX", () => {
+  const code = `
+export const ExternalLink = () => (
+  <a href="https://example.com" target="_blank">External</a>
+);
+`;
+  const violations = auditCode(code, "src/Link.tsx", "src/Link.tsx");
+  const violation = violations.find((v) => v.rule === "SECURITY_REVERSE_TABNABBING");
+  assert.ok(violation, "Expected SECURITY_REVERSE_TABNABBING violation in JSX");
+  assert.strictEqual(violation.severity, "MEDIUM");
+});
+
+test("Audit Security: passes external link with rel=noopener noreferrer in JSX", () => {
+  const code = `
+export const ExternalLink = () => (
+  <a href="https://example.com" target="_blank" rel="noopener noreferrer">External</a>
+);
+`;
+  const violations = auditCode(code, "src/Link.tsx", "src/Link.tsx");
+  const violation = violations.find((v) => v.rule === "SECURITY_REVERSE_TABNABBING");
+  assert.strictEqual(violation, undefined);
+});
+
+test("Audit Security: flags target=_blank missing rel in Vue template", () => {
+  const code = `
+<template>
+  <a href="https://example.com" target="_blank">External</a>
+</template>
+`;
+  const violations = auditCode(code, "src/Link.vue", "src/Link.vue");
+  const violation = violations.find((v) => v.rule === "SECURITY_REVERSE_TABNABBING");
+  assert.ok(violation, "Expected SECURITY_REVERSE_TABNABBING in Vue template");
+});
+
+test("Audit Security: flags javascript: pseudo-protocol in JSX href", () => {
+  const code = `
+export const BadLink = () => (
+  <a href="javascript:alert(1)">Click Me</a>
+);
+`;
+  const violations = auditCode(code, "src/BadLink.tsx", "src/BadLink.tsx");
+  const violation = violations.find((v) => v.rule === "SECURITY_JAVASCRIPT_URL");
+  assert.ok(violation, "Expected SECURITY_JAVASCRIPT_URL violation");
+  assert.strictEqual(violation.severity, "CRITICAL");
+});
+
+test("Audit Security: flags javascript: in template attributes", () => {
+  const code = `
+<template>
+  <form action="javascript:void(0)">
+    <button type="submit">Submit</button>
+  </form>
+</template>
+`;
+  const violations = auditCode(code, "src/Form.vue", "src/Form.vue");
+  const violation = violations.find((v) => v.rule === "SECURITY_JAVASCRIPT_URL");
+  assert.ok(violation, "Expected SECURITY_JAVASCRIPT_URL in template");
+});
+
+test("Audit Security: flags dynamic code execution via eval()", () => {
+  const code = `
+export const runDynamic = (str: string) => {
+  return eval(str);
+};
+`;
+  const violations = auditCode(code, "src/eval.ts", "src/eval.ts");
+  const violation = violations.find((v) => v.rule === "SECURITY_DYNAMIC_CODE_EXECUTION");
+  assert.ok(violation, "Expected SECURITY_DYNAMIC_CODE_EXECUTION for eval()");
+  assert.strictEqual(violation.severity, "CRITICAL");
+});
+
+test("Audit Security: flags dynamic code execution via new Function()", () => {
+  const code = `
+export const buildFn = (code: string) => {
+  return new Function("return " + code);
+};
+`;
+  const violations = auditCode(code, "src/fn.ts", "src/fn.ts");
+  const violation = violations.find((v) => v.rule === "SECURITY_DYNAMIC_CODE_EXECUTION");
+  assert.ok(violation, "Expected SECURITY_DYNAMIC_CODE_EXECUTION for new Function()");
+  assert.strictEqual(violation.severity, "CRITICAL");
+});
+
+test("Audit Security: flags string-based execution in setTimeout", () => {
+  const code = `
+export const scheduleCode = () => {
+  setTimeout("alert('hello')", 1000);
+};
+`;
+  const violations = auditCode(code, "src/timer.ts", "src/timer.ts");
+  const violation = violations.find((v) => v.rule === "SECURITY_DYNAMIC_CODE_EXECUTION");
+  assert.ok(violation, "Expected SECURITY_DYNAMIC_CODE_EXECUTION for string setTimeout");
+});
+
+test("Audit Security: does NOT flag function callback setTimeout", () => {
+  const code = `
+export const scheduleCode = () => {
+  const timer = setTimeout(() => {
+    // legitimate callback
+  }, 1000);
+  return () => clearTimeout(timer);
+};
+`;
+  const violations = auditCode(code, "src/timer.ts", "src/timer.ts");
+  const violation = violations.find((v) => v.rule === "SECURITY_DYNAMIC_CODE_EXECUTION");
+  assert.strictEqual(violation, undefined);
+});
+
+test("Audit Security: flags sensitive variable logging in console", () => {
+  const code = `
+export const debugAuth = (authToken: string, user: any) => {
+  console.log("Authenticated with token:", authToken);
+  console.info("User details:", { password: user.password });
+};
+`;
+  const violations = auditCode(code, "src/auth.ts", "src/auth.ts");
+  const loggingViolations = violations.filter((v) => v.rule === "SECURITY_SENSITIVE_LOGGING");
+  assert.strictEqual(loggingViolations.length >= 1, true, "Expected SECURITY_SENSITIVE_LOGGING violation");
+  assert.strictEqual(loggingViolations[0].severity, "HIGH");
+});
+
+test("Audit Security: does NOT flag normal non-sensitive console logging", () => {
+  const code = `
+export const debugCount = (itemCount: number) => {
+  console.log("Items rendered:", itemCount);
+};
+`;
+  const violations = auditCode(code, "src/items.ts", "src/items.ts");
+  const violation = violations.find((v) => v.rule === "SECURITY_SENSITIVE_LOGGING");
+  assert.strictEqual(violation, undefined);
+});
+

package/cli/build.d.ts

@@ -2,7 +2,8 @@ import type { BuildAuditReport, BuildOptions } from './build/types.js';
 
 export function runBuildAudit(
   rawArgs?: readonly string[],
-  isCli?: boolean
+  isCli?: boolean,
+  options?: { readonly print?: boolean; readonly silent?: boolean }
 ): Promise<BuildAuditReport>;
 
 export {

package/cli/build.js

@@ -20,16 +20,17 @@ const parseCommandFromArgs = (args) => {
   return candidate ? candidate.trim() : null;
 };
 
-export const runBuildAudit = async (rawArgs = [], isCli = false) => {
+export const runBuildAudit = async (rawArgs = [], isCli = false, options = {}) => {
   const isJson = rawArgs.includes('--json');
-  const isSilent = rawArgs.includes('--silent');
+  const isSilent = rawArgs.includes('--silent') || options.silent === true;
   const isRaw = rawArgs.includes('--raw');
   const isSummary = rawArgs.includes('--summary');
+  const shouldPrint = options.print !== false;
 
   const customCommand = parseCommandFromArgs(rawArgs);
   const command = detectProjectBuildCommand(customCommand, process.cwd());
 
-  const shouldPrintStart = !isJson && !isSilent && !isRaw;
+  const shouldPrintStart = shouldPrint && !isJson && !isSilent && !isRaw;
   if (shouldPrintStart) {
     process.stdout.write(`${ANSI.CYAN}Auditing build:${ANSI.RESET} ${ANSI.DIM}${command}${ANSI.RESET}\n`);
   }
@@ -39,13 +40,15 @@ export const runBuildAudit = async (rawArgs = [], isCli = false) => {
   const report = groupBuildDiagnostics(rawDiagnostics, executionResult);
 
   if (isJson) {
-    process.stdout.write(formatJsonBuildReport(report) + '\n');
+    if (shouldPrint) {
+      process.stdout.write(formatJsonBuildReport(report) + '\n');
+    }
     if (isCli) process.exit(report.exitCode);
     return report;
   }
 
   const terminalOutput = formatTerminalBuildReport(report, { silent: isSilent, summary: isSummary });
-  if (terminalOutput) {
+  if (terminalOutput && shouldPrint) {
     process.stdout.write(terminalOutput);
   }
 

package/cli/columnar.d.ts

@@ -0,0 +1,14 @@
+export interface ColumnarData<T = any> {
+  readonly cols: readonly string[];
+  readonly rows: readonly T[][];
+}
+
+export declare function toColumnar<T extends Record<string, any>>(
+  items?: readonly T[],
+  cols?: readonly string[],
+  accessors?: Record<string, (item: T) => any>
+): ColumnarData;
+
+export declare function fromColumnar<T extends Record<string, any>>(
+  columnar?: ColumnarData
+): readonly T[];

package/cli/columnar.js

@@ -0,0 +1,52 @@
+/**
+ * Chemical X Protocol: Columnar Serialization Utility
+ * Converts object collections into compact single-schema matrices
+ * to eliminate repeated dictionary keys and slash token consumption.
+ */
+
+/**
+ * Transforms an array of objects into a single-schema columnar structure.
+ *
+ * @param {readonly object[]} items Array of record objects.
+ * @param {readonly string[]} cols Column names to extract.
+ * @param {Record<string, (item: any) => any>} [accessors={}] Optional field transformers.
+ * @returns {{ cols: readonly string[], rows: readonly any[][] }}
+ */
+export const toColumnar = (items = [], cols = [], accessors = {}) => {
+  if (!items || items.length === 0) {
+    return { cols, rows: [] };
+  }
+
+  const rows = items.map((item) => {
+    return cols.map((col) => {
+      const accessor = accessors[col];
+      if (typeof accessor === 'function') {
+        return accessor(item);
+      }
+      return item[col];
+    });
+  });
+
+  return { cols, rows };
+};
+
+/**
+ * Reconstructs an array of objects from a columnar structure.
+ *
+ * @param {{ cols: readonly string[], rows: readonly any[][] }} columnar
+ * @returns {readonly Record<string, any>[]}
+ */
+export const fromColumnar = (columnar) => {
+  if (!columnar || !columnar.cols || !columnar.rows) {
+    return [];
+  }
+
+  const { cols, rows } = columnar;
+  return rows.map((row) => {
+    const obj = {};
+    cols.forEach((col, idx) => {
+      obj[col] = row[idx];
+    });
+    return obj;
+  });
+};

package/cli/columnar.spec.js

@@ -0,0 +1,49 @@
+import test from 'node:test';
+import assert from 'node:assert';
+import { toColumnar, fromColumnar } from './columnar.js';
+
+test('toColumnar: converts array of objects into cols and rows', () => {
+  const items = [
+    { file: 'src/a.ts', tier: 'atom', lines: 40 },
+    { file: 'src/b.ts', tier: 'molecule', lines: 75 }
+  ];
+
+  const result = toColumnar(items, ['file', 'tier', 'lines']);
+
+  assert.deepStrictEqual(result.cols, ['file', 'tier', 'lines']);
+  assert.strictEqual(result.rows.length, 2);
+  assert.deepStrictEqual(result.rows[0], ['src/a.ts', 'atom', 40]);
+  assert.deepStrictEqual(result.rows[1], ['src/b.ts', 'molecule', 75]);
+});
+
+test('toColumnar: handles empty or missing arrays cleanly', () => {
+  assert.deepStrictEqual(toColumnar([], ['file', 'tier']), { cols: ['file', 'tier'], rows: [] });
+  assert.deepStrictEqual(toColumnar(null, ['file']), { cols: ['file'], rows: [] });
+});
+
+test('toColumnar: supports custom accessor functions for nested fields', () => {
+  const items = [
+    { file: 'src/card.vue', symbols: [{ name: 'UserCard' }, { name: 'CardBadge' }] }
+  ];
+
+  const result = toColumnar(items, ['file', 'symbols'], {
+    symbols: (item) => item.symbols.map((s) => s.name)
+  });
+
+  assert.deepStrictEqual(result.rows[0], ['src/card.vue', ['UserCard', 'CardBadge']]);
+});
+
+test('fromColumnar: reconstructs array of objects from columnar data', () => {
+  const columnar = {
+    cols: ['file', 'tier', 'lines'],
+    rows: [
+      ['src/a.ts', 'atom', 40],
+      ['src/b.ts', 'molecule', 75]
+    ]
+  };
+
+  const items = fromColumnar(columnar);
+  assert.strictEqual(items.length, 2);
+  assert.deepStrictEqual(items[0], { file: 'src/a.ts', tier: 'atom', lines: 40 });
+  assert.deepStrictEqual(items[1], { file: 'src/b.ts', tier: 'molecule', lines: 75 });
+});

package/cli/help.js

@@ -51,6 +51,25 @@ export const printHelp = () => {
     `      Flags: ${CYAN}--json${RESET}, ${CYAN}--silent${RESET}, ${CYAN}--raw${RESET}, ${CYAN}--summary${RESET}`,
     `      Examples: ${CYAN}npx chemx build${RESET} or ${CYAN}npx chemx build -- pnpm build${RESET}`,
     '',
+    `  ${CYAN}verify${RESET} [options]  ${DIM}(alias: check:all)${RESET}`,
+    `      Zero-token-burn project verification pipeline (AST Audit + Typecheck + Tests).`,
+    `      Runs all verification layers silently and emits a single summary card (~45 tokens if green).`,
+    `      AI agents should always run this instead of separate raw shell commands.`,
+    `      Flags: ${CYAN}--dir=<path>${RESET}, ${CYAN}--build${RESET}, ${CYAN}--json${RESET}`,
+    `      Examples: ${CYAN}npx chemx verify${RESET} or ${CYAN}npx chemx verify --json${RESET}`,
+    '',
+    `  ${CYAN}typecheck${RESET} [options] [-- <command>]  ${DIM}(aliases: check:types, tsc)${RESET}`,
+    `      Silent TypeScript typecheck audit. Drops compiler noise and returns structured`,
+    `      file, line, code, and suggestion metadata only if errors exist. Zero noise when clean.`,
+    `      Flags: ${CYAN}--json${RESET}, ${CYAN}--raw${RESET}`,
+    `      Examples: ${CYAN}npx chemx typecheck${RESET} or ${CYAN}npx chemx typecheck --json${RESET}`,
+    '',
+    `  ${CYAN}test${RESET} [options] [-- <command>]  ${DIM}(aliases: tests, check:test)${RESET}`,
+    `      Silent, failure-only project test runner. Suppresses hundreds of passing checkmarks`,
+    `      and runtime banners; emits ONLY failing test assertions and stack diffs.`,
+    `      Flags: ${CYAN}--json${RESET}, ${CYAN}--raw${RESET}`,
+    `      Examples: ${CYAN}npx chemx test${RESET} or ${CYAN}npx chemx test --json${RESET}`,
+    '',
     `  ${CYAN}audit${RESET} [options]`,
     `      Run the 7-Pillar Molecular Architecture static analysis audit.`,
     `      Scans AST for line budgets, control flow booleans, nested ternaries,`,
@@ -97,16 +116,22 @@ export const printHelp = () => {
     `  ${CYAN}mcp${RESET}  ${DIM}(aliases: mcp-server)${RESET}`,
     `      ${GREEN}[FREE]${RESET} Launch the Chemical X Model Context Protocol (MCP) server.`,
     `      Communicates via JSON-RPC 2.0 stdio with Cursor, Claude Desktop, Windsurf, and Antigravity.`,
-    `      Exposes 6 core tools (chemx_query_patterns, chemx_autofix, chemx_audit,`,
-    `      chemx_generate_capsule, chemx_get_refactor_prompt, chemx_audit_build),`,
-    `      living resources (chemx://directives, chemx://scorecard), and prompts.`,
+    `      Exposes 10 AST-aware tools:`,
+    `        • Discovery: chemx_query_patterns, chemx_q`,
+    `        • Reading & Patching: chemx_read, chemx_patch`,
+    `        • Verification: chemx_verify, chemx_typecheck, chemx_test, chemx_audit, chemx_check, chemx_audit_build`,
+    `        • Remediation: chemx_autofix, chemx_generate_capsule, chemx_get_refactor_prompt`,
+    `      Plus living resources (chemx://directives, chemx://scorecard) and prompts.`,
     `      Example: ${CYAN}npx chemx mcp${RESET}`,
     '',
     `  ${CYAN}install-mcp${RESET} [directory]  ${DIM}(aliases: setup-mcp)${RESET}`,
-    `      ${GREEN}[FREE]${RESET} Auto-configure Chemical X MCP server for your project and tools.`,
+    `      ${GREEN}[FREE]${RESET} Auto-configure Chemical X MCP server for your project and editors.`,
     `      Registers in .cursor/mcp.json, .vscode/mcp.json, and ~/.gemini/config/mcp_config.json.`,
     `      Example: ${CYAN}npx chemx install-mcp${RESET}`,
     '',
+    `  ${CYAN}--version${RESET}, ${CYAN}-v${RESET}, ${CYAN}version${RESET}`,
+    `      Display current Chemical X package version string.`,
+    '',
     `  ${CYAN}help${RESET}, ${CYAN}--help${RESET}, ${CYAN}-h${RESET}`,
     `      Display this comprehensive CLI documentation and options guide.`,
     '',

package/cli/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import './silence-warnings.js';
 import fs from 'node:fs';
 import path from 'node:path';
 import {
@@ -37,12 +38,24 @@ import { runBuildAudit } from './build.js';
 import { runSearch, syncSearchIndex, resolveTargetDir, syncViolationsIndex, recordAuditSnapshot, handleCheckCommand } from './search.js';
 import { runMutatorCli } from './mutators.js';
 import { runReaderCli, readTokenOptimized } from './reader.js';
-import { runPatcherCli, patchFile } from './patcher.js';
+import { runPatcherCli, patchFile, runWriterCli, writeFile } from './patcher.js';
 import { runMcpServer, runMcpInstaller } from './mcp/index.js';
+import { runTypecheckAudit, runTestAudit, runProjectVerify } from './verify.js';
 import { sanitizeOutputStreams } from './terminal.js';
 
 sanitizeOutputStreams();
 
+const getPackageVersion = () => {
+  try {
+    const pkgPath = new URL('../package.json', import.meta.url);
+    const pkgContent = fs.readFileSync(pkgPath, 'utf-8');
+    const pkg = JSON.parse(pkgContent);
+    return pkg.version || 'unknown';
+  } catch {
+    return 'unknown';
+  }
+};
+
 const rawArgs = process.argv.slice(2);
 const invokedBin = path.basename(process.argv[1] || '');
 const CAPSULE_PREFIXES = ['m-', 'a-', 'o-', 't-', 'use-', 'v-'];
@@ -131,11 +144,19 @@ export const runAudit = async (customDir = null, isCli = false) => {
     recordAuditSnapshot(syncRes.db, report);
   }
 
-  const hasCriticalOrHigh = report.violations.some((v) => v.severity === 'CRITICAL' || v.severity === 'HIGH');
-  const isStrictFail = isStrict && report.violations.length > 0;
+  const isSevereViolation = (v) => {
+    const isCritical = v.severity === 'CRITICAL';
+    const isHigh = v.severity === 'HIGH';
+    return isCritical || isHigh;
+  };
+
+  const hasCriticalOrHigh = report.violations.some(isSevereViolation);
+  const hasViolations = report.violations.length > 0;
+  const isStrictFail = isStrict && hasViolations;
   const isGradeFail = isGradeBelowMinimum(report.health.grade, minGrade);
-  const isScoreFail = minScore !== null && !isNaN(minScore) && report.health.score < minScore;
-  const hasThreshold = Boolean(minGrade) || (minScore !== null && !isNaN(minScore));
+  const hasMinScore = minScore !== null && !isNaN(minScore);
+  const isScoreFail = hasMinScore && report.health.score < minScore;
+  const hasThreshold = Boolean(minGrade) || hasMinScore;
   const isDefaultFail = !hasThreshold && !isStrict && hasCriticalOrHigh;
   const hasFailingViolations = evaluateAuditFailure([isStrictFail, isDefaultFail, isGradeFail, isScoreFail]);
 
@@ -239,7 +260,9 @@ export {
   runReaderCli,
   readTokenOptimized,
   runPatcherCli,
-  patchFile
+  patchFile,
+  runWriterCli,
+  writeFile
 };
 
 const main = async () => {
@@ -265,6 +288,9 @@ const main = async () => {
     case 'edit':
       runPatcherCli(rawArgs.slice(1), true);
       break;
+    case 'write':
+      runWriterCli(rawArgs.slice(1), true);
+      break;
     case 'search':
     case 'q':
     case 'query':
@@ -294,7 +320,6 @@ const main = async () => {
       await runInstallWizard(rawArgs[1] || process.cwd());
       break;
     case 'check':
-    case 'verify':
       handleCheckCommand(rawArgs[1], {
         isJson: rawArgs.includes('--json'),
         isCli: true
@@ -327,6 +352,25 @@ const main = async () => {
     case 'setup-mcp':
       await runMcpInstaller(rawArgs.slice(1));
       break;
+    case '-v':
+    case '--version':
+    case 'version':
+      process.stdout.write(`create-chemx v${getPackageVersion()}\n`);
+      break;
+    case 'verify':
+    case 'check:all':
+      await runProjectVerify(rawArgs.slice(1), true);
+      break;
+    case 'typecheck':
+    case 'check:types':
+    case 'tsc':
+      await runTypecheckAudit(rawArgs.slice(1), true);
+      break;
+    case 'test':
+    case 'tests':
+    case 'check:test':
+      await runTestAudit(rawArgs.slice(1), true);
+      break;
     case 'help':
     case '--help':
     case '-h':

package/cli/installer.js

@@ -105,8 +105,10 @@ export const installAgentSearchConfig = async (targetDir = '.') => {
       pkg.scripts = pkg.scripts || {};
       pkg.scripts.q = 'chemx search';
       pkg.scripts.search = 'chemx search';
+      pkg.scripts.verify = 'chemx verify';
+      pkg.scripts.check = 'chemx verify';
       fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
-      process.stdout.write('  \x1b[32m✔\x1b[0m Configured "q" and "search" scripts in package.json (run via pnpm q <query>)\n');
+      process.stdout.write('  \x1b[32m✔\x1b[0m Configured "q", "search", and "verify" scripts in package.json\n');
     } catch {
       process.stdout.write('  \x1b[33m⚠\x1b[0m Could not update package.json scripts\n');
     }
@@ -114,20 +116,35 @@ export const installAgentSearchConfig = async (targetDir = '.') => {
 
   // 2. Inject rule into AGENTS.md
   const agentsPath = path.join(resolvedTarget, 'AGENTS.md');
-  const searchDirective = `
+  const agentDirectives = `
 ## Chemical X Codebase Query Machine Protocol
 - Search First Rule: AI agents MUST invoke 'pnpm q "<query>"' (or 'npx chemx search "<query>"') before running broad ripgrep, find, or file dumping.
 - AST Architecture Intelligence: Always leverage 'pnpm q' to inspect component tiers, exported symbols, props, and hooks with minimal token burn.
-- Inspect Mode: Use 'pnpm q "<capsule-name>" --inspect' to examine props and hooks without catting entire source files.
+- Inspect Mode: Use 'pnpm q "<capsule-name>" --inspect' to examine props and hooks without reading entire source files.
 - JSON Mode: Use 'pnpm q "<query>" --json' for zero-overhead, machine-readable agent lookups.
+
+## Chemical X Verification-First Protocol & Zero-Token-Burn Pipeline
+- Verification First Rule: AI agents MUST NEVER run raw, unthrottled "npm test", "pnpm test", "vitest", "tsc --noEmit", or "npm run build" directly in a bash subshell.
+- MCP Verification Tools First: AI agents MUST invoke dedicated Chemical X MCP tools or CLI wrappers ('npx chemx verify', 'npx chemx test', 'npx chemx typecheck', 'npx chemx build') before running terminal commands.
 `;
 
   if (fs.existsSync(agentsPath)) {
     try {
       const content = fs.readFileSync(agentsPath, 'utf-8');
-      if (!content.includes('Chemical X Codebase Query Machine Protocol')) {
-        fs.appendFileSync(agentsPath, `\n${searchDirective}\n`, 'utf-8');
-        process.stdout.write('  \x1b[32m✔\x1b[0m Injected search-first directive into AGENTS.md\n');
+      const hasQueryProtocol = content.includes('Chemical X Codebase Query Machine Protocol');
+      const hasVerifyProtocol = content.includes('Chemical X Verification-First Protocol');
+
+      if (!hasQueryProtocol && !hasVerifyProtocol) {
+        fs.appendFileSync(agentsPath, `\n${agentDirectives}\n`, 'utf-8');
+        process.stdout.write('  \x1b[32m✔\x1b[0m Injected query and verification directives into AGENTS.md\n');
+      } else if (!hasVerifyProtocol) {
+        const verifyOnly = `
+## Chemical X Verification-First Protocol & Zero-Token-Burn Pipeline
+- Verification First Rule: AI agents MUST NEVER run raw, unthrottled "npm test", "pnpm test", "vitest", "tsc --noEmit", or "npm run build" directly in a bash subshell.
+- MCP Verification Tools First: AI agents MUST invoke dedicated Chemical X MCP tools or CLI wrappers ('npx chemx verify', 'npx chemx test', 'npx chemx typecheck', 'npx chemx build') before running terminal commands.
+`;
+        fs.appendFileSync(agentsPath, `\n${verifyOnly}\n`, 'utf-8');
+        process.stdout.write('  \x1b[32m✔\x1b[0m Injected verification-first directive into AGENTS.md\n');
       }
     } catch (err) {
       const error = err instanceof Error ? err : new Error(String(err));

package/cli/mcp/antigravity.js

@@ -0,0 +1,59 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { MCP_TOOLS } from './manifests.js';
+
+export const buildMcpInstructions = () => {
+  return [
+    '# Chemical X Protocol: Mandatory AI Agent Directives',
+    '',
+    'MANDATORY VERIFICATION & TOKEN CONSERVATION PROTOCOL:',
+    '1. NEVER execute raw, unthrottled "npm test", "pnpm test", "vitest", "tsc --noEmit", or "npm run build" in a bash shell. Raw execution floods context with hundreds of lines of passing checkmarks and compiler spam.',
+    '2. ALWAYS invoke Chemical X MCP tools or CLI wrappers first:',
+    '   - chemx_verify (or "npx chemx verify --json"): Complete AST Audit + Typecheck + Tests (~45 tokens if green).',
+    '   - chemx_typecheck (or "npx chemx typecheck --json"): Silent TypeScript audit; returns structured errors only.',
+    '   - chemx_test (or "npx chemx test --json"): Silent test runner; returns ONLY failing assertions and diffs.',
+    '   - chemx_audit_build (or "npx chemx build --json"): Silent build audit; categorizes errors by subsystem.',
+    '',
+    'AST SEARCH & SURGICAL EDITING PROTOCOL:',
+    '3. ALWAYS invoke chemx_q (or "pnpm q <query>") for AST symbol search before running broad ripgrep or find.',
+    '4. ALWAYS use chemx_read (with outline: true or symbol: "name") to inspect code structure without dumping entire files into context.',
+    '5. ALWAYS use chemx_patch for surgical file edits and chemx_check to verify molecular boundary compliance.',
+    '',
+    'MOLECULAR ARCHITECTURE GUARDRAILS:',
+    '6. 100-line outer bound per molecule capsule file. Never exceed.',
+    '7. Zero raw DOM elements in molecules or organisms: raw HTML tags are restricted exclusively to foundational atoms.',
+    '8. Two-stage atomic boolean composition: break multi-clause logic into named booleans before decision computeds.',
+    ''
+  ].join('\n');
+};
+
+export const syncAntigravityMcpSchemas = (customTargetDir = null, options = {}) => {
+  const isSilent = Boolean(options.silent);
+  const targetDir = customTargetDir || path.join(os.homedir(), '.gemini', 'antigravity', 'mcp', 'chemical-x');
+
+  if (!fs.existsSync(targetDir)) {
+    fs.mkdirSync(targetDir, { recursive: true });
+  }
+
+  let toolCount = 0;
+  for (const tool of MCP_TOOLS) {
+    const filePath = path.join(targetDir, `${tool.name}.json`);
+    const schema = JSON.stringify({
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.inputSchema
+    });
+    fs.writeFileSync(filePath, schema, 'utf-8');
+    toolCount += 1;
+  }
+
+  const instructionsPath = path.join(targetDir, 'instructions.md');
+  fs.writeFileSync(instructionsPath, buildMcpInstructions(), 'utf-8');
+
+  if (!isSilent) {
+    process.stdout.write(`  \x1b[32m✔\x1b[0m Synchronized ${toolCount} MCP tool schemas and instructions.md in: ${targetDir}\n`);
+  }
+
+  return { targetDir, toolCount, instructions: true };
+};

package/cli/mcp/index.js

@@ -1,5 +1,5 @@
 import { startStdioServer, createMcpHandler } from './server.js';
-import { MCP_TOOLS, executeMcpTool } from './tools.js';
+import { MCP_TOOLS, executeMcpTool, Tools } from './tools.js';
 import { MCP_RESOURCES, readMcpResource } from './resources.js';
 import { MCP_PROMPTS, getMcpPrompt } from './prompts.js';
 import {
@@ -27,6 +27,7 @@ export {
   startStdioServer,
   MCP_TOOLS,
   executeMcpTool,
+  Tools,
   MCP_RESOURCES,
   readMcpResource,
   MCP_PROMPTS,