@ingcrea/aumic-puf 3.1.0 → 3.2.1

package/README.es.md

@@ -1,256 +1,258 @@
 # AUM-IC PUF — Protocolo Universal contra Fallos (PUF-23)
 
-[![Licencia AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
+[![Licencia AGPL-3.0](https://img.shields.io/badge/licencia-AGPL--3.0-blue.svg)](LICENSE)
 [![Estándar AUM-IC 7:2026](https://img.shields.io/badge/est%C3%A1ndar-AUM--IC%207%3A2026-gold.svg)](https://github.com/ingcrea/aum-ic)
-[![npm version](https://img.shields.io/badge/npm-v3.0.0-cb3837.svg)](https://www.npmjs.com/package/@ingcrea/aumic-puf)
+[![npm version](https://img.shields.io/badge/npm-v3.2.1-cb3837.svg)](https://www.npmjs.com/package/@ingcrea/aumic-puf)
 
-> 🌐 **Navegación:** 🇺🇸 [Read in English](./README.md) | 📜 [Manifiesto (ES)](./MANIFEST.es.md) | 📜 [Manifesto (EN)](./MANIFEST.md) | 🌌 [Estándar AUM-IC 7](https://github.com/ingcrea/aum-ic)
+> 🌐 **Navegación:** 🇲🇽 [Leer en Español](./README.es.md) | 🇺🇸 [Read in English](./README.md) | 📜 [Manifiesto (ES)](./MANIFEST.es.md) | 📜 [Manifesto (EN)](./MANIFEST.md) | 🌌 [Estándar AUM-IC 7](https://github.com/ingcrea/aum-ic)
 
-> Suite oficial de aseguramiento de calidad y orquestador determinista para facilitar el cumplimiento del estándar [AUM-IC 7:2026](https://github.com/ingcrea/aum-ic) por **Ingeniería Creativa (IngCrea)**.
+Suite oficial de aseguramiento determinista de calidad y orquestador multi-lenguaje de 23 compuertas (G0 a G22) bajo el estándar **AUM-IC 7:2026**, diseñado y mantenido por **Ingeniería Creativa (IngCrea)**.
 
 ---
 
-## Matriz de 23 Compuertas de Calidad (G0 - G22)
+## Filosofía y Arquitectura del Motor
 
-### 0. G0: Higiene Forense Anti-Entropía y Codificación Pura (aumic-sanitizer Audit)
-- **Alcance:** Diagnóstico in-process de mojibake, entropía de caracteres, saltos CRLF y codificación UTF-8 pura.
+El Protocolo Universal contra Fallos (PUF) no es un linter superficial ni una colección dispersa de scripts. Es un **motor de auditoría determinista de ciclo cerrado** concebido para erradicar la entropía del software antes de que alcance entornos de producción.
 
-### 1. G1: Mapeo de Comportamientos y Límites (Behavior & Boundary Mapping)
-- **Alcance:** Analizar el flujo completo de ejecución, ciclo de vida de la UI y desacoplamiento de hilos pesados.
+Opera de forma agnóstica a través de adaptadores especializados para **Rust, TypeScript/JavaScript, Astro, Next.js, Python, PHP, Java/JVM, C#, C/C++, Flutter/Dart y Shell**, garantizando cumplimiento riguroso con normativas internacionales de fiabilidad (**ISO/IEC 25010**), seguridad de la información (**ISO 27001**) y testabilidad (**ISO 29119**).
 
-### 2. G2: Test de Reproducción — Fase Roja (Reproduction Test-First)
-- **Alcance:** Escribir y verificar test automatizado previo a tocar código de lógica (*Red State*).
+### Características Clave del Motor v3.2.1
 
-### 3. G3: Checkpoint Inmutable (State Snapshot)
-- **Alcance:** Respaldos atómicos con hash SHA-256 en `checkpoints/` para permitir reversión instantánea.
+* **Snapshot VFS en Memoria (`LectorArbolProyecto`):** Mapeo virtual del sistema de archivos con caché volátil estructurado. Permite que múltiples compuertas analicen el repositorio de forma concurrente sin provocar saturación de I/O en disco.
+* **Persistencia Forense Indexada (`RepositorioSqliteAudit`):** Almacenamiento nativo en SQLite (`.aumic/puf_audit.sqlite`) de cada ejecución, registrando métricas de latencia, violaciones detectadas y telemetría histórica con tiempos de consulta inferiores a 20 ms.
+* **Perfiles Dinámicos de Auditoría (`--profile`):** Flexibilidad de inspección según el ciclo de entrega (`enterprise`, `mvp`, `dev`, `security`).
+* **Zero-Black-Box Telemetry:** Reportes forenses interactivos en HTML (`puf-report.html`) con diagramas SVG gauge, tarjetas KPI de impacto y trazabilidad exacta de archivo y línea.
 
-### 4. G4: Reparación Focalizada y Cero CSS Inline (Pure Logic Refactor)
-- **Alcance:** Erradicación de causa raíz, cero código muerto y prohibición de atributos `style="..."` inline.
-
-### 5. G5: Validación de Test y No-Regresión — Fase Verde (Green State & Non-Regression)
-- **Alcance:** 100% de aserciones aprobadas y verificación perimetral contra regresiones colaterales.
-
-### 6. G6: Análisis Estático Estricto (Static Gate Multi-Ecosystem)
-- **Alcance:** Compiladores y linters en modo estricto (Rust, TypeScript, Python, PHP, Java, C#, C++, Swift, etc.).
+---
 
-### 7. G7: Documentación Semántica y Registro ADR (Intent & Architecture Decision)
-- **Alcance:** Registro obligatorio de decisiones de arquitectura en `BITACORA.md`.
+## Matriz Exhaustiva de las 23 Compuertas de Calidad (G0 a G22)
+
+### G0: Higiene Forense Anti-Entropía y Codificación Pura (In-Process Sanitizer)
+* **Para qué sirve:** Garantiza que ningún byte corrupto, BOM invisible o secuencia de caracteres rotos ingrese al flujo de desarrollo.
+* **Qué hace:** Ejecuta diagnósticos directos en memoria (vía motor `aumic-sanitizer`), auditando que el 100% de los archivos del proyecto mantengan codificación **UTF-8 pura sin BOM** y terminaciones de línea Unix **LF (`\n`)**, purgando de inmediato secuencias de mojibake y eliminando el riesgo de discrepancias entre sistemas operativos.
+
+### G1: Mapeo de Comportamientos, Límites y Aislamiento de Hilos (Behavior & Boundary Mapping)
+* **Para qué sirve:** Blinda la estabilidad del ciclo de vida y previene la degradación o congelamiento de las interfaces de usuario.
+* **Qué hace:** Inspecciona contratos, firmas y puntos de entrada identificando valores extremos (`null`, `undefined`, `None`, cadenas vacías y desbordamientos numéricos). Audita que **ninguna operación pesada de I/O, comandos síncronos ni peticiones de red** se invoquen dentro de temporizadores o bucles directos de la interfaz (`slint::Timer`, `setInterval`, `requestAnimationFrame`), forzando su delegación a tareas asíncronas desacopladas o memorias caché atómicas.
+
+### G2: Test de Reproducción — Fase Roja (Reproduction Test-First)
+* **Para qué sirve:** Erradica correcciones a ciegas y asunciones subjetivas al resolver anomalías.
+* **Qué hace:** Exige la existencia o creación previa de una prueba automatizada (unitaria, funcional o de integración) que replique con fidelidad el defecto reportado. El motor verifica que el test falle inequívocamente contra el código base actual (*Estado Rojo*) antes de permitir cualquier mutación de lógica.
+
+### G3: Checkpoint Inmutable de Estado (State Snapshot Guard)
+* **Para qué sirve:** Otorga inmunidad frente a pérdidas de código o regresiones destructivas durante una reparación.
+* **Qué hace:** Captura una copia de seguridad atómica con marca de tiempo en el directorio `checkpoints/` (`<archivo>.bak_YYYYMMDDHHMMSS`) registrando su huella criptográfica SHA-256. Esto permite realizar reversiones instantáneas e íntegras mediante `puf revertir` si el proceso de remediación se descarrila.
+
+### G4: Reparación Focalizada, Refactorización Limpia y Cero CSS Inline (Pure Logic Refactor)
+* **Para qué sirve:** Asegura soluciones de raíz sin parches superficiales, código muerto ni deuda de estilos acoplados.
+* **Qué hace:** Audita que la solución resuelva la causa fundamental sin generar efectos colaterales. Impone principios estrictos por lenguaje (en Rust prohíbe `unwrap()` injustificados forzando `Result`/`Option`; en PHP exige `declare(strict_types=1);`; en Astro separa lógica de frontmatter). Prohíbe de manera tajante el uso de atributos `style="..."` inline en HTML, JSX, PHP o Astro, exigiendo que todo diseño resida en hojas `.css` o `.scss` modulares.
+
+### G5: Validación de Test y No-Regresión — Fase Verde (Green State & Non-Regression)
+* **Para qué sirve:** Certifica matemáticamente que el defecto quedó subsanado sin romper módulos adyacentes.
+* **Qué hace:** Reejecuta el test automatizado introducido en G2 constatando el 100% de aserciones aprobadas (*Estado Verde*). Simultáneamente lanza la suite de pruebas perimetral para validar que ninguna funcionalidad preexistente haya sufrido regresiones.
+
+### G6: Análisis Estático, Tipado y Compilador Estricto (Static Gate Multi-Ecosystem)
+* **Para qué sirve:** Cero tolerancia a advertencias, tipos implícitos y descuidos detectables en tiempo de compilación.
+* **Qué hace:** Invoca el instrumental estático oficial del lenguaje detectado bajo banderas de rigor máximo:
+  * **TypeScript / Astro:** `npx astro check`, `npx tsc --noEmit` y ESLint sin warnings permitidos.
+  * **Rust:** `cargo check` y `cargo clippy -- -D warnings`.
+  * **Python:** `mypy --strict` y `ruff check`.
+  * **PHP:** `php -l` y `phpstan analyse --level=max`.
+  * **Java / JVM:** Validación contra Maven (`mvn test-compile`), Gradle o `javac`.
+  * **C# / .NET:** `dotnet build /warnaserror`.
+
+### G7: Documentación Semántica y Registro ADR (Intent & Architecture Decision)
+* **Para qué sirve:** Preserva la memoria técnica y el razonamiento del porqué se tomaron las decisiones.
+* **Qué hace:** Verifica que el código cuente con comentarios que expliquen la intención arquitectónica y valida la existencia y actualización de la bitácora `BITACORA.md` en la raíz del proyecto bajo el formato estricto:
+  ```text
+  [Timestamp] | Contexto | Decisión | Consecuencia
+  ```
+
+### G8: Aplanadora POSIX y Sanitización Anti-Mojibake (POSIX Squasher)
+* **Para qué sirve:** Evita fallos de build, inconsistencias en git diffs y scripts inutilizables en entornos Linux/Docker.
+* **Qué hace:** Barre en memoria la totalidad de los archivos de código fuente, aplastando de manera definitiva los saltos de línea Windows CRLF (`\r\n`) para forzar Unix LF (`\n`) y erradicando caracteres residuales con codificaciones no compatibles con POSIX.
+
+### G9: Integridad Operativa, Permisos y Secretos Zero-Trust (Ops Shield)
+* **Para qué sirve:** Blinda la infraestructura contra fugas de credenciales y permisos de sistema inseguros.
+* **Qué hace:** Inspecciona permisos en el sistema de archivos (forzando `644` para archivos regulares, `755` para ejecutables/directorios y `600` para llaves de acceso). Realiza análisis de patrones en búsqueda de credenciales, contraseñas, API keys o tokens expuestos en texto plano, obligando el uso de variables de entorno o bóvedas de secretos.
+
+### G10: Invalidación y Purga de Estado Efímero (State Flush)
+* **Para qué sirve:** Garantiza que clientes y desarrolladores consuman código fresco, descartando cachés corrompidas.
+* **Qué hace:** Localiza y purga de forma determinista árboles de compilación residuales y cachés locales (`.next`, `.turbo`, `dist`, `target`, `__pycache__`, `.phpunit.cache`, `storage/framework/cache`), recomendando o ejecutando el reinicio controlado de workers (PM2, Systemd, Gunicorn) según corresponda.
+
+### G11: Blindaje de Ergonomía del SO y Cero Robo de Foco (Zero-Focus Stealing Guard)
+* **Para qué sirve:** Evita la degradación de la experiencia del usuario y parpadeos molestos en el sistema operativo.
+* **Qué hace:** En entornos de escritorio Windows, audita que toda llamada a subprocesos nativos (`Command::new`, `powershell`, `cmd`, `exec`) incorpore obligatoriamente la bandera `creation_flags(0x08000000)` (`CREATE_NO_WINDOW`), impidiendo la aparición repentina de ventanas de consola negras que roben el foco del usuario. Igualmente audita que las consultas repetitivas de privilegios se resuelvan mediante cachés atómicos (`AtomicU8` / `OnceLock`).
+
+### G12: Topología de Rutas Vivas y Barredora de Enlaces Rotos (Living Routes Gate)
+* **Para qué sirve:** Erradica pantallas 404 y enlaces huérfanos antes del despliegue.
+* **Qué hace:** Escanea archivos de plantillas y componentes (`.astro`, `.tsx`, `.jsx`, `.vue`, `.html`, `.php`), extrayendo atributos `href`, `src`, `to` y `action`. Verifica que cada ruta relativa local referenciada tenga una correspondencia física real en el árbol de rutas del proyecto.
+
+### G13: Grafo de Interactividad y Erradicación Zombie (Living UI Actions Gate)
+* **Para qué sirve:** Asegura que ningún control en pantalla sea un adorno inútil o carezca de respuesta.
+* **Qué hace:** Analiza sintácticamente la interfaz buscando eventos interactivos huérfanos o inertes (`onClick=""`, `onClick={undefined}`, `on:click=""`, `@click=""`, botones sin atributo de tipo o sin listener). Todo elemento interactivo debe desencadenar un flujo concreto: llamada de API, apertura modal, mutación de estado o respuesta háptica/visual.
+
+### G14: Traza de Contratos HTTP y Endpoints Vivos (Living API Contract Gate)
+* **Para qué sirve:** Previene discrepancias entre los llamados frontend y los endpoints provistos por el backend.
+* **Qué hace:** Rastrea invocaciones cliente (`fetch(...)`, `axios.get/post/...`, `ky`) contrastando que no existan rutas huérfanas, endpoints deprecados ni rutas locales relativas no mapeadas en los controladores del servidor.
+
+### G15: Headless E2E Crawler y Runtime Exceptions (Headless Handshake Gate)
+* **Para qué sirve:** Captura fallos silenciosos de renderizado, bloqueos de layout y excepciones de consola no controladas.
+* **Qué hace:** Detecta la existencia de suites E2E (Playwright `playwright.config.ts` o Cypress `cypress.config.ts`). Si existen, valida su integración determinista; si no están configuradas, marca la compuerta como `omitida` con una recomendación técnica sin bloquear el proceso general de certificación.
+
+### G16: Calidad Visual, Core Web Vitals y Auditoría Web (Lighthouse / CWV Guard)
+* **Para qué sirve:** Asegura puntuaciones competitivas en motores de búsqueda y una experiencia de usuario de alto nivel.
+* **Qué hace:** Evalúa métricas críticas de rendimiento web (LCP - Largest Contentful Paint, CLS - Cumulative Layout Shift, INP - Interaction to Next Paint), accesibilidad (a11y), cumplimiento de SEO y buenas prácticas. Exige una calificación mínima promedio de 70/100 sobre reportes locales (`aumic-live-report.json`) o telemetría en vivo.
+
+### G17: Blindaje Legal, Integridad de Licencias y Compatibilidad (IP & License Guard)
+* **Para qué sirve:** Protege la titularidad intelectual del software y previene litigios o incompatibilidades de código abierto.
+* **Qué hace:** Audita la consistencia legal entre el manifiesto (`package.json`, `Cargo.toml`, `composer.json`) y los archivos físicos de licenciamiento (`LICENSE`, `LICENSE.md`, `LICENSE-DOCS`). Erradica placeholders sin llenar (ej. `<year>`, `<owner>`), valida compatibilidad de licencias de terceros y ofrece modo consultivo para código privativo de clientes.
+
+### G18: Consistencia de Motores de Estilo y Erradicación de Antipatrones (Style Engine Consistency)
+* **Para qué sirve:** Mantiene un diseño limpio y previene conflictos catastróficos entre librerías CSS.
+* **Qué hace:** Audita que el proyecto no mezcle frameworks antagónicos (por ejemplo, Tailwind CSS y Bootstrap conviviendo en el mismo proyecto). Adicionalmente, fiscaliza la deuda técnica de especificidad CSS, marcando alerta o rechazo si la presencia de la regla `!important` excede el umbral tolerado (máximo 5 ocurrencias justificadas).
+
+### G19: Blindaje de Superficie de Ataque y Cero Inyecciones (Zero-Injection & Attack Surface Guard)
+* **Para qué sirve:** Cierra vectores de ataque comunes y previene intrusiones o robo de información.
+* **Qué hace:** Escanea el repositorio descartando la presencia accidental de volcados de base de datos (`dump.sql`, `backup.sql`), scripts de diagnóstico peligrosos (`phpinfo.php`, `xmlrpc.php`) o llaves privadas SSH. Audita que el archivo `.env` se encuentre estrictamente ignorado en `.gitignore` e identifica patrones de concatenación directa de entradas de usuario en sentencias SQL, forzando consultas parametrizadas o Query Builders tipados.
+
+### G20: Topología de Entornos y Cero Conexiones Fantasma (Topology Guard)
+* **Para qué sirve:** Erradica fallos silenciosos y llamadas a servidores de desarrollo en despliegues a producción.
+* **Qué hace:** Analiza el código fuente en búsqueda de direcciones locales (`http://localhost`, `127.0.0.1`) hardcodeadas dentro de controladores o servicios de producción, exigiendo su desacoplamiento absoluto mediante variables de entorno configuradas por entorno (`dev`, `staging`, `prod`).
+
+### G21: Cumplimiento Oficial WordPress y WooCommerce (WPCS & WC Guidelines Guard)
+* **Para qué sirve:** Garantiza código seguro, preparado para HPOS y resistente a fallos transaccionales en plataformas WordPress y WooCommerce.
+* **Qué hace:** Se activa automáticamente al detectar proyectos PHP/WordPress ejecutando un conjunto de reglas especializadas:
+  * **`WP-SEC-01` (Sanitización y Nonces):** Valida sanitización de superglobales (`$_GET`, `$_POST`, `$_REQUEST`) y verificación obligatoria de nonces con `check_admin_referer()` / `wp_verify_nonce()`.
+  * **`WP-SEC-02` (Prepared Queries):** Prohíbe consultas directas a `$wpdb` sin `$wpdb->prepare()`.
+  * **`WC-HPOS-01` (CRUD Mandatorio de Pedidos):** Prohíbe lecturas o escrituras directas a `wp_postmeta` para metadatos de pedidos, forzando los métodos canónicos de la API CRUD de `WC_Order` (`$order->get_id()`, `$order->get_meta()`, `$order->update_meta_data()`, `$order->save()`).
+  * **`WC-CORE-01` (Propiedades Obsoletas):** Detecta accesos a propiedades deprecadas del core de WooCommerce (como `$order->id`).
+  * **`WP-ROBUST-OPT-01` (Empty Coalesce Guard):** Previene fallos sutiles donde el operador `??` sobre arrays de opciones falla porque una cadena vacía (`''`) no se evalúa como nula, evadiendo los valores de respaldo indispensables.
+  * **`WP-CIRCUIT-BREAKER-01` (Hardcoded Flags):** Detecta banderas booleanas fijas en código que bloquean silenciosamente flujos transaccionales o de pago.
+
+### G22: Diagnóstico Universal de Sintaxis y Delimitadores (Universal Syntax Guard)
+* **Para qué sirve:** Diagnostica en milisegundos errores sintácticos sutiles sin requerir compiladores pesados instalados en la máquina.
+* **Qué hace:** Motor de análisis sintáctico in-memory multi-lenguaje (PHP, CSS/SCSS, JSON, JavaScript, TypeScript, Java) que:
+  * Localiza omisiones exactas de punto y coma (`;`) en sentencias PHP y CSS/SCSS.
+  * Audita la integridad de archivos JSON (detectando comas faltantes o trailing commas no permitidas).
+  * Evalúa el balanceo perfecto de delimitadores (`{ }`, `[ ]`, `( )`), ignorando inteligentemente literales de cadenas, comentarios y expresiones regulares para reportar la línea precisa de cualquier desbalance.
 
-### 8. G8: Aplanadora POSIX y Sanitización Anti-Mojibake
-- **Alcance:** Blindaje de bytes LF puros y UTF-8 estricto sin BOM.
+---
 
-### 9. G9: Integridad Operativa, Permisos y Secretos Zero-Trust
-- **Alcance:** Permisos POSIX (644/755) y cero credenciales en texto plano.
+## Perfiles Dinámicos de Auditoría (`--profile`)
 
-### 10. G10: Invalidación y Purga de Estado Efímero
-- **Alcance:** Purga de cachés de compilación (.next, .turbo, target, __pycache__, .phpunit.cache).
+Para optimizar pipelines de integración continua o verificaciones rápidas antes de un commit, el PUF incorpora perfiles de auditoría seleccionables:
 
-### 11. G11: Ergonomía del SO, Foco de Ventanas y Aislamiento UI (Zero-Focus Stealing)
-- **Alcance:** Compuerta obligatoria contra robo de foco en Windows (`CREATE_NO_WINDOW`) e I/O desacoplado de loops UI.
+| Perfil | Compuertas Evaluadas | Caso de Uso |
+| :--- | :--- | :--- |
+| **`enterprise`** *(Predeterminado)* | **G0 a G22 (23 compuertas)** | Certificación integral obligatoria previa a releases y despliegues productivos. |
+| **`mvp`** | `G0`, `G4`, `G6`, `G8`, `G22` | Verificación ágil de prototipos rápidos: higiene, lógica limpia, tipado estricto y sintaxis. |
+| **`dev`** | `G0`, `G4`, `G6`, `G8`, `G22` | Ciclo de desarrollo local ultrarrápido sin bloqueos por suites accesorias. |
+| **`security`** | `G0`, `G8`, `G9`, `G17`, `G19`, `G20` | Auditoría de ciberseguridad, permisos POSIX, blindaje legal, topología y cero inyecciones. |
 
-### 12. G12: Topología de Rutas Vivas & Dead Link Sweeper
-- **Alcance:** Detección de enlaces y destinos locales rotos en código web.
+---
 
-### 13. G13: Grafo de Interactividad & Erradicación Zombie
-- **Alcance:** Erradicación de botones decorativos o handlers de eventos inertes.
+## Manual de Uso del CLI (`puf` / `aumic-puf`)
 
-### 14. G14: Traza de Contratos HTTP & Endpoints Vivos
-- **Alcance:** Detección estática de contratos HTTP rotos o paths huérfanos.
+### Instalación
 
-### 15. G15: Headless E2E Crawler & Runtime Exceptions
-- **Alcance:** Suites E2E (Playwright / Cypress) para verificación de flujo funcional.
+```bash
+# Instalación global vía npm
+npm install -g @ingcrea/aumic-puf
 
-### 16. G16: Calidad Visual, Core Web Vitals y Auditoría Web (Lighthouse / CWV)
-- **Alcance:** Puntuación de experiencia de usuario, layouts DOM estables y Core Web Vitals.
+# O uso directo sin instalación vía npx
+npx @ingcrea/aumic-puf auditar
+```
 
-### 17. G17: Blindaje Legal, Integridad de Licencias y Compatibilidad (IP & License Guard)
-- **Alcance:** Consistencia entre manifiestos (`package.json`, `Cargo.toml`) y archivos `LICENSE`, titularidad y copyright.
+### Comandos de Operación
 
-### 18. G18: Consistencia de Motores de Estilo y Erradicación de Antipatrones (Style Engine Consistency)
-- **Alcance:** Prevención de colisión entre frameworks (ej. Tailwind + Bootstrap) y control de deuda de `!important`.
+#### 1. Auditoría Completa de la Matriz (Enterprise)
+```bash
+# Audita las 23 compuertas de calidad concurrentemente en el directorio actual
+puf auditar
 
-### 19. G19: Blindaje de Superficie de Ataque y Cero Inyecciones (Zero-Injection Guard)
-- **Alcance:** Erradicación de archivos expuestos (`.env`, `dump.sql`) y prevención de concatenación SQL directa.
+# Ejecución fail-fast (aborta de inmediato al primer fallo detectado)
+puf auditar --fast
+```
 
-### 20. G20: Topología de Entornos, Aislamiento de Red y Cero Conexiones Fantasma (Topology Guard)
-- **Alcance:** Erradicación de referencias hardcodeadas a `localhost` / `127.0.0.1` en entornos de producción.
+#### 2. Auditoría por Perfil Dinámico
+```bash
+# Auditoría rápida para entornos de desarrollo local
+puf auditar --profile=dev
 
-### 21. G21: Cumplimiento Oficial WordPress & WooCommerce (WPCS & WC Guidelines)
-- **Alcance:** Auditoría estricta de sanitización de superglobales, prepared queries en `$wpdb`, compatibilidad obligatoria con High-Performance Order Storage (HPOS) y métodos CRUD canónicos de `WC_Order`.
+# Auditoría estricta de seguridad perimetral
+puf auditar --profile=security
 
-### 22. G22: Diagnóstico Universal de Sintaxis y Delimitadores (Universal Syntax Guard)
-- **Alcance:** Localización exacta de omisiones de punto y coma (`;`), comas en JSON y llaves/corchetes/paréntesis desbalanceados en memoria sin requerir compiladores externos.
+# Auditoría ligera de entrega rápida (MVP)
+puf auditar --profile=mvp
+```
 
----
+#### 3. Auditoría Focalizada por Compuertas
+```bash
+# Evalúa únicamente higiene forense, compliance de WordPress y sintaxis universal
+puf auditar -g G0,G21,G22
 
-## Uso del Orquestador (CLI)
+# Evalúa seguridad y topología de red
+puf auditar -g G9,G19,G20
+```
 
+#### 4. Gestión de Incidentes y Reversión Atómica
 ```bash
-# Instalación global desde npm
-npm install -g @ingcrea/aumic-puf
+# Inicia un incidente (genera andamio de test G2 y captura checkpoint inmutable G3)
+puf iniciar INC-104 "Corrección de cálculo en pasarela de pagos" src/checkout.ts
 
-# Auditar todas las compuertas de la matriz (G0 a G22)
-puf auditar
+# Reversión de emergencia a partir del checkpoint SHA-256 en caso de error
+puf revertir INC-104 src/checkout.ts
+```
 
-# Auditar compuertas focalizadas (G0, G21, G22)
-puf auditar -g G0,G21,G22
+#### 5. Blindaje de Repositorio Git (Pre-commit Hook)
+```bash
+# Instala el guardián nativo en .git/hooks/pre-commit
+puf instalar-hook
 
-# Modo fail-fast (aborta al primer fallo detectado)
-puf auditar --fast
+# Validación en staged: impide realizar commits si se violan G4 (código muerto/CSS inline) o G7 (ADR)
+puf guard
+```
 
-# Consultar versión instalada
+#### 6. Consulta de Versión
+```bash
 puf -v
+# o
+puf --version
 ```
 
-### 1. G1: Mapeo de Comportamientos y Limites (Behavior & Boundary Mapping)
-- **Alcance:** Analizar el flujo completo de ejecucion y ciclo de vida de la UI.
-- **Acciones:**
-  - Identificar entradas, tipos, contratos, mutaciones y salidas esperadas.
-  - Definir formalmente casos de borde: valores nulos (`None`, `null`, `Option::None`), cadenas vacias, desbordamientos numericos, condiciones de carrera/concurrencia y accesos no autenticados.
-  - **Aislamiento del Bucle de UI:** Prohibido disparar I/O pesado, comandos o procesos sincronos dentro de temporizadores o callbacks de interfaz grafica (`slint::Timer`, `setInterval`, `requestAnimationFrame`). Deben delegarse a tareas de fondo asincronas o cachearse atomicamente.
-
-### 2. G2: Test de Reproduccion -- Fase Roja (Reproduction Test-First)
-- **Alcance:** Probar y demostrar empiricamente el defecto antes de tocar una sola linea de logica.
-- **Acciones:**
-  - Escribir un test automatizado (unitario, integracion o CLI determinista) que replique la falla reportada con fidelidad.
-  - Ejecutar el test y confirmar que falle contra el codigo actual (*Red State*).
-
-### 3. G3: Checkpoint Inmutable (State Snapshot)
-- **Alcance:** Blindaje de rollback y preservacion de estado pre-mutacion.
-- **Acciones:**
-  - Generar un respaldo atomico timestamped en `checkpoints/` (`<archivo>.bak_YYYYMMDDHHMMSS`).
-  - Registrar hash SHA-256 para permitir reversion instantanea sin perdida de informacion.
-
-### 4. G4: Reparacion Focalizada y Refactorizacion Limpia (Pure Logic Refactor)
-- **Alcance:** Correccion quirurgica de la causa raiz.
-- **Acciones:**
-  - Atacar la causa raiz sin parches superficiales. Cero codigo muerto, cero dependencias circulares.
-  - Cumplir principios de codigo limpio del stack correspondiente:
-    - **Rust:** Cero `unwrap()` no justificado; manejo exhaustivo con `Result` / `Option`.
-    - **Astro:** Componentes puros, separacion de logica frontmatter y JSX estatico/reactivo.
-    - **Python:** Tipado estricto (Type hints), PEP 8, manejo explicito de excepciones.
-    - **PHP:** POO fuertemente tipada, `declare(strict_types=1);`, inyeccion de dependencias.
-  - **Prohibicion Absoluta de CSS Inline:** Queda terminantemente prohibido inyectar `style="..."` en HTML/PHP/JSX/Astro. Si existen estilos inline preexistentes, refactorizarlos a archivos `.css`/`.scss`.
-
-### 5. G5: Validacion de Test y No-Regresion -- Fase Verde (Green State & Non-Regression)
-- **Alcance:** Verificacion de solucion completa y estabilidad perimetral.
-- **Acciones:**
-  - Reejecutar el test de G2 y validar el 100% de aserciones aprobadas (*Green State*).
-  - Ejecutar la suite de pruebas perimetral/completa para certificar cero regresiones colaterales.
-
-### 6. G6: Analisis Estatico, Tipado y Compilador Estricto (Static Gate)
-- **Alcance:** Tolerancia cero a advertencias del compilador o linters.
-- **Acciones:**
-  - Ejecutar compilador y analisis estatico en modo estricto segun el stack:
-    - **Rust:** `cargo clippy -- -D warnings` y `cargo check`.
-    - **Astro / TypeScript:** `npx astro check` y `npx eslint`.
-    - **Python:** `ruff check` y `mypy --strict`.
-    - **PHP:** `php -l` y `phpstan analyse --level=max`.
-  - Cero advertencias o errores tolerados.
-
-### 7. G7: Documentacion Semantica y Registro ADR (Intent & Architecture Decision)
-- **Alcance:** Memoria tecnica e intencion arquitectonica.
-- **Acciones:**
-  - Explicar en comentarios de codigo el *por que* de la decision y no solo el *que hace*.
-  - Registrar en `BITACORA.md` de la raiz del proyecto bajo el formato estricto:
-    ```
-    [Timestamp] | Contexto | Decision | Consecuencia
-    ```
-
-### 8. G8: Aplanadora POSIX y Sanitizacion Anti-Mojibake (aumic-sanitizer)
-- **Alcance:** Integridad de codificacion y terminacion de linea.
-- **Acciones:**
-  - Barrer los archivos con `node C:\Users\NexoRemoto\Proyectos\aumic-sanitizer\dist\index.js audit .`
-  - Purgar caracteres Mojibake forzando UTF-8 puro sin BOM.
-  - Aplanar y forzar saltos de linea Unix LF (`\n`), erradicando Windows CRLF (`\r\n`).
-
-### 9. G9: Integridad Operativa, Permisos y Secretos Zero-Trust (Ops Shield)
-- **Alcance:** Blindaje de infraestructura y seguridad de credenciales.
-- **Acciones:**
-  - Verificar permisos restrictivos en sistema de archivos (`chmod 644` archivos / `755` directorios, llaves SSH `600`).
-  - Cero credenciales, tokens o contrasenas en texto plano. Gestionar accesos via variables de entorno seguras o `SECRETOS.py`.
-
-### 10. G10: Invalidacion y Purga de Estado Efimero (State Flush)
-- **Alcance:** Consumo garantizado del codigo fresco en runtime.
-- **Acciones:**
-  - Purgar deterministamente cache de objetos (Redis, Memcached, Opcache, `.next`, `dist`).
-  - Reiniciar workers (Gunicorn, Systemd, SSR Node, PM2) para garantizar que los clientes consuman el codigo validado.
-
-### 11. G11: Blindaje de Ergonomia del SO, Foco de Ventanas y Aislamiento UI (OS & Desktop Ergonomics Gate)
-- **Alcance:** Experiencia de usuario inmaculada, ausencia total de robo de foco.
-- **Acciones:**
-  - **Inmunidad al Robo de Foco (Zero-Focus Stealing):** Toda invocacion de subprocesos en Windows (`Command::new`, `powershell`, `cmd`) DEBE incorporar `.creation_flags(0x08000000)` (`CREATE_NO_WINDOW`).
-  - **Zero-Ghost Processes:** Al cerrar la aplicacion, no deben quedar procesos huerfanos consumiendo CPU.
-  - **Cache de Consultas de Privilegios:** Usar cache atomico perezoso (`AtomicU8` / `OnceLock`), evitando invocaciones repetidas en bucles.
-
 ---
 
-### 12. G12: Topologia de Rutas Vivas & Dead Link Sweeper (Living Routes Gate)
-- **Alcance:** Integridad de navegacion sin pantallas 404 ni rutas huerfanas en Web (Astro, React, Next, Vue), Mobile (Flutter) y Desktop (Slint, C#/WPF, Tauri).
-- **Acciones:**
-  - Escanear los archivos HTML/JSX/Astro/PHP afectados con el metodo `auditarRutasVivas()` del adaptador.
-  - Detectar atributos `href`, `src`, `to`, `action` que apunten a rutas locales que no existen en el filesystem.
-  - Cero enlaces rotos hacia destinos locales inexistentes. Toda ruta relativa debe resolverse a un archivo real.
-  - El orquestador informa la lista exacta: `archivo.astro -> "/ruta/inexistente" (no existe en filesystem)`.
-  - **Solo aplica a extensiones web:** `.astro`, `.jsx`, `.tsx`, `.html`, `.php`, `.vue`, `.svelte`.
-
-### 13. G13: Grafo de Interactividad & Erradicacion Zombie (Living UI Actions Gate)
-- **Alcance:** Cero botones decorativos, pseudoelementos inertes o acciones no conectadas.
-- **Acciones:**
-  - Escanear los archivos web afectados con el metodo `auditarInteractividad()` del adaptador.
-  - Detectar patrones de handler inerte: `onClick=""`, `onClick={undefined}`, `on:click=""`, `@click=""`.
-  - Todo control interactivo debe resolver en un evento real (API call, modal, mutacion de estado o feedback visual).
-  - El orquestador reporta exactamente que archivo y linea contiene el handler zombie.
-  - **Solo aplica a extensiones web:** `.astro`, `.jsx`, `.tsx`, `.html`, `.php`, `.vue`, `.svelte`.
-
-### 14. G14: Traza de Contratos HTTP & Endpoints Vivos (Living API Contract Gate)
-- **Alcance:** Consistencia granular entre las llamadas del cliente y los controladores declarados en el backend.
-- **Acciones:**
-  - Analizar los archivos afectados buscando llamadas `fetch(...)` o `axios.get/post/...` con rutas hardcodeadas locales (no `/api/`, no variables de entorno `${}`).
-  - Cero llamadas HTTP a paths huerfanos o inexistentes detectados estaticamente.
-  - Si se detectan inconsistencias, listar exactamente el archivo y el endpoint problematico.
-
-### 15. G15: Headless E2E Crawler & Runtime Exceptions (Headless Handshake Gate)
-- **Alcance:** Deteccion de errores silenciosos, excepciones de runtime y bloqueos de interfaz.
-- **Acciones:**
-  - Verificar si existe suite E2E (Playwright `playwright.config.ts`, Cypress `cypress.config.ts`) en la raiz del proyecto.
-  - Si existe: marcar como **APROBADA** e instruir al Jefe Maestro a ejecutarla manualmente para certificacion completa.
-  - Si NO existe: marcar como **OMITIDA** (no bloquea certificacion) con recomendacion de configurar Playwright.
-  - **G15 OMITIDA no es un fallo:** `todasAprobadas` acepta tanto `aprobada` como `omitida`.
+## Integración Continua (GitHub Actions)
 
----
-
-## Reglas Inviolables de Ejecucion
-
-1. **Cero Complacencia:** No dejar tareas a medias ni usar marcadores vacios (`// el resto del codigo aqui`).
-2. **Determinismo Tecnico:** Todo entregable debe ser determinista, verificado en consola y listo para produccion.
-3. **Reporte por Compuerta:** Reportar siempre el estado de cada compuerta (G1 a G15) con su respectiva evidencia.
-4. **G15 es OMITIDA, no RECHAZADA:** Si no hay suite E2E, G15 se omite sin bloquear la certificacion.
-5. **G12 y G13 aplican solo a archivos web:** Para proyectos Rust/Python/Shell sin frontend, estas compuertas se aprueban automaticamente por ausencia de extensiones web en los archivos afectados.
+El repositorio incluye la plantilla oficial [`puf-github-action.yml`](puf-github-action.yml). Para blindar cualquier repositorio en GitHub:
 
-## Uso del Orquestador (CLI)
-
-```bash
-# Inicializar incidente (crea andamio G2 + checkpoints G3)
-puf iniciar INC-042 "Descripcion del fallo" src/archivo.ts
+```yaml
+name: Certificación AUM-IC PUF-23
+on: [push, pull_request]
 
-# Auditar las 15 compuertas concurrentemente
-puf auditar INC-042 src/archivo.ts
+jobs:
+  auditoria-puf:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout del Repositorio
+        uses: actions/checkout@v4
 
-# Modo fail-fast (aborta al primer fallo)
-puf auditar INC-042 src/archivo.ts --fast
+      - name: Configurar Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
 
-# Revertir a estado pre-fallo (usando checkpoint G3)
-puf revertir INC-042 archivo.ts
-
-# Instalar guardian de Git (pre-commit hook)
-puf instalar-hook
+      - name: Ejecutar Auditoría PUF
+        run: npx @ingcrea/aumic-puf auditar --profile=enterprise --fast
 ```
 
-## Licencia
+---
+
+## Licencia y Propiedad Intelectual
 
-Distribuido bajo licencia **GNU Affero General Public License v3.0 (AGPL-3.0)**. Ver [LICENSE](LICENSE).
+Distribuido bajo licencia **GNU Affero General Public License v3.0 (AGPL-3.0)**. Consulta el archivo [LICENSE](LICENSE) para mayores detalles sobre derechos y libertades de uso de software libre.
 
 ---
 
-**[Ingeniería Creativa](https://ingcrea.com)** | [Estándar AUM-IC](https://github.com/ingcrea/aum-ic)
+**[Ingeniería Creativa (IngCrea)](https://ingcrea.com)** | [Estándar AUM-IC 7:2026](https://github.com/ingcrea/aum-ic)