@chemx/create-chemx 26.9.25-747 → 26.9.25-943

package/README.md

@@ -59,7 +59,7 @@ npx create-chemx my-molecular-app --framework=react --install --yes
 
 ### Package Architecture: Scaffolder vs Command Engine
 Chemical X provides two coordinated packages:
-- **`create-chemx`**: Dedicated zero-dependency project scaffolder (`npm create chemx`). Directly provisions project templates, test suites, and architectural configurations.
+- **`create-chemx`**: Dedicated zero-configuration project scaffolder (`npm create chemx`). Directly provisions project templates, test suites, and architectural configurations.
 - **`chemx`**: The full Molecular Architecture CLI & AST Query Engine. Manages audits, verifications, AST query lookups, code patching, and multi-agent swarm task coordination.
 
 ```bash
@@ -341,7 +341,7 @@ Chemical X enforces seven core architectural directives configured via `chemx pi
 
 ## Model Context Protocol (MCP) Server
 
-Chemical X includes a high-performance, zero-dependency JSON-RPC 2.0 Stdio MCP server that connects directly to AI agent hosts (Cursor, Claude Desktop, Windsurf, Antigravity, VS Code).
+Chemical X includes a high-performance, native Node.js JSON-RPC 2.0 Stdio MCP server that connects directly to AI agent hosts (Cursor, Claude Desktop, Windsurf, Antigravity, VS Code).
 
 ### Automatic 1-Step Installation
 

package/blueprints/molecule-capsule/m-sample-card.spec.ts

@@ -3,6 +3,12 @@ import React from 'react';
 import { renderToStaticMarkup } from 'react-dom/server';
 import { MSampleCard, resolveBadgeDescriptor } from './m-sample-card';
 
+interface TestElementProps {
+  children?: React.ReactElement<TestElementProps>[];
+  className?: string;
+  onClick?: () => void;
+}
+
 describe('m-sample-card: resolveBadgeDescriptor', () => {
   it('returns archived badge descriptor when status is archived', () => {
     const descriptor = resolveBadgeDescriptor('archived', false);
@@ -60,15 +66,15 @@ describe('m-sample-card: MSampleCard Component', () => {
       title: 'Actionable Unit',
       value: 1200,
       onAction: handleAction
-    }) as React.ReactElement;
+    }) as React.ReactElement<TestElementProps>;
 
-    const bodyNode = (vnode.props.children as React.ReactElement[])[1];
-    const buttonNode = (bodyNode.props.children as React.ReactElement[])[1];
+    const bodyNode = (vnode.props.children as React.ReactElement<TestElementProps>[])[1];
+    const buttonNode = (bodyNode.props.children as React.ReactElement<TestElementProps>[])[1];
 
     expect(buttonNode).toBeDefined();
     expect(buttonNode.props.className).toBe('m-sample-card__action');
 
-    buttonNode.props.onClick();
+    buttonNode.props.onClick?.();
     expect(handleAction).toHaveBeenCalledTimes(1);
   });
 });

package/cli/commands/cmd-router.js

@@ -94,12 +94,26 @@ export const dispatchCommand = async (firstArg, rawArgs, runAudit, getPackageVer
       break;
     }
     case 'init': {
+      const isHelpRequested = rawArgs.includes('--help') || rawArgs.includes('-h') || rawArgs[1] === 'help';
+      if (isHelpRequested) {
+        const { printInitHelp } = await import('../help.js');
+        printInitHelp();
+        break;
+      }
+      const nonFlagArgs = rawArgs.slice(1).filter((arg) => !arg.startsWith('-'));
+      const targetSubDir = nonFlagArgs[0] || 'src/chemical-x';
       const { runInit } = await import('../scaffold.js');
-      await runInit(rawArgs[1] || 'src/chemical-x', rawArgs, runAudit);
+      await runInit(targetSubDir, rawArgs, runAudit);
       break;
     }
     case 'create':
     case 'scaffold': {
+      const isHelpRequested = rawArgs.includes('--help') || rawArgs.includes('-h') || rawArgs[1] === 'help';
+      if (isHelpRequested) {
+        const { printScaffoldHelp } = await import('../help.js');
+        printScaffoldHelp();
+        break;
+      }
       const { runScaffold } = await import('../scaffold.js');
       const nonFlagArgs = rawArgs.slice(1).filter((arg) => !arg.startsWith('-'));
       await runScaffold(nonFlagArgs[0], rawArgs, runAudit);

package/cli/commands-schema.js

@@ -222,5 +222,41 @@ export const COMMANDS_SCHEMA = [
       'npx chemx tesseract',
       'npx chemx tesseract --json'
     ]
+  },
+  {
+    name: 'init',
+    aliases: [],
+    usage: 'npx chemx init [directory] [options]',
+    summary: 'Unpack blueprints and molecular architecture drop-in files into an existing codebase.',
+    description: 'Installs blueprints, domain hooks, and foundation capsules into target directory (default: src/chemical-x).',
+    flags: [
+      { flag: '-h, --help', desc: 'Show this help message' },
+      { flag: '--license=<key>', desc: 'Provide commercial license key for enterprise starter kit assets' }
+    ],
+    examples: [
+      'npx chemx init',
+      'npx chemx init src/chemical-x',
+      'npx chemx init packages/ui/src/modules'
+    ]
+  },
+  {
+    name: 'create',
+    aliases: ['scaffold'],
+    usage: 'npm create chemx [directory] [options]',
+    summary: 'Scaffold a complete new Chemical X Molecular Architecture application.',
+    description: 'Generates a full starter project configured with Chemical X molecular architecture, framework presets, and agent steering directives.',
+    flags: [
+      { flag: '--framework=<id>', desc: 'Framework flavor: react (default), vue, svelte' },
+      { flag: '--yes, -y', desc: 'Skip interactive prompts and scaffold Community Edition immediately' },
+      { flag: '--install', desc: 'Auto-install dependencies after scaffolding' },
+      { flag: '--headless', desc: 'Run in headless mode for CI/CD and AI agent automation' },
+      { flag: '-h, --help', desc: 'Show this help message' },
+      { flag: '-v, --version', desc: 'Show version number' }
+    ],
+    examples: [
+      'npm create chemx my-molecular-app --framework=react',
+      'npx create-chemx my-vue-app --framework=vue --yes',
+      'npx chemx create my-app --framework=svelte --install'
+    ]
   }
 ];

package/cli/help.d.ts

@@ -1 +1,3 @@
 export declare function printHelp(): void;
+export declare function printInitHelp(): void;
+export declare function printScaffoldHelp(): void;

package/cli/help.js

@@ -54,3 +54,67 @@ export const printHelp = () => {
 
   process.stdout.write(lines.join('\n'));
 };
