@chemx/starter-kit 26.10.7-1061 → 26.10.10-75

package/AGENTS.md

@@ -5,6 +5,24 @@
 
 ---
 
+## ⚡ Quick Agent Reflex Table (Token-Bounded Commands)
+| Standard Reflex | `chemx` Equivalent | Token & Architecture Advantage |
+| :--- | :--- | :--- |
+| `grep -rn "pattern" .` | `chemx q -g "pattern"` or `chemx q -g "pattern" -l` | Fixed-string search of every text file `.gitignore` allows (submodules, docs, styles, JSON, PHP); full `path:line:text` lines or line-only (-l); `--regex` opts into regex; `-- <pattern>` for a pattern starting with `-`. Uses `rg` when installed, a JS walker otherwise; the header states files searched and the engine. |
+| `git diff` | `chemx d` | Zero-context (`-U0`), auto-collapses to `--stat` if > 80 lines, micro-syncs index. |
+| `git log` | `chemx log -n 5` | One-line commit history (5 commits measured about 140 tokens on 2026-10-09, roughly 28 per commit). |
+| `find . -name "*.vue"` | `chemx f "*.vue"` | Strictly filters by `.gitignore` and ignored dirs. |
+| `cat package.json` | `chemx p -s` / `chemx p <script>` | Single script or dep extraction (`p -s` listing 15 scripts measured about 240 tokens on 2026-10-09). |
+| `cat <data.json>` | `chemx j <file.json>` | Structural schema shape only; collapses repeating arrays. |
+| `cat <file>` / `head <file>` | `chemx read <file> --outline` | AST signatures only (outline of `cli/reader.js` measured about 300 tokens against about 4,800 for the file, 2026-10-09; other targets in `benchmarks/README.md`). |
+| `npm test` / `tsc` | `chemx test` / `chemx verify` | Prints a summary on success and the failing diffs on failure. |
+| `cat .chemx/history.json` | `chemx audit --feed=scopes` / MCP `audit_feed` | Recorded audit results as flat rows (per scope, per run or per pillar) without re-running the audit; `--json` for every row. |
+| Auditing each package by hand | `chemx audit --each=submodules` | One scoped audit per submodule or workspace package, then a one-line-per-package summary. |
+| Multiple CLI actions | `chemx 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
@@ -14,7 +32,7 @@
   - **Hook & State Density**: Max 4 independent hooks/state setters before extracting into a domain hook or reducer.
   - **Render Tree Depth**: Max 4 nesting levels in JSX/templates; nested ternaries are strictly banned in favor of computed descriptor objects.
   - **Prop Surface Area**: Max 7 flat props before grouping into a typed domain entity model.
-  - **Line Budget**: Soft warning at 250 lines only if cyclomatic complexity is high.
+  - **Line Budget**: Soft warning at 250 lines only if cyclomatic complexity is high. Any file above 500 lines is a monolith warning (HIGH at 1,000, CRITICAL at 2,000). View entry templates (1.B) warn above 200 template lines. Type files follow the same budget (2.A). Lines are counted like `wc -l`. Tier globs for molecules and views are configurable in `.chemxrc` (`tiers: { molecule: ["**/prefabs/**"] }`).
 - **Atomic-Strict Profile (`--profile=atomic-strict`)**: Opt-in strict mode enforcing 100-line capsule caps and mandatory atomization for teams building foundational design system component primitives.
 - **The Rule of Three for Abstractions**: Premature abstraction is worse than duplication. Do NOT extract an atom or molecule until a pattern is reused across 3+ distinct features, or until it encapsulates isolated behavioral/accessibility requirements.
 
@@ -26,7 +44,7 @@
 - Every molecule and organism lives in an isolated, self-contained directory capsule:
   ```
   m-<feature>-card/
