@chemx/create-chemx 26.10.7-1061 → 26.10.8-344

package/AGENTS.md

@@ -5,6 +5,22 @@
 
 ---
 
+## ⚡ Quick Agent Reflex Table (Token-Bounded Commands)
+| Standard Reflex | Chemical X (`cx`) Equivalent | Token & Architecture Advantage |
+| :--- | :--- | :--- |
+| `grep -rn "pattern" .` | `cx q -g "pattern"` or `cx q -g "pattern" -l` | Auto-ignores build/vendor; clamps lines to 60 chars or line-only (-l). |
+| `git diff` | `cx d` | Zero-context (`-U0`), auto-collapses to `--stat` if > 80 lines, micro-syncs index. |
+| `git log` | `cx log -n 5` | Single-line compact commit history (~8 tokens/commit). |
+| `find . -name "*.vue"` | `cx f "*.vue"` | Strictly filters by `.gitignore` and ignored dirs. |
+| `cat package.json` | `cx p -s` / `cx p <script>` | Instant single script or dep extraction (~3 tokens vs 300 lines). |
+| `cat <data.json>` | `cx j <file.json>` | Structural schema shape only; collapses repeating arrays. |
+| `cat <file>` / `head <file>` | `cx read <file> --outline` | AST signatures only (~50 tokens vs thousands). |
+| `npm test` / `tsc` | `cx test` / `cx verify` | Silent on success; returns only failing diffs. |
+| Multiple CLI actions | `cx do "<cmd1>" "<cmd2>"` | Executes sequentially in a single warm Node process. |
+| Multiple MCP tool calls | `chemx({ commands: [...] })` | Executes multiple sub-operations in a single agent turn. |
+
+---
+
 ## 1. The Molecular Architecture Protocol
 
 ### A. Structural Weight, Cognitive Cohesion & Profile Architecture
@@ -38,12 +54,11 @@
 - Encapsulate shared feature state in dedicated domain composables/hooks, scoped stores, or typed provide/inject.
 - Child components consume state directly from the domain composable and emit minimal, intention-revealing semantic events.
 
-### E. Same-Name Prop Shorthand (Vue 3.4+ & Svelte 5)
-- **Vue 3.4+**: Always use same-name `:prop` shorthand instead of redundant `:prop="prop"`:
-  `<m-spark-kpi-strip :metrics :records :can-refresh />`
-- **Svelte 5**: Always use same-name `{prop}` shorthand instead of `prop={prop}`:
-  `<SparkKpiStrip {metrics} {records} {canRefresh} />`
-- **React 19 (JSX)**: Explicitly bind `prop={prop}`. Never write `<Comp prop />` for variables (JSX evaluates bare attributes to boolean `true`).
+### E. Idiomatic Shorthand Binding
+Use same-name shorthand across all languages; eliminate redundant `key: key` duplication:
+- **JS / TS / Rust Data Structures**: `{ foo, bar }` over `{ foo: foo, bar: bar }`.
+- **Vue 3.4+ & Svelte 5 Templates**: `<Comp :prop />` or `<Comp {prop} />` over `:prop="prop"`.
+- **React / JSX Exception**: Explicit `prop={prop}` (bare `<Comp prop />` coerces to boolean `true`).
 
 ### F. Pre-Split Pattern Discovery & Harmonization Protocol
 - **Survey Before Slicing**: Before decomposing any monolithic file or collection of files, the AI must first conduct a cross-file pattern discovery audit across all candidate monoliths.
@@ -62,7 +77,7 @@
   - When repeated elements accumulate behavioral logic, accessibility handling, or styling variants across 3+ places (Rule of Three), extract into a canonical capsule (`m-tab-button`).
 
 ### H. AI Agent Codebase Query Machine Protocol