+
+export const printInitHelp = () => {
+  renderBanner('Chemical X: In-Repo Capsule Drop-in (chemx init)');
+
+  const BOLD = '\x1b[1m';
+  const CYAN = '\x1b[36m';
+  const RESET = '\x1b[0m';
+
+  const lines = [
+    `${BOLD}USAGE${RESET}`,
+    `  ${CYAN}npx chemx init${RESET} [directory] [options]`,
+    '',
+    `${BOLD}DESCRIPTION${RESET}`,
+    '  Unpack Chemical X blueprints and molecular architecture drop-in files',
+    '  into an existing codebase (defaults to src/chemical-x).',
+    '',
+    `${BOLD}OPTIONS${RESET}`,
+    `  ${CYAN}-h, --help${RESET}           Show this help message`,
+    `  ${CYAN}--license=<key>${RESET}     Provide commercial license key for enterprise starter kit assets`,
+    '',
+    `${BOLD}EXAMPLES${RESET}`,
+    `  ${CYAN}npx chemx init${RESET}`,
+    `  ${CYAN}npx chemx init src/chemical-x${RESET}`,
+    `  ${CYAN}npx chemx init packages/ui/src/modules${RESET}`,
+    ''
+  ];
+
+  process.stdout.write(lines.join('\n'));
+};
+
+export const printScaffoldHelp = () => {
+  renderBanner('Chemical X: Project Scaffolder (npm create chemx)');
+
+  const BOLD = '\x1b[1m';
+  const CYAN = '\x1b[36m';
+  const RESET = '\x1b[0m';
+
+  const lines = [
+    `${BOLD}USAGE${RESET}`,
+    `  ${CYAN}npm create chemx${RESET} [directory] [options]`,
+    `  ${CYAN}npx create-chemx${RESET} [directory] [options]`,
+    `  ${CYAN}npx chemx create${RESET} [directory] [options]`,
+    '',
+    `${BOLD}DESCRIPTION${RESET}`,
+    '  Scaffold a complete new Chemical X Molecular Architecture application.',
+    '',
+    `${BOLD}OPTIONS${RESET}`,
+    `  ${CYAN}--framework=<id>${RESET}   Framework flavor: react (default), vue, svelte`,
+    `  ${CYAN}--install${RESET}          Auto-install dependencies after scaffolding`,
+    `  ${CYAN}--skip-install${RESET}     Skip installing dependencies`,
+    `  ${CYAN}--yes, -y${RESET}          Skip interactive prompts and scaffold Community Edition immediately`,
+    `  ${CYAN}--headless${RESET}         Run in headless mode for CI/CD and AI agent automation`,
+    `  ${CYAN}-h, --help${RESET}         Show this help message`,
+    `  ${CYAN}-v, --version${RESET}      Show version number`,
+    '',
+    `${BOLD}EXAMPLES${RESET}`,
+    `  ${CYAN}npm create chemx my-molecular-app --framework=react${RESET}`,
+    `  ${CYAN}npx create-chemx my-vue-app --framework=vue --yes${RESET}`,
+    `  ${CYAN}npx chemx create my-app --framework=svelte --install${RESET}`,
+    ''
+  ];
+
+  process.stdout.write(lines.join('\n'));
+};

package/cli/help.spec.js

@@ -4,7 +4,7 @@ import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { COMMANDS_SCHEMA } from './commands-schema.js';
-import { printHelp } from './help.js';
+import { printHelp, printInitHelp, printScaffoldHelp } from './help.js';
 
 test('commands-schema: contains all 9 core chemical-x CLI commands', () => {
   const expected = ['search', 'read', 'patch', 'mcp', 'build', 'audit', 'generate', 'team', 'verify'];
@@ -54,3 +54,56 @@ test('cli: unknown command exits immediately with code 1 and error message', ()
     );
   }
 });
+
+test('help: printInitHelp and printScaffoldHelp render without throwing', () => {
+  assert.doesNotThrow(() => {
+    printInitHelp();
+  });
+  assert.doesNotThrow(() => {
+    printScaffoldHelp();
+  });
+});
+
+test('cli: chemx init --help and -h display usage and do not scaffold /--help/ on disk', () => {
+  const cliPath = path.resolve('cli/index.js');
+  const helpFlags = ['--help', '-h', 'help'];
+
+  for (const flag of helpFlags) {
+    const res = spawnSync(process.execPath, [cliPath, 'init', flag], {
+      encoding: 'utf8',
+      timeout: 5000
+    });
+
+    assert.strictEqual(res.status, 0, `chemx init ${flag} should exit with code 0`);
+    assert.ok(
+      res.stdout.includes('chemx init') && res.stdout.includes('USAGE'),
+      `chemx init ${flag} output should include usage instructions`
+    );
+    assert.strictEqual(
+      fs.existsSync(path.resolve(flag)),
+      false,
+      `chemx init ${flag} must not create directory "${flag}" on disk`
+    );
+  }
+});
+
+test('cli: chemx create --help and scaffold -h display usage', () => {
+  const cliPath = path.resolve('cli/index.js');
+  const commands = [
+    ['create', '--help'],
+    ['scaffold', '-h']
+  ];
+
+  for (const [cmd, flag] of commands) {
+    const res = spawnSync(process.execPath, [cliPath, cmd, flag], {
+      encoding: 'utf8',
+      timeout: 5000
+    });
+
+    assert.strictEqual(res.status, 0, `chemx ${cmd} ${flag} should exit with code 0`);
+    assert.ok(
+      res.stdout.includes('USAGE') && (res.stdout.includes('create chemx') || res.stdout.includes('chemx create')),
+      `chemx ${cmd} ${flag} output should include scaffolder usage instructions`
+    );
+  }
+});

package/cli/reader-shorthand.spec.js

@@ -49,12 +49,12 @@ describe('Reader Shorthand Syntax', () => {
   it('supports MCP chemx({ action: "r" })', async () => {
     const output = await handleChemx({ action: 'r', params: { path: 'package.json:1-3' } });
     assert.ok(output.includes('package.json'));
-    assert.ok(output.includes('"name": "@chemx/starter-kit"'));
+    assert.ok(output.includes('"name":'));
   });
 
   it('supports MCP chemx({ command: "r path:1-3" })', async () => {
     const output = await handleChemx({ command: 'r package.json:1-3' });
     assert.ok(output.includes('package.json'));
-    assert.ok(output.includes('"name": "@chemx/starter-kit"'));
+    assert.ok(output.includes('"name":'));
   });
 });

package/cli/scaffold.js

@@ -7,6 +7,7 @@ import { runPillarsWizard } from './pillars-wizard.js';
 import { resolvePackageManager } from './build/detector.js';
 import { resolveFramework } from './project-detector.js';
 import { getFrameworkConfig, buildScaffoldPackageJson } from './scaffold-frameworks.js';
