@chemx/create-chemx 26.9.24-393 → 26.9.25-747

package/README.md

@@ -26,23 +26,35 @@ Create a brand new molecular architecture project in seconds using your preferre
 # npm (interactive or pass project directory)
 npm create chemx my-molecular-app
 
+# Choose framework (react, vue, or svelte)
+npm create chemx my-molecular-app -- --framework=react
+
+# Auto-install dependencies upon scaffolding
+npm create chemx my-molecular-app -- --framework=react --install
+
 # Automated / Agent / Headless mode (skips prompts, scaffolds Community Edition immediately)
 npm create chemx my-molecular-app -- --yes
 
 # npx
-npx create-chemx my-molecular-app --yes
+npx create-chemx my-molecular-app --framework=react --install --yes
 
 # pnpm / yarn / bun
-pnpm create chemx my-molecular-app
-yarn create chemx my-molecular-app
+pnpm create chemx my-molecular-app --framework=vue
+yarn create chemx my-molecular-app --framework=svelte
 bun create chemx my-molecular-app
 ```
 
+### Framework & Installation Flags
+* `--framework=<react|vue|svelte>` (or `-f <name>`): Selects target framework. Scaffolds strictly matching components, file templates, and dependencies with zero cross-framework leakage.
+* `--install`: Runs package manager install immediately after project creation.
+* `--skip-install` (or `--no-install`): Explicitly skips automatic dependency installation (default).
+* `--yes` (or `-y`): Automatically confirms prompts with standard molecular presets.
+
 ### Headless & Autonomous Agent Mode
 When running in unattended environments (CI/CD pipelines, Cursor Agent, Windsurf, Claude Code, Antigravity), pass `--yes` (or `-y`, `--ci`, `--headless`) to bypass interactive terminal menus and immediately scaffold the free Community Edition with recommended architectural pillars:
 
 ```bash
-npx create-chemx my-molecular-app --yes
+npx create-chemx my-molecular-app --framework=react --install --yes
 ```
 
 ### Package Architecture: Scaffolder vs Command Engine
@@ -233,12 +245,13 @@ Scaffold production-ready component capsules matching strict zero-raw-DOM standa
 ```bash
 # Molecule capsule (component, controller, glass styling, types, spec)
 chemx m-task-card
+chemx m-task-card --framework=react       # Explicit framework (react, vue, or svelte)
 
 # Atom foundation (the only tier permitted raw HTML elements)
-chemx a-status-pill
+chemx a-status-pill --framework=vue
 
 # Organism module (complex grouping of molecules and atoms)
-chemx o-workspace-header
+chemx o-workspace-header --framework=svelte
 
 # Pure reactive hook / domain composable
 chemx use-task-filter
@@ -256,13 +269,60 @@ chemx team task list --agent=@agent-alpha
 # Claim an open task
 chemx team task claim 1 --as=@agent-alpha
 