-- **Search First Rule**: AI agents MUST invoke `pnpm chemx q "<query>"` (or `npx chemx search "<query>"`) before running broad ripgrep, find, or file dumping.
+- **AST & Literal Search First Rule**: AI agents should invoke `cx q "<query>"` for AST symbols or `cx q -g "<pattern>"` for literal text before running broad unthrottled grep. If AST search returns 0 results, check the suggested `cx q -g` fallback before escalating to raw ripgrep.
 - **AST Architecture Intelligence**: Always leverage `pnpm chemx q` to inspect component tiers, exported symbols, props, and hooks with minimal token burn.
 - **Mandatory Blast Radius Pre-Refactor Check**: Prior to modifying any foundational atom (`a-*`), shared molecule, or central composable (`use*`), agents MUST calculate the transitive blast radius (`pnpm chemx q <target> --blast-radius --json` or `chemx({ action: 'q', params: { query: '<target>', blastRadius: true } })`). Never perform blind refactors without mapping direct consumers, transitive dependents, and impacted tiers.
 - **Hybrid RRF Discovery Protocol**: When discovering components, controllers, or state machines without an exact symbol name, agents MUST use hybrid search (`pnpm chemx q "<concept>" --hybrid --json` or `chemx({ action: 'q', params: { query: '<concept>', hybrid: true } })`). This blends BM25 keyword matching and vector cosine similarity via Reciprocal Rank Fusion (RRF), eliminating keyword misses and semantic hallucinations.
