@christianmaf80/agentic-workflow 1.14.0-beta.1 → 1.14.0-beta.2

package/dist/rules/constitution/drivers.md

@@ -1,294 +0,0 @@
----
-trigger: model_decision
-description: Se aplica cuando se crean, modifican o auditan drivers, o cuando un agente toma decisiones sobre ellos, garantizando estructura contractual, aislamiento, compatibilidad multi-browser y ausencia de lógica de negocio
----
-
----
-id: constitution.drivers
-type: rule
-owner: architect-agent
-version: 1.0.0
-severity: PERMANENT
-scope: global
----
-
-# CONSTITUTION: Drivers (Extensio)
-
-## Objetivo
-Este documento define **reglas obligatorias** y contractuales para los drivers de Extensio.
-Todo driver **DEBE** cumplir estas reglas.  
-El `role.driver-agent` **DEBE** auditar y hacer cumplir este contrato.
-
----
-
-## 1. Definición (qué es un driver)
-Un driver es una **fachada** (facade) que abstrae APIs del navegador (WebExtensions) o Web APIs
-para que el resto del framework sea **browser-agnóstico**.
-
-Un driver:
-- adapta APIs (shape, compat, eventos, tipos)
-- expone una API estable y documentada
-- encapsula diferencias entre navegadores
-
-Un driver:
-- NO contiene lógica de negocio
-- NO conoce módulos de negocio
-- NO decide flujos o workflows
-- NO persiste estado de negocio (solo adapta storage si es driver de storage)
-
----
-
-## 2. Estructura obligatoria por driver
-Cada driver **DEBE** seguir esta estructura mínima:
-
-- `src/index.mts` → **wrapper público** (API estable + JSDoc)
-- `src/__BROWSER__/index.mts` → implementación por navegador (chrome/firefox/safari)
-- `src/types.d.mts` → tipos locales del driver
-- `src/constants.mts` → constantes tipadas (`Record<string, string>`)
-- `src/common/index.mts` → implementación compartida (si aplica)
-- Integración de tipos en `globals.d.mts` (root) y de constantes en `constants.mts` (root)
-  como parte obligatoria de la estructura del driver.
-
-### 2.1 Wrapper (src/index.mts)
-Reglas:
-- `src/index.mts` **NO puede** ser un simple re-export.
-- Debe exponer una clase o funciones wrapper que:
-  - deleguen en la implementación específica (`__BROWSER__`)
-  - añadan JSDoc
-  - mantengan API estable
-- Debe importar `__BROWSER__/index.mts` usando el patrón del build (ej. `__BROWSER__`).
-
-### 2.2 Implementación por navegador (src/__BROWSER__/index.mts)
-Reglas:
-- Debe mapear a las APIs reales del navegador.
-- Debe mantener el contrato de tipos definido por `types.d.mts`.
-- Debe aislar diferencias específicas del navegador sin filtrar detalles al wrapper.
-
-### 2.3 Types (src/types.d.mts)
-Reglas:
-- El driver **DEBE** definir sus tipos localmente.
-- Import interno de tipos del mismo driver:
-  - `import type { X } from '../types.d.mts'`
-- Los drivers **NO** consumen tipos de otros drivers:
-  - cada driver define sus propios tipos para mantener independencia y portabilidad
-- Interfaces genéricas comunes (p.ej. `BrowserEvent`) **se duplican** localmente
-  para evitar dependencias cruzadas indeseadas.
-- La integracion de tipos **DEBE** reflejarse correctamente en `globals.d.mts`
-  (imports/exports sin duplicados ni nombres corruptos).
-- Todo driver **DEBE** registrar sus tipos en `globals.d.mts` dentro del
-  namespace global `Extensio.<NamespaceDelDriver>`.
-
-Ejemplo (globals.d.mts):
-```ts
-declare global {
-  namespace Extensio {
-    namespace Tabs {
-      type TabStatusType = typeof TabStatus[keyof typeof TabStatus];
-    }
-  }
-}
-```
-
-### 2.4 Constants (src/constants.mts)
-Reglas:
-- Todo string repetido o enumeración string-based debe centralizarse aquí.
-- Toda enumeración **DEBE** definirse en `constants.mts` y usarse para crear tipos.
-  - Objetivo: reutilizar los valores como objetos en runtime y como tipos en compile-time.
-- Debe tiparse como `Record<string, string>`.
-- Los drivers **NO** consumen constantes de otros drivers:
-  - cada driver define sus propias constantes para mantener independencia y portabilidad
-- Las constantes del driver **DEBEN** extender las constantes globales del proyecto
-  para que puedan ser usadas por los módulos.
-- La integracion de constantes **DEBE** reflejarse correctamente en el `constants.mts`
-  del root (exports sin duplicados ni nombres corruptos).
-- Todo driver **DEBE** exportar sus constantes en el `constants.mts` del root.
-
-Ejemplo (constants.mts root):
-```ts
-export { TabStatus, WindowType } from '@extensio/driver-tabs/src/constants.mts';
-```
-- Prohibido hardcodear “magic strings” repetidos en el código del driver.
-
-### 2.5 Common (src/common/index.mts)
-Reglas:
-- Solo si existe lógica compartible entre navegadores.
-- No debe incluir lógica de negocio.
-- Debe ser consumida por los `__BROWSER__/index.mts`, no por módulos.
-
-### 2.6 Demo (demo/)
-Reglas:
-- Si un driver tiene carpeta `demo`, cualquier import hacia `src` **DEBE** usar
-  el alias `__PARENT_SRC__` (nunca rutas relativas al `src`).
-  - Ejemplo: `import { Tabs } from '__PARENT_SRC__/index.mts';`
-- La demo **DEBE** mantener la estructura de Extensio y cumplir `constitution.extensio_architecture`.
-- La demo **DEBE** generarse con `mcp_extensio-cli tools` cuando exista soporte aplicable.
-
----
-
-## 3. Events (contrato obligatorio)
-Los eventos **DEBEN** exponerse como wrappers que implementen una interfaz local `BrowserEvent`.
-
-Ejemplo de forma:
-- En `types.d.mts`:
-  - `export interface BrowserEvent<T extends (...args: any) => void> { addListener(cb: T): void; removeListener(cb: T): void; hasListener(cb: T): boolean; }`
-- En `src/__BROWSER__/index.mts`:
-  - `static onCreated: BrowserEvent<(arg: X) => void> = { addListener: ..., removeListener: ..., hasListener: ... }`
-
-Regla:
-- Prohibido exponer directamente eventos crudos del navegador (ej. `chrome.tabs.onUpdated`).
-
----
-
-## 4. Scoping y dependencias (aislamiento)
-- Un driver no debe depender de otro driver por imports directos.
-- Si necesita tipos externos, usar `Extension.*`.
-- Un driver **NUNCA** debe usar otro driver; deben ser agnósticos e independientes.
-- Los drivers **DEBEN** definir sus propios tipos; **NO** deben usar `@types` de otras librerías.
-- Si necesita interactuar con otros drivers, hacerlo a través del dominio superior (módulo/core),
-  nunca creando dependencia de paquete circular.
-
----
-
-## 5. Clean Code (en drivers)
-- Se aplica `clean-code.md` como contrato obligatorio para drivers.
-
----
-
-## 6. Compatibilidad multi-browser
-- La API del wrapper debe ser **estable** entre navegadores.
-- Las divergencias deben resolverse en `__BROWSER__`.
-- Si una API no existe en un navegador:
-  - se define comportamiento fallback (documentado)
-  - o se lanza error controlado (documentado)
-- Debe evitarse divergencia silenciosa.
-
----
-
-## 7. Tooling recomendado (scaffolding)
-Cuando exista comando disponible, los drivers **DEBEN** generarse con `mcp_extensio-cli tools`.
-
-Principio:
-- Preferir generación por CLI para consistencia.
-- Si el CLI no soporta una operación, la modificación manual es válida solo si:
-  - cumple este contrato
-  - queda registrada como “lección aprendida” por el `driver-agent`.
-
----
-
-## 8. Auditoría de cumplimiento
-Criterios mínimos de auditoría:
-- estructura de carpetas correcta (Sección 2)
-- wrapper no es re-export (2.1)
-- types aislados (2.3)
-- events como wrappers (3)
-- constants centralizadas (2.4)
-- no lógica de negocio (1)
-- compatibilidad documentada (6)
-
----
-
-## 9. Severidad
-Cualquier violación de:
-- estructura (Sección 2)
-- types isolation (2.3)
-- events wrappers (3)
-- lógica de negocio en drivers (1)
-
-se considera **SEVERITY: HIGH** y debe corregirse antes de integrar cambios.
-
----
-
-## 10. Ejemplos (drivers reales)
-Los ejemplos respetan la independencia entre drivers: no hay consumo de tipos ni
-constantes de otros drivers dentro de un driver.
-
-### 10.1 Enumeraciones en `constants.mts` (Tabs driver)
-Fuente: `packages/drivers/tabs/src/constants.mts`
-```ts
-export const TabStatus: Record<string, string> = {
-  Loading: 'loading',
-  Complete: 'complete',
-};
-
-export const WindowType: Record<string, string> = {
-  Normal: 'normal',
-  Popup: 'popup',
-  Panel: 'panel',
-  App: 'app',
-  Devtools: 'devtools',
-};
-```
-
-### 10.2 Tipos derivados de constantes (Tabs driver)
-Fuente: `packages/drivers/tabs/src/types.d.mts`
-```ts
-import { TabStatus, WindowType } from './constants.mts';
-
-export type TabStatusType = typeof TabStatus[keyof typeof TabStatus];
-export type WindowTypeType = typeof WindowType[keyof typeof WindowType];
-```
-
-### 10.3 Re-export de constantes (Tabs driver)
-Fuente: `packages/drivers/tabs/src/types.d.mts`
-```ts
-export { TabStatus, WindowType };
-```
-
----
-
-### 10.4 Clase wrapper en `src/index.mts` (Tabs driver)
-Fuente: `packages/drivers/tabs/src/index.mts`
-```ts
-import { Tabs as CommonTabs } from '__BROWSER__/index.mts';
-import type { Tab, BrowserEvent } from './types.d.mts';
-
-export class Tabs extends CommonTabs {
-  static override get(tabId: number): Promise<Tab> {
-    return CommonTabs.get(tabId);
-  }
-
-  static override onCreated: BrowserEvent<(tab: Tab) => void> = {
-    addListener: (cb) => CommonTabs.onCreated.addListener(cb),
-    removeListener: (cb) => CommonTabs.onCreated.removeListener(cb),
-    hasListener: (cb) => CommonTabs.onCreated.hasListener(cb),
-  };
-}
-```
-
----
-
-### 10.5 Consumo desde Core/Modules (Navigation)
-Fuente: `packages/core/src/engine/navigation/index.mts`
-```ts
-import { Tabs } from '@extensio/driver-tabs';
-import { Windows } from '@extensio/driver-windows';
-
-await Tabs.create({ url, active: true });
-await Windows.create({ url, type: 'popup', focused: true });
-```
-
----
-
-### 10.6 Demo usando `__PARENT_SRC__`
-Ejemplo (alias definido en `tsconfig.json` de drivers):
-```ts
-import { Tabs } from '__PARENT_SRC__/index.mts';
-```
-
----
-
-### 10.7 Extensión de globals (Prompt AI driver)
-Fuente: `packages/drivers/prompt-ai/src/types.d.mts`
-```ts
-declare global {
-  interface WindowOrWorkerGlobalScope {
-    ai?: {
-      languageModel: AILanguageModelFactory;
-    };
-  }
-}
-```
-
----
-
-Fin de la constitución de drivers.