-# Mark task complete (automatically re-audits target file on disk to guarantee zero hazards)
-chemx team task done 1 --as=@agent-alpha
+# Mark task complete with inline AST verification gate
+# Re-audits target file on disk to guarantee zero blocking hazards before completion:
+chemx team task done 1 --as=@agent-alpha --target=src/components/m-card.vue
+
+# Emergency override / escape hatch: complete task despite non-blocking warnings:
+chemx team task done 1 --as=@agent-alpha --target=src/components/m-card.vue --force
 
 # Inspect multi-agent swarm status and lock queues
 chemx team status
 ```
 
+### 5. Live Swarm Web UI & Direct Task Routing
+Launch the real-time Chemical X Swarm Control Panel backed by SQLite (`.chemx/index.db`) with full SPA routing and deep linking:
+```bash
+# Launch Live Swarm Web UI (default: http://localhost:4173)
+npx chemx ui
+
+# Launch on a custom port
+npx chemx ui --port=8080
+```
+
+* **Direct Task Routing:** Link straight to any task in the Kanban board: `http://localhost:4173/tasks/:id` (e.g. `http://localhost:4173/tasks/42`)
+* **Auto-Focus & Highlighting:** Opening a task route automatically switches to the **📋 Tasks & Kanban** view, smoothly centers the card, and illuminates it with a cyan highlight glow.
+* **One-Click Share:** Click the `🔗` icon on any Kanban card to copy its direct URL straight to your clipboard.
+* **Single-Task API:** Fetch individual task state and verification diff receipts directly via `GET /api/tasks/:id`.
+
+---
+
+## Language-Agnostic Polyglot Architecture
+
+Chemical X is **language-agnostic**. The core physics of AI agent code generation—**Zero Context Rot, Monolith Slicing, and Verified Anti-Hallucination Gating**—apply universally across backend, frontend, and systems stacks.
+
+### Supported Language Ecosystems
+
+| Language / Framework | Extensions | Parser Engine | Capabilities |
+| :--- | :--- | :--- | :--- |
+| **C# / .NET 10** | `.cs` | Structural Regex / AST | Line budgets, MediatR handlers, shallow catch detection, fake in-memory stubs (`UseInMemoryDatabase`), `using` namespace indexing |
+| **Python** | `.py` | Structural Regex / AST | Line budgets, AI slop text patterns, fake assertions (`assert True`), `def`/`class` and `import` indexing |
+| **Go** | `.go` | Structural Regex / AST | Line budgets, mock data scanning, tautological assertions, `func`/`type` package indexing |
+| **Rust** | `.rs` | Structural Regex / AST | Line budgets, AI slop text patterns, secret scanning, struct and fn indexing |
+| **TypeScript / JavaScript** | `.ts`, `.tsx`, `.js`, `.jsx` | `@babel/parser` AST | Full 11-Pillar AST visitors, Zero-Raw-DOM, hook contracts, 2-stage booleans |
+| **Vue & Svelte** | `.vue`, `.svelte` | Babel + Template Registry | SFC template clone detection, reactive state verification |
+
+### Two-Tier Decoupled Audit Pipeline
+1. **Tier 1: Universal Polyglot Rules (Runs on ALL languages)**
+   * **Sliding-Scale Line Budgets:** Flags files exceeding 100, 500, or 1,000 lines (`LINE_BUDGET_FILE`) to eliminate LLM context rot.
+   * **AI Slop Text Patterns:** Strips conversational residue (*"Here is the code"*), leaked markdown code fences, and lazy truncation placeholders (`// ... rest of implementation`).
+   * **Synthetic Mock Data Scanners:** Catches fake emails (`@example.com`), `555-` phone numbers, and hardcoded dummy collections in services.
+   * **Security & Secret Guards:** Scans for high-entropy API keys, JWTs, AWS credentials, and unmanaged sensitive logging.
+   * **Polyglot Fake Green Tests:** Catches tautological assertions in C# (`Assert.True(true)`), Python (`assert True`), and Go (`assert.True(t, true)`).
+2. **Tier 2: Deep Language-Specific Analyzers**
+   * **Babel Engine:** Deep AST inspection for JS/TS/Vue/Svelte (zero false-positive syntax errors on non-JS code).
+   * **C# / Clean Architecture Analyzer:** Flags empty `catch (Exception) {}` blocks, simulated delays (`Task.Delay`), and monolithic controllers.
+
 ---
 
 ## The 7 Molecular Architecture Pillars

package/blueprints/atoms/a-button.svelte

@@ -0,0 +1,30 @@
+<script lang="ts">
+  let {
+    type = 'button',
+    disabled = false,
+    ariaLabel = undefined,
+    variant = 'primary',
+    class: className = '',
+    onclick,
+    children
+  } = $props<{
+    type?: 'button' | 'submit' | 'reset';
+    disabled?: boolean;
+    ariaLabel?: string;
+    variant?: 'primary' | 'ghost' | 'glass';
+    class?: string;
+    onclick?: (e: MouseEvent) => void;
+    children?: import('svelte').Snippet;
+  }>();
+</script>
+
+<button
+  {type}
+  {disabled}
+  aria-label={ariaLabel}
+  class="a-button cursor-pointer {className}"
+  data-variant={variant}
+  {onclick}
+>
+  {@render children?.()}
+</button>

package/blueprints/atoms/a-button.tsx