@@ -105,6 +120,14 @@
 - **Command Forwarding Syntax**: Agents may invoke either structured action objects (`chemx({ action: 'test' })`, `chemx({ action: 'build' })`, `chemx({ action: 'audit', params: { path: 'src' } })`) or CLI command strings (`chemx({ command: 'test' })`, `chemx({ command: 'build' })`, `chemx({ command: 'audit src' })`).
 - **Master Action & Parameter Dispatch Matrix**:
   ```typescript
+  // Fast Token-Bounded Wrappers & Multi-Action Batching
+  chemx({ commands: ['d', 'p -s', 'test'] }); // Multi-command batch in single turn
+  chemx({ action: 'd' });                      // Zero-context diff (-U0), auto-stat if > 80 lines
+  chemx({ action: 'log', params: { limit: 5 } }); // Compact single-line commit history
+  chemx({ action: 'p', params: { command: '-s' } }); // Read scripts from package.json
+  chemx({ action: 'j', params: { path: 'data.json' } }); // Structural JSON schema shape
+  chemx({ action: 'q', params: { query: 'theme', literal: true } }); // Literal ripgrep (-g)
+
   // Discovery & Impact Analysis
   chemx({ action: 'q', params: { query: 'a-button', blastRadius: true } });
   chemx({ action: 'q', params: { query: 'button state', semantic: true } });
@@ -146,7 +169,7 @@
 - **Read Window Auto-Outline**: Files longer than the chemx read window (100 lines by default), read without a target symbol or slice, automatically render an AST outline to prevent token exhaustion and host buffer spillovers (such as IDE `output.txt` dumps). The read window is a tool budget, not an architecture rule; file size is governed by 1.A.
 - **Enrich Mode (Component Capsules Only)**: When an agent needs both exported signatures AND logic flow for a component capsule, use `enrich: true` with `outline: true`: one response card holds the outline and a compacted logic skeleton, optionally with a forward trace or reverse caller chain (`traceSymbol`, `backtraceSymbol`). The skeleton generator is tuned for components; on procedural modules (services, CLI code, utilities) enrich saves only a few percent over reading the whole file, so use plain `outline: true` or `symbol: '<name>'` there.
 - **Symbol Connection Graph Over Multi-File Dumps**: Rather than reading multiple files to understand imports and consumers, agents MUST request symbol connections: `chemx({ action: 'read', params: { path, symbol: '<name>', connections: true } })` or `chemx({ action: 'q', params: { query, connections: true } })`. This instantly returns the definition, imported dependencies, and caller references in ~45 tokens.
-- **Prohibition on Native File Analyzers (`view_file` Ban)**: AI agents are strictly prohibited from using native IDE file-viewing tools (`view_file`, `read_file`, `cat`, `head`, `tail`, or full-file context dumps). Dumping raw files burns thousands of tokens, causes premature context exhaustion, and defeats the token economics of the molecular architecture. All inspections MUST flow through Chemical X AST readers.
+- **Token-First File Inspection & Native Fallback**: AI agents should prioritize Chemical X AST readers (`cx read --outline` or `cx read --symbol`) to conserve tokens. Dumping raw files burns thousands of tokens and causes premature context exhaustion. If an agent requires exact raw verification or unformatted bytes, native tools (`view_file`, `grep`, `cat`) are permitted as an intentional fallback.
 
 ### O. Universal Programmatic File Jig & Closed-Loop Execution Protocol
 - **Deterministic Parameterized Synthesis**: When creating non-UI files (services, API route handlers, state stores, database repositories, utilities, or test specs), AI agents MUST NOT emit hundreds of lines of mechanical boilerplate via raw file writing tools. Agents MUST invoke `chemx generate --jig=<kind>` or `chemx({ action: 'generate', params: { jig: true, kind, name, ... } })`.
@@ -275,11 +298,7 @@
 - When branching performs uniform operations (e.g. mapping string keys to action handlers, CSS classes, prompt builders, or payload converters), extract into an O(1) keyed dictionary or method map (`const Registry = { ... }; Registry[key](...)`).
 - **Branch Chains**: An `if` / `else if` chain of 3 or more branches testing the same subject is a lookup, not a series of decisions. Use a keyed map; do not hoist a named boolean per branch (3.A does not apply to such chains).
 - **Prototype Pollution Guardrail**: Always guard dynamic object key access using `Object.hasOwn(Registry, key)` or `Object.prototype.hasOwnProperty.call(Registry, key)` before invoking mapped methods.
-- **Architectural Benefits**:
-  - O(1) constant time lookup instead of O(N) linear string comparison branching.
-  - Eliminates boilerplate syntax duplication, drastically slashing token burn and AI context footprint.
-  - Complies with the Open-Closed Principle (OCP): new handlers can be registered dynamically without modifying the dispatcher AST.
-  - Enables granular unit testing and mocking of individual handlers in isolation.
+- **Architectural Benefits**: O(1) lookup over O(N) string branching, eliminates boilerplate syntax duplication, complies with OCP, and isolates unit testing.
 
 ### F. Name Quality, Assertion Prefixes & Adjacency
 - **Assertion Prefixes**: A condition name starts with `is`, `are`, `has`, `have`, `can`, `could`, `should`, `would`, `does`, `did`, `needs`, `must`, `allows`, `enables`, `contains`, `includes`, `supports`, `requires`, `exceeds`, `matches`, or `wants`, followed by its subject (`isEscapeChar`, `exceedsHookBudget`). A bare verb callee (`test`, `existsSync`, `includes`, `startsWith`) is not a name: bind its result to one first.
@@ -287,6 +306,11 @@
 - **Adjacency**: Declare a single-use named boolean on the statement immediately before its `if`. Hoist it only when it is referenced 2 or more times in the enclosing function, and then only to a point before its first use. A wall of `const is*` declarations at function top is a readability regression.
 - **No Double Negation**: `if (!isNotFound)` names the wrong side. Name the positive and negate at the point of use.
 
+### G. Explicit Guardrail Aborts (No Silent Failures)
+- Guard clauses in event handlers, mutations, and async flows must never fail silently via bare `return;`.
+- Halting execution requires an explicit contract: return a `ResultTuple` (`return [null, error]`), emit diagnostic logging (`logger.warn(...)`), update a user-facing error state (`state.error = '...'`), or throw a domain invariant.
+- **Exemptions**: Benign lifecycle no-ops (`abortSignal.aborted`, `!isMounted`), optional prop callbacks (`!props.onClick`), debounce/throttle timers, and pure query predicates.
+
 ---
 
 ## 4. Reactivity, Composables & Hooks
@@ -469,15 +493,3 @@ Raw inline `style="..."` attributes are strictly prohibited. Visual styling flow
 ### C. "No Fake Doc-Sync" Anti-Pattern
 - Mirroring the "No Fake Green" testing rule in Section 10.D, superficial doc edits (whitespace tweaks, comment formatting, minor typo fixes) made merely to pass CI touch-checks without addressing substantive semantic changes are strictly prohibited.
 - Documentation reviews must verify substantive alignment between code behavior and documented contracts.
-
-
-## Chemical X Codebase Query Machine Protocol
-- Search First Rule: AI agents MUST invoke 'pnpm chemx q "<query>"' (or 'npx chemx search "<query>"') before running broad ripgrep, find, or file dumping.
-- AST Architecture Intelligence: Always leverage 'pnpm chemx q' to inspect component tiers, exported symbols, props, and hooks with minimal token burn.
-- Inspect Mode: Use 'pnpm chemx q "<capsule-name>" --inspect' to examine props and hooks without reading entire source files.
-- JSON Mode: Use 'pnpm chemx 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 ('pnpm chemx verify', 'npx chemx verify', 'pnpm chemx build', 'npx chemx build') before running terminal commands.
-

package/cli/audit/ast-visitors.js

@@ -5,7 +5,12 @@ import {
   isCustomHookFunction,
   resolveStartLine,
   isZeroDelayTimeout,
-  isUnguardedConsoleCall
+  isUnguardedConsoleCall,
+  isSilentGuardClause,
+  isSwallowedCatch,
+  countOptionalChainingDepth,
+  isCombinatorCall,
+  isRawBooleanArg
 } from './rules-predicates.js';
 import { validateHookReturnShape } from './hook-shape-validator.js';
 import { evaluateComponentStructuralWeight } from './structural-weight-evaluator.js';
@@ -117,6 +122,22 @@ export const createAstVisitors = ({ relativePath, violations, hookRegistry, conf
           });
         }
       }
+
+      const silentGuard = isSilentGuardClause(astPath, t);
+      if (silentGuard) {
+        const line = astPath.node.loc?.start.line || 1;
+        const meta = RULE_REGISTRY.CONTROL_FLOW_SILENT_GUARD;
+        violations.push({
+          filePath: relativePath,
+          line,
+          column: astPath.node.loc?.start.column || 1,
+          hazard: `Silent guard abort detected in ${silentGuard.funcName}: bare return; swallows error condition without logging or error state. Return [null, error] or emit diagnostic per Directive 3.G.`,
+          rule: 'CONTROL_FLOW_SILENT_GUARD',
+          severity: meta.severity,
+          pillar: meta.pillar,
+          directive: meta.directive
+        });
+      }
     },
 
     ConditionalExpression(astPath) {
@@ -299,6 +320,100 @@ export const createAstVisitors = ({ relativePath, violations, hookRegistry, conf
           directive: meta.directive
         });
       }
+
+      // Pillar 6: Orphaned Event Listener
+      if (t.isMemberExpression(callee) && t.isIdentifier(callee.property, { name: 'addEventListener' })) {
+        const fnParent = astPath.getFunctionParent();
+        let hasCleanup = false;
+        if (fnParent) {
+          const fnName = fnParent.node.id?.name || '';
+          if (fnName === 'listen') {
+            hasCleanup = true;
+          } else {
+            fnParent.traverse({
+              CallExpression(innerCall) {
+                const innerCallee = innerCall.node.callee;
+                if (t.isMemberExpression(innerCallee) && t.isIdentifier(innerCallee.property, { name: 'removeEventListener' })) {
+                  hasCleanup = true;
+                }
+              }
+            });
+          }
+        }
+        if (!hasCleanup) {
+          const line = astPath.node.loc?.start.line || 1;
+          const meta = RULE_REGISTRY.LIFECYCLE_ORPHANED_LISTENER;
+          violations.push({
+            filePath: relativePath,
+            line,
+            column: astPath.node.loc?.start.column || 1,
+            hazard: 'Raw addEventListener call lacking lifecycle disposer or removeEventListener teardown',
+            rule: 'LIFECYCLE_ORPHANED_LISTENER',
+            severity: meta.severity,
+            pillar: meta.pillar,
+            directive: meta.directive
+          });
+        }
+      }
+
+      // Pillar 2: Combinator Raw Boolean Arguments
+      if (isCombinatorCall(callee, t)) {
+        const hasRawArg = astPath.node.arguments.some((arg) => isRawBooleanArg(arg, t));
+        if (hasRawArg) {
+          const line = astPath.node.loc?.start.line || 1;
+          const meta = RULE_REGISTRY.COMBINATOR_RAW_BOOLEAN;
+          violations.push({
+            filePath: relativePath,
+            line,
+            column: astPath.node.loc?.start.column || 1,
+            hazard: `Raw boolean expression passed to ${callee.name}(). Decompose into named predicate or thunk.`,
+            rule: 'COMBINATOR_RAW_BOOLEAN',
+            severity: meta.severity,
+            pillar: meta.pillar,
+            directive: meta.directive
+          });
+        }
+      }
+    },
+
+    // Pillar 2: Swallowed Exceptions
+    CatchClause(astPath) {
+      if (isSwallowedCatch(astPath, t)) {
+        const line = astPath.node.loc?.start.line || 1;
+        const meta = RULE_REGISTRY.ERROR_SWALLOWED_EXCEPTION;
+        violations.push({
+          filePath: relativePath,
+          line,
+          column: astPath.node.loc?.start.column || 1,
+          hazard: 'Swallowed exception in catch block without active handling, logging, or ResultTuple',
+          rule: 'ERROR_SWALLOWED_EXCEPTION',
+          severity: meta.severity,
+          pillar: meta.pillar,
+          directive: meta.directive
+        });
+      }
+    },
+
+    // Pillar 4: Deep Optional Chaining Churn
+    OptionalMemberExpression(astPath) {
+      const isParentOptional = t.isOptionalMemberExpression(astPath.parent) || t.isOptionalCallExpression(astPath.parent);
+      if (!isParentOptional) {
+        const depth = countOptionalChainingDepth(astPath.node, t);
+        if (depth >= 3) {
+          const line = astPath.node.loc?.start.line || 1;
+          const meta = RULE_REGISTRY.DATA_FLOW_OPTIONAL_CHAINING_CHURN;
+          violations.push({
+            filePath: relativePath,
+            line,
+            column: astPath.node.loc?.start.column || 1,
+            hazard: `Deep optional chaining churn (${depth} chained operators >= 3 limit). Level data shapes line 1.`,
+            rule: 'DATA_FLOW_OPTIONAL_CHAINING_CHURN',
+            severity: meta.severity,
+            pillar: meta.pillar,
+            directive: meta.directive
+          });
+        }
+      }
     },
 
     // Pillar 4: Type Co-location

package/cli/audit/history.js

@@ -11,10 +11,43 @@ const GREEN = '\x1b[32m';
 const YELLOW = '\x1b[33m';
 const RED = '\x1b[31m';
 
+export const findChemxDir = (startDir = process.cwd()) => {
+  const hasCustomRoot = Boolean(process.env.CHEMX_PROJECT_ROOT);
+  if (hasCustomRoot) {
+    return path.resolve(process.env.CHEMX_PROJECT_ROOT, '.chemx');
+  }
+
+  let current = path.resolve(startDir);
+  let gitRoot = null;
+  while (true) {
+    const candidate = path.join(current, '.chemx');
+    const hasExistingChemx = fs.existsSync(candidate);
+    if (hasExistingChemx) {
+      return candidate;
+    }
+    const hasGit = !gitRoot && fs.existsSync(path.join(current, '.git'));
+    if (hasGit) {
+      gitRoot = current;
+    }
+    const parent = path.dirname(current);
+    const isRootReached = parent === current;
+    if (isRootReached) break;
+    current = parent;
+  }
+
+  const hasDiscoveredGitRoot = Boolean(gitRoot);
+  if (hasDiscoveredGitRoot) {
+    return path.join(gitRoot, '.chemx');
+  }
+
+  return path.resolve(startDir, '.chemx');
+};
+
 export const ensureChemxDir = (cwd = process.cwd()) => {
-  const dir = path.resolve(cwd, '.chemx');
+  const dir = findChemxDir(cwd);
   try {
-    if (!fs.existsSync(dir)) {
+    const isDirMissing = !fs.existsSync(dir);
+    if (isDirMissing) {
       fs.mkdirSync(dir, { recursive: true });
     }
   } catch {
@@ -22,17 +55,21 @@ export const ensureChemxDir = (cwd = process.cwd()) => {
   }
 
   // Ensure .chemx is gitignored if git repo exists
-  const gitDir = path.resolve(cwd, '.git');
-  if (fs.existsSync(gitDir)) {
-    const gitignorePath = path.resolve(cwd, '.gitignore');
+  const targetParent = path.dirname(dir);
+  const gitDir = path.resolve(targetParent, '.git');
+  const hasGit = fs.existsSync(gitDir);
+  if (hasGit) {
+    const gitignorePath = path.resolve(targetParent, '.gitignore');
     try {
-      let content = fs.existsSync(gitignorePath) ? fs.readFileSync(gitignorePath, 'utf-8') : '';
-      if (!content.includes('.chemx')) {
-        const trailingNewline = content.endsWith('\n') || content.length === 0 ? '' : '\n';
+      const hasGitignore = fs.existsSync(gitignorePath);
+      let content = hasGitignore ? fs.readFileSync(gitignorePath, 'utf-8') : '';
+      const hasChemxEntry = content.includes('.chemx');
+      if (!hasChemxEntry) {
+        const hasTrailingNewline = content.endsWith('\n') || content.length === 0;
+        const trailingNewline = hasTrailingNewline ? '' : '\n';
         fs.appendFileSync(gitignorePath, `${trailingNewline}# Chemical X local telemetry & audit history\n.chemx/\n`, 'utf-8');
       }