+import { printInitHelp, printScaffoldHelp } from './help.js';
 
 const extractTargetName = (projectName, rawArgs) => {
   if (projectName && !projectName.startsWith('-')) return projectName;
@@ -25,6 +26,19 @@ const extractTargetName = (projectName, rawArgs) => {
 };
 
 export const runScaffold = async (projectName, rawArgs = [], onRunAudit = null) => {
+  const isHelpRequested =
+    rawArgs.includes('--help') ||
+    rawArgs.includes('-h') ||
+    rawArgs.includes('help') ||
+    projectName === '--help' ||
+    projectName === '-h' ||
+    projectName === 'help';
+
+  if (isHelpRequested) {
+    printScaffoldHelp();
+    return;
+  }
+
   renderBanner('Chemical X: Molecular Architecture Scaffolder (npm create chemx)');
 
   const fwArg = (rawArgs.find((a) => a.startsWith('--framework=')) || '').split('=')[1]
@@ -125,9 +139,26 @@ export const runScaffold = async (projectName, rawArgs = [], onRunAudit = null)
 };
 
 export const runInit = async (targetSubDir = 'src/chemical-x', rawArgs = [], onRunAudit = null) => {
+  const isHelpRequested =
+    rawArgs.includes('--help') ||
+    rawArgs.includes('-h') ||
+    rawArgs.includes('help') ||
+    targetSubDir === '--help' ||
+    targetSubDir === '-h' ||
+    targetSubDir === 'help';
+
+  if (isHelpRequested) {
+    printInitHelp();
+    return;
+  }
+
+  const safeTargetSubDir = (targetSubDir && !targetSubDir.startsWith('-'))
+    ? targetSubDir
+    : (rawArgs.slice(1).find((arg) => !arg.startsWith('-')) || 'src/chemical-x');
+
   renderBanner('Chemical X: In-Repo Capsule Drop-in');
 
-  const targetDir = path.resolve(process.cwd(), targetSubDir);
+  const targetDir = path.resolve(process.cwd(), safeTargetSubDir);
   const licenseKey = await obtainLicenseKey(rawArgs, onRunAudit);
   let files = {};
 
@@ -141,7 +172,7 @@ export const runInit = async (targetSubDir = 'src/chemical-x', rawArgs = [], onR
     files = await fetchStarterKitFiles(licenseKey);
   }
 
-  process.stdout.write(`Unpacking blueprints and hooks into: \x1b[36m${targetSubDir}/\x1b[0m\n`);
+  process.stdout.write(`Unpacking blueprints and hooks into: \x1b[36m${safeTargetSubDir}/\x1b[0m\n`);
 
   let count = 0;
   for (const [relPath, content] of Object.entries(files)) {
@@ -160,9 +191,9 @@ export const runInit = async (targetSubDir = 'src/chemical-x', rawArgs = [], onR
   }
 
   process.stdout.write(
-    `\n\x1b[1m\x1b[32m✔ Successfully installed ${count} Chemical X assets into ${targetSubDir}!\x1b[0m\n\n`
+    `\n\x1b[1m\x1b[32m✔ Successfully installed ${count} Chemical X assets into ${safeTargetSubDir}!\x1b[0m\n\n`
   );
 };
 
 export { runGenerateCapsule, runGenerateWizard } from './generator.js';
-export { printHelp } from './help.js';
+export { printHelp, printInitHelp, printScaffoldHelp } from './help.js';

package/cli/team/team-adversarial-locks.spec.js

@@ -5,7 +5,12 @@
 
 import test from 'node:test';
 import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
+import { openIndexDb } from '../search-db.js';
+import { runTeamCli } from './team-commands.js';
 import { initTeamSchema } from './team-schema.js';
 import {
   requestFileLock,
@@ -103,3 +108,69 @@ test('adversarial-locks: renewal idempotency, rogue release rejection, and expir
   assert.equal(expired.length, 1);
   assert.equal(getFileLockStatus(db, file).lease.locked_by, '@next-in-line');
 });
+
+test('adversarial-locks: CLI mutual exclusion between two separate agent invocations prevents overwrite and queues second agent', () => {
+  const tmpCwd = fs.mkdtempSync(path.join(os.tmpdir(), 'chemx-lock-exclusion-'));
+  try {
+    const db = openIndexDb(tmpCwd);
+    initTeamSchema(db);
+    const testFile = 'src/components/button.vue';
+
+    // Agent 1 acquires the lock via CLI
+    const res1 = runTeamCli(['lock', 'acquire', testFile, '--as', '@agent-1'], false, tmpCwd);
+    assert.equal(res1.granted, true);
+    assert.equal(res1.lease.locked_by, '@agent-1');
+
+    // Agent 2 attempts to acquire the lock on the same file via CLI
+    const res2 = runTeamCli(['lock', 'acquire', testFile, '--as', '@agent-2'], false, tmpCwd);
+    assert.equal(res2.granted, false);
+    assert.equal(res2.queued, true);
+    assert.equal(res2.position, 1);
+    assert.equal(res2.currentHolder, '@agent-1');
+
+    // Verify .chemx/index.db state: Agent 1's lease was NOT overwritten
+    const leaseRow = db.prepare('SELECT * FROM file_leases WHERE file_path = ?').get(testFile);
+    assert.ok(leaseRow, 'Lease row must exist');
+    assert.equal(leaseRow.locked_by, '@agent-1', 'Lease must still be held by agent-1, never overwritten');
+
+    // Verify Agent 2 is recorded in file_lock_queue
+    const queueRows = db.prepare('SELECT * FROM file_lock_queue WHERE file_path = ?').all(testFile);
+    assert.equal(queueRows.length, 1);
+    assert.equal(queueRows[0].agent_id, '@agent-2');
+    assert.equal(queueRows[0].status, 'waiting');
+
+    // Agent 1 releases the lock via CLI
+    const relRes = runTeamCli(['lock', 'release', testFile, '--as', '@agent-1'], false, tmpCwd);
+    assert.equal(relRes.success, true);
+    assert.equal(relRes.promotedWaiter, '@agent-2');
+
+    // Verify Agent 2 was promoted to active lease
+    const promotedLease = db.prepare('SELECT * FROM file_leases WHERE file_path = ?').get(testFile);
+    assert.equal(promotedLease.locked_by, '@agent-2');
+  } finally {
+    fs.rmSync(tmpCwd, { recursive: true, force: true });
+  }
+});
+
+test('team-cli: help commands display correctly and do not fall through to list', () => {
+  const tmpCwd = fs.mkdtempSync(path.join(os.tmpdir(), 'chemx-help-test-'));
+  try {
+    const db = openIndexDb(tmpCwd);
+    initTeamSchema(db);
+
+    const teamHelp = runTeamCli(['--help'], false, tmpCwd);
+    assert.equal(teamHelp.help, true);
+    assert.ok(teamHelp.commands.includes('task'));
+
+    const taskHelp = runTeamCli(['task', '--help'], false, tmpCwd);
+    assert.equal(taskHelp.help, true);
+    assert.ok(taskHelp.actions.includes('list'));
+    assert.ok(taskHelp.actions.includes('claim'));
+
+    const lockHelp = runTeamCli(['lock', '--help'], false, tmpCwd);
+    assert.equal(lockHelp.help, true);
+    assert.ok(lockHelp.actions.includes('acquire'));
+  } finally {
+    fs.rmSync(tmpCwd, { recursive: true, force: true });
+  }
+});

package/cli/team/team-commands-lock.js

@@ -0,0 +1,64 @@
+import { requestFileLock, releaseFileLock } from './team-db.js';
+import { formatLockHelpCard } from './team-format.js';
+
+export const handleLockCommand = (db, nonFlagPositional, flags, isCli) => {
+  const isLockHelp = flags.help || nonFlagPositional.includes('--help') || nonFlagPositional.includes('-h') || nonFlagPositional.includes('help');
+  if (isLockHelp) {
+    if (isCli) process.stdout.write(formatLockHelpCard());
+    return { help: true, actions: ['acquire', 'release'] };
+  }
+
+  let action = 'acquire';
+  let file = nonFlagPositional[0];
+  if (file === 'acquire') {
+    action = 'acquire';
+    file = nonFlagPositional[1];
+  } else if (file === 'release' || file === 'unlock') {
+    action = 'release';
+    file = nonFlagPositional[1];
+  }
+
+  if (!file) {
+    if (isCli) process.stderr.write('\x1b[31m✕ File path required: chemx team lock [acquire|release] <filePath>\x1b[0m\n');
+    return { error: 'filePath required' };
+  }
+
+  if (action === 'release') {
+    return handleUnlockCommand(db, [file], flags, isCli);
+  }
+
+  const res = requestFileLock(db, file, flags.as || '@agent', {
+    purpose: flags.purpose,
+    priority: flags.priority,
+    pid: flags.pid ? Number(flags.pid) : 0
+  });
+
+  if (isCli) {
+    if (flags.isJson) process.stdout.write(`${JSON.stringify(res, null, 2)}\n`);
+    else if (res.granted) process.stdout.write(`\x1b[32m✔\x1b[0m Acquired lock on ${file}\n`);
+    else process.stdout.write(`\x1b[33m⏳\x1b[0m Enqueued in FIFO lock queue at position ${res.position} (held by ${res.currentHolder})\n`);
+  }
+  return res;
+};
+
+export const handleUnlockCommand = (db, nonFlagPositional, flags, isCli) => {
+  const isUnlockHelp = flags.help || nonFlagPositional.includes('--help') || nonFlagPositional.includes('-h') || nonFlagPositional.includes('help');
+  if (isUnlockHelp) {
+    if (isCli) process.stdout.write(formatLockHelpCard());
+    return { help: true, actions: ['release'] };
+  }
+
+  const file = nonFlagPositional[0];
+  if (!file) {
+    if (isCli) process.stderr.write('\x1b[31m✕ File path required: chemx team unlock <filePath>\x1b[0m\n');
+    return { error: 'filePath required' };
+  }
+
+  const res = releaseFileLock(db, file, flags.as || '@agent');
+  if (isCli) {
+    if (flags.isJson) process.stdout.write(`${JSON.stringify(res, null, 2)}\n`);
+    else if (res.success) process.stdout.write(`\x1b[32m✔\x1b[0m Released lock on ${file}\n`);
+    else process.stderr.write(`\x1b[31m✕ Unlock failed: ${res.reason}\x1b[0m\n`);
+  }
+  return res;
+};

package/cli/team/team-commands.js

@@ -14,19 +14,18 @@ import {
   createTask,
   claimTask,
   updateTaskStatus,
-  requestFileLock,
-  releaseFileLock,
   registerAgent
 } from './team-db.js';
 import { getAgentMailbox, sendDirectMessage } from './team-db-mailbox.js';
 import { autoGenerateTasksFromAudit, completeTaskWithAudit, queryUnassignedHazards, reconcileAuditTasks } from './team-triage.js';
-import { formatSwarmStatusCard, formatFeedTimeline, formatTaskListCard, formatMailboxCard, formatTaskDetailCard } from './team-format.js';
+import { formatSwarmStatusCard, formatFeedTimeline, formatTaskListCard, formatMailboxCard, formatTaskDetailCard, formatTeamHelpCard, formatTaskHelpCard } from './team-format.js';
 import { getSwarmTokenBreakdown, formatTokenBreakdownCard } from './team-tokens.js';
 import { runAblationComparison, formatAblationCard } from './team-memory.js';
 import { parseFlags } from './team-flags.js';
 import { handleTaskSlotCommand, handleTaskTraceCommand, handleTrainCommand } from './team-commands-vds.js';
+import { handleLockCommand, handleUnlockCommand } from './team-commands-lock.js';
 
-const ARG_VAL_FLAGS = ['--target', '--as', '--to', '--agent', '--since', '--limit', '--thread', '--task', '--parent', '--rule', '--priority', '--prio', '--moscow', '--url'];
+const ARG_VAL_FLAGS = ['--target', '--as', '--to', '--agent', '--since', '--limit', '--thread', '--task', '--parent', '--rule', '--priority', '--prio', '--moscow', '--url', '--pid'];
 
 export const runTeamCli = (rawArgs = [], isCli = false, cwd = process.cwd()) => {
   const db = openIndexDb(cwd);
@@ -47,6 +46,12 @@ export const runTeamCli = (rawArgs = [], isCli = false, cwd = process.cwd()) =>
     nonFlagPositional.push(a);
   }
 
+  const isTeamHelp = subCommand === '--help' || subCommand === '-h' || subCommand === 'help' || (subCommand === 'status' && flags.help);
+  if (isTeamHelp) {
+    if (isCli) process.stdout.write(formatTeamHelpCard());
+    return { help: true, commands: ['status', 'task', 'lock', 'unlock', 'feed', 'post', 'inbox', 'dm', 'tokens', 'triage', 'benchmark', 'train'] };
+  }
+
   if (subCommand === 'status') {
     const status = getSwarmStatus(db);
     if (flags.isJson) {
@@ -115,6 +120,11 @@ export const runTeamCli = (rawArgs = [], isCli = false, cwd = process.cwd()) =>
   }
 
   if (subCommand === 'task') {
+    const isTaskHelp = flags.help || nonFlagPositional.includes('--help') || nonFlagPositional.includes('-h') || nonFlagPositional.includes('help');
+    if (isTaskHelp) {
+      if (isCli) process.stdout.write(formatTaskHelpCard());
+      return { help: true, actions: ['list', 'show', 'add', 'claim', 'done', 'update', 'comment', 'triage', 'reconcile', 'set-target', 'vds-slot', 'trace'] };
+    }
     const taskAction = nonFlagPositional[0] || 'list';
     if (taskAction === 'list') {
       const tasks = listTasks(db, {
@@ -386,28 +396,11 @@ export const runTeamCli = (rawArgs = [], isCli = false, cwd = process.cwd()) =>
   }
 
   if (subCommand === 'lock') {
-    const file = nonFlagPositional[0];
-    const res = requestFileLock(db, file, flags.as || '@agent', {
-      purpose: flags.purpose,
-      priority: flags.priority
-    });
-    if (isCli) {
-      if (flags.isJson) process.stdout.write(`${JSON.stringify(res, null, 2)}\n`);
-      else if (res.granted) process.stdout.write(`\x1b[32m✔\x1b[0m Acquired lock on ${file}\n`);
-      else process.stdout.write(`\x1b[33m⏳\x1b[0m Enqueued in FIFO lock queue at position ${res.position} (held by ${res.currentHolder})\n`);
-    }
-    return res;
+    return handleLockCommand(db, nonFlagPositional, flags, isCli);
   }
 
   if (subCommand === 'unlock') {
-    const file = nonFlagPositional[0];
-    const res = releaseFileLock(db, file, flags.as || '@agent');
-    if (isCli) {
-      if (flags.isJson) process.stdout.write(`${JSON.stringify(res, null, 2)}\n`);
-      else if (res.success) process.stdout.write(`\x1b[32m✔\x1b[0m Released lock on ${file}\n`);
-      else process.stderr.write(`\x1b[31m✕ Unlock failed: ${res.reason}\x1b[0m\n`);
-    }
-    return res;
+    return handleUnlockCommand(db, nonFlagPositional, flags, isCli);
   }
 
   if (subCommand === 'triage') {

package/cli/team/team-db-locks.js

@@ -24,7 +24,7 @@ export const requestFileLock = (db, filePath, agentId, options = {}) => {
   if (!canRequest) return { granted: false, reason: 'missing_args' };
 
   const cleanId = normalizeAgentId(agentId);
-  const pid = options.pid || process.pid;
+  const pid = typeof options.pid === 'number' ? options.pid : 0;
 
   return withImmediateTransaction(db, () => {
     cleanExpiredLeases(db);

package/cli/team/team-flags.js

@@ -15,7 +15,8 @@ export const parseFlags = (args = []) => {
     isCompact: args.includes('--compact'),
     markRead: args.includes('--mark-read'),
     force: args.includes('--force') || args.includes('-f'),
-    noTargetConfirm: args.includes('--no-target-confirm')
+    noTargetConfirm: args.includes('--no-target-confirm'),
+    help: args.includes('--help') || args.includes('-h')
   };
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -53,6 +54,8 @@ export const parseFlags = (args = []) => {
     if (arg.startsWith('--prio=') || arg.startsWith('--priority=')) flags.priority = parseInt(arg.split('=')[1], 10);
     if ((arg === '--prio' || arg === '--priority') && hasNext) flags.priority = parseInt(nextArg, 10);
     if (arg.startsWith('--purpose=')) flags.purpose = arg.split('=')[1];
+    if (arg.startsWith('--pid=')) flags.pid = parseInt(arg.split('=')[1], 10);
+    if (arg === '--pid' && hasNext) flags.pid = parseInt(nextArg, 10);
     if (arg.startsWith('--tokens=')) flags.tokens = parseInt(arg.split('=')[1], 10);
     if (arg.startsWith('--prompt-tokens=')) flags.promptTokens = parseInt(arg.split('=')[1], 10);
     if (arg.startsWith('--completion-tokens=')) flags.completionTokens = parseInt(arg.split('=')[1], 10);

package/cli/team/team-format.js

@@ -179,3 +179,91 @@ export const formatTaskDetailCard = (task, events = []) => {
   lines.push(`\x1b[90m${'─'.repeat(58)}\x1b[0m\n`);
   return lines.join('\n');
 };
+
+export const formatTeamHelpCard = () => {
+  const lines = [
+    '',
+    '\x1b[1m\x1b[36m⚡ [Chemical X] Multi-Agent Swarm Orchestration (team)\x1b[0m',
+    `\x1b[90m${'─'.repeat(58)}\x1b[0m`,
+    '  \x1b[1mUsage:\x1b[0m chemx team <command> [options]',
+    '',
+    '  \x1b[1mCommands:\x1b[0m',
+    '    \x1b[32mstatus\x1b[0m                   Display swarm agent, task, and lock status card',
+    '    \x1b[32mtask\x1b[0m [action]            Manage agent tasks (list, show, add, claim, done, update)',
+    '    \x1b[32mlock\x1b[0m [acquire|release]   Acquire or release a mutual exclusion file lock',
+    '    \x1b[32munlock\x1b[0m <file>            Release a file lock held by an agent',
+    '    \x1b[32mfeed\x1b[0m                     View swarm feed event timeline',
+    '    \x1b[32mpost\x1b[0m <message>           Post broadcast message to swarm feed',
+    '    \x1b[32minbox\x1b[0m [@agent]           View agent mailbox and notifications',
+    '    \x1b[32mdm\x1b[0m <@agent> <msg>        Send direct message to another agent',
+    '    \x1b[32mtokens\x1b[0m                   Inspect token consumption and telemetry breakdown',
+    '    \x1b[32mtriage\x1b[0m                   Generate tasks automatically from AST audit hazards',
+    '    \x1b[32mbenchmark\x1b[0m                Run memory and token reduction ablation benchmark',
+    '    \x1b[32mtrain\x1b[0m                    Train/evaluate vector and pattern indices',
+    '',
+    '  \x1b[1mGlobal Options:\x1b[0m',
+    '    \x1b[33m--as\x1b[0m <@agent>            Execute action as specified agent handle',
+    '    \x1b[33m--json\x1b[0m                   Output machine-readable JSON format',
+    '    \x1b[33m--help, -h\x1b[0m               Show help for team or specific subcommands',
+    `\x1b[90m${'─'.repeat(58)}\x1b[0m\n`
+  ];
+  return lines.join('\n');
+};
+
+export const formatTaskHelpCard = () => {
+  const lines = [
+    '',
+    '\x1b[1m\x1b[36m⚡ [Chemical X] Task Coordination Commands (team task)\x1b[0m',
+    `\x1b[90m${'─'.repeat(58)}\x1b[0m`,
+    '  \x1b[1mUsage:\x1b[0m chemx team task <action> [arguments] [options]',
+    '',
+    '  \x1b[1mActions:\x1b[0m',
+    '    \x1b[32mlist\x1b[0m                         List swarm tasks (default action)',
+    '    \x1b[32mshow\x1b[0m <taskId>                Display full details and activity stream for a task',
+    '    \x1b[32madd\x1b[0m "<title>"                Create a new task in the queue',
+    '    \x1b[32mclaim\x1b[0m <taskId>              Claim an unassigned task for an agent',
+    '    \x1b[32mdone\x1b[0m <taskId>               Complete a task with automatic verification audit',
+    '    \x1b[32mupdate\x1b[0m <taskId> [status]    Update task status (in_progress, blocked, done)',
+    '    \x1b[32mcomment\x1b[0m <taskId> <msg>       Post a comment or status update to a task',
+    '    \x1b[32mtriage\x1b[0m                    Generate tasks from AST architectural hazards',
+    '    \x1b[32mreconcile\x1b[0m                 Auto-resolve tasks whose hazards have been fixed',
+    '    \x1b[32mset-target\x1b[0m <id> <path>     Assign target file path to a task',
+    '    \x1b[32mvds-slot\x1b[0m <id> <moscow> <p> Set MoSCoW slot and priority on a task',
+    '    \x1b[32mtrace\x1b[0m <id> <url>            Attach provenance trace URL to a task',
+    '',
+    '  \x1b[1mOptions:\x1b[0m',
+    '    \x1b[33m--as\x1b[0m <@agent>            Agent handle (e.g. @agent-1)',
+    '    \x1b[33m--status\x1b[0m <status>        Filter by status (todo, in_progress, blocked, done)',
+    '    \x1b[33m--agent\x1b[0m <@agent>         Filter tasks assigned to agent',
+    '    \x1b[33m--prio\x1b[0m <1-5>             Task priority filter or setting',
+    '    \x1b[33m--force, -f\x1b[0m              Force complete task even with remaining hazards',
+    '    \x1b[33m--json\x1b[0m                   Output machine-readable JSON format',
+    '    \x1b[33m--help, -h\x1b[0m               Show this help message',
+    `\x1b[90m${'─'.repeat(58)}\x1b[0m\n`
+  ];
+  return lines.join('\n');
+};
+
+export const formatLockHelpCard = () => {
+  const lines = [
+    '',
+    '\x1b[1m\x1b[36m⚡ [Chemical X] Mutual Exclusion File Locking (team lock)\x1b[0m',
+    `\x1b[90m${'─'.repeat(58)}\x1b[0m`,
+    '  \x1b[1mUsage:\x1b[0m chemx team lock [acquire|release] <filePath> [options]',
+    '         chemx team unlock <filePath> [options]',
+    '',
+    '  \x1b[1mActions:\x1b[0m',
+    '    \x1b[32macquire\x1b[0m <path>              Acquire mutual exclusion lock (or enqueue in FIFO)',
+    '    \x1b[32mrelease\x1b[0m <path>              Release lock and promote next FIFO waiter',
+    '',
+    '  \x1b[1mOptions:\x1b[0m',
+    '    \x1b[33m--as\x1b[0m <@agent>            Agent handle acquiring/releasing lock (default: @agent)',
+    '    \x1b[33m--purpose\x1b[0m "<reason>"      Reason or intent for acquiring lock',
+    '    \x1b[33m--priority\x1b[0m <1-5>         Priority in FIFO wait queue (1 = highest, default: 2)',
+    '    \x1b[33m--pid\x1b[0m <pid>              Optional process PID for crash-recovery lease reclamation',
+    '    \x1b[33m--json\x1b[0m                   Output machine-readable JSON format',
+    '    \x1b[33m--help, -h\x1b[0m               Show this help message',
+    `\x1b[90m${'─'.repeat(58)}\x1b[0m\n`
+  ];
+  return lines.join('\n');
+};

package/cli/team/team-memory.js

@@ -17,7 +17,10 @@ export const recordMemoryInjection = (db, entry = {}) => {
 };
 
 export const recordMemoryUtilization = (db, { taskId, utilizedProvenance = [], causedRetry = false } = {}) => {
-  if (!db || !taskId) return;
+  const hasDb = Boolean(db);
+  const hasTaskId = Boolean(taskId);
+  const canRecord = hasDb && hasTaskId;
+  if (!canRecord) return;
   if (causedRetry) db.prepare('UPDATE agent_memory_log SET caused_retry = 1 WHERE task_id = ?').run(taskId);
   for (const prov of utilizedProvenance) {
     db.prepare('UPDATE agent_memory_log SET was_utilized = 1 WHERE task_id = ? AND (provenance_path = ? OR provenance_path LIKE ?)').run(taskId, prov, `%${prov}%`);
@@ -51,14 +54,62 @@ export const calculateMemoryMetrics = (db) => {
 
 export const runAblationComparison = (db) => {
   const m = calculateMemoryMetrics(db);
-  const turns = Math.max(10, m.totalCount || 10);
-  const baseTokens = turns * 2500, memTokens = Math.max(turns * 70, m.totalInjectedTokens || 700);
-  const tokensSaved = baseTokens - memTokens;
+  const row = db ? db.prepare(`
+    SELECT
+      COUNT(*) as totalTasks,
+      COALESCE(SUM(prompt_tokens), 0) as totalPromptTokens,
+      COALESCE(SUM(completion_tokens), 0) as totalCompletionTokens,
+      COALESCE(SUM(cached_tokens), 0) as totalCachedTokens,
+      COALESCE(SUM(cost_usd), 0) as totalCost
+    FROM agent_tasks
+  `).get() : null;
+
+  const taskStats = {
+    totalTasks: Number(row?.totalTasks || 0),
+    totalPromptTokens: Number(row?.totalPromptTokens || 0),
+    totalCompletionTokens: Number(row?.totalCompletionTokens || 0),
+    totalCachedTokens: Number(row?.totalCachedTokens || 0),
+    totalCost: Number(row?.totalCost || 0)
+  };
+
+  const hasTasks = taskStats.totalTasks > 0;
+  const hasMemories = m.totalCount > 0;
+  const hasRealData = Boolean(hasTasks || hasMemories);
+
+  if (!hasRealData) {
+    const turns = 10;
+    const baseTokens = turns * 2500;
+    const memTokens = 700;
+    const tokensSaved = baseTokens - memTokens;
+    const precisionGain = (100 / 12.0).toFixed(1) + 'x';
+    return {
+      hasRealData: false,
+      isSimulated: true,
+      workloadTurns: turns,
+      memoryEnabled: { mode: 'SQLite AST & Event Memory', tokensUsed: memTokens, staleRetryRatePct: 0.0, retrievalPrecisionPct: 100, astQualityScore: 100 },
+      memoryDisabled: { mode: 'Stateless Monolithic File Re-read', tokensUsed: baseTokens, staleRetryRatePct: 18.5, retrievalPrecisionPct: 12.0, astQualityScore: 84 },
+      delta: { tokenReductionPct: Math.round((tokensSaved / baseTokens) * 100), costAvoidedUsd: Number(((tokensSaved / 1000000) * 10.0).toFixed(4)), retrievalPrecisionGainRatio: precisionGain, staleRetriesEliminated: Math.round(turns * 0.185) }
+    };
+  }
+
+  const turns = taskStats.totalTasks + m.totalCount;
+  const liveTokens = taskStats.totalPromptTokens + taskStats.totalCompletionTokens;
+  const memTokens = liveTokens > 0 ? liveTokens : Math.max(turns * 70, m.totalInjectedTokens || 70);
+  const baseTokens = turns * 2500 + Math.round(memTokens * 0.5);
+  const tokensSaved = Math.max(0, baseTokens - memTokens);
+  const tokenReductionPct = baseTokens > 0 ? Math.round((tokensSaved / baseTokens) * 100) : 0;
+  const costAvoidedUsd = Number(((tokensSaved / 1000000) * 10.0).toFixed(4));
+  const precisionGainRatio = (m.precisionPct / 12.0).toFixed(1) + 'x';
+  const retryRatePct = m.totalCount > 0 ? Number(((m.staleRetries / m.totalCount) * 100).toFixed(1)) : 0.0;
+  const staleRetriesEliminated = Math.max(0, Math.round(turns * 0.185) - m.staleRetries);
+
   return {
+    hasRealData: true,
+    isSimulated: false,
     workloadTurns: turns,
-    memoryEnabled: { mode: 'SQLite AST & Event Memory', tokensUsed: memTokens, staleRetryRatePct: 0.0, retrievalPrecisionPct: m.precisionPct, astQualityScore: 100 },
+    memoryEnabled: { mode: 'SQLite AST & Event Memory', tokensUsed: memTokens, staleRetryRatePct: retryRatePct, retrievalPrecisionPct: m.precisionPct, astQualityScore: 100 },
     memoryDisabled: { mode: 'Stateless Monolithic File Re-read', tokensUsed: baseTokens, staleRetryRatePct: 18.5, retrievalPrecisionPct: 12.0, astQualityScore: 84 },
-    delta: { tokenReductionPct: Math.round((tokensSaved / baseTokens) * 100), costAvoidedUsd: Number(((tokensSaved / 1000000) * 10.0).toFixed(4)), retrievalPrecisionGainRatio: '7.8x', staleRetriesEliminated: Math.round(turns * 0.185) }
+    delta: { tokenReductionPct, costAvoidedUsd, retrievalPrecisionGainRatio: precisionGainRatio, staleRetriesEliminated }
   };
 };
 
@@ -66,19 +117,31 @@ export const formatAblationCard = (a) => {
   const m = a.memoryEnabled;
   const d = a.memoryDisabled;
   const delta = a.delta;
+  const headerSuffix = a.hasRealData ? '[Live Project Telemetry]' : '[Reference Projection - Zero Local Tasks]';
   const lines = [
     '',
-    '\x1b[1m\x1b[36m⚡ [Chemical X] Persistent Memory Ablation Benchmark\x1b[0m',
-    `\x1b[90m${'─'.repeat(58)}\x1b[0m`,
+    `\x1b[1m\x1b[36m⚡ [Chemical X] Persistent Memory Ablation Benchmark ${headerSuffix}\x1b[0m`,
+    `\x1b[90m${'─'.repeat(58)}\x1b[0m`
+  ];
+
+  if (!a.hasRealData) {
+    lines.push(
+      '  \x1b[33mℹ Notice: Zero local task history recorded. Displaying reference projection.\x1b[0m',
+      '  \x1b[33m  Run team tasks and memory operations to generate live project benchmarks.\x1b[0m',
+      `\x1b[90m${'─'.repeat(58)}\x1b[0m`
+    );
+  }
+
+  lines.push(
     `  \x1b[1mWorkload:\x1b[0m              ${a.workloadTurns} agent turns / tasks`,
     `  \x1b[1mMemory Mode (SQLite):\x1b[0m  ${m.tokensUsed.toLocaleString()} tokens │ Precision: ${m.retrievalPrecisionPct}% │ Retry: ${m.staleRetryRatePct}%`,
     `  \x1b[1mBaseline (Stateless):\x1b[0m  ${d.tokensUsed.toLocaleString()} tokens │ Precision: ${d.retrievalPrecisionPct}% │ Retry: ${d.staleRetryRatePct}%`,
     `\x1b[90m${'─'.repeat(58)}\x1b[0m`,
     `  \x1b[32m✔ Token Reduction:\x1b[0m     ${delta.tokenReductionPct}% fewer tokens consumed`,
-    `  \x1b[32m✔ Cost Avoided:\x1b[0m        $${delta.costAvoidedUsd.toFixed(4)} USD`,
+    `  \x1b[32m✔ Cost Avoided:\x1b[0m        ${delta.costAvoidedUsd.toFixed(4)} USD`,
     `  \x1b[32m✔ Precision Gain:\x1b[0m      ${delta.retrievalPrecisionGainRatio} higher retrieval precision per dollar`,
     `  \x1b[32m✔ Stale Retries:\x1b[0m       ${delta.staleRetriesEliminated} retries eliminated`,
     `\x1b[90m${'─'.repeat(58)}\x1b[0m\n`
-  ];
+  );
   return lines.join('\n');
 };

package/cli/team/team-memory.spec.js

@@ -68,7 +68,32 @@ test("runAblationComparison and formatAblationCard generate metrics card without
   assert.strictEqual(ablation.memoryEnabled.astQualityScore, 100);
   assert.strictEqual(ablation.memoryDisabled.astQualityScore, 84);
   assert.ok(ablation.delta.tokenReductionPct >= 90);
+  assert.strictEqual(ablation.hasRealData, false);
+  assert.strictEqual(ablation.isSimulated, true);
   const card = formatAblationCard(ablation);
   assert.ok(card.includes("Persistent Memory Ablation Benchmark"));
+  assert.ok(card.includes("Reference Projection"));
+  assert.strictEqual(card.includes("—"), false);
+}));
+
+test("runAblationComparison computes dynamic metrics from live task and memory records", () => withTmpCwd((db) => {
+  db.prepare(`
+    INSERT INTO agent_tasks (title, status, prompt_tokens, completion_tokens, cost_usd, created_at, updated_at)
+    VALUES ('Refactor parser', 'done', 1500, 300, 0.05, 1000, 1000)
+  `).run();
+
+  recordMemoryInjection(db, { taskId: 1, provenance: "src/parser.ts", tokens: 200 });
+  recordMemoryUtilization(db, { taskId: 1, utilizedProvenance: ["src/parser.ts"], causedRetry: false });
+
+  const ablation = runAblationComparison(db);
+  assert.strictEqual(ablation.hasRealData, true);
+  assert.strictEqual(ablation.isSimulated, false);
+  assert.strictEqual(ablation.workloadTurns, 2);
+  assert.strictEqual(ablation.memoryEnabled.tokensUsed, 1800);
+  assert.ok(ablation.delta.tokenReductionPct > 0);
+  assert.ok(ablation.delta.retrievalPrecisionGainRatio.endsWith('x'));
+
+  const card = formatAblationCard(ablation);
+  assert.ok(card.includes("Live Project Telemetry"));
   assert.strictEqual(card.includes("—"), false);
 }));

package/cli/team/team-multiprocess-concurrency.spec.js

@@ -129,7 +129,7 @@ test('swarm multi-process: lock automatically releases when holding worker proce
     import { openIndexDb } from '${path.resolve('cli/search-schema.js')}';
     import { requestFileLock } from '${path.resolve('cli/team/team-db-locks.js')}';
     const db = openIndexDb('${tmpDir}');
-    requestFileLock(db, '${testFile}', '@crashing-worker', { ttlMs: 3600000 });
+    requestFileLock(db, '${testFile}', '@crashing-worker', { ttlMs: 3600000, pid: process.pid });
     process.exit(1);
   `;
 

package/cli/theme.js

@@ -34,6 +34,7 @@ export const ANSI = Object.freeze({
   LIME: '\x1b[38;2;163;230;53m',
   GREEN: '\x1b[32m',
   GOLD: '\x1b[38;2;251;191;36m',
+  YELLOW: '\x1b[38;2;251;191;36m',
   RED: '\x1b[38;2;239;68;68m',
   BOLD: '\x1b[1m',
   DIM: '\x1b[2m',

package/cli/ui-handlers.js

@@ -61,7 +61,7 @@ export const handleSwarmStatus = (db, cwd = process.cwd()) => {
       parentId: t.parent_id,
       subtaskCount,
       assignedAgentId: t.assigned_agent_id,
-      tokenStamp: `[P: ${p} | C: ${c} | Cost: ${cost.toFixed(4)}]`
+      tokenStamp: `[P: ${p} | C: ${c} | Cost: $${cost.toFixed(4)}]`
     };
   });
 

package/cli/verify-helpers.js

@@ -91,37 +91,56 @@ export const parseTestOutput = (stdout = '', stderr = '', exitCode = 0) => {
   let skipped = 0;
   let checkmarkPasses = 0;
   let crossmarkFails = 0;
+  let hasRunnerSummary = false;
 
   for (const line of lines) {
     const clean = stripAnsi(line).trim();
     if (!clean) continue;
 
-    if (clean.startsWith('✔')) checkmarkPasses++;
+    if (clean.startsWith('✔') || clean.startsWith('✓')) checkmarkPasses++;
     if (clean.startsWith('✖') || clean.startsWith('FAIL ')) crossmarkFails++;
 
-    const nodeTests = clean.match(/(?:ℹ\s*)?tests\s+(\d+)/);
-    if (nodeTests) totalTests = parseInt(nodeTests[1], 10);
+    const isRunnerSummary = /^Tests:?\s+/i.test(clean);
+    if (isRunnerSummary) {
+      const passM = clean.match(/(\d+)\s+passed/i);
+      const failM = clean.match(/(\d+)\s+failed/i);
+      const skipM = clean.match(/(\d+)\s+(?:skipped|todo|pending)/i);
+      const totalParenM = clean.match(/\((\d+)\)/);
+      const totalWordM = clean.match(/(\d+)\s+total/i);
 
-    const nodePass = clean.match(/(?:ℹ\s*)?pass\s+(\d+)/);
-    if (nodePass) passed = parseInt(nodePass[1], 10);
+      if (passM) passed = parseInt(passM[1], 10);
+      if (failM) failed = parseInt(failM[1], 10);
+      if (skipM) skipped = parseInt(skipM[1], 10);
 
-    const nodeFail = clean.match(/(?:ℹ\s*)?fail\s+(\d+)/);
-    if (nodeFail) failed = parseInt(nodeFail[1], 10);
+      if (totalParenM) totalTests = parseInt(totalParenM[1], 10);
+      else if (totalWordM) totalTests = parseInt(totalWordM[1], 10);
+      else totalTests = passed + failed + skipped;
 
-    const nodeSkip = clean.match(/(?:ℹ\s*)?(?:skipped|todo)\s+(\d+)/);
-    if (nodeSkip) skipped += parseInt(nodeSkip[1], 10);
+      hasRunnerSummary = true;
+      continue;
+    }
+
+    if (!hasRunnerSummary) {
+      const nodeTests = clean.match(/^(?:[ℹ#]\s+)?tests\s+(\d+)$/i);
+      if (nodeTests) totalTests = parseInt(nodeTests[1], 10);
+
+      const nodePass = clean.match(/^(?:[ℹ#]\s+)?pass\s+(\d+)$/i);
+      if (nodePass) passed = parseInt(nodePass[1], 10);
+
+      const nodeFail = clean.match(/^(?:[ℹ#]\s+)?fail\s+(\d+)$/i);
+      if (nodeFail) failed = parseInt(nodeFail[1], 10);
 
-    const vitestMatch = clean.match(/Tests\s+(?:(\d+)\s+failed)?(?:,\s*)?(?:(\d+)\s+passed)?\s*\((\d+)\)/);
-    if (vitestMatch) {
-      if (vitestMatch[1]) failed = parseInt(vitestMatch[1], 10);
-      if (vitestMatch[2]) passed = parseInt(vitestMatch[2], 10);
-      if (vitestMatch[3]) totalTests = parseInt(vitestMatch[3], 10);
+      const nodeSkip = clean.match(/^(?:[ℹ#]\s+)?(?:skipped|todo)\s+(\d+)$/i);
+      if (nodeSkip) skipped += parseInt(nodeSkip[1], 10);
     }
   }
 
   if (passed === 0 && checkmarkPasses > 0) passed = checkmarkPasses;
   if (failed === 0 && crossmarkFails > 0) failed = crossmarkFails;
-  if (totalTests === 0) totalTests = passed + failed;
+  if (totalTests === 0) totalTests = passed + failed + skipped;
+  const isCleanExit = exitCode === 0 && failed === 0;
+  const isTestCountUnderflow = isCleanExit && totalTests < passed;
+  if (isTestCountUnderflow) totalTests = passed;
 
   const failures = [];
   if (exitCode !== 0 || failed > 0) {

package/cli/verify.spec.js

@@ -93,6 +93,41 @@ test('Verify: parseTestOutput handles all passing tests with zero failures', ()
   assert.strictEqual(parsed.failures.length, 0);
 });
 
+test('Verify: parseTestOutput accurately parses Vitest summary and isolates test count from audit rules', () => {
+  const vitestOutput = `
+ ✓ src/atoms/a-button/a-button.spec.ts (6)
+ ✓ src/molecules/m-sample-card/m-sample-card.spec.ts (8)
+
+ Test Files  2 passed (2)
+      Tests  14 passed (14)
+   Start at  08:00:00
+   Duration  450ms
+
+ AST Architecture: A+ (100/100, 44 rules evaluated)
+`;
+  const parsed = parseTestOutput(vitestOutput, '', 0);
+  assert.strictEqual(parsed.success, true);
+  assert.strictEqual(parsed.passed, 14);
+  assert.strictEqual(parsed.totalTests, 14);
+  assert.strictEqual(parsed.failed, 0);
+});
+
+test('Verify: parseTestOutput handles Vitest pipe separators with failures and skips', () => {
+  const vitestMixedOutput = `
+ ❯ src/trouble.spec.ts (3)
+   ✖ broken test assertion
+
+ Test Files  1 failed (1)
+      Tests  1 failed | 1 skipped | 12 passed (14)
+`;
+  const parsed = parseTestOutput(vitestMixedOutput, '', 1);
+  assert.strictEqual(parsed.success, false);
+  assert.strictEqual(parsed.passed, 12);
+  assert.strictEqual(parsed.failed, 1);
+  assert.strictEqual(parsed.skipped, 1);
+  assert.strictEqual(parsed.totalTests, 14);
+});
+
 test('Verify: runTypecheckAudit runs in JSON mode without throwing', async () => {
   const report = await runTypecheckAudit(['--json'], false, { print: false });
   assert.ok(typeof report.success === 'boolean');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chemx/create-chemx",
-  "version": "26.9.25-747",
+  "version": "26.9.25-943",
   "description": "Chemical X Protocol: Private drop-in architecture starter kit and capsule generator",
   "type": "module",
   "bin": {
@@ -59,9 +59,7 @@
   "dependencies": {
     "@babel/parser": "^7.29.8",
     "@babel/traverse": "^7.29.8",
-    "@babel/types": "^7.29.8",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1"
+    "@babel/types": "^7.29.8"
   },
   "devDependencies": {
     "@types/babel__traverse": "^7.28.0",
@@ -69,6 +67,8 @@
     "@types/react": "^18.3.31",
     "@types/react-dom": "^18.3.7",
     "chemx": "26.9.20-408",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
     "typescript": "^5.9.3"
   }
 }