@@ -0,0 +1,36 @@
+import React from 'react';
+
+export interface AtomButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: 'primary' | 'ghost' | 'glass';
+  ariaLabel?: string;
+  children?: React.ReactNode;
+}
+
+export const AtomButton: React.FC<AtomButtonProps> = ({
+  type = 'button',
+  disabled = false,
+  ariaLabel,
+  variant = 'primary',
+  children,
+  className = '',
+  onClick,
+  ...rest
+}) => {
+  const rootClass = `a-button cursor-pointer ${className}`.trim();
+
+  return (
+    <button
+      type={type}
+      disabled={disabled}
+      aria-label={ariaLabel}
+      className={rootClass}
+      data-variant={variant}
+      onClick={onClick}
+      {...rest}
+    >
+      {children}
+    </button>
+  );
+};
+
+export default AtomButton;

package/blueprints/molecule-capsule/m-chemx-badge/m-chemx-badge.svelte

@@ -0,0 +1,35 @@
+<script lang="ts">
+  import type { MChemxBadgeProps } from './types';
+
+  export const resolveGradeClass = (grade: string): string => {
+    const g = grade.toUpperCase();
+    if (g.startsWith('A')) return 'm-chemx-badge__grade--a';
+    if (g.startsWith('B')) return 'm-chemx-badge__grade--b';
+    if (g.startsWith('C')) return 'm-chemx-badge__grade--c';
+    if (g.startsWith('D')) return 'm-chemx-badge__grade--d';
+    return 'm-chemx-badge__grade--f';
+  };
+
+  let {
+    label = 'AI Slop cleaned with Chemical X',
+    grade = 'A+',
+    href = 'https://chemicalx.xophz.com',
+    reportUrl = undefined,
+    className = ''
+  } = $props<MChemxBadgeProps>();
+
+  const targetHref = $derived(reportUrl || href);
+  const gradeClass = $derived(resolveGradeClass(grade));
+</script>
+
+<a
+  href={targetHref}
+  target="_blank"
+  rel="noopener noreferrer"
+  class="m-chemx-badge {className}"
+  title="Verified by Chemical X Molecular Architecture Protocol"
+>
+  <span class="m-chemx-badge__dot"></span>
+  <span class="m-chemx-badge__label">{label}</span>
+  <span class="m-chemx-badge__grade {gradeClass}">[{grade}]</span>
+</a>

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