-    } catch (err) {
-      const error = err instanceof Error ? err : new Error(String(err));
+    } catch {
       return dir;
     }
   }

package/cli/audit/rules-predicates.js

@@ -138,3 +138,203 @@ export const isNonInteractiveSession = (rawArgs, env = process.env) => {
   const isNotTTY = Boolean(process.stdout && process.stdout.isTTY === false);
   return [hasCliFlag, hasOutputFlag, hasFormatFlag, hasCiEnv, isNotTTY].some(Boolean);
 };
+
+const EXEMPT_TEST_PATTERNS = [
+  /abort/i,
+  /signal/i,
+  /mounted/i,
+  /unmount/i,
+  /destroy/i,
+  /cleanup/i,
+  /timer/i,
+  /timeout/i,
+  /interval/i,
+  /debounce/i,
+  /throttle/i,
+  /\bon[A-Z]/,
+  /\bcall(?:back|backFn)?\b/i,
+  /\bcb\b/i,
+  /\bhandler\b/i
+];
+
+const MUTATING_FUNCTION_PATTERNS = [
+  /^handle[A-Z]/,
+  /^on[A-Z]/,
+  /^(?:save|update|delete|remove|create|add|insert|post|send|process|submit|dispatch|execute|mutate|checkout|charge|sync|write)/i
+];
+
+const PURE_PREDICATE_PATTERNS = [
+  /^(?:is|has|can|should|check)[A-Z]/
+];
+
+const isDiagnosticOrErrorStatement = (stmt, t) => {
+  if (t.isThrowStatement(stmt)) return true;
+  if (t.isExpressionStatement(stmt)) {
+    const expr = stmt.expression;
+    if (t.isCallExpression(expr)) {
+      const callee = expr.callee;
+      if (t.isMemberExpression(callee)) {
+        const objName = t.isIdentifier(callee.object) ? callee.object.name : '';
+        const propName = t.isIdentifier(callee.property) ? callee.property.name : '';
+        if (['console', 'logger', 'log'].includes(objName)) return true;
+        if (/^(?:error|warn|info|trace|notify|alert)/i.test(propName)) return true;
+      }
+      if (t.isIdentifier(callee) && /^(?:report|notify|alert|set.*Error|handleError)/i.test(callee.name)) return true;
+    }
+    if (t.isAssignmentExpression(expr)) {
+      const left = expr.left;
+      if (t.isMemberExpression(left) && t.isIdentifier(left.property) && /error/i.test(left.property.name)) return true;
+      if (t.isIdentifier(left) && /error/i.test(left.name)) return true;
+    }
+  }
+  return false;
+};
+
+export const isSilentGuardClause = (ifPath, t) => {
+  const node = ifPath.node;
+  if (!node || node.alternate) return false;
+
+  let hasBareReturn = false;
+  let hasDiagnosticOrHandling = false;
+
+  const checkStatement = (stmt) => {
+    if (t.isReturnStatement(stmt)) {
+      const isBare = !stmt.argument || (t.isIdentifier(stmt.argument) && stmt.argument.name === 'undefined');
+      if (isBare) hasBareReturn = true;
+    } else if (isDiagnosticOrErrorStatement(stmt, t)) {
+      hasDiagnosticOrHandling = true;
+    }
+  };
+
+  if (t.isReturnStatement(node.consequent)) {
+    checkStatement(node.consequent);
+  } else if (t.isBlockStatement(node.consequent)) {
+    for (const stmt of node.consequent.body) {
+      checkStatement(stmt);
+    }
+  }
+
+  if (!hasBareReturn || hasDiagnosticOrHandling) return false;
+
+  const collectTestIdentifiers = (n) => {
+    const names = [];
+    const walk = (item) => {
+      if (!item) return;
+      if (t.isIdentifier(item)) {
+        names.push(item.name);
+      } else if (t.isMemberExpression(item)) {
+        walk(item.object);
+        walk(item.property);
+      } else if (t.isUnaryExpression(item)) {
+        walk(item.argument);
+      } else if (t.isLogicalExpression(item) || t.isBinaryExpression(item)) {
+        walk(item.left);
+        walk(item.right);
+      } else if (t.isCallExpression(item)) {
+        walk(item.callee);
+        for (const arg of item.arguments) walk(arg);
+      }
+    };
+    walk(n);
+    return names;
+  };
+
+  const testIdentifiers = collectTestIdentifiers(node.test);
+  const isExemptTest = testIdentifiers.some((name) => EXEMPT_TEST_PATTERNS.some((pat) => pat.test(name)));
+  if (isExemptTest) return false;
+
+  const funcParent = ifPath.getFunctionParent();
+  if (!funcParent) return false;
+
+  let funcName = '';
+  if (funcParent.node.id?.name) {
+    funcName = funcParent.node.id.name;
+  } else if (funcParent.parentPath?.isVariableDeclarator() && t.isIdentifier(funcParent.parentPath.node.id)) {
+    funcName = funcParent.parentPath.node.id.name;
+  } else if (t.isIdentifier(funcParent.node.key)) {
+    funcName = funcParent.node.key.name;
+  }
+
+  const isAsync = Boolean(funcParent.node.async);
+  const isMutatingName = MUTATING_FUNCTION_PATTERNS.some((pat) => pat.test(funcName));
+  const isPurePredicate = PURE_PREDICATE_PATTERNS.some((pat) => pat.test(funcName));
+
+  if (isPurePredicate && !isAsync && !isMutatingName) return false;
+
+  const isTargetFunction = isAsync || isMutatingName;
+  if (!isTargetFunction) return false;
+
+  return { funcName: funcName || (isAsync ? 'async operation' : 'command handler') };
+};
+
+export const isSwallowedCatch = (astPath, t) => {
+  const body = astPath.node.body?.body || [];
+  if (body.length === 0) return true;
+
+  const nonNoopStatements = body.filter((stmt) => !t.isEmptyStatement(stmt));
+  if (nonNoopStatements.length === 0) return true;
+
+  let hasActiveHandling = false;
+  astPath.traverse({
+    ThrowStatement() {
+      hasActiveHandling = true;
+    },
+    ReturnStatement(retPath) {
+      if (retPath.node.argument !== null) {
+        hasActiveHandling = true;
+      }
+    },
+    CallExpression(callPath) {
+      const callee = callPath.node.callee;
+      if (t.isMemberExpression(callee)) {
+        const objName = t.isIdentifier(callee.object) ? callee.object.name : '';
+        const propName = t.isIdentifier(callee.property) ? callee.property.name : '';
+        const isLogger = ['console', 'logger', 'log', 'telemetry', 'reportError'].includes(objName);
+        const isHandlingMethod = ['error', 'warn', 'info', 'captureException', 'track'].includes(propName);
+        const isProcessStderr = t.isMemberExpression(callee.object) &&
+          t.isIdentifier(callee.object.object, { name: 'process' }) &&
+          t.isIdentifier(callee.object.property, { name: 'stderr' });
+        if (isLogger || isHandlingMethod || isProcessStderr) {
+          hasActiveHandling = true;
+        }
+      } else if (t.isIdentifier(callee)) {
+        const isHandler = ['handleError', 'reportError', 'captureException', 'toResult'].includes(callee.name);
+        if (isHandler) {
+          hasActiveHandling = true;
+        }
+      }
+    }
+  });
+
+  return !hasActiveHandling;
+};
+
+export const countOptionalChainingDepth = (node, t) => {
+  let count = 0;
+  let curr = node;
+  while (curr && (t.isOptionalMemberExpression(curr) || t.isOptionalCallExpression(curr) || t.isMemberExpression(curr))) {
+    if (curr.optional) {
+      count++;
+    }
+    curr = curr.object || curr.callee;
+  }
+  return count;
+};
+
+const COMBINATOR_NAMES = new Set(['all', 'any', 'none', 'allPass', 'anyPass', 'nonePass']);
+
+export const isCombinatorCall = (callee, t) => {
+  if (t.isIdentifier(callee)) {
+    return COMBINATOR_NAMES.has(callee.name);
+  }
+  return false;
+};
+
+export const isRawBooleanArg = (arg, t) => {
+  if (t.isBinaryExpression(arg)) return true;
+  if (t.isLogicalExpression(arg)) return true;
+  if (t.isBooleanLiteral(arg)) return true;
+  if (t.isUnaryExpression(arg, { operator: '!' })) return true;
+  return false;
+};
+