package/dist/rules/constitution/extensio-architecture.md

@@ -1,131 +0,0 @@
----
-trigger: always_on
----
-
-# EXTENSIO ARCHITECTURE - FRAMEWORK RULES
-
-Este documento define los **principios arquitectónicos fundamentales** del framework Extensio.
-Para reglas contractuales detalladas de cada componente, consultar su constitución específica.
-
----
-
-## 1. PRINCIPIOS ARQUITECTÓNICOS (PERMANENT)
-
-### 1.1 Filosofía Base
-Extensio es un framework para construir extensiones de navegador complejas
-de forma modular, reactiva y predecible.
-
-Su filosofía se basa en los siguientes principios:
-
-- Separar estrictamente la lógica de negocio de las APIs del navegador (Drivers) y de la UI (Surfaces).
-- Aislar cada dominio funcional en paquetes independientes del monorepo, sin dependencias cruzadas.
-- Utilizar un modelo reactivo como único mecanismo de comunicación entre los módulos.
-- Priorizar la predecibilidad del comportamiento frente a la flexibilidad implícita.
-- Diseñar el sistema para escalar en complejidad sin degradar mantenibilidad.
-- Mantener el código agnóstico del navegador y del entorno de ejecución.
-
-### 1.2 Independencia y Dirección de Dependencias
-- Todos los paquetes DEBEN ser independientes y versionables.
-- El acoplamiento directo entre paquetes del mismo tipo está PROHIBIDO.
-- El uso de capacidades externas DEBE realizarse exclusivamente mediante Drivers.
-- Core NO DEBE conocer ni depender de ningún paquete del proyecto.
-
-### 1.3 Prohibición de Dependencias Cruzadas
-- Un módulo NO DEBE depender de otro módulo.
-- Un driver NO DEBE depender de otro driver.
-- El uso de drivers por parte de los módulos NO constituye una dependencia conceptual.
-- Ningún paquete DEBE introducir ciclos de dependencias, directos o indirectos.
-
-### 1.4 Separación de Responsabilidades
-- El principio SRP (Single Responsibility Principle) DEBE aplicarse estrictamente.
-- Está PROHIBIDO mezclar UI con lógica de negocio dentro de módulos.
-- Los drivers NO DEBEN contener lógica de negocio.
-- Los bucles reactivos están PROHIBIDOS.
-
----
-
-## 2. SCOPES DEL FRAMEWORK (PERMANENT)
-
-El framework define tres scopes principales. Cada uno tiene su propia constitución con reglas detalladas.
-
-### 2.1 Engine
-- El Engine es el componente central y obligatorio de todo módulo.
-- Se ejecuta en el entorno de Service Worker.
-- Es responsable del estado reactivo y persistente del módulo.
-- **NO DEBE** renderizar UI ni acceder al DOM.
-- **Constitución detallada**: `constitution.modules`
-
-### 2.2 Context
-- Un Context es una extensión opcional del Engine.
-- Encapsula lógica que requiere acceso al DOM o APIs no disponibles en el Service Worker.
-- El Engine controla completamente el ciclo de vida del Context.
-- **NO DEBE** contener lógica de negocio ni renderizar UI.
-- **Constitución detallada**: `constitution.modules`
-
-### 2.3 Surfaces
-Las Surfaces representan la capa visual del framework. Se dividen en:
-
-#### Pages
-- Documentos completos que se renderizan en un tab del navegador.
-- Representan vistas de alto nivel (opciones, dashboards).
-- **Constitución detallada**: `constitution.pages`
-
-#### Shards
-- Componentes visuales reutilizables (WebComponents).
-- Componentes de UI puros, sin estado persistente propio.
-- **Constitución detallada**: `constitution.shards`
-
----
-
-## 3. DRIVERS (PERMANENT)
-
-Los Drivers son adaptadores que envuelven APIs del navegador.
-Representan la frontera de efectos laterales del sistema.
-
-**Constitución detallada**: `constitution.drivers`
-
----
-
-## 4. CORE PACKAGE (PERMANENT)
-
-- Core DEBE exponer Engine, Context y Surfaces.
-- Core DEBE proveer el sistema reactivo (@property, @onChanged).
-- Core NO DEBE depender de ningún paquete del proyecto.
-- Core NO DEBE contener lógica de negocio de ningún módulo.
-
----
-
-## 5. EXTENSIO CLI (PERMANENT)
-
-El tool `mcp_extensio-cli` es el ÚNICO punto de entrada para build y test.
-- Unit e Integration **DEBEN** ejecutarse con **Vitest**.
-- E2E **DEBE** ejecutarse con **Playwright**.
-- Scaffolding de módulos, drivers y surfaces **DEBE** usar `mcp_extensio-cli`.
-
----
-
-## 6. ORDEN DE COMPOSICIÓN DE CLASES (PERMANENT)
-
-1. Propiedades estáticas
-2. Métodos estáticos
-3. Propiedades de instancia
-4. Constructor
-5. Event handlers
-6. Métodos privados
-7. Métodos públicos
-
----
-
-## 7. CONSTITUCIONES ESPECÍFICAS
-
-Para reglas contractuales detalladas, consultar:
-
-| Componente | Constitución |
-|------------|--------------|
-| Módulos | `constitution.modules` |
-| Drivers | `constitution.drivers` |
-| Pages | `constitution.pages` |
-| Shards | `constitution.shards` |
-| Clean Code | `constitution.clean_code` |
-
----

package/dist/rules/constitution/modules.md

@@ -1,280 +0,0 @@
----
-trigger: model_decision
-description: Se aplica cuando se crean, modifican o auditan módulos, o cuando un agente toma decisiones sobre ellos, garantizando estructura contractual, reactividad y cumplimiento arquitectónico.
----
-
----
-id: constitution.modules
-type: rule
-owner: architect-agent
-version: 2.0.0
-severity: PERMANENT
-scope: global
----
-
-# CONSTITUTION: Módulos (Extensio)
-
-## Objetivo
-Este documento define **reglas obligatorias** y contractuales para los módulos de Extensio.
-Todo módulo **DEBE** cumplir estas reglas.
-El `role.module-agent` **DEBE** auditar y hacer cumplir este contrato.
-
----
-
-## 1. Definición (qué es un módulo)
-
-Un módulo es una **unidad de negocio** que organiza lógica reactiva y persistente.
-
-Un módulo:
-- Gobierna un dominio funcional concreto
-- Expone un estado reactivo propio
-- Interactúa con drivers mediante APIs
-
-Un módulo **NO**:
-- Es UI (las Surfaces son sus vistas)
-- Contiene drivers (los consume como puertos)
-- Depende de otros módulos
-
----
-
-## 2. Scopes del Módulo
-
-| Scope | Obligatorio | Descripción |
-|-------|-------------|-------------|
-| **Engine** | ✅ Sí | Componente central. Se ejecuta en Service Worker. Gestiona estado reactivo. |
-| **Context** | ❌ Opcional | Extensión del Engine para lógica que requiere DOM o APIs no disponibles en SW. |
-| **Surfaces** | ❌ Opcional | Capa visual: Pages (documentos) y Shards (componentes). |
-
-**Regla**: Si existe Context o Surfaces, **DEBE** documentarse el motivo y relación con Engine.
-
----
-
-## 3. Estructura Obligatoria
-
-Cada módulo **DEBE** seguir esta estructura mínima:
-
-```
-packages/modules/<module-name>/
-├── src/
-│   ├── index.mts              # Entry point público
-│   ├── types.d.mts            # Tipos locales del módulo
-│   ├── constants.mts          # Constantes tipadas
-│   ├── engine/
-│   │   └── index.mts          # Engine del módulo (OBLIGATORIO)
-│   ├── context/               # (si aplica)
-│   │   └── index.mts
-│   └── surface/
-│       ├── pages/
-│       │   └── index.mts      # Índice de Pages (si usa Pages)
-│       └── shards/
-│           └── index.mts      # Registro de Shards (si usa Shards)
-├── package.json
-└── tsconfig.json
-```
-
-### 3.1 Types (`src/types.d.mts`)
-
-- El módulo **DEBE** definir sus tipos localmente.
-- Import interno: `import type { X } from '../types.d.mts'`
-- Los módulos **NO** consumen tipos de otros módulos directamente.
-- Tipos consumidos externamente **DEBEN** registrarse en `global.d.mts`:
-
-```ts
-// global.d.mts
-declare global {
-  namespace Extensio {
-    namespace SessionManager {
-      export type SessionState = SessionState;
-      export type SessionConfig = SessionConfig;
-    }
-  }
-}
-```
-
-### 3.2 Constants (`src/constants.mts`)
-
-- Todo string repetido o enumeración string-based debe centralizarse aquí.
-- Toda enumeración **DEBE** definirse como `Record<string, string>`.
-- Prohibido hardcodear "magic strings" en el código.
-
-```ts
-// constants.mts
-export const SessionStatus = {
-  Active: 'active',
-  Idle: 'idle',
-  Expired: 'expired',
-} as const;
-
-export type SessionStatusType = typeof SessionStatus[keyof typeof SessionStatus];
-```
-
-### 3.3 Naming Conventions
-
-| Elemento | Convención | Ejemplo |
-|----------|------------|---------|
-| Archivos/carpetas | kebab-case | `session-manager/`, `user-profile.mts` |
-| Clases | PascalCase | `SessionManagerEngine`, `UserProfileContext` |
-| Registro de Shards | kebab-case con guión | `session-manager-widget` |
-| Namespace global | PascalCase | `Extensio.SessionManager` |
-
----
-
-## 4. Ciclo de Vida del Módulo (PERMANENT)
-
-Todo módulo **DEBE** respetar estrictamente la siguiente secuencia:
-
-### Secuencia de Ejecución
-
-| # | Método | Tipo | Descripción |
-|---|--------|------|-------------|
-| 1 | `run()` | Público | Único punto de entrada. Inicia el ciclo completo. |
-| 2 | `_setup()` | Privado (Core) | Inicializa infraestructura reactiva. **NO sobrescribir.** |
-| 3 | `_listen()` | Privado (Core) | Registra listeners internos del framework. **NO sobrescribir.** |
-| 4 | `setup()` | Público | Configuración del dominio. **NO acceder a props persistentes.** |
-| 5 | `listen()` | Público | Registro de listeners con `@onChanged`. **NO lógica de negocio.** |
-| 6 | `loadProps()` | Interno | Carga propiedades persistentes desde storage. |
-| 7 | `start()` | Público | Ejecución inicial. **PUEDE** leer props y ejecutar lógica. |
-
-### Reglas del Ciclo de Vida
-
-- `run()` es el **único** punto de arranque.
-- `_setup()` y `_listen()` son privados y gestionados por Core.
-- `setup()` y `listen()` **NO DEBEN** acceder a estado persistente.
-- `start()` es el primer punto donde se puede leer estado y ejecutar lógica inicial.
-
----
-
-## 5. Reactividad (PERMANENT)
-
-### Decoradores Obligatorios
-
-| Decorador | Uso | Regla |
-|-----------|-----|-------|
-| `@property` | Declarar propiedades persistentes | **OBLIGATORIO** para todo estado reactivo |
-| `@onChanged` | Reaccionar a cambios de propiedades | **OBLIGATORIO** para listeners |
-
-### Sincronización
-
-En clases que extienden de Core (Engine, Context):
-- **OBLIGATORIO** usar `await this.waitingLoadProps()` si un listener accede a props reactivas.
-
-```ts
-@onChanged('session')
-async onSessionChanged(value: SessionState) {
-  await this.waitingLoadProps();
-  // Ahora es seguro acceder a otras props
-}
-```
-
-### Event Listeners de Drivers (PERMANENT)
-
-**REGLA OBLIGATORIA**: Los event listeners de drivers **SIEMPRE** deben registrarse en `listen()`, **NUNCA** en `start()`.
-
-```ts
-// ❌ INCORRECTO - Event listener en start()
-override async start() {
-  Runtime.onInstalled.addListener(...); // MAL
-}
-
-// ✅ CORRECTO - Event listener en listen()
-override async listen() {
-  // Event listeners de drivers DEBEN estar aquí
-  Runtime.onInstalled.addListener((details) => {
-    if (details.reason === 'install' || details.reason === 'update') {
-      this.handleInstall();
-    }
-  });
-  
-  Tabs.onActivated.addListener((info) => {
-    this.handleTabActivated(info);
-  });
-}
-```
-
-**Justificación**: El método `listen()` es el espacio designado para configurar event listeners en extensiones. Esto garantiza:
-- Separación clara entre inicialización (`start()`) y escucha de eventos (`listen()`)
-- Coherencia con el ciclo de vida de Extensio
-- Facilita testing y debugging
-
----
-
-## 6. Aislamiento (PERMANENT)
-
-- Un módulo **NO PUEDE** depender de otro módulo.
-- No se permiten dependencias cruzadas (ni directas ni indirectas).
-- Los drivers se consumen como **puertos de acceso**, sin acoplamiento conceptual.
-- El módulo **NO CONOCE** la implementación interna del driver.
-
----
-
-## 7. Integración con Surfaces
-
-### 7.1 Pages (`src/surface/pages/index.mts`)
-
-Si el módulo define Pages:
-- Este archivo es **OBLIGATORIO**.
-- **Responsabilidad**: Importar archivos `.html` y exportar URLs resueltas.
-
-```ts
-// src/surface/pages/index.mts
-import dashboard from "./dashboard/dashboard.html";
-export const Pages = { dashboard };
-```
-
-- El Engine debe importar este índice para que el CLI detecte las páginas.
-
-### 7.2 Shards (`src/surface/shards/index.mts`)
-
-Si el módulo implementa Shards:
-- Este archivo es **OBLIGATORIO**.
-- **Único lugar** donde se registran los WebComponents.
-- Usar `Shard.register(tagName, ComponentClass)`.
-
-```ts
-// src/surface/shards/index.mts
-import { Shard } from '@extensio/core/shard';
-import { MyShard } from './my-shard.mts';
-
-Shard.register('my-module-shard', MyShard);
-export { MyShard };
-```
-
-- El Engine debe importar los Shards para que el CLI los compile independientemente.
-
----
-
-## 8. Tooling
-
-- Los módulos **DEBEN** generarse con `mcp_extensio-cli` cuando esté disponible.
-- Si no existe soporte CLI, la creación manual es válida solo si:
-  - Cumple este contrato
-  - Queda registrada como lección aprendida
-
----
-
-## 9. Auditoría
-
-Criterios mínimos de auditoría para un módulo:
-
-| Criterio | Verificación |
-|----------|--------------|
-| Estructura de carpetas | Conforme a §3 |
-| Ciclo de vida | Conforme a §4 |
-| Reactividad | `@property` y `@onChanged` correctos |
-| Types/Constants | Aislados en sus archivos |
-| Aislamiento | Sin dependencias cruzadas |
-| Surfaces indexadas | Si aplica, conforme a §7 |
-
----
-
-## 10. Severidad
-
-Cualquier violación de:
-- Estructura (§3)
-- Ciclo de vida (§4)
-- Reactividad (§5)
-- Aislamiento (§6)
-
-se considera **SEVERITY: HIGH** y bloquea la validación del módulo.
-
----