@@ -0,0 +1,58 @@
+<script lang="ts">
+  import AButton from '../../atoms/a-button.svelte';
+  import type { MSampleCardProps, SampleCardBadgeDescriptor } from './types';
+
+  let {
+    title,
+    subtitle = undefined,
+    value,
+    status = 'active',
+    onAction = undefined
+  } = $props<MSampleCardProps>();
+
+  const isHighValue = $derived(value > 1000);
+
+  const badge = $derived.by((): SampleCardBadgeDescriptor => {
+    if (status !== 'active') {
+      return {
+        text: status,
+        className: 'm-sample-card__badge m-sample-card__badge--archived'
+      };
+    }
+    if (isHighValue) {
+      return {
+        text: status,
+        className: 'm-sample-card__badge m-sample-card__badge--high-value'
+      };
+    }
+    return {
+      text: status,
+      className: 'm-sample-card__badge m-sample-card__badge--standard'
+    };
+  });
+</script>
+
+<div class="m-sample-card">
+  <div class="m-sample-card__header">
+    <div class="m-sample-card__title-group">
+      <h3 class="m-sample-card__title">{title}</h3>
+      {#if subtitle}
+        <p class="m-sample-card__subtitle">{subtitle}</p>
+      {/if}
+    </div>
+    <span class={badge.className}>{badge.text}</span>
+  </div>
+  <div class="m-sample-card__body">
+    <div class="m-sample-card__value">
+      ${value.toLocaleString()}
+    </div>
+    {#if onAction}
+      <AButton
+        class="m-sample-card__action"
+        onclick={onAction}
+      >
+        Action
+      </AButton>
+    {/if}
+  </div>
+</div>

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

@@ -1,4 +1,5 @@
 import React from 'react';
+import AtomButton from '../atoms/a-button';
 import type { MSampleCardProps, SampleCardBadgeDescriptor } from './types';
 
 export const resolveBadgeDescriptor = (
@@ -56,13 +57,12 @@ export const MSampleCard: React.FC<MSampleCardProps> = ({
           ${value.toLocaleString()}
         </div>
         {onAction && (
-          <button
-            type="button"
+          <AtomButton
             className="m-sample-card__action"
             onClick={handleActionClick}
           >
             Action
-          </button>
+          </AtomButton>
         )}
       </div>
     </div>

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

@@ -0,0 +1,60 @@
+<script setup lang="ts">
+import { computed } from 'vue';
+import AButton from '../../atoms/a-button.vue';
+import type { MSampleCardProps, SampleCardBadgeDescriptor } from './types';
+
+const props = withDefaults(defineProps<MSampleCardProps>(), {
+  subtitle: undefined,
+  status: 'active',
+  onAction: undefined
+});
+
+const isHighValue = computed(() => props.value > 1000);
+
+const badge = computed((): SampleCardBadgeDescriptor => {
+  if (props.status !== 'active') {
+    return {
+      text: props.status,
+      className: 'm-sample-card__badge m-sample-card__badge--archived'
+    };
+  }
+  if (isHighValue.value) {
+    return {
+      text: props.status,
+      className: 'm-sample-card__badge m-sample-card__badge--high-value'
+    };
+  }
+  return {
+    text: props.status,
+    className: 'm-sample-card__badge m-sample-card__badge--standard'
+  };
+});
+
+const handleActionClick = () => {
+  if (props.onAction) props.onAction();
+};
+</script>
+
+<template>
+  <div class="m-sample-card">
+    <div class="m-sample-card__header">
+      <div class="m-sample-card__title-group">
+        <h3 class="m-sample-card__title">{{ title }}</h3>
+        <p v-if="subtitle" class="m-sample-card__subtitle">{{ subtitle }}</p>
+      </div>
+      <span :class="badge.className">{{ badge.text }}</span>
+    </div>
+    <div class="m-sample-card__body">
+      <div class="m-sample-card__value">
+        ${{ value.toLocaleString() }}
+      </div>
+      <AButton
+        v-if="onAction"
+        class="m-sample-card__action"
+        @click="handleActionClick"
+      >
+        Action
+      </AButton>
+    </div>
+  </div>
+</template>

package/blueprints/view-template.svelte

@@ -0,0 +1,18 @@
+<script lang="ts">
+  let {
+    title,
+    children
+  } = $props<{
+    title: string;
+    children?: import('svelte').Snippet;
+  }>();
+</script>
+
+<main class="view-template">
+  <header class="view-template__header">
+    <h1 class="view-template__title">{title}</h1>
+  </header>
+  <div class="view-template__content">
+    {@render children?.()}
+  </div>
+</main>

package/blueprints/view-template.vue

@@ -0,0 +1,18 @@
+<script setup lang="ts">
+interface Props {
+  title: string;
+}
+
+defineProps<Props>();
+</script>
+
+<template>
+  <main class="view-template">
+    <header class="view-template__header">
+      <h1 class="view-template__title">{{ title }}</h1>
+    </header>
+    <div class="view-template__content">
+      <slot />
+    </div>
+  </main>
+</template>

package/blueprints/workflows/chemx-audit.yml

@@ -76,3 +76,39 @@ jobs:
             gh pr comment "\${PR_NUMBER}" --body-file PR_COMMENT.md
           fi
 
+  scaffold-smoke-test:
+    name: Framework Scaffolding Smoke Test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - name: Install Dependencies
+        run: npm install
+      - name: Run Test Suite
+        run: npm test
+      - name: Multi-Framework Scaffolding Smoke Test
+        run: |
+          for fw in react vue svelte; do
+            echo "Smoke testing scaffolding for framework: $fw"
+            node cli/create.js test-app-$fw --framework=$fw --yes --skip-install
+            if [ "$fw" = "react" ]; then
+              test -f test-app-react/src/components/m-sample-card/m-sample-card.tsx
+              ! ls test-app-react/src/components/m-sample-card/*.vue 2>/dev/null
+              ! ls test-app-react/src/components/m-sample-card/*.svelte 2>/dev/null
+            elif [ "$fw" = "vue" ]; then
+              test -f test-app-vue/src/components/m-sample-card/m-sample-card.vue
+              ! ls test-app-vue/src/components/m-sample-card/*.tsx 2>/dev/null
+              ! ls test-app-vue/src/components/m-sample-card/*.svelte 2>/dev/null
+            elif [ "$fw" = "svelte" ]; then
+              test -f test-app-svelte/src/components/m-sample-card/m-sample-card.svelte
+              ! ls test-app-svelte/src/components/m-sample-card/*.vue 2>/dev/null
+              ! ls test-app-svelte/src/components/m-sample-card/*.tsx 2>/dev/null
+            fi
+            echo "Framework $fw scaffolded cleanly."
+          done
+
+

package/cli/audit/ast-visitors.js

@@ -8,10 +8,18 @@ import {
   isUnguardedConsoleCall
 } from './rules-predicates.js';
 import { validateHookReturnShape } from './hook-shape-validator.js';
+import { evaluateComponentStructuralWeight } from './structural-weight-evaluator.js';
 
-export const createAstVisitors = ({ relativePath, violations, hookRegistry }) => {
+export const createAstVisitors = ({ relativePath, violations, hookRegistry, config }) => {
   return {
     Function(astPath) {
+      evaluateComponentStructuralWeight({
+        funcPath: astPath,
+        relativePath,
+        violations,
+        config
+      });
+
       const isCustomHook = isCustomHookFunction(astPath);
 
       // Pillar 3: Hook Saturation
@@ -178,18 +186,22 @@ export const createAstVisitors = ({ relativePath, violations, hookRegistry }) =>
       if (attrName === 'style') {
         const value = astPath.node.value;
         if (t.isJSXExpressionContainer(value) && t.isObjectExpression(value.expression)) {
-          const line = astPath.node.loc?.start.line || 1;
-          const meta = RULE_REGISTRY.RAW_INLINE_STYLE;
-          violations.push({
-            filePath: relativePath,
-            line,
-            column: astPath.node.loc?.start.column || 1,
-            hazard: 'Raw inline style attribute detected in JSX',
-            rule: 'RAW_INLINE_STYLE',
-            severity: meta.severity,
-            pillar: meta.pillar,
-            directive: meta.directive
-          });
+          const preferTokens = config?.preferDesignTokens || 'warning';
+          if (preferTokens !== 'off') {
+            const line = astPath.node.loc?.start.line || 1;
+            const meta = RULE_REGISTRY.RAW_INLINE_STYLE;
+            const severity = preferTokens === 'error' ? 'HIGH' : meta.severity;
+            violations.push({
+              filePath: relativePath,
+              line,
+              column: astPath.node.loc?.start.column || 1,
+              hazard: 'Raw inline style attribute detected in JSX',
+              rule: 'RAW_INLINE_STYLE',
+              severity,
+              pillar: meta.pillar,
+              directive: meta.directive
+            });
+          }
         }
       } else if (attrName === 'className' || attrName === 'class') {
         const value = astPath.node.value;

package/cli/audit/csharp-analyzer.js

@@ -0,0 +1,80 @@
+/**
+ * Chemical X C# / .NET Structural Analyzer
+ * Evaluates .NET Clean Architecture, MediatR handlers, EF Core usage, and AI slop.
+ */
+import { RULE_REGISTRY } from './rules-registry.js';
+
+const SHALLOW_CATCH_PATTERN = /catch\s*(?:\([^)]*\))?\s*\{\s*(?:\/\/[^\n]*)?\s*\}/;
+const IN_MEMORY_DB_PATTERN = /\bUseInMemoryDatabase\s*\(/;
+const SIMULATED_DELAY_PATTERN = /\bTask\.Delay\s*\(\s*\d+\s*\)/;
+const HARDCODED_LIST_MOCK_PATTERN = /new\s+List<[A-Za-z0-9_]+>\s*\{\s*new\s+[A-Za-z0-9_]+\s*\{/;
+
+export const analyzeCSharpCode = (content, relativePath, violations) => {
+  const lines = content.split('\n');
+
+  // Multi-line and single-line shallow catch detection
+  const catchMatches = content.matchAll(/catch\s*(?:\([^)]*\))?\s*\{(?:\s*|\s*\/\/[^\n]*\s*)\}/g);
+  for (const m of catchMatches) {
+    const lineNum = content.slice(0, m.index).split('\n').length;
+    const meta = RULE_REGISTRY.AI_SLOP_SHALLOW_CATCH;
+    violations.push({
+      filePath: relativePath,
+      line: lineNum,
+      column: 1,
+      hazard: 'Empty or shallow catch block detected in C# handler/service',
+      rule: 'AI_SLOP_SHALLOW_CATCH',
+      severity: meta.severity,
+      pillar: meta.pillar,
+      directive: meta.directive
+    });
+  }
+
+  lines.forEach((lineText, idx) => {
+    const lineNum = idx + 1;
+
+    // Simulated Mock Data / Stubs
+    if (IN_MEMORY_DB_PATTERN.test(lineText)) {
+      const meta = RULE_REGISTRY.SYNTHETIC_MOCK_DATA;
+      violations.push({
+        filePath: relativePath,
+        line: lineNum,
+        column: 1,
+        hazard: 'UseInMemoryDatabase mock provider detected (unverified live persistence)',
+        rule: 'SYNTHETIC_MOCK_DATA',
+        severity: meta.severity,
+        pillar: meta.pillar,
+        directive: meta.directive
+      });
+    }
+
+    if (SIMULATED_DELAY_PATTERN.test(lineText)) {
+      const meta = RULE_REGISTRY.AI_SLOP_LAZY_PLACEHOLDER;
+      violations.push({
+        filePath: relativePath,
+        line: lineNum,
+        column: 1,
+        hazard: 'Simulated Task.Delay detected (artificial asynchronous latency stub)',
+        rule: 'AI_SLOP_LAZY_PLACEHOLDER',
+        severity: meta.severity,
+        pillar: meta.pillar,
+        directive: meta.directive
+      });
+    }
+
+    if (HARDCODED_LIST_MOCK_PATTERN.test(lineText)) {
+      const meta = RULE_REGISTRY.SYNTHETIC_MOCK_DATA;
+      violations.push({
+        filePath: relativePath,
+        line: lineNum,
+        column: 1,
+        hazard: 'Hardcoded synthetic entity collection detected in C# service',
+        rule: 'SYNTHETIC_MOCK_DATA',
+        severity: meta.severity,
+        pillar: meta.pillar,
+        directive: meta.directive
+      });
+    }
+  });
+
+  return violations;
+};

package/cli/audit/extended-text-patterns.js

@@ -15,7 +15,13 @@ const SECRET_PATTERNS = [
 const FAKE_GREEN_PATTERNS = [
   /expect\s*\(\s*(true|false|1|0)\s*\)\s*\.\s*to(?:Be|Equal|StrictEqual)\s*\(\s*\1\s*\)/,
   /assert\s*\.\s*(?:strictEqual|equal|deepEqual)\s*\(\s*(true|false|1|0)\s*,\s*\1\s*\)/,
-  /assert\s*\.\s*ok\s*\(\s*(?:true|1)\s*\)/
+  /assert\s*\.\s*ok\s*\(\s*(?:true|1)\s*\)/,
+  /\bAssert\.(?:True|IsTrue)\s*\(\s*true\s*\)/i,
+  /\bAssert\.(?:False|IsFalse)\s*\(\s*false\s*\)/i,
+  /\bAssert\.(?:Equal|AreEqual)\s*\(\s*(true|false|1|0)\s*,\s*\1\s*\)/i,
+  /\bassert\s+(?:True|1\s*==\s*1)\b/,
+  /\bself\.assert(?:True|Equal)\s*\(\s*(?:True|1\s*,\s*1)\s*\)/,
+  /\bassert\.(?:True|Equal)\s*\(\s*t\s*,\s*(?:true|1\s*,\s*1)\s*\)/
 ];
 
 const IMG_WITHOUT_ALT_PATTERN = new RegExp(['<', 'img\\b', '(?![^>]*\\balt\\s*=)', '[^>]*>'].join(''), 'i');
@@ -192,7 +198,10 @@ export const checkExtendedTextPatterns = (content, lines, relativePath, filePath
   checkMoleculeCoLocatedTest(filePath, relativePath, violations);
   checkControllerViewContract(filePath, relativePath, content, violations);
 
-  const isTestFile = /\.(test|spec)\.[jt]sx?$/.test(filePath);
+  const isTestFile = /\.(test|spec)\.[jt]sx?$/.test(filePath)
+    || /(?:^|[\\/])(?:test_[^\\/]+\.py|[^\\/]+_test\.(?:py|go)|[^\\/]+Tests?\.cs)$/i.test(filePath)
+    || /(?:^|[\\/])tests?[\\/]/i.test(filePath)
+    || (filePath.endsWith('.cs') && (content.includes('[Fact]') || content.includes('[Test]')));
   const ext = path.extname(filePath);
   const isTemplateFile = isTemplateExtension(ext);
 

package/cli/audit/pattern-detector.js

@@ -29,15 +29,17 @@ export const createPatternRegistry = () => {
     });
   };
 
-  const resolveHarmonizationCandidates = (hotspots = []) => {
+  const resolveHarmonizationCandidates = (hotspots = [], options = {}) => {
     const hotspotFiles = new Set(hotspots.map((h) => h.filePath));
     const candidates = [];
+    const minFiles = options.ruleOfThree ? 3 : 2;
 
     for (const [key, bucket] of buckets.entries()) {
       const uniqueFiles = Array.from(new Set(bucket.occurrences.map((o) => o.filePath)));
-      if (uniqueFiles.length < 2) continue;
-
       const hasHotspot = uniqueFiles.some((f) => hotspotFiles.has(f));
+      const isCandidateEligible = hasHotspot ? uniqueFiles.length >= 2 : uniqueFiles.length >= minFiles;
+      if (!isCandidateEligible) continue;
+
       const impactScore = uniqueFiles.length * (hasHotspot ? 3 : 1.5) + bucket.occurrences.length;
 
       let label = 'Recurring Pattern';

package/cli/audit/pattern-detector.spec.js

@@ -94,3 +94,20 @@ test('categorizeUiStructure: maps semantic AST topologies to specialized capsule
   assert.equal(fallbackRes.suggestedCapsule, 'm-feature-card');
 });
 
+test('Rule of Three: requires pattern across 3+ files unless a hotspot is involved', () => {
+  const registry = createPatternRegistry();
+  const template = `<template><v-sheet><x-btn>1</x-btn><x-btn>2</x-btn></v-sheet></template>`;
+
+  recordTemplatePatterns(registry, template, 'src/components/A.vue');
+  recordTemplatePatterns(registry, template, 'src/components/B.vue');
+
+  // With Rule of Three enabled and no hotspots, 2 files do not trigger premature abstraction
+  const strictCandidates = registry.resolveHarmonizationCandidates([], { ruleOfThree: true });
+  assert.equal(strictCandidates.length, 0, '2 occurrences without hotspot should not trigger premature abstraction');
+
+  // When a 3rd file adopts the pattern, Rule of Three threshold is satisfied
+  recordTemplatePatterns(registry, template, 'src/components/C.vue');
+  const satisfiedCandidates = registry.resolveHarmonizationCandidates([], { ruleOfThree: true });
+  assert.equal(satisfiedCandidates.length, 1, '3 occurrences should satisfy Rule of Three threshold');
+});
+

package/cli/audit/reporter-grades.js

@@ -267,6 +267,7 @@ export const formatGradeASection = (report) => {
     lines.push(`   ${GREEN}✔${RESET} Low Context Hazard & Token Burn Risk`);
   }
 
+  lines.push(`\n   ${DIM}ℹ Notice: Architectural grade measures AST rules only. Run chemx verify for full typecheck and test verification.${RESET}`);
   lines.push(`\n${GREEN}======================================================================${RESET}\n`);
   return lines.join('\n');
 };

package/cli/audit/reporter-markdown.js

@@ -39,6 +39,8 @@ export const generateMarkdownReport = (report) => {
     lines.push('');
   }
   lines.push('> *Comprehensive static analysis report enforcing Chemical X Molecular Architecture standards.*');
+  lines.push('> ');
+  lines.push('> **Notice**: Architectural grades measure AST rule compliance only. Run `chemx verify` for full production readiness (typecheck + test suite).');
   lines.push('');
   lines.push('## 1. Executive Summary & Scorecard');
   lines.push('');