package/cli/audit/rules-registry.js

@@ -111,6 +111,21 @@ export const RULE_REGISTRY = {
     severity: 'MEDIUM',
     directive: 'Replace repetitive dispatch switch with an O(1) keyed dictionary or method map (Directive 3.E)'
   },
+  CONTROL_FLOW_SILENT_GUARD: {
+    pillar: PILLARS.PILLAR_2,
+    severity: 'MEDIUM',
+    directive: 'Replace silent bare return in side-effecting logic with explicit ResultTuple, logger diagnostic, or error state (Directive 3.G)'
+  },
+  ERROR_SWALLOWED_EXCEPTION: {
+    pillar: PILLARS.PILLAR_2,
+    severity: 'CRITICAL',
+    directive: 'Do not swallow caught exceptions silently; log with error context or return explicit ResultTuple error (Directive 3.B)'
+  },
+  COMBINATOR_RAW_BOOLEAN: {
+    pillar: PILLARS.PILLAR_2,
+    severity: 'MEDIUM',
+    directive: 'Do not pass inline boolean expressions or raw booleans into logical combinators; use named predicates or thunks (Directive 3.A)'
+  },
   HOOK_SATURATION: {
     pillar: PILLARS.PILLAR_3,
     severity: 'HIGH',
@@ -141,6 +156,11 @@ export const RULE_REGISTRY = {
     severity: 'CRITICAL',
     directive: 'Replace render-hack setTimeout(0) with await nextTick() or RAF'
   },
+  LIFECYCLE_ORPHANED_LISTENER: {
+    pillar: PILLARS.PILLAR_6,
+    severity: 'HIGH',
+    directive: 'Wrap event listeners in self-cleaning disposers or register pairing removeEventListener (Directive 3.F)'
+  },
   TYPE_COLOCATION: {
     pillar: PILLARS.PILLAR_4,
     severity: 'MEDIUM',
@@ -156,6 +176,11 @@ export const RULE_REGISTRY = {
     severity: 'MEDIUM',
     directive: 'Use live API data or explicit empty states instead of mock placeholders'
   },
+  DATA_FLOW_OPTIONAL_CHAINING_CHURN: {
+    pillar: PILLARS.PILLAR_4,
+    severity: 'LOW',
+    directive: 'Level incoming data shapes line 1 using sentinels or normalizeArray instead of deep optional chaining churn (Directive 4.D)'
+  },
   RAW_INLINE_STYLE: {
     pillar: PILLARS.PILLAR_5,
     severity: 'MEDIUM',

package/cli/commands/cmd-router.js

@@ -75,6 +75,41 @@ export const dispatchCommand = async (firstArg, rawArgs, runAudit, getPackageVer
       await runSearch(rawArgs.slice(1), true);
       break;
     }
+    case 'd':
+    case 'diff': {
+      const { runDiff } = await import('./cmd-wrappers.js');
+      await runDiff(rawArgs, true);
+      break;
+    }
+    case 'log': {
+      const { runLog } = await import('./cmd-wrappers.js');
+      await runLog(rawArgs, true);
+      break;
+    }
+    case 'p':
+    case 'pkg': {
+      const { runPkg } = await import('./cmd-wrappers.js');
+      await runPkg(rawArgs, true);
+      break;
+    }
+    case 'f':
+    case 'ls': {
+      const { runFiles } = await import('./cmd-wrappers.js');
+      await runFiles(rawArgs, true);
+      break;
+    }
+    case 'j':
+    case 'json': {
+      const { runJsonShape } = await import('./cmd-wrappers.js');
+      await runJsonShape(rawArgs, true);
+      break;
+    }
+    case 'do':
+    case 'batch': {
+      const { runBatch } = await import('./cmd-wrappers.js');
+      await runBatch(rawArgs, true, (cmd, args) => dispatchCommand(cmd, args, runAudit, getPackageVersion, isCapsulePrefix));
+      break;
+    }
     case 'trace': {
       const { runTraceCli } = await import('../search-commands-graph.js');
       await runTraceCli(rawArgs.slice(1), true);