-  ├── m-<feature>-card.<ext>          (< 100 lines: declarative layout & bindings)
+  ├── m-<feature>-card.<ext>          (declarative layout & bindings; line budget per 1.A)
   ├── m-<feature>-card.controller.ts  (pure reactive state & 2-stage booleans)
   ├── _m-<feature>-card.scss          (mixin-only glass styling)
   ├── types.d.ts                      (pure Props & Emits declarations)
@@ -38,12 +56,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,14 +79,14 @@
   - 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 `chemx q "<query>"` for AST symbols or `chemx q -g "<pattern>"` for literal text before running broad unthrottled grep. AST answers cover only the index scope they print (`index: scope . (...)`). The default scope is the project scope: the `scope` key of `.chemx/config.json` when set, else the whole root. In a git repo it holds the git-tracked source files plus untracked files `.gitignore` allows, minus generated and vendored dirs (`node_modules`, `dist`, `coverage`...); outside git, every source file outside those dirs. A git-ignored dir is indexed only when passed explicitly with `--dir=<path>`; `chemx q -g` searches text across the repo. An answer with `status: inconclusive` (exit 3) is not a negative result.
 - **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.
-- **Semantic Vector Discovery**: Use `pnpm chemx q "<query>" --semantic --json` for purely conceptual lookups.
+- **Hybrid Discovery**: When looking for components, controllers, or state machines without an exact symbol name, try hybrid search (`pnpm chemx q "<words>" --hybrid --json` or `chemx({ action: 'q', params: { query: '<words>', hybrid: true } })`). It fuses BM25 keyword ranking with feature-hash similarity via Reciprocal Rank Fusion (RRF). Both halves are lexical: they match names, tokens and trigrams, not meaning, so a miss is not proof of absence. Follow up with `chemx q -g` for the words you expect in the code.
+- **Feature-hash similarity (`--semantic`)**: `pnpm chemx q "<words>" --semantic --json` ranks exported names by 128-dim hashed name/trigram vectors. It is fuzzy lexical matching (useful for spelling variants such as `useTabs`/`useTabBar`), not a learned embedding: it will not connect `login` to `authentication`.
 - **Inspect Mode**: Use `pnpm chemx q "<capsule-name>" --inspect` to examine props and hooks without reading entire source files into context.
 - **JSON & Columnar Mode**: Use `pnpm chemx q "<query>" --json` for zero-overhead, machine-readable agent lookups in token-compact columnar format (`cols` and `rows`).
-- **Tier Filtering**: Use `pnpm chemx q "<query>" --tier=molecule` (or `atom`, `organism`, `hook`) to narrow scope instantly.
+- **Tier Filtering**: Use `pnpm chemx q "<query>" --tier=molecule` (or `atom`, `organism`, `hook`) to narrow scope.
 
 ### I. Capsule Trust-Tier Classification & Audit Escalation
 - **Tier 1 (Pure / Stateless)**: Atoms, formatters, pure validators, and API client wrappers. Agents may trust exported interface contracts without inspecting internal implementation details.
@@ -82,10 +99,10 @@
 - **Prohibition on Method Slicing**: Never split methods sharing internal instance state into isolated files or micro-functions. Atomization must not destroy the cohesive state machine.
 - **Decomposition Protocol**: When approaching file line limits, decompose exclusively by extracting pure, stateless helper functions, mathematical derivations, and boundary validators out of the class into standalone utility capsules, preserving the class methods and instance state together.
 
-### K. The Verification-First Protocol & Zero-Token-Burn Pipeline
+### K. The Verification-First Protocol & Compact Verification Pipeline
 - **Verification First Rule**: AI agents MUST NEVER execute raw, unthrottled `npm test`, `pnpm test`, `vitest`, `tsc --noEmit`, or `npm run build` directly in a bash subshell. Raw shell executions flood the context window with hundreds of lines of passing checkmarks, compiler noise, and bundle asset tables, burning thousands of tokens and causing premature context exhaustion.
 - **MCP Verification Tools First**: Agents MUST invoke the dedicated Chemical X MCP tools or CLI wrappers (`pnpm chemx <subcommand>` or `npx chemx <subcommand>`):
-  1. `chemx_verify` (or `pnpm chemx verify --json` / `npx chemx verify --json`): Runs the full verification pipeline (AST Audit + Typecheck + Tests) and returns a single token-compact status card (~45 tokens if green).
+  1. `chemx_verify` (or `pnpm chemx verify --json` / `npx chemx verify --json`): Runs the full verification pipeline (AST Audit + Typecheck + Tests) and returns a short status card when green (size not benchmarked).
   2. `chemx_typecheck` (or `pnpm chemx typecheck --json` / `npx chemx typecheck --json`): Runs silent TypeScript typecheck; returns structured diagnostics only if errors exist.
   3. `chemx_test` (or `pnpm chemx test --json` / `npx chemx test --json`): Runs silent project tests; suppresses passing tests and returns ONLY failing test assertions and stack diffs.
   4. `chemx_audit_build` (or `pnpm chemx build --json` / `npx chemx build --json`): Runs silent production builds; catalogs diagnostics into TypeScript, Rollup, and style budgets.
@@ -93,21 +110,30 @@
 
 ### L. Database-First Swarm Coordination & The Zero-Markdown-Monolith Directive
 - **Database as the Master Source of Truth**: The multi-agent orchestrator and subagents MUST record all milestones, task assignments, status changes, file locks, and architectural contracts directly in `.chemx/index.db` (`agent_tasks`, `file_lock_queue`, `agent_feed`) rather than creating monolithic, multi-thousand-token markdown specification files.
-- **Prohibition on Monolithic Project Markdown Parsing**: Subagents MUST NOT load giant monolithic `PROJECT.md` or status markdown files into context. Subagents query only their assigned task slice and dependencies via `pnpm chemx team task list --agent=@my-id` or MCP `chemx_team_task`, slashing token consumption by 80%+.
+- **Prohibition on Monolithic Project Markdown Parsing**: Subagents MUST NOT load giant monolithic `PROJECT.md` or status markdown files into context. Subagents query only their assigned task slice and dependencies via `pnpm chemx team task list --agent=@my-id` or MCP `chemx_team_task`.
+- **Leases and handoff**: A file lock is a 5-minute lease that any chemx command run as the holder extends and that lapses after 5 minutes without activity (`docs/team-locks.md`). The commit hook refuses staged files another handle leases live. `chemx team task handoff <id> @<to> --as=@<from>` passes a task on (assignee or task creator only); it keeps the task `in_progress`, records from/to/by in the feed, and does not move file locks, so the old holder releases and the new owner acquires.
 - **Project Markdown as a Generated Read-Only Projection**: If a human-readable `PROJECT.md` is requested, it MUST be generated on-demand as a read-only projection compiled from the database state via `pnpm chemx team status` or export tools.
 
-### M. The Master MCP Tool Protocol & Zero-Permission Dispatch
+### M. The Master MCP Tool Protocol & Single-Permission Dispatch
 - **Master Gateway Rule**: When operating inside environments with per-tool permission controls (e.g. Antigravity, Claude Desktop, Cursor), AI agents MUST invoke the unified master MCP tool `chemx` (or `chemx({ action, params })`) rather than invoking fragmented tool names or dropping down to bash subshells.
 - **Antigravity Tool Mapping**: In Google Antigravity, `chemx` is registered under server name `chemical-x` (`call_mcp_tool` with `ServerName: "chemical-x"`, `ToolName: "chemx"`). Always prioritize this tool for all AST reading, querying, testing, verification, and file operations.
 - **Strict Ban on Fragmented Sub-Tool Calls**: Agents are strictly prohibited from calling individual tool names (such as `chemx_read`, `chemx_audit`, or `chemx_write`) directly when the master gateway tool is available. Every distinct tool name triggers a separate permission confirmation dialog for the user, resulting in severe prompt fatigue. Calling `chemx({ action, params })` or `chemx({ command })` routes through a single authorization point.
-- **One-Time Approval Advantage**: The `chemx` master tool provides a single authorization point for the user. Once approved, all operations (`test`, `build`, `verify`, `typecheck`, `audit`, `check`, `patch`, `write`, `read`, `team`, `q`, `autofix`, `issue`) execute silently in-process with zero terminal confirmation prompts.
+- **One-Time Approval Advantage**: The `chemx` master tool provides a single authorization point for the user. Once approved, all operations (`test`, `build`, `verify`, `typecheck`, `audit`, `check`, `patch`, `write`, `read`, `team`, `q`, `autofix`, `issue`) run in-process through one tool, so the host asks for one approval for the tool instead of one per action (hosts that prompt per call still may).
 - **In-Band JSON-RPC Communication (Zero Disk Dumps)**: All query, inspection, and verification tools must communicate strictly in-band via MCP `CallToolResult` objects (`content: [{ type: "text", text: "..." }]`). Tools must never dump intermediate text files (.txt/.md) or scratch files to disk for AI consumption.
 - **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 } }); // Repo-wide fixed-string search (-g)
+
   // Discovery & Impact Analysis
   chemx({ action: 'q', params: { query: 'a-button', blastRadius: true } });
-  chemx({ action: 'q', params: { query: 'button state', semantic: true } });
+  chemx({ action: 'q', params: { query: 'button state', semantic: true } }); // feature-hash name similarity
   chemx({ action: 'q', params: { query: 'useAttentionCardController', hybrid: true } });
 
   // Surgical AST Reading & Connections
@@ -121,11 +147,17 @@
   chemx({ action: 'read', params: { path: 'src/...', outline: true, enrich: true, backtraceSymbol: 'handleCheckout' } });
 
   // Surgical Modification & Rules Check
+  // Preview first: dryRun returns the unified diff and writes nothing (CLI: --dry-run or -n)
+  chemx({ action: 'patch', params: { path: 'src/...', target: 'oldCode', replacement: 'newCode', dryRun: true } });
   chemx({ action: 'patch', params: { path: 'src/...', target: 'oldCode', replacement: 'newCode' } });
+  // Removing a top-level declaration (renames included) is refused unless named (CLI: --allow-remove=oldName)
+  chemx({ action: 'patch', params: { path: 'src/...', target: 'oldName', replacement: 'newName', allowRemoved: ['oldName'] } });
+  // write creates; replacing an existing file needs overwrite (CLI: --overwrite)
   chemx({ action: 'write', params: { path: 'src/...', content: '...' } });
+  chemx({ action: 'write', params: { path: 'src/...', content: '...', overwrite: true } });
   chemx({ action: 'check', params: { path: 'src/...' } });
 
-  // Deterministic Parameterized Scaffolding (Universal Jig - 90%+ Token Reduction)
+  // Deterministic Parameterized Scaffolding (Programmatic Jig; token saving not benchmarked)
   chemx({ action: 'generate', params: { jig: true, kind: 'service', name: 'payment-gateway', methods: [{ name: 'charge', params: 'amount: number' }] } });
   chemx({ action: 'generate', params: { jig: true, kind: 'route', name: 'api-orders', routes: ['GET /orders', 'POST /orders'] } });
   chemx({ action: 'generate', params: { jig: true, kind: 'store', name: 'session-store' } });
@@ -145,17 +177,17 @@
 - **Targeted Symbol-Only Extraction**: AI agents MUST NEVER dump entire source files into context. When an agent needs to inspect a function, hook, interface, or class, it MUST request only that specific symbol: `chemx({ action: 'read', params: { path, symbol: '<name>' } })`.
 - **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.
+- **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 returns the definition, imported dependencies, and caller references. Size grows with the symbol: `q <symbol> --connections` measured about 140 tokens and `read --symbol --connections` about 2,400 for `readTokenOptimized` on 2026-10-09.
+- **Token-First File Inspection & Native Fallback**: AI agents should prioritize Chemical X AST readers (`chemx read --outline` or `chemx 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
+### O. 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, ... } })`.
-- **The 90%+ Output Token Reduction Thesis**: Passing a 30-50 token structured parameter set replaces 1,000-2,500 output tokens of repetitive TypeScript, imports, error tuples, and test boilerplate.
+- **The Output Token Thesis (not benchmarked)**: A short structured parameter set stands in for repetitive TypeScript, imports, error tuples, and test boilerplate. No measurement of the saving exists in this repo; prefer the jig for consistency of the output, not for a promised saving.
 - **The Closed-Loop ChemX Execution Cycle**:
   1. *Generate (Jig)*: Stamp out compliant architecture via `chemx({ action: 'generate', params: { jig: true, ... } })`.
   2. *Read (Outline)*: Inspect AST shape via `chemx({ action: 'read', params: { path, outline: true } })`.
   3. *Patch (Surgical Edit)*: Ingest domain logic via `chemx({ action: 'patch', params: { path, target, replacement } })`.
-  4. *Test (Targeted Slice)*: Run isolated unit tests in milliseconds via `chemx({ action: 'test', params: { target: '<spec-path>' } })`.
+  4. *Test (Targeted Slice)*: Run isolated unit tests for the spec path via `chemx({ action: 'test', params: { target: '<spec-path>' } })`.
   5. *Verify (Full Guard)*: Validate AST score and types via `chemx({ action: 'verify' })`.
 
 ---
@@ -205,6 +237,13 @@
 - **Bidirectional Schema Validation**: Domain types and boundary interfaces must be validated against the active schema or OpenAPI contract rather than treated as independently authoritative.
 - **Drift Prevention**: Never hand-craft unvalidated entity definitions. Mismatches in nullability, default values, or field mutations must fail compile-time checks or contract test suites before ingestion.
 
+### H. Swallowed Exceptions (No Silent Catch)
+- A `catch` must propagate (`throw`), return a value (`return [null, error]`), report (a logger, notifier or handler call), or record the failure in state that outlives the catch (`state.error = err`, a fallback assigned to an outer binding). An empty catch is HIGH; a body that still discards the error is MEDIUM (`ERROR_SWALLOWED_EXCEPTION`).
+- An intentional best-effort catch says so on the catch line, inside the block, or on the line above, with a mandatory reason: `catch { // chemx-allow: best-effort cache warmup is optional }`. The same annotation with a rule id (`// chemx-allow: RULE_ID <reason>`) suppresses that one rule on that line.
+
+### I. Data Leveling (No Optional-Chaining Churn)
+- Level an incoming payload once at the boundary (2.F) with sentinels or `normalizeArray`, instead of chaining three or more `?.` through every consumer (`DATA_FLOW_OPTIONAL_CHAINING_CHURN`).
+
 ---
 
 ## 3. Control Flow & Self-Documenting Logic
@@ -237,7 +276,7 @@
   1. **Structural primitives** (`lib/is/`: `value`, `collection`, `text`, `fs`, `type`): subject-agnostic and finite (`isAbsent`, `hasItems`, `isNonEmptyString`, `pathExists`). They import nothing, and the set does not grow. Every primitive is a TypeScript type predicate (`(x: unknown): x is string`), never a plain `boolean`, or callers lose narrowing.
   2. **Domain vocabulary** (`<subsystem>/<domain>-predicates.<ext>`, colocated with the subsystem it describes): built from Layer 1. A condition earns a domain predicate at its 2nd use; a threshold duplicated across files (`score >= 90`) silently disagrees the day one copy changes, so name it once (`isGradeA`). Promote threshold literals in predicate bodies to named constants (`score >= GRADE_A_THRESHOLD`).
   3. **Decisions**: single-use composites declared at the call site per 3.A. Never extract them: extracting every condition is *indirection masquerading as modularity* (1.A).
-- Before naming a new predicate, search for an existing one (`chemx({ action: 'q', params: { query: '<concept>', semantic: true } })`). A synonym beside an existing predicate (`hasNoItems` beside `isEmpty`) is lexicon rot.
+- Before naming a new predicate, search for an existing one: `chemx q -g "<likely words>"` for the literal names, plus `chemx({ action: 'q', params: { query: '<concept>', hybrid: true } })` for spelling variants. Neither finds pure synonyms (`hasNoItems` vs `isEmpty`), so also scan the predicates module of the domain. A synonym beside an existing predicate is lexicon rot.
 - Repeated filter conditions are Layer 2 candidates: extract the predicate, compose a named higher-order filter, and keep derivations declarative:
   ```typescript
   // ❌ Bad: inlined multi-clause predicate, repeated per derivation
@@ -275,11 +314,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 +322,54 @@
 - **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.
+
+### H. Domain Validator Functions & Lazy Rule Trees
+- When a decision or validation sequence requires 3 or more conditions, cascading early returns at the call site fragment linear control flow and obscure decision logic (`CONTROL_FLOW_CASCADE_GUARDS`).
+- Extract multi-condition validation sequences into a pure **Domain Validator Function** utilizing the canonical `ruleTree` atom (inline the gate in the handler, or extract it into a `validate<Action>` function):
+  - **Stage 1 (Atomic Primitives & Thunks)**: Raw facts or lazy thunks (`() => !user.isVerified`). With `{ failFast: true }`, thunks are skipped once an earlier rule has failed, so later rules can rely on earlier ones. Plain values (`missing: !user`) are evaluated eagerly, and without `failFast` every thunk runs.
+  - **Stage 2 (Domain Rule Tree)**: Categorized tree object (`user: { ... }, cart: { ... }`) evaluated via `ruleTree` or `assertRuleTree`.
+  - **Stage 3 (1-Line Guard Return with Callback)**: Single-line early return accompanied by a diagnostic callback (`if (!gate.ok) return logger.warn(gate.first);`), satisfying Directive 3.G without multiline block ceremonies.
+- **2-Stage Booleans vs Rule Trees**:
+  - Use 2-Stage Booleans (3.A) for 1 or 2 atomic conditions at the call site.
+  - Use `ruleTree` for 3 or more conditions (`CONTROL_FLOW_CASCADE_GUARDS`).
+  ```typescript
+  // ❌ Bad: Cascading early returns at call site (>= 3 guards)
+  const handleCheckout = (cart: Cart, user: User | null, totalCost: number) => {
+    if (!user) return;
+    if (!user.isVerified) return;
+    if (cart.items.length === 0) return;
+    if (user.balance < totalCost) return;
+    processPayment(cart);
+  };
+
+  // ✅ Good: Literate Lazy Rule Tree with 1-line callback return
+  import { ruleTree } from '@chemx/x-atoms';
+
+  const handleCheckout = (cart: Cart, user: User | null, totalCost: number) => {
+    const gate = ruleTree({
+      user: {
+        missing: !user,
+        unverified: () => !user?.isVerified
+      },
+      cart: {
+        empty: cart.items.length === 0
+      },
+      payment: {
+        insufficient_funds: () => (user?.balance ?? 0) < totalCost
+      }
+    }, { failFast: true });
+
+    // Single-line early return with diagnostic callback
+    if (!gate.ok) return logger.warn(`Checkout blocked: ${gate.first}`);
+
+    processPayment(cart);
+  };
+  ```
+
 ---
 
 ## 4. Reactivity, Composables & Hooks
@@ -363,6 +446,9 @@ Raw inline `style="..."` attributes are strictly prohibited. Visual styling flow
 ### C. Self-Cleaning Timer Composables
 - Timers for real-world delays must be managed through self-cleaning composables (`useTimeoutFn`, `useDebounceFn`) that cancel automatically on component unmount via `onScopeDispose` or effect teardown.
 
+### D. Listener Disposal
+- Every `addEventListener` has a matching teardown in the same module: `removeEventListener` with the same event and handler (for example in `onBeforeUnmount`, `onUnmounted`, `onScopeDispose` or an effect cleanup), an `AbortController` `{ signal }`, or `{ once: true }` (`LIFECYCLE_ORPHANED_LISTENER`).
+
 ---
 
 ## 7. Infrastructure, Extensibility & Global Hygiene
@@ -433,9 +519,16 @@ Raw inline `style="..."` attributes are strictly prohibited. Visual styling flow
 ### D. No Fake Green
 - Never write a test that trivially passes without exercising real logic (e.g. asserting `true === true`, mocking away the exact behavior under test).
 
-### E. Silent Verification & Zero Passing Noise
+### E. Silent Verification & No Passing Noise
 - AI agents executing tests or verifying code MUST invoke `chemx_test` (or `npx chemx test --json`) and `chemx_verify` (or `npx chemx verify --json`).
-- Strictly prohibit executing verbose raw `npm test` or `pnpm test` in the shell: hundreds of passing test markers pollute context. If tests pass, agents consume a ~25-token green acknowledgment; if tests fail, agents consume only the failing test name, assertion message, and diff.
+- Strictly prohibit executing verbose raw `npm test` or `pnpm test` in the shell: hundreds of passing test markers pollute context. If tests pass, agents get a short green summary; if tests fail, they get the failing test names, assertion messages, and diffs.
+- **Test loop, in order of cost** (details: `docs/test-lanes.md`):
+  1. `chemx test --changed --depth=3`: only the specs within 3 import hops of your change. Fastest, and NOT proof: the report lists how many deeper specs were skipped.
+  2. `chemx test --changed`: every spec the import graph says your change can reach, fast lane only. Slow-lane specs that it reaches are named as not run.
+  3. `chemx test`: the whole fast lane. `chemx test --all` adds the slow lane (specs that spawn the CLI or MCP server, stress and timing specs); that is what CI's `npm test` runs. `chemx test --slow` runs only the slow lane.
+  4. `chemx test --profile [--all] [--top=<n>]`: per-spec-file wall time, slowest first, with the measuring method printed beside the numbers.
+- Lane membership lives in `test-lanes.json`, not in `package.json`. A new spec is fast unless the manifest (or a `*.slow.spec.js`, `*.perf.spec.js`, `*.e2e.spec.js` file name) says otherwise. A spec file that no test glob collects fails `cli/test-lanes-coverage.spec.js`.
+- A spec that asserts a wall-clock or CPU budget belongs in the slow lane (name it `*.perf.spec.js`), or its margin must hold on a machine running many agents.
 
 ---
 
@@ -470,14 +563,36 @@ Raw inline `style="..."` attributes are strictly prohibited. Visual styling flow
 - 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.
-
+## 13. Host Enforcement and Friction
+
+### A. Installed Hooks, Not Prose
+* Install the Claude Code integration with `chemx install-hooks --host=claude [--scope=local|project] [--dry-run]`. It adds the PreToolUse guard (`chemx hook claude-pre-tool`), the PostToolUse check (`claude-post-edit`), the SessionStart card and the statusline. The `.mcp.json` launch, the git pre-commit hook and the CI pin are opt-in: add `--write-mcp`, `--git-hooks` and `--pin-ci`; without them none of those files is written. Run `chemx doctor` when MCP answers look stale; `chemx doctor --fix` repairs hooks and the MCP launch only.
+* Alternatively install the Claude Code plugin (`plugins/claude-code`, marketplace `.claude-plugin/marketplace.json`): the same hooks, the chemical-x MCP server and a short chemx skill, resolving the kit from `CHEMX_KIT`, the project's node_modules or PATH. Use the plugin or install-hooks, not both, or every hook runs twice. The statusline comes only from install-hooks.
+* The guard tokenizes the shell command. Raw test/typecheck/lint/build runners, `git diff`/`git log` and reads of repo source files are routed through chemx. Native Read, Edit, Write and Grep on project text files are warned by default (`nativeFileTools` in `.chemxrc`, or `CHEMX_NATIVE_FILE_TOOLS`): `warn` names the chemx equivalent, `block` denies the call, `allow` is silent.
+
+### B. Bypass and Friction
+* When chemx truly cannot do the job, append `# chemx-bypass: <reason>` to the Bash command. The bypass and every guard denial are logged to `.chemx/friction.jsonl`.
+* `chemx friction` summarises that log; `chemx friction add "<note>"` records a gap by hand; `chemx friction export --to=<file.md>` appends new entries to a Markdown friction log.
+* Measure adoption with `chemx friction --usage <transcript dir>` (Claude Code agent JSONL transcripts): chemx vs raw calls per subcommand, bypass reasons, recursive grep vs `chemx q`, chemx output piped through filters, MCP calls and guard denials.
+
+<!-- chemx:protocol begin -->
+## Chemical X coordination protocol (generated)
+
+Shared-workspace protocol. Several agents edit this checkout at once, and chemx records claims, locks and messages in its team database. This host cannot run Claude Code hooks, so nothing blocks you: following these steps is up to you.
+
+1. Identity: Pass `--as=@<your session name>` on every `chemx team` command, or set `CHEMX_AGENT_ID`. Never act as the default `@agent`.
+2. Before choosing work: Run `chemx status`, `chemx team status`, `chemx team inbox @<you>` and `chemx team task list --status=in_progress` so you know what is claimed and locked.
+3. Claim: Find or create the task (`chemx team task add "<title>" --needs=light|standard|deep`), then run `chemx team task claim <id> --as=@<you>`.
+4. Lock before edit: Run `chemx team lock acquire <file> --as=@<you> --purpose="#<id>"` before the first edit of each file. If another handle holds the lock, do not edit that file: send `chemx team dm @<handle> "<msg>" --as=@<you>` or pick other work.
+5. Edit through chemx: Read with `chemx read <path> --outline` or `--symbol=<name>`, search with `chemx q` or `chemx q -g "<text>"`, find files with `chemx f`, and edit with `chemx patch` or `chemx write`. Avoid cat, sed, grep and direct file writes where chemx has an equivalent.
+6. Test: Run targeted specs with `chemx test <spec files> [-t name]`. Run a full suite only after parallel editors have finished.
+7. Commit: Run `chemx commit <files> -m "<type>(<area>): <summary> (#<id>)"`. It stages and commits only the listed files, runs the repository pre-commit hook and refuses a file under another handle's lease. Do not use `git add -A`, `git commit -a`, `git stash`, git worktrees or side branches.
+8. Wait: Use `chemx wait --task=<id>`, `chemx wait --lock-free=<file>` or `chemx wait --verify-idle` instead of sleep loops. The result is true as of the last poll only.
+9. Progress: Record progress with `chemx team task comment <id> "<msg>" --as=@<you>` and decisions with `chemx team post "<msg>" --type=decision --task=<id> --as=@<you>`.
+10. Inbox: Run `chemx team inbox @<you>` at every task boundary: after claiming, after committing, and before starting the next task.
+11. Handoff: To pass a task to another agent, run `chemx team task handoff <id> @<to> --as=@<you>`. Only the assignee or creator can hand off.
+12. Finish: Run the package gate (`chemx verify`), commit, release every lock with `chemx team lock release <file> --as=@<you>`, then run `chemx team task done <id> --target=<file> --as=@<you>`. If the gate refuses, mark the task blocked with a reason. Do not use `--force`.
+13. Friction: When a chemx command misbehaves, you bypass it, or a flag is missing, file `chemx team task add "Friction: <what happened>" --needs=light --desc="<exact command and output>"` and keep going.
+
+Regenerate with `chemx pillars --protocol --write`; edits inside this block are overwritten.
+<!-- chemx:protocol end -->