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

package/dist/artifacts/11-revision-sistema-agentic/modules-v2.md

@@ -1,250 +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
-}
-```
-
----
-
-## 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.
-
----

package/dist/artifacts/11-revision-sistema-agentic/pages-v2.md

@@ -1,366 +0,0 @@
----
-trigger: model_decision
-description: Se aplica cuando se crean, modifican o auditan Pages, o cuando un agente toma decisiones sobre ellas, garantizando estructura contractual, ciclo de vida y cumplimiento arquitectónico.
----
-
----
-id: constitution.pages
-type: rule
-owner: architect-agent
-version: 2.1.0
-severity: PERMANENT
-scope: global
----
-
-# CONSTITUTION: Pages (Extensio)
-
-## Objetivo
-Este documento define **reglas obligatorias** y contractuales para las Pages de Extensio.
-Toda Page **DEBE** cumplir estas reglas.
-Los agentes **DEBEN** auditar y hacer cumplir este contrato.
-
----
-
-## 1. Definición (qué es una Page)
-
-Una Page es una **Surface de nivel superior** que representa un documento HTML completo dentro de la extensión.
-
-Una Page:
-- Es un documento HTML que vive dentro de la extensión
-- Se renderiza en su propio contexto (popup, tab, panel)
-- Hereda de la clase `Page` que extiende `Surface` → `Core`
-- Carga JavaScript mediante `<script type="module" src="...">`
-- Puede tener de 1 a N scripts asociados
-- Sigue el ciclo de vida estándar de Extensio: `run()` → `listen()` → `start()`
-
-Una Page **NO**:
-- Contiene lógica de negocio (eso es responsabilidad del Engine)
-- Accede directamente al estado del módulo sin usar el sistema reactivo
-- Se instancia directamente; se navega mediante `Engine.navigate()`
-
----
-
-## 2. Jerarquía de Clases
-
-```
-Core
-  └── Surface (clase abstracta)
-        └── Page (clase concreta)
-```
-
-### Clase Base: `Surface`
-
-La clase `Surface` extiende `Core` y añade:
-- Hooks DOM: `onMount()` (inicia ciclo con `run()`), `onUnmount()` (cleanup)
-- Listener de Storage: `onStorageChanged()`, `checkListeners()`
-- El sistema reactivo (`@property`, `@onChanged`) viene de `Core`
-
-### Clase: `Page`
-
-```ts
-import { Surface } from '../surface.mts';
-import { Scope } from '../../constants.mts';
-
-export class Page extends Surface {
-    constructor(name: string, scope: string = Scope.Page) {
-        super(name, scope);
-    }
-}
-```
-
----
-
-## 3. Estructura Obligatoria
-
-Cada Page **DEBE** seguir esta estructura dentro del módulo:
-
-```
-packages/modules/<module-name>/
-└── src/
-    └── surface/
-        └── pages/
-            ├── index.mts              # Índice de Pages (OBLIGATORIO)
-            └── <page-name>/
-                ├── index.html         # Documento HTML
-                ├── index.mts          # Script principal (lógica de la Page)
-                └── styles.css         # Estilos (opcional)
-```
-
-### 3.1 Índice de Pages (`src/surface/pages/index.mts`)
-
-Este archivo es **OBLIGATORIO** si el módulo define Pages.
-
-**Responsabilidad**:
-- Importar todos los archivos `.html` del módulo
-- Exportar las URLs resueltas para uso con `navigate()`
-- Permitir al CLI detectar y procesar las páginas
-
-```ts
-// src/surface/pages/index.mts
-import dashboard from "./dashboard/index.html";
-import settings from "./settings/index.html";
-
-export const Pages = {
-  dashboard,
-  settings,
-};
-```
-
-> **IMPORTANTE**: El import de un `.html` es transformado por el CLI en una URL runtime.
-> El valor exportado es un `string` (la URL), **NO** un objeto JavaScript.
-
-### 3.2 Documento HTML (`index.html`)
-
-El archivo HTML **DEBE**:
-- Ser un documento HTML5 válido
-- Incluir al menos un `<script type="module" src="...">` que cargue el entry point
-- No contener lógica inline (todo en archivos externos)
-
-```html
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Dashboard</title>
-  <link rel="stylesheet" href="./styles.css">
-</head>
-<body>
-  <div id="app"></div>
-  <script type="module" src="./index.mts"></script>
-</body>
-</html>
-```
-
-### 3.3 Script Principal (`index.mts`)
-
-El script de entrada **DEBE**:
-- Extender la clase `Page`
-- Implementar el ciclo de vida de Extensio
-- Llamar a `run()` para iniciar
-
-```ts
-// index.mts
-import { Page } from '@extensio/core/surface/pages';
-
-class DashboardPage extends Page {
-  constructor() {
-    super('dashboard-page');
-  }
-
-  // Opcional: configurar listeners de eventos/drivers
-  override listen() {
-    super.listen();
-    // Registrar listeners aquí
-  }
-
-  // Punto de entrada principal - se ejecuta después de cargar props
-  override start() {
-    this.render();
-  }
-
-  private render() {
-    const app = document.getElementById('app');
-    if (app) {
-      app.innerHTML = '<h1>Dashboard</h1>';
-    }
-  }
-}
-
-// Iniciar la Page
-const page = new DashboardPage();
-page.run();
-```
-
----
-
-## 4. Ciclo de Vida de una Page
-
-El ciclo de vida de una Page sigue el patrón estándar de Extensio:
-
-### 4.1 Secuencia de Ejecución
-
-| # | Método | Tipo | Descripción |
-|---|--------|------|-------------|
-| 1 | `constructor()` | Público | Inicializa la Page con nombre |
-| 2 | `run()` | Público | **Punto de entrada**. Inicia el ciclo de vida completo. |
-| 3 | `_setup()` | Privado (Core) | Inicializa infraestructura reactiva. Llama a `_listen()`, `listen()`, `loadProps()`. |
-| 4 | `_listen()` | Privado (Surface) | Registra listener de Storage |
-| 5 | `listen()` | Público | Punto para registrar listeners de eventos y drivers |
-| 6 | `loadProps()` | Interno | Carga propiedades persistentes |
-| 7 | `start()` | Público | **Método principal**. Aquí se ejecuta la lógica de la Page. |
-
-### 4.2 Reglas del Ciclo de Vida
-
-- `run()` es el **único** punto de arranque de la Page
-- `listen()` es para registrar listeners, **NO** para lógica de negocio
-- `start()` es el primer punto donde se puede leer estado y renderizar
-
----
-
-## 5. Navegación
-
-### 5.1 Cargar una Page desde el Engine
-
-Las Pages se cargan mediante el método `navigate()` del Engine:
-
-```ts
-// En el Engine
-import { Pages } from './surface/pages/index.mts';
-
-// Navegar a una Page de la extensión
-// Pages.dashboard es un STRING (la URL del HTML)
-await this.navigate(Pages.dashboard);
-
-// Navegar con opciones
-await this.navigate(Pages.settings, {
-  type: 'popup',
-  rect: { width: 400, height: 600 },
-  active: true,
-});
-```
-
-> **NOTA**: `navigate()` recibe el **path del HTML** (string), nunca un objeto JavaScript.
-
-### 5.2 Cómo funciona `navigate()`
-
-```ts
-public async navigate(url: string | { default: string }, options?: NavigationOptions) {
-  const resolvedUrl = typeof url === 'object' && 'default' in url
-    ? url.default
-    : this.getUrl(url as string);
-
-  return Navigation.open(resolvedUrl, options);
-}
-```
-
-El método acepta:
-- Un `string` directo (URL o path)
-- Un objeto con `{ default: string }` (para compatibilidad con imports)
-
-### 5.3 NavigationOptions
-
-| Opción | Tipo | Default | Descripción |
-|--------|------|---------|-------------|
-| `type` | `'regular' \| 'popup'` | `'regular'` | Tipo de ventana |
-| `rect.width` | `number` | - | Ancho de la ventana (solo popup) |
-| `rect.height` | `number` | - | Alto de la ventana (solo popup) |
-| `rect.top` | `number` | - | Posición Y (solo popup) |
-| `rect.left` | `number` | - | Posición X (solo popup) |
-| `active` | `boolean` | `true` | Si la ventana debe tener foco |
-
-### 5.4 Escuchar Navegación (onNavigate)
-
-Cada Engine tiene un listener `onNavigate` que captura eventos de navegación:
-
-```ts
-// En el Engine
-override onNavigate(event: NavigationEvent) {
-  console.log('Navegación detectada:', event);
-  
-  if (event.isExtensionPage) {
-    // Es una Page de la extensión
-  } else {
-    // Es una URL externa
-  }
-}
-```
-
-### 5.5 NavigationEvent
-
-| Campo | Tipo | Descripción |
-|-------|------|-------------|
-| `event` | `string` | Tipo de evento: `'load'`, `'focus'`, `'window'` |
-| `url` | `string` | URL de la página |
-| `title` | `string?` | Título de la página |
-| `tabId` | `number` | ID del tab |
-| `windowId` | `number` | ID de la ventana |
-| `isExtensionPage` | `boolean` | `true` si es una Page de la extensión |
-
----
-
-## 6. Integración con Shards (PENDIENTE)
-
-> **NOTA**: Esta funcionalidad está pendiente de implementar en Core.
-
-Una Page **PODRÁ**:
-- Registrar Shards locales
-- Cargar Shards dinámicamente en su DOM
-- Comunicarse con Shards mediante el sistema reactivo
-
----
-
-## 7. Build y Compilación
-
-### 7.1 Plugin `surface-pages`
-
-El CLI usa el plugin `surface-pages` para procesar Pages:
-
-1. **Detección**: Intercepta imports de archivos `.html`
-2. **Parsing**: Lee el HTML y busca `<script src="...">` 
-3. **Compilación**: Compila cada script como módulo ES (`.mjs`)
-4. **Transformación**: Actualiza las referencias en el HTML de `.mts/.ts` a `.mjs`
-5. **Copia**: Escribe el HTML transformado en `dist/`
-6. **Export**: Retorna la URL runtime del HTML
-
-### 7.2 Transformación del Import
-
-```ts
-// Código fuente
-import dashboard from "./dashboard/index.html";
-
-// Código transformado por el CLI
-const runtimeUrl = globalThis.Extension?.Runtime?.getURL("surface/pages/dashboard/index.html") || "surface/pages/dashboard/index.html";
-export default runtimeUrl;
-```
-
-### 7.3 Output
-
-```
-dist/
-└── surface/
-    └── pages/
-        └── dashboard/
-            ├── index.html    # HTML con referencias actualizadas
-            ├── index.mjs     # Script compilado
-            └── styles.css    # Estilos copiados
-```
-
----
-
-## 8. Naming Conventions
-
-| Elemento | Convención | Ejemplo |
-|----------|------------|---------|
-| Carpeta de Page | kebab-case | `user-settings/` |
-| Archivo HTML | `index.html` | `index.html` |
-| Archivo Script | `index.mts` | `index.mts` |
-| Clase Page | PascalCase + `Page` | `UserSettingsPage` |
-
----
-
-## 9. Auditoría
-
-Criterios mínimos de auditoría para una Page:
-
-| Criterio | Verificación |
-|----------|--------------|
-| Estructura | Conforme a §3 |
-| Índice de Pages | Existe y exporta la Page |
-| HTML válido | Documento HTML5 con `<script type="module">` |
-| Ciclo de vida | Extiende `Page`, usa `run()` y `start()` |
-| Navegación | Se carga mediante `Engine.navigate()` |
-| No lógica de negocio | Solo UI y comunicación reactiva |
-
----
-
-## 10. Severidad
-
-Cualquier violación de:
-- Estructura (§3)
-- Ciclo de vida (§4)
-- Navegación (§5)
-
-se considera **SEVERITY: HIGH** y bloquea la validación de la Page.
-
----