@chemx/starter-kit 26.10.4-1258 → 26.10.7-1061

package/AGENTS.md

@@ -0,0 +1,483 @@
+# Chemical X Molecular Architecture Directives
+
+> *"Clean, literate code that reads like poetry to both humans and AI."*
+> Mandatory architectural directives for AI agents operating on this repository. Strictly enforce these standards on every code generation, refactor, and review pass.
+
+---
+
+## 1. The Molecular Architecture Protocol
+
+### A. Structural Weight, Cognitive Cohesion & Profile Architecture
+- **The Pragmatic Staff Engineer Paradigm (Default)**: Chemical X audits **Structural Weight and Responsibility Density**, not arbitrary mechanical line caps. A cohesive 140-line table, modal, or canvas wrapper where state and layout are naturally co-located is far cleaner and more reliable for LLMs to edit than six fractured micro-files connected by prop-drilling. Slicing cohesive logic into artificial files just to appease a counter is an anti-pattern: *indirection masquerading as modularity*.
+- **Structural Weight Limits (Pragmatic Default)**:
+  - **Cyclomatic Complexity**: Max 12 decision points per component/hook.
+  - **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.
+- **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.
+
+### B. Table-of-Contents Views
+- Top-level page views MUST NEVER contain hundreds of lines of nested DOM scaffolding.
+- A view template MUST read like a clean, 10 to 20 line declarative Table of Contents assembling self-contained molecules and organisms via named slot templates (`#header`, `#default`, `#modals`).
+
+### C. Crystalline Molecule Capsules
+- 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.controller.ts  (pure reactive state & 2-stage booleans)
+  ├── _m-<feature>-card.scss          (mixin-only glass styling)
+  ├── types.d.ts                      (pure Props & Emits declarations)
+  └── index.ts                        (clean public entrypoint)
+  ```
+
+### D. Anti-Prop-Drilling & Domain State
+- Never pass 10+ props or chained event bubbles across component tiers.
+- 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`).
+
+### 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.
+- **Identify Recurring Structures**: Map shared UI layouts, duplicate controllers, repeated predicates, common state machines, and mirrored type definitions across files before writing any split code.
+- **Map to Existing Foundations**: Check the design system, shared atom catalog (`x-*`), central composables, and core utilities first. Never invent a bespoke one-off atom or utility if an equivalent foundation exists.
+- **Canonical Extraction First**: Consolidate and extract shared atoms, molecules, or composables once into canonical capsules before splitting consumer monoliths.
+- **Zero Bespoke Pattern Proliferation**: Decompose consumer monoliths by binding directly to the extracted canonical capsules, preventing the proliferation of duplicate, slightly divergent patterns across spliced views.
+
+### G. Component Encapsulation, Semantic Integrity & The Zero-Raw-DOM Scope
+- **Pragmatic Profile (Default)**: Wrapping every native `<button>`, `<input>`, or `<a>` in a trivial single-line atom creates pointless wrapper boilerplate. In Pragmatic mode, native semantic elements are permitted, provided they maintain:
+  1. *Design Token Integrity*: Styled using design tokens, theme utilities, or scoped classes (no hardcoded hex colors or raw style objects).
+  2. *Accessibility Standard*: Native semantic interactive elements (never clickable `<div>` without keyboard roles), valid `type` on buttons, and `aria-label`/alt tags.
+  3. *Security Sanitization*: DOMPurify sanitization on dynamic HTML; no `javascript:` pseudo-protocols.
+- **Atomic-Strict Profile (`--profile=atomic-strict`)**: When building standalone design system libraries, the strict Zero-Raw-DOM rule applies: raw DOM elements are restricted strictly to the Atom tier (`a-*`).
+- **Tab List & Complex Pattern Harmonization**:
+  - 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 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.
+- **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.
+
+### 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.
+- **Tier 2 (Stateful / Side-Effecting)**: Auth, payments, data mutation, session lifecycle, and transactional service layers. Declared explicitly in capsule `index.ts` metadata or capsule frontmatter (`trustTier: 2`).
+- **Exemption from Shallow Interface Trust**: Tier 2 capsules are strictly exempted from "agent trusts interface, never reads implementation". Agents must inspect implementation details for state invariants and side-effect guarantees.
+- **Automated Audit Escalation**: Query tools and audits automatically escalate review strictness for Tier 2 capsules, requiring deep verification of state transitions, mutation boundaries, and failure recoverability.
+
+### J. Stateful Class & Shared Instance State Carve-Out
+- **Atomic Unit Protection**: Stateful classes and services holding shared instance state across methods are treated as a single atomic unit.
+- **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
+- **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).
+  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.
+- **Actionable Failure Focus**: If a verification step fails, agents consume the exact failure line and diff, fix the code surgically, and re-verify without ever paying the token penalty of passing checks.
+
+### 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%+.
+- **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
+- **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.
+- **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
+  // 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: 'useAttentionCardController', hybrid: true } });
+
+  // Surgical AST Reading & Connections
+  chemx({ action: 'read', params: { path: 'src/...', symbol: 'ButtonVariant', connections: true } });
+  chemx({ action: 'read', params: { path: 'src/...', outline: true } });
+  // Component capsules only: outline + logic skeleton in one call (procedural modules: outline or symbol)
+  chemx({ action: 'read', params: { path: 'src/...', outline: true, enrich: true } });
+  // Component capsules: outline + logic + forward call trace card
+  chemx({ action: 'read', params: { path: 'src/...', outline: true, enrich: true, traceSymbol: 'handleCheckout' } });
+  // Component capsules: outline + logic + reverse caller chain card
+  chemx({ action: 'read', params: { path: 'src/...', outline: true, enrich: true, backtraceSymbol: 'handleCheckout' } });
+
+  // Surgical Modification & Rules Check
+  chemx({ action: 'patch', params: { path: 'src/...', target: 'oldCode', replacement: 'newCode' } });
+  chemx({ action: 'write', params: { path: 'src/...', content: '...' } });
+  chemx({ action: 'check', params: { path: 'src/...' } });
+
+  // Deterministic Parameterized Scaffolding (Universal Jig - 90%+ Token Reduction)
+  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' } });
+
+  // Verification, Targeted Testing & Multi-Agent Swarm
+  chemx({ action: 'test', params: { target: 'src/services/payment-gateway.spec.ts' } });
+  chemx({ action: 'test', params: { target: 'cli/generator.spec.js', filter: 'jig' } });
+  chemx({ action: 'verify' });
+  chemx({ action: 'team', params: { action: 'task', subAction: 'claim', taskId: 1, as: '@agent' } });
+  chemx({ action: 'team', params: { action: 'task', subAction: 'done', taskId: 1, as: '@agent', force: true } });
+  chemx({ action: 'team', params: { action: 'lock', subAction: 'acquire', filePath: 'src/...', agentId: '@agent' } });
+  ```
+- **Strict Prohibition on Bash Escalation**: Agents MUST NOT spawn bash subshells (`run_command` with `pnpm chemx ...` or `node cli/...`) when an equivalent in-process `chemx` MCP action exists.
+
+### N. Database-First Navigation, Symbol Connections & The Zero-Native-File-Dump Directive
+- **Database Master Index First**: Before inspecting or modifying any file, AI agents MUST query the SQLite database (`.chemx/index.db`) or the AST Query Machine (`chemx({ action: 'team', params: { action: 'list' } })`, `chemx({ action: 'q', params: { query } })`) rather than exploring the filesystem with broad find or ripgrep commands.
+- **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.
+
+### 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, ... } })`.
+- **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 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>' } })`.
+  5. *Verify (Full Guard)*: Validate AST score and types via `chemx({ action: 'verify' })`.
+
+---
+
+## 2. Domain-Based Type Architecture & Data Integrity
+
+### A. The Anti-Type-Monolith Rule & Domain-Scoped Capsules
+- Strictly prohibit dumping thousands of unrelated entity types into a single monolithic `types.ts` or `global.d.ts`.
+- Co-locate granular `types/*.d.ts` declaration files directly inside each molecule, organism, or feature directory capsule.
+- Split type files by domain, not by line count: once a file declares entities from more than one domain, decompose it into granular domain files (`session.d.ts`, `auth.d.ts`, `billing.d.ts`). File length follows 1.A; there is no separate type-file line cap.
+- Root `types/*.d.ts` is reserved strictly for universal system primitives (`ResultTuple<T>`, `AsyncDataState<T>`, base envelopes). It never contains domain entity models.
+- Zero runtime logic in type files. Zero implicit `any`.
+
+### B. Discriminated State Unions (Zero Impossible States)
+- Model component and session state as strict discriminated/disjoint unions in domain `types/*.d.ts` rather than multiple conflicting booleans:
+  ```typescript
+  export type SessionState =
+    | { readonly status: 'idle' }
+    | { readonly status: 'loading'; readonly progress: number }
+    | { readonly status: 'active';  readonly sessionId: string }
+    | { readonly status: 'fault';   readonly faultMessage: string };
+  ```
+
+### C. Result Tuple Pattern (`toResult`)
+- Avoid nested `try/catch` blocks in async flows. Return Go/Rust-style `[data, error]` tuples with top-of-function early guard clauses:
+  ```typescript
+  const [data, fetchError] = await toResult(api.fetchEntity(id));
+  if (fetchError) {
+    handleError(fetchError);
+    return;
+  }
+  initializeEntity(data);
+  ```
+
+### D. Zero Synthetic or Mock Data
+- Never generate fake names, synthetic emails (`@gmail.com`), random phone numbers (`555-xxx`), mock license numbers, or fake entity arrays.
+- Return genuine live API data or explicit empty states (`No records found`).
+
+### E. Immutable State Action Boundaries
+- Never mutate deep nested store properties inside child components. State transitions occur strictly through named, traceable store actions.
+
+### F. Runtime API Boundary Guards
+- External API and network payloads must be verified through pure, atomic runtime type guards before ingestion into reactive state.
+
+### G. Backend Schema Ground-Truth Hierarchy
+- **Schema as Single Source of Truth**: Backend database schemas (SQL/Prisma/migrations) and OpenAPI specifications constitute ground truth: domain types are strictly derived views.
+- **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.
+
+---
+
+## 3. Control Flow & Self-Documenting Logic
+
+### A. Named Conditions & Two-Stage Composition
+> The `if` never asks a question. The question is asked and named before the branch, and the `if` reads the answer.
+
+- Every conditional test is a named boolean: an identifier, its negation, or a call or member access whose name is an assertion (3.F). A raw comparison (`x === y`, `n >= 5`), a truthiness check on a non-boolean (`if (user)`, `if (obj.prop)`), inline compound logic (`a && b`), or a verb-named call (`RE.test(s)`, `fs.existsSync(p)`) inside the test is a violation.
+- Naming is the point, not the ceremony: it forces the question inline code hides (why `<= 0` and not `=== -1`?), and an edit to a named condition changes its definition without touching the branch.
+- **Stage 1** names each atomic concept. **Stage 2** names the decision, only when 2 or more concepts compose; a single comparison gets one name and no wrapper. Guard with early returns.
+  ```typescript
+  if (hookCount > 5) return;                  // ❌ the if asks
+  const exceedsHookBudget = hookCount > 5;    // ✅ the question, named
+  if (exceedsHookBudget) return;              //    the if reads the answer
+
+  const handleCheckout = () => {
+    // Stage 1: atomic concepts (Layer 1/2 predicates from 3.B where they exist)
+    const hasSufficientFunds = userBalance >= totalCost;
+    const isFormComplete = isAddressValid && hasAcceptedTerms;
+    // Stage 2: the decision
+    const canCheckout = hasItems(cart) && isFormComplete && hasSufficientFunds && !isProcessing;
+    if (!canCheckout) return;
+    processPayment();
+  };
+  ```
+- In React, booleans are pure in-render derivations: never use `useEffect` for computed/derived state.
+
+### B. The Predicate Lexicon & Higher-Order Filter Extraction
+- Named conditions come from three layers. A raw comparison belongs in a named declaration (3.A) or inside a Layer 1 or Layer 2 predicate body, never in a conditional test.
+  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.
+- 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
+  const viewsFiles = computed(() => filteredFiles.value.filter(f => f.path.startsWith("src/") && (f.path.includes("views/") || f.tier === "views")));
+
+  // ✅ Good: domain predicate + named higher-order filter + declarative derivations
+  const isTierFile = (file: Capsule, tier: string): boolean => {
+    const isSrc = file.path.startsWith("src/");
+    if (!isSrc) return false;
+    return file.path.includes(`${tier}/`) || file.tier === tier;
+  };
+  const filterFiles = (tier: string) => filteredFiles.value.filter(f => isTierFile(f, tier));
+  const viewsFiles = computed(() => filterFiles("views"));
+  const organismsFiles = computed(() => filterFiles("organisms"));
+  ```
+
+### C. Single-Action Command Handlers
+- Event handlers are linear, unnested orchestrations of pure atomic verbs:
+  ```typescript
+  const handleAction = async (id: string) => {
+    if (!canProceed.value) return;
+    triggerHapticFeedback();
+    recordTelemetryMetric('action:trigger', { id });
+    await executeServiceCall(id);
+    dismissActiveModal();
+  };
+  ```
+
+### D. Ban on Nested Ternaries in Templates
+- Never use nested ternaries in templates (`a ? (b ? 'x' : 'y') : 'z'`).
+- Extract complex UI display states into dedicated computed descriptor objects returning `{ text: string, color: string }`.
+
+### E. Keyed Map Dispatch Over Monolithic Switch Statements
+- Prohibit monolithic `switch` statements used as procedural dispatch tables or value lookups.
+- 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.
+
+### 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.
+- **Reject Restatements**: A name built only from the words of its own expression teaches nothing. `isChEqualsBackslash = ch === '\\'` and `isCountGreaterThanFive = count > 5` are rejected; `isEscapeChar = ch === '\\'` adds a domain term and passes. If a condition cannot be named in words absent from the condition itself, it is not yet understood: find out before branching on it.
+- **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.
+
+---
+
+## 4. Reactivity, Composables & Hooks
+
+### A. The Molecular Composable Destructuring Contract
+1. **Safe Destructuring**: Composables must always return plain objects containing individual `ref()`, `computed()`, and pure functions. Never return a raw `reactive()` object.
+2. **The Shape-Classification Contract**: Return values must classify strictly into three canonical buckets: State (domain data), Status (lifecycle/health info), and Actions (verb-prefixed functions flat at top level). No arbitrary property count ceiling applies. Unclassifiable properties (raw DOM refs, intermediate values, non-verb callbacks), nested action wrappers (`actions: {}`), and cross-hook naming inconsistencies are strictly prohibited. (Note: For stateful service classes holding shared instance state, refer to the Section 1.J carve-out).
+3. **Standardized Aliasing**: Use standardized names (`data`, `isLoading`, `error`, `execute`) to enable clean concurrent destructuring.
+4. **Autonomous Lifecycle Teardown**: Side effects (listeners, timers, observers) must be cleaned up automatically using `onScopeDispose()` or effect cleanup functions.
+5. **Flexible Input Ergonomics**: Accept raw values, refs, or getters interchangeably via `toValue()` / `MaybeRefOrGetter<T>`.
+
+### B. Clean 3-State Async Pipelines
+- Every asynchronous operation follows a predictable state container (`data`, `isLoading`, `error`, `execute`):
+  ```typescript
+  const { data: items, isLoading, error, execute: loadItems } = useAsyncData(fetchItemsApi);
+  const hasItems = computed(() => items.value.length > 0);
+  const shouldShowEmptyState = computed(() => !isLoading.value && !hasItems.value && !error.value);
+  const shouldShowErrorState = computed(() => !isLoading.value && Boolean(error.value));
+  ```
+
+### C. Strict Lexical Declaration Order (TDZ Prevention)
+To eliminate Temporal Dead Zone (TDZ) ReferenceErrors, `<script setup>` and controllers strictly follow this lexical declaration order:
+1. Composables & Stores (`useRouter()`, `useStore()`)
+2. Reactive Primitives (`ref()`, `reactive()`)
+3. Computed State (`computed()`)
+4. Helper Methods & Actions (`const handleClick = () => { ... }`)
+5. Watchers (`watch()`, `watchEffect()`)
+6. Lifecycle Hooks (`onMounted()`, `onUnmounted()`)
+*Mandatory Rule*: Never reference a reactive value, computed property, or helper in an immediate watcher callback before its declaration.
+
+---
+
+## 5. Design System, Styling & UI Performance
+
+### A. The 4-Tier Zero-Inline-Style Rule
+Raw inline `style="..."` attributes are strictly prohibited. Visual styling flows through the standardized 4-tier hierarchy:
+1. **Level 1 (Atom Props)**: Semantic props on atoms (`:color="brandColor"`, `variant="glass"`, `size="lg"`).
+2. **Level 2 (Mixins & Utilities)**: Centralized SCSS mixins (`@include glass;`, `@include glass-hover;`) and utility classes.
+3. **Level 3 (Scoped BEM Classes)**: Scoped classes in component stylesheets referencing design tokens or encapsulating shorthand via `@apply`.
+4. **Level 4 (Dynamic Root Variables)**: Dynamic runtime coordinates passed exclusively as root CSS custom properties (`:style="{ '--win-x': \`${x}px\`, '--win-y': \`${y}px\` }"`).
+
+### B. The Anti-Tailwind-Soup Directive (Class Decoupling)
+- Prohibit monolithic utility class chains (> 4-5 classes per element) directly inside HTML templates.
+- Long strings of utility shorthand recreate the exact cognitive noise and AI context degradation of inline styles.
+- Decouple visual styling into scoped classes via `@apply` or centralized SCSS mixins (`@include glass;`).
+- Templates must read like a clean, semantic outline rather than an unreadable wall of styling shorthand.
+
+### C. Wrapper Atoms & Explicit Slot Forwarding
+- Never use dynamic slot iteration with `v-for="(_, slot) in $slots"` in wrapper components.
+- Explicitly forward named slots: `<template #<slot-name>="scope"><slot :name="<slot-name>" v-bind="scope || {}" /></template>`.
+- Always wrap default slot in `<template #default="scope"><slot v-bind="scope || {}" /></template>`.
+
+### D. Flat CSS Specificity & Icon Safety
+- Single-depth BEM semantic class naming. Never use `!important` overrides.
+- **FontAwesome SVG Compliance**: Never attach `text-*` utility classes to FontAwesome icons (breaks SVG rendering). Use native `:color` prop or inline CSS.
+
+### E. 60 FPS Non-Blocking UI Offloading
+- Heavy computational operations (parsing, sorting, cryptographic hashing) must be offloaded to Web Workers or chunked micro-batches via `requestIdleCallback`.
+
+---
+
+## 6. Timer & Macro-Task Discipline
+
+### A. Zero `setInterval` in Component & Business Logic
+- Polling with `setInterval` is strictly prohibited.
+- Use `requestAnimationFrame` for animations and physics.
+- Use `videoElement.requestVideoFrameCallback()` for camera/video streams.
+- Use a single shared system clock composable (`useSystemClock()`) for time displays.
+- Use Server-Sent Events or WebSockets for server state sync.
+
+### B. Zero Render-Hack `setTimeout` (Mandatory `nextTick`)
+- Never use `setTimeout(() => { ... }, 0)` to wait for DOM elements to render. Use `await nextTick()` or `watch(..., { flush: 'post' })`.
+
+### 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.
+
+---
+
+## 7. Infrastructure, Extensibility & Global Hygiene
+
+### A. Zero-Conditional `debug.log` Proxy
+- Never use `if (import.meta.env.DEV)` or `if (isProd)` checks around logging statements. Use a central `debug` proxy that automatically silences in production while preserving errors.
+
+### B. Typography Hygiene
+- Never use em dashes anywhere in code, copy, markdown, or documentation. Use standard hyphens or colons.
+
+---
+
+## 8. Accessibility & Semantic Integrity
+
+### A. Semantic HTML First
+- Never reach for a generic `<div>` or `<span>` with a click handler where a native element (`<button>`, `<a>`, `<label>`, `<nav>`) already carries the correct behavior and semantics for free.
+- Interactive elements must be genuinely interactive elements. A clickable `<div>` requires manually re-implementing keyboard focus, Enter/Space activation, and role semantics that native elements provide automatically.
+
+### B. Keyboard & Focus Management
+- Every interactive element must be reachable and operable via keyboard alone: Tab to focus, Enter/Space to activate, Esc to dismiss modals and overlays.
+- Modals, drawers, and dropdowns must trap focus while open and return focus to the triggering element on close.
+- Never remove default focus outlines (`outline: none`) without providing a visible, equivalent custom focus state.
+
+### C. ARIA as a Last Resort, Not a First Layer
+- Use ARIA attributes (`aria-label`, `aria-expanded`, `role`) only to fill genuine gaps semantic HTML cannot cover, not as a substitute for correct markup.
+- Every image conveying meaning requires alt text; purely decorative images use `alt=""`.
+- Form inputs require an associated `<label>`, not a placeholder alone.
+
+### D. Color & Motion Safety
+- Text and interactive elements must meet WCAG AA contrast ratios in both light and dark modes; verify new color tokens against both themes, not just one.
+- Respect `prefers-reduced-motion` for non-essential animations and transitions.
+
+---
+
+## 9. Security & Content Safety
+
+### A. Zero Unsanitized HTML Injection
+- Never render user-supplied or externally-fetched content via `v-html`, `dangerouslySetInnerHTML`, or equivalent raw-HTML injection without passing it through a sanitizer (e.g. DOMPurify) first.
+- Treat all externally-fetched content (API responses, user uploads, third-party embeds) as untrusted by default.
+
+### B. Output Encoding & Injection Boundaries
+- Never interpolate user input directly into constructed HTML strings, SQL queries, or shell commands. Use parameterized queries and framework-native escaping.
+- Never build URLs for redirects or API calls by concatenating unvalidated user input; validate against an allowlist.
+
+### C. Secrets & Credential Hygiene
+- Never hardcode API keys, tokens, or credentials in source files, even temporarily during development. Use environment variables or a secrets manager.
+- Never log full request/response payloads that may contain auth tokens, passwords, or PII.
+
+### D. CSRF & Auth Boundaries
+- State-changing requests (POST/PUT/DELETE) must carry CSRF protection appropriate to the framework's convention, not be assumed safe because they're behind a login.
+- Never trust client-side role or permission checks as the sole gate for sensitive actions; the server must re-verify authorization independently.
+
+---
+
+## 10. Testing Discipline
+
+### A. Co-located Test Files
+- Test files live alongside the capsule they cover (`m-<feature>-card.spec.ts` inside the capsule directory), not in a separate parallel test tree that drifts from the source structure.
+
+### B. What Must Be Covered
+- Every exported pure function, composable, and domain type guard requires at least one test exercising its primary path and one exercising a failure/edge path.
+- UI components require at least a render smoke test; interactive components require a test covering their primary user action.
+
+### C. Refactor Discipline
+- When decomposing a file per Section 1, existing tests move and are updated to match the new file boundaries in the same pass; a refactor is not complete until its tests pass against the new structure.
+- Never delete or skip a failing test to unblock a commit; fix the code or the test, or flag the failure explicitly.
+
+### 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
+- 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.
+
+---
+
+## 11. Naming Conventions
+
+### A. Casing
+- Files: kebab-case (`m-user-card.controller.ts`).
+- Variables, functions, composables: camelCase (`isLoading`, `useAsyncData`).
+- Types, interfaces, components: PascalCase (`SessionState`, `UserCard`).
+- Constants meant to be immutable module-level config: SCREAMING_SNAKE_CASE (`MAX_RETRY_COUNT`).
+
+### B. Boolean & Predicate Prefixes
+- Booleans and predicates start with an assertion prefix from 3.F (`isLoading`, `hasItems`, `canCheckout`, `exceedsHookBudget`). Never name a boolean as a bare noun or adjective (`loading`, `valid`) that hides its type at the call site.
+
+### C. Event & Handler Naming
+- Emitted events describe what happened, not what to do (`item-selected`, not `select-item`).
+- Handler functions describe the action taken, prefixed `handle` (`handleCheckout`), matching Section 3.C.
+
+---
+
+## 12. Documentation Discipline
+
+### A. Derived Contract Synchronization
+- Derived contract fields (signatures, parameters, payload structures, return types) in capsule documentation must be extracted directly from `types.d.ts`, never manually duplicated or hand-typed.
+- Any change to `types.d.ts` must automatically propagate to or be validated against the capsule reference documentation.
+
+### B. Mandatory Doc-Touch CI Gate
+- A commit that modifies a capsule's implementation or controller without updating the corresponding documentation prose section must fail CI validation.
+- Refactors and behavioral changes are not complete until documentation accurately reflects updated semantics, mirroring Section 10.C.
+
+### 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/blueprints/molecule-capsule/m-sample-card.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-  import AButton from '../../atoms/a-button.svelte';
+  import AButton from '../atoms/a-button.svelte';
   import type { MSampleCardProps, SampleCardBadgeDescriptor } from './types';
 
   let {

package/blueprints/molecule-capsule/m-sample-card.vue

@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { computed } from 'vue';
-import AButton from '../../atoms/a-button.vue';
+import AButton from '../atoms/a-button.vue';
 import type { MSampleCardProps, SampleCardBadgeDescriptor } from './types';
 
 const props = withDefaults(defineProps<MSampleCardProps>(), {

package/cli/audit/audit-summary.js

@@ -0,0 +1,30 @@
+import { resolveProjectName, resolveCostFigures } from '../navigator-banner-helpers.js';
+
+const countHazards = (violations = []) => {
+  const counts = { critical: 0, highMedium: 0, low: 0 };
+  for (const v of violations) {
+    const isCritical = v.severity === 'CRITICAL';
+    const isHighOrMedium = v.severity === 'HIGH' || v.severity === 'MEDIUM';
+    if (isCritical) counts.critical += 1;
+    else if (isHighOrMedium) counts.highMedium += 1;
+    else counts.low += 1;
+  }
+  return counts;
+};
+
+export const buildAuditSummary = (report, { projectRoot, scope }) => {
+  const gate = report.gate ?? {};
+  const summary = {
+    project: resolveProjectName(projectRoot),
+    scope,
+    files: report.metrics?.scannedFiles ?? 0,
+    loc: report.metrics?.totalLoc ?? 0,
+    tokens: { estimate: report.contextAnalysis?.estimatedTokens ?? 0, savingsPct: report.contextAnalysis?.potentialSavingsPct ?? 0 },
+    health: { score: report.health.score, grade: report.health.grade, label: report.health.label ?? null },
+    aiSlop: { score: report.aiSlop?.score ?? 100, grade: report.aiSlop?.grade ?? 'A+' },
+    hazards: countHazards(report.violations),
+    cost: resolveCostFigures(report.contextAnalysis),
+    gate: { passing: gate.isPassing ?? null, basis: gate.basis ?? null, regressions: (gate.regressions ?? []).slice(0, 5), note: gate.note ?? null }
+  };
+  return report.rebaseline ? { ...summary, rebaseline: report.rebaseline } : summary;
+};

package/cli/audit/gate-verdict.js

@@ -0,0 +1,30 @@
+import { readRatchet, evaluateRatchet } from './ratchet.js';
+
+const RATCHET_STATUSES = new Set(['pass', 'fail', 'invalid']);
+
+const isSevereViolation = (v) => v.severity === 'CRITICAL' || v.severity === 'HIGH';
+
+export const evaluateGateVerdict = ({ violations, ratchetEval }) => {
+  const isRatchetBasis = RATCHET_STATUSES.has(ratchetEval.status);
+  if (isRatchetBasis) {
+    return {
+      isPassing: ratchetEval.status === 'pass',
+      basis: 'ratchet',
+      regressions: ratchetEval.regressions,
+      note: ratchetEval.message ?? null
+    };
+  }
+  const hasSevereViolation = violations.some(isSevereViolation);
+  return { isPassing: !hasSevereViolation, basis: 'severity', regressions: [], note: ratchetEval.message ?? null };
+};
+
+const PARTIAL_SCAN_EVAL = {
+  status: 'partial',
+  regressions: [],
+  message: 'Partial scan (--git, --changed, or --fast): the ratchet applies to full scans only; using severity gate.'
+};
+
+export const computeGateVerdict = ({ projectRoot, scope, violations, isPartialScan = false }) => {
+  const ratchetEval = isPartialScan ? PARTIAL_SCAN_EVAL : evaluateRatchet(readRatchet(projectRoot), { scope, violations });
+  return evaluateGateVerdict({ violations, ratchetEval });
+};