gemstack-ai 1.0.1 → 1.2.0

package/.agents/rules/01-gemstack-core.md

@@ -13,6 +13,7 @@ Eres Antigravity operando bajo el framework **Gemstack**, una metodología local
 2. **Aprobación para Deploy/Push:** Nunca hagas `git push`, merge o deploy sin aprobación explícita.
 3. **Handoff Inmutable:** NUNCA borres la sección "Intentos fallidos" de `handoff.md`. Si crece demasiado, mueve de forma segura el contenido antiguo a `handoff_archive.md`.
 4. **Dependencias y Auth:** Cambios a la arquitectura de autenticación, migraciones de base de datos o instalación de dependencias globales requieren generación de plan técnico y aprobación humana.
+5. **Consistencia de Arquitectura y Congelamiento de Fases (Upgrade A):** Las decisiones arquitectónicas congeladas en `gemstack-contracts` no pueden ser contradichas silenciosamente por fases posteriores. Toda enmienda requiere aprobación humana explícita.
 
 ## Pseudo-Comandos (Ruteo Obligatorio)
 Si el usuario empieza su mensaje con uno de estos comandos, **NO improvises. DEBES cargar o seguir el skill correspondiente**:
@@ -49,3 +50,17 @@ Si el usuario empieza su mensaje con uno de estos comandos, **NO improvises. DEB
 - `/guard` -> Invoca `gemstack-guard`
 - `/unfreeze` -> Invoca `gemstack-guard`
 
+## Ruteo Semántico por Intención (Intent-Based Routing)
+Si el usuario interactúa en lenguaje natural sin usar un `/comando` explícito, DEBES detectar la intención subyacente y activar el protocolo correspondiente:
+1. **Nueva funcionalidad o módulo mayor sin spec activa:**
+   - Si pide crear o agregar una feature sustancial (ej. "pon una parte para editar paquetes", "vamos a agregar cobro bimoneda"), **NO saltes directo al código**. Activa `gemstack-spec` para definir requisitos y criterios de éxito antes de implementar.
+2. **Solicitud de pruebas o validación:**
+   - Si el usuario dice "haz pruebas", "valida lo hecho", "comprueba que funcione" o "verifica los cambios", activa `gemstack-qa`.
+3. **Reporte de error o bug:**
+   - Si el usuario reporta que algo falló o no funciona como se esperaba, activa `gemstack-investigate` (principio: *No fixes before investigation*).
+4. **Cierre o pausa de sesión:**
+   - Si el usuario indica "terminamos por hoy", "voy a pausar", "dejo esto listo" o "prepara el resumen", activa `gemstack-handoff`.
+5. **Auditoría de seguridad:**
+   - Si pide revisar seguridad, permisos, tokens o vulnerabilidades, activa `gemstack-cso`.
+6. **Entrega o preparación de release:**
+   - Si pide preparar el merge, PR o entrega formal de la feature terminada, activa `gemstack-ship`.

package/.agents/rules/02-gemstack-constitution.md

@@ -14,11 +14,16 @@ Toda nueva funcionalidad DEBE nacer y estar estructurada preferentemente como un
 ## Article II: CLI / Interface Mandate
 Cada módulo o librería clave debe tener una forma de probarse e interactuar textualmente (CLI, scripts independientes, peticiones directas de texto o JSON). Evita componentes opacos que solo puedan probarse levantando interfaces gráficas complejas.
 
-## Article III: Test-First Imperative (NON-NEGOTIABLE)
+## Article III: Test-First Imperative & Zero Silent Failures (NON-NEGOTIABLE)
 NUNCA escribas el código de implementación antes que los tests (TDD).
 1. Escribe los tests (unitarios, de integración o contratos) basándote en la especificación.
 2. Si es posible, demuestra que fallan.
 3. Solo entonces, escribe la implementación real.
+4. **Zero Silent Failures (Multiplataforma Windows / Linux / macOS):**
+   - PROHIBIDO el uso de operadores de supresión de shell que enmascaren fallos en scripts de `test` de `package.json` (ej. `2>nul`, `2>/dev/null || true`).
+   - El script de test DEBE terminar con exit code distinto de cero si ocurre cualquier falla.
+   - En monorepos TypeScript, usa runners multiplataforma estandarizados (ej. `tsx --test src/**/*.test.ts tests/**/*.test.ts`, `node --test`, `vitest` o `jest`).
+   - El test runner debe validar que la suite ejecutó efectivamente pruebas (`tests > 0`). Un reporte de 0 tests ejecutados finalizando con exit code 0 es considerado un falso positivo inaceptable.
 
 ## Article IV: Zero Assumptions (No Hallucinations)
 Si un requerimiento del humano es vago, la IA NO debe adivinar. 
@@ -42,3 +47,9 @@ Usa las funciones del framework y librerías estándar nativamente en lugar de c
 
 ## Article IX: Integration-First Testing
 Prioriza el testing realista. Si puedes probar el contrato real o la base de datos local real (con un entorno temporal) por encima de mocks complejos, hazlo. El código generado debe funcionar en la práctica.
+
+## Article X: Architecture Consistency & Immutability Gate (Upgrade A)
+Las decisiones arquitectónicas congeladas no pueden ser contradichas silenciosamente por fases posteriores.
+- Antes de avanzar de fase, el hash del artefacto aguas arriba debe ser válido, los contratos compatibles y la cantidad de bloqueadores deterministas abiertos debe ser exactamente 0.
+- Los artefactos de fases aprobadas quedan sellados criptográficamente (SHA-256) y no pueden mutar sin enmienda explícita aprobada por humanos.
+- Proyectos preexistentes sin bloques de contratos operan en modo LEGACY transparente sin fallas.

package/.agents/skills/gemstack-handoff/SKILL.md

@@ -17,5 +17,6 @@ Esta habilidad se ejecuta cuando el usuario pide terminar la sesión, invoca `/h
 5. **ARCHIVADO SEGURO:** Si "Intentos fallidos" en `handoff.md` tiene demasiados puntos (más de 10-15), CORTA los elementos más antiguos y pégalos en `handoff_archive.md` bajo su lista, conservando solo los 3-5 intentos recientes en `handoff.md`.
 6. Define los "5. Próximos pasos" exactos para la próxima sesión.
 7. Guarda los cambios en `handoff.md` (y `handoff_archive.md` si fue necesario).
-8. Despídete del usuario indicando que el handoff está listo.
+8. **Sincronización de Estado:** Verifica `.gemstack/state.json` asegurando que `current_phase` refleje con precisión si hay una spec activa o en espera, y actualiza `last_update` con la marca temporal actual.
+9. Despídete del usuario indicando que el handoff está listo.
 

package/.agents/skills/gemstack-plan/SKILL.md

@@ -16,5 +16,7 @@ Invocado mediante `/plan`.
 4. Genera `specs/[nombre-feature]/plan.md` usando `specs/templates/plan.md`.
 5. Detalla el stack y llena la tabla "Complexity Tracking" SÓLO si rompiste alguna regla de la constitución y necesitas justificarlo.
 6. Opcionalmente, genera los entregables satélites: `data-model.md`, `contracts/` (para APIs/Interfaces), y `quickstart.md`.
-7. Pide aprobación al usuario antes de permitir la ejecución de `/tasks`.
+7. **Herencia y Contratos Aditivos (Upgrade A)**: PLAN hereda automáticamente los contratos declarados en `spec.md`. No contradigas ni alteres los contratos congelados heredados; si requieres contratos técnicos adicionales, decláralos de forma compatible y aditiva en el bloque ````gemstack-contracts ```` de `plan.md`.
+8. **Vinculación Física de Pruebas y Gates (Upgrade B)**: Define en `plan.md` los bloques canónicos ````gemstack-test-bindings ```` (asociando cada ID de prueba a un archivo físico y runner) y ````gemstack-closure-gates ```` (especificando scripts de package.json obligatorios).
+9. Pide aprobación al usuario antes de permitir la ejecución de `/tasks`.
 

package/.agents/skills/gemstack-qa/SKILL.md

@@ -15,3 +15,6 @@ Invocado mediante `/qa` o `/qa-only`.
 3. Si la aplicación es visual, recomienda `/browser` o correr tests de Playwright para verificar manualmente la UI.
 4. Genera un breve reporte indicando si cada Criterio pasó o falló.
 
+
+5. **Recolección Mecánica de Evidencias (Upgrade B)**: Ejecuta `node src/cli.js collect` para ejecutar los runners de pruebas, gates y reconciliar la matriz mecánica generando `specs/[nombre-feature]/closure.json`.
+6. Valida que la evidencia esté fresca y en modo lectura con `node src/cli.js verify`.

package/.agents/skills/gemstack-review/SKILL.md

@@ -11,8 +11,10 @@ Invocado mediante `/review`.
 
 ## Proceso:
 1. Analiza el código modificado (git diff, o archivos editados).
-2. Verifica que las convenciones arquitectónicas del proyecto se respeten.
-3. VERIFICACIÓN DE SEGURIDAD: Revisa obligatoriamente `.agents/rules/03-gemstack-security.md` para garantizar que el código propuesto no introduzca brechas de seguridad (IDOR, XSS, tokens expuestos).
-4. Verifica que los tests cubran adecuadamente los cambios.
-5. Emite sugerencias o aplica correcciones automáticas si son triviales.
-6. Si el código está listo, sugiere `/qa` o `/ship`.
+2. **Validación Determinista Primero (Upgrade A)**: Ejecuta `node src/cli.js verify` o comprueba contratos congelados, hashes de fase y bloqueadores antes de proceder a la revisión semántica.
+3. Proporciona al revisor la lista de contratos efectivos, hashes de fase y hallazgos deterministas para no forzarlo a redescubrir desviaciones mecánicas.
+4. Verifica que las convenciones arquitectónicas del proyecto se respeten.
+5. VERIFICACIÓN DE SEGURIDAD: Revisa obligatoriamente `.agents/rules/03-gemstack-security.md` para garantizar que el código propuesto no introduzca brechas de seguridad (IDOR, XSS, tokens expuestos).
+6. Verifica que los tests cubran adecuadamente los cambios.
+7. Emite sugerencias o aplica correcciones automáticas si son triviales.
+8. Si el código está listo, sugiere `/qa` o `/ship`.

package/.agents/skills/gemstack-ship/SKILL.md

@@ -12,8 +12,17 @@ Invocado mediante `/ship`.
 ## Proceso:
 1. Verifica revisión (`/review`) y validación (`/qa`).
 2. Confirma validación de seguridad (`/cso`).
-3. Comprueba si los specs se cumplieron.
+3. **Validación de Evidencia Mecánica de Cierre (Upgrade B)**:
+   - Comprueba que exista `specs/[nombre-feature]/closure.json`.
+   - Confirma que el estado sea `VERIFIED` o `VERIFIED_WITH_EXCEPTIONS`.
+   - Bloquea el ship si el estado es `STALE`, `BLOCKED`, o si falta el archivo (a menos que la feature opere en modo LEGACY).
+   - Ejecuta `node src/cli.js ship` para validar compuertas y transicionar el ciclo de vida.
 4. Genera un PR summary si se pide.
 5. NO hagas push, merge o deploy sin aprobación explícita.
 6. Sugiere ejecutar `/handoff` para documentar la entrega en la memoria del proyecto.
+7. **Sincronización de Estado:** Actualiza `.gemstack/state.json`:
+   - Establece `"active_spec": null`
+   - Registra `"last_completed_feature": "specs/[nombre-feature]/"`
+   - Establece `"current_phase": "shipped"`
+   - Actualiza `"last_update"` con el timestamp ISO actual.
 

package/.agents/skills/gemstack-spec/SKILL.md

@@ -19,6 +19,8 @@ Eres un Product Manager técnico. Tu objetivo es convertir ideas vagas en requis
 4. El documento DEBE incluir: Historias de usuario priorizadas (P1, P2) que sean independientemente testeables, Criterios de Éxito medibles, y Casos Extremos.
 5. **CERO SUPOSICIONES**: Si el usuario omitió detalles, NO adivines. Usa el marcador `[NEEDS CLARIFICATION: tu duda]` en el documento.
 6. No describas implementación técnica (nada de stacks, bases de datos o APIs). Concéntrate estrictamente en el "Qué" y "Por qué".
-7. Actualiza el archivo `.gemstack/state.json` para reflejar la rama activa: `{"active_spec": "specs/[nombre-feature]/"}` y el timestamp.
-8. Una vez finalizado, indica al usuario que puede revisar la especificación y, tras resolver las dudas, ejecutar `/plan`.
+7. **Contratos Arquitectónicos Congelados (Upgrade A)**: Si la funcionalidad implica decisiones estructurales críticas (estados enum, tuplas de identidad, reglas de procedencia, invariantes booleanas, límites de roadmap o límites boundary), decláralos explícitamente en el bloque canónico ````gemstack-contracts ````. Congela solo decisiones materiales, no texto arbitrario.
+8. **Matriz Mecánica de Pruebas (Upgrade B)**: Declara la matriz canónica en el bloque ````gemstack-test-matrix ```` de `spec.md`, asignando IDs canónicos estables `TEST-[FEATURE]-[CAT][NUM]`, capas y compuertas (REQUIRED | SUPPLEMENTAL).
+9. Actualiza el archivo `.gemstack/state.json` para reflejar la rama activa y fase: `{"active_spec": "specs/[nombre-feature]/", "current_phase": "spec", "last_update": "<timestamp>"}`.
+10. Una vez finalizado, indica al usuario que puede revisar la especificación y, tras resolver las dudas, ejecutar `/plan`.
 

package/.agents/skills/gemstack-tasks/SKILL.md

@@ -12,7 +12,9 @@ Invocado mediante `/tasks`.
 ## Proceso:
 1. Lee `specs/[nombre-feature]/plan.md` y, si existen, `data-model.md` y la carpeta `contracts/`.
 2. Convierte los contratos, entidades y el plan en una lista estricta de ejecución en `specs/[nombre-feature]/tasks.md` usando la plantilla `specs/templates/tasks.md`.
-3. Aplica Test-First: Las tareas de escribir pruebas (y validarlas) deben ir ANTES que la implementación de código.
-4. Usa el marcador `[P]` para tareas independientes que se puedan paralelizar.
-5. Ofrece al usuario comenzar automáticamente con la primera tarea o delegar a subagentes paralelos si hay múltiples `[P]`.
+3. **Herencia de Contratos (Upgrade A)**: TASKS hereda automáticamente los contratos consolidados de SPEC y PLAN. No se requiere declarar un bloque de contratos propio salvo que se agreguen contratos operacionales específicos de tareas.
+4. **Trazabilidad TASK -> TEST (Upgrade B)**: Para cada tarea, incluye comentarios de metadatos `<!-- gemstack:validation_required=true|false -->`, `<!-- gemstack:tests=... -->`, y `<!-- gemstack:files=... -->`, asegurando que todas las pruebas canónicas requeridas estén mapeadas a al menos una tarea de implementación.
+5. Aplica Test-First: Las tareas de escribir pruebas (y validarlas) deben ir ANTES que la implementación de código.
+6. Usa el marcador `[P]` para tareas independientes que se puedan paralelizar.
+7. Ofrece al usuario comenzar automáticamente con la primera tarea o delegar a subagentes paralelos si hay múltiples `[P]`.
 

package/.gemstack/state.json

@@ -1,11 +1,27 @@
 {
   "version": "0.1",
-  "current_phase": "idle",
+  "current_phase": "shipped",
+  "status": "SHIPPED",
+  "stop_reason": "UPGRADE_B_SHIPPED_DONE",
   "active_spec": null,
+  "completed_phases": [
+    "spec",
+    "plan"
+  ],
+  "phase_hashes": {
+    "spec": "75f7b5aee9a7d45836128f619ba67d0870c9be3a2634d9152b01c6501faa513d",
+    "plan": "c77a3b1410d3b3028b72d66db524c6a23b0998dce12dddaee2507b4e446aec3b",
+    "tasks": "69ea9ae8557a41f98102c7b91905f74b3645ea59cbe301a54425216d5789b1d8"
+  },
+  "consistency": {
+    "status": "PASS",
+    "open_blockers": 0
+  },
   "guard_mode": {
     "careful": false,
     "freeze": false,
     "allowed_paths": []
   },
-  "last_update": "2026-08-30T11:10:00Z"
+  "last_update": "2026-09-11T16:49:53.470Z",
+  "last_completed_feature": "specs/007-mechanical-test-matrix-closure-evidence/"
 }

package/CHANGELOG.md

@@ -2,6 +2,90 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.2.0] - 2026-09-11
+### Added
+- **Mechanical Test Matrix & Closure Evidence (Upgrade B)**: Full mechanical closure verification framework eliminating false closure and test discovery hallucinations.
+- Canonical fenced `gemstack-test-matrix` blocks in `spec.md` with 20 canonical acceptance test criteria (`TEST-CLOSURE-A01` through `H01`).
+- Deterministic Acceptance Signature (`acceptanceSignature`): SHA-256 digest calculated across all canonical test definitions ensuring immutable acceptance criteria.
+- Bidirectional Task <-> Test Traceability: strict mapping between `tasks.md` validation blocks and canonical acceptance tests.
+- Zero-Shell Test Runner Adapters: safe, cross-platform `node:test` TAP runner adapter with suite container detection (`kind: 'SUITE'` vs `kind: 'TEST'`).
+- Exact Canonical Reconciliation Arithmetic: verifies `canonical_required = canonical_passed + missing`, `physical_executed = canonical_executed + supporting_executed`, and prevents phantoms and orphans.
+- Mutating Evidence Collector (`gemstack collect`): executes bound test files and required `PACKAGE_SCRIPT` gates to produce `specs/<feature>/closure.json`.
+- Dynamic Closure Context Freshness (`closureContextHash`): binds closure evidence to the repository state (clean/dirty git or non-git), phase hashes, test files, and bounded implementation code.
+- Read-Only Closure Gate in `gemstack verify`: stage 5/6 verifies `closure.json` freshness and acceptance criteria without writing or mutating any files on disk.
+- Lifecycle Ship Enforcement (`gemstack ship`): requires status `VERIFIED` in `closure.json` before transitioning feature lifecycle to `SHIPPED`.
+- Progressive `LEGACY` mode support: features lacking test matrix blocks continue without friction or errors.
+
+### Changed
+- `gemstack verify` upgraded to a 6-stage deterministic verification pipeline with zero-mutation read-only verification.
+- `package.json` test script explicitly enumerates all 11 physical test suites for portable cross-platform execution.
+- Agent skills (`gemstack-spec`, `gemstack-plan`, `gemstack-tasks`, `gemstack-qa`, `gemstack-ship`) and templates updated with Upgrade B canonical workflows.
+
+### Compatibility
+- 100% backward compatible with existing Gemstack repositories and Upgrade A contract blocks.
+- Zero external runtime or development npm dependencies added (`package.json` dependencies remain `{}`).
+
+### Validation
+- 22/22 Upgrade B implementation tasks complete (T001–T022).
+- 20/20 canonical P1 acceptance tests passing.
+- 45/45 combined canonical acceptance tests passing (25 Upgrade A + 20 Upgrade B).
+- 53/53 physical tests passing with 0 regressions.
+- `npm test` exit code 0.
+- `gemstack verify` exit code 0 with 0 open blockers.
+- Self-dogfooded on `specs/007-mechanical-test-matrix-closure-evidence/` with closure status `VERIFIED`.
+
+## [v1.1.2] - 2026-09-11
+### Fixed
+- Fixed host-dependent normalization of simulated Windows paths in the Architecture Consistency Engine.
+- Canonical repository-relative locations now use explicit win32/posix path semantics based on input path flavor.
+- Restored TEST-CONSISTENCY-G01 on Linux CI without changing Upgrade A architecture or acceptance semantics.
+
+## [v1.1.1] - 2026-09-11
+### Fixed
+- Fixed cross-platform CI test discovery for Node's built-in test runner.
+- Replaced shell-dependent recursive glob invocation with deterministic explicit test-file execution (`node --test tests/contracts.test.js tests/hasher.test.js tests/findings.test.js tests/init.test.js tests/verify.test.js`).
+- No Upgrade A architecture or acceptance semantics changed.
+
+## [v1.1.0] - 2026-09-11
+### Added
+- `FrozenContractRegistry`: deterministic architectural contract engine supporting 6 canonical types (`ENUM_SET`, `IDENTITY_TUPLE`, `PROVENANCE_RULE`, `BOOLEAN_INVARIANT`, `BOUNDARY`, `ROADMAP_LIMIT`).
+- Canonical fenced `gemstack-contracts` blocks in phase artifacts (`spec.md`, `plan.md`, `tasks.md`).
+- Cross-phase contract inheritance (`SPEC` -> `PLAN` -> `TASKS`) and deterministic contradiction detection (`FROZEN_CONTRACT_VIOLATION`).
+- Phase artifact SHA-256 freezing and mutation detection (`FROZEN_ARTIFACT_CHANGED`).
+- Canonical 64-character lowercase SHA-256 finding fingerprints with 12-character cosmetic display tokens.
+- Anti-loop finding lifecycle reconciliation (`OPEN`, `RESOLVED`, `ACCEPTED_EXCEPTION`, `SUPERSEDED`).
+- Formal accepted exception suppression bound to deterministic 3-tuple `contextHash`.
+- Per-feature `.gemstack.json` historical metadata sidecar preserving phase hash and finding audit trails.
+- Atomic state and sidecar persistence with temporary file write and atomic rename with bounded retry for cross-platform file locking.
+- Progressive `LEGACY` mode ensuring features without contract blocks continue without friction or errors.
+- Integrated Stage 4/5 Architectural Consistency verification into `gemstack verify` (alias `audit`).
+
+### Changed
+- `gemstack verify` upgraded from 4-stage to 5-stage deterministic verification pipeline.
+- Agent skills (`gemstack-spec`, `gemstack-plan`, `gemstack-tasks`, `gemstack-review`) and phase templates updated to generate and validate frozen architectural contracts.
+- Gemstack Constitution strengthened to forbid silent downstream contradictions of frozen contracts.
+
+### Compatibility
+- Existing projects without `gemstack-contracts` blocks remain 100% supported through progressive LEGACY mode.
+- No mandatory migration is required.
+- Zero external runtime or development npm dependencies added (`package.json` dependencies remain `{}`).
+
+### Validation
+- 17 / 17 Upgrade A implementation tasks complete.
+- 25 / 25 canonical P1 acceptance tests passing (Categories A–H).
+- 33 / 33 physical test cases passing across 5 test suites.
+- `npm test` exit code 0.
+- `gemstack verify` exit code 0 with 0 open blockers.
+- Self-dogfooded on `specs/006-architecture-consistency-engine/` with 5 base contracts passing and 0 contradictions.
+
+## [v1.0.2] - 2026-09-03
+### Added
+- Intent-Based Routing in `01-gemstack-core.md`: semantic intent detection for natural language interactions without mandatory slash prefixes.
+- Zero Silent Failures clause in Article III of `02-gemstack-constitution.md`: bans `2>nul` and error-suppressing shell operators in test runners.
+- `gemstack verify` (alias `audit`): full-stack CLI auditor validating structure, memory integrity, state consistency, and security flags.
+- Auto State Sync across `gemstack-spec`, `gemstack-ship`, and `gemstack-handoff` keeping `.gemstack/state.json` synchronized with the active feature lifecycle.
+- Unit tests for verify command in `tests/verify.test.js`.
+
 ## [v0.3.0] - 2026-08-19
 ### Added
 - GitHub Actions CI/CD workflows (`pr-ci.yml`, `main-ci.yml`, `release-readiness.yml`).

package/MANUAL.md

@@ -20,7 +20,7 @@ Es una herramienta de cero dependencias (funciona en cualquier lenguaje y comput
 No necesitas instalar librerías pesadas. En cualquier proyecto (sea nuevo o uno que ya lleve meses de desarrollo), abre tu terminal y ejecuta:
 
 ```bash
-npx gemstack init
+npx gemstack-ai init
 ```
 
 **¿Qué hace esto?**
@@ -60,7 +60,7 @@ Gemstack viene con funcionalidades avanzadas (Skills) que puedes invocar como co
 Dile a la IA: *"Ejecuta `/cso`"*. El Chief Security Officer auditará tu código. Gemstack tiene leyes estrictas implantadas en su núcleo (AppSec Nivel 2 y DevOps). Si tienes una contraseña expuesta, o tu base de datos es vulnerable a un ataque de fuerza bruta, el agente detendrá todo y te obligará a parcharlo.
 
 ### 🪝 Prevención Activa (Git Hooks)
-Gemstack se asegura de que tú, como humano, tampoco cometas errores. Al hacer `npx gemstack init`, se instala un guardián invisible. Si intentas hacer un `git commit` y por error incluiste una llave de Amazon Web Services (AWS) o un archivo `.env`, Gemstack bloqueará el commit en tu terminal y te regañará.
+Gemstack se asegura de que tú, como humano, tampoco cometas errores. Al hacer `npx gemstack-ai init`, se instala un guardián invisible. Si intentas hacer un `git commit` y por error incluiste una llave de Amazon Web Services (AWS) o un archivo `.env`, Gemstack bloqueará el commit en tu terminal y te regañará.
 
 ### 📊 Dashboard Interactivo (`/dashboard`)
 ¿Perdido en el código? Dile a tu chat de IA (si usas Antigravity):
@@ -71,11 +71,11 @@ La IA leerá tu lista de tareas y generará una interfaz gráfica incrustada en
 ### 🔌 Instalación de Skills Externos
 Gemstack es extensible. Si alguien en internet creó un súper agente especialista en Python, puedes descargarlo a tu proyecto directamente desde la terminal:
 ```bash
-npx gemstack install https://raw.githubusercontent.com/usuario/repo/main/SKILL.md
+npx gemstack-ai install https://raw.githubusercontent.com/usuario/repo/main/SKILL.md
 ```
 
 ### 🤖 Servidor MCP (Para IAs Externas)
-Si usas Claude Desktop u otro cliente que soporte **Model Context Protocol (MCP)**, puedes configurar Gemstack como una de sus herramientas nativas. Simplemente configura el servidor ejecutando en tu cliente: `npx gemstack mcp`. La IA podrá "llamar" a Gemstack directamente por debajo de la mesa para preguntarle cuáles son tus tareas actuales y reglas de seguridad sin que tengas que decirle nada.
+Si usas Claude Desktop u otro cliente que soporte **Model Context Protocol (MCP)**, puedes configurar Gemstack como una de sus herramientas nativas. Simplemente configura el servidor ejecutando en tu cliente: `npx gemstack-ai mcp`. La IA podrá "llamar" a Gemstack directamente por debajo de la mesa para preguntarle cuáles son tus tareas actuales y reglas de seguridad sin que tengas que decirle nada.
 
 ---
 

package/README.md

@@ -1,9 +1,9 @@
 <div align="center">
-  <img src="https://via.placeholder.com/150x150/1a1a2e/ffffff?text=GS" alt="Gemstack Logo" width="120" height="120" />
+  <img src="assets/logo.jpg" alt="Gemstack Logo" width="200" style="border-radius: 20px" />
   <h1>Gemstack</h1>
   <p><b>The Local-First Agentic Framework for Spec-Driven Development</b></p>
 
-  [![npm version](https://img.shields.io/npm/v/gemstack.svg?style=flat-square)](https://www.npmjs.com/package/gemstack)
+  [![npm version](https://img.shields.io/npm/v/gemstack-ai.svg?style=flat-square)](https://www.npmjs.com/package/gemstack-ai)
   [![CI Build](https://img.shields.io/github/actions/workflow/status/rtorrescodes/Gemstack/main-ci.yml?style=flat-square&branch=main)](https://github.com/rtorrescodes/Gemstack/actions)
   [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
   [![Security Shield](https://img.shields.io/badge/Security-Military--Grade-red.svg?style=flat-square)](#military-grade-security-shield)
@@ -33,19 +33,19 @@ Start a new project or upgrade an existing one in seconds:
 
 ```bash
 # Initialize Gemstack in your current repository
-npx gemstack init
+npx gemstack-ai init
 ```
 
 This will generate the `.agents/`, `.gemstack/`, and `specs/` directories.
 
 To ensure your framework is healthy or to check for manual tampering:
 ```bash
-npx gemstack doctor
+npx gemstack-ai doctor
 ```
 
 To update your project when Gemstack releases new Agent Skills:
 ```bash
-npx gemstack update
+npx gemstack-ai update
 ```
 
 ## 🧠 How it Works
@@ -68,6 +68,46 @@ Gemstack ships with `03-gemstack-security.md` and `04-gemstack-infrastructure.md
 - **DevSecOps & Infra**: Enforces Immutable Infrastructure (Docker/Terraform), Private Subnets (VPC), IAM Least Privilege, and Cloud Secret Managers.
 - **Server-Side Validation**: Complete distrust of frontend state.
 
+## 🔒 Architecture Consistency & Phase Freezing
+
+Gemstack mechanically prevents AI agents from silently violating or hallucinating deviations from approved architecture. Critical decisions declared in `spec.md` are frozen using canonical cryptographic contracts and checked deterministically through `plan.md`, `tasks.md`, and implementation:
+
+```gemstack-contracts
+[
+  {
+    "id": "zero-dependency-core",
+    "type": "BOOLEAN_INVARIANT",
+    "value": true
+  },
+  {
+    "id": "external-sync",
+    "type": "BOUNDARY",
+    "value": "FORBIDDEN"
+  }
+]
+```
+
+- **SPEC** owns base architectural contracts.
+- **PLAN** inherits them and may add compatible technical contracts.
+- **TASKS** inherits the consolidated registry.
+- Contradictions become deterministic blockers (`FROZEN_CONTRACT_VIOLATION`).
+- Phase artifacts are frozen via canonical SHA-256 digests; tampering is caught immediately (`FROZEN_ARTIFACT_CHANGED`).
+- `gemstack verify` performs strictly read-only verification without mutating or overwriting accepted phase hashes (`VERIFY != FREEZE`).
+- Existing projects without structured contracts automatically run in **LEGACY** mode without breaking.
+
+
+## 🧪 Mechanical Test Matrix & Closure Evidence
+
+Gemstack Upgrade B guarantees that what was planned is what was physically tested:
+- **Canonical Test Matrix**: `spec.md` declares canonical acceptance tests and cryptographic `acceptanceSignature`.
+- **Physical Test Bindings**: `plan.md` maps canonical IDs 1:1 to physical runner test files.
+- **Task Traceability**: `tasks.md` validates that all required canonical tests have implementation tasks.
+- **Safe Runner Adapters**: Direct zero-shell execution of test suites and package script gates.
+- **`gemstack collect`**: Mutating runner that executes tests and atomically writes `specs/<feature>/closure.json`.
+- **`gemstack verify`**: Strictly read-only 6-stage validator verifying evidence freshness against `closureContextHash`.
+- **`gemstack ship`**: Gatekeeper requiring verified evidence before allowing transition to `SHIPPED`.
+- **Git Optionality & Legacy Support**: Works identically on clean Git, dirty Git, and non-Git projects, with graceful legacy fallback.
+
 ## 🐝 Advanced Autonomy (The WOW Update)
 
 Gemstack isn't just passive documents; it actively orchestrates agentic capabilities:
@@ -82,7 +122,7 @@ Gemstack isn't just passive documents; it actively orchestrates agentic capabili
 
 ## 🪝 Active Security (Git Hooks)
 
-Gemstack ships with native, zero-dependency Git hooks. Run `npx gemstack hooks` (or just `npx gemstack init`) to install a local `pre-commit` hook that automatically blocks commits containing:
+Gemstack ships with native, zero-dependency Git hooks. Run `npx gemstack-ai hooks` (or just `npx gemstack-ai init`) to install a local `pre-commit` hook that automatically blocks commits containing:
 - Exposed `.env` files.
 - Hardcoded secrets (Stripe, AWS, JWT keys).
 - Unresolved merge conflict markers (`<<<<<<< HEAD`).
@@ -91,7 +131,7 @@ Gemstack ships with native, zero-dependency Git hooks. Run `npx gemstack hooks`
 
 You can install agent skills created by the community directly into your project using the `install` command. Gemstack will fetch the `SKILL.md`, parse its metadata, and integrate it into your AI's brain automatically:
 ```bash
-npx gemstack install https://raw.githubusercontent.com/community/gemstack-skills/main/django-expert/SKILL.md
+npx gemstack-ai install https://raw.githubusercontent.com/community/gemstack-skills/main/django-expert/SKILL.md
 ```
 
 ## 🤖 MCP Server (Model Context Protocol)
@@ -104,7 +144,7 @@ Add the following to your MCP client configuration:
   "mcpServers": {
     "gemstack": {
       "command": "npx",
-      "args": ["gemstack", "mcp"]
+      "args": ["gemstack-ai", "mcp"]
     }
   }
 }
@@ -115,6 +155,7 @@ Add the following to your MCP client configuration:
 Dive deeper into the Gemstack architecture:
 - [📖 **Manual de Usuario**](MANUAL.md) - The Definitive Guide for beginners.
 - [🧠 Spec-Driven Development](docs/spec-driven-development.md) - How the SDD loop works.
+- [🔒 Architecture Consistency](docs/architecture-consistency.md) - Deterministic contracts & phase freezing.
 - [Available Skills](docs/skills.md)
 - [Security Model](docs/security.md)
 - [Handoff Protocol](docs/handoff.md)

package/RELEASE_NOTES.md

@@ -1,5 +1,134 @@
 # Gemstack Release Notes
 
+# Gemstack v1.2.0 — Mechanical Test Matrix & Closure Evidence
+
+## Highlights
+- **Mechanical Test Matrix & Closure Verification (Upgrade B)**: Eliminates false closure and test discovery hallucinations by introducing a deterministic verification pipeline from specification to shipment.
+- **Canonical Test Matrix (`gemstack-test-matrix`)**: Explicit acceptance criteria defined in `spec.md` with deterministic `acceptanceSignature` (SHA-256) ensuring acceptance rules are immutable once approved.
+- **Task ↔ Test Traceability**: Explicit bidirectional binding between implementation tasks in `tasks.md` and canonical acceptance tests.
+- **Safe Zero-Shell Runners**: Pure Node.js `node:test` TAP runner adapter with suite container exclusion (`kind: 'SUITE'` vs `kind: 'TEST'`), ensuring TAP headers/containers are never counted as physical tests.
+- **Exact Canonical Reconciliation Arithmetic**: Mechanical validation proving `canonical_required = canonical_passed + missing` and `physical_executed = canonical_executed + supporting_executed` with zero tolerance for phantoms or orphans.
+- **Mutating Collector (`gemstack collect`)**: Executes bound test suites and required `PACKAGE_SCRIPT` gates to produce `specs/<feature>/closure.json`.
+- **Dynamic Closure Context Freshness (`closureContextHash`)**: Cryptographically binds closure evidence to repository state (clean git, dirty git, or non-git), phase hashes, bound test files, and bounded implementation source files.
+- **Read-Only Verification Pipeline (`gemstack verify`)**: Stage 5/6 inspects closure freshness and gate outcomes in memory with 0 disk mutations.
+- **Ship Gatekeeper (`gemstack ship`)**: Strict gate requiring `status: "VERIFIED"` in `closure.json` before transitioning feature lifecycle to `SHIPPED`.
+- **Progressive LEGACY Mode**: Full backward compatibility for features without test matrices or contract blocks.
+- **Zero-Dependency Architecture**: 100% native Node.js standard library implementation with zero third-party production dependencies.
+
+## Acceptance & Regression Baseline
+- 25 Upgrade A canonical acceptance tests passing (`TEST-CONSISTENCY-A01` through `H02`).
+- 20 Upgrade B canonical acceptance tests passing (`TEST-CLOSURE-A01` through `H01`).
+- 45 total canonical acceptance tests passing.
+- 53 total physical tests passing with 0 regressions.
+- 11 physical test suites explicitly enumerated for cross-platform reliability.
+
+---
+
+# Gemstack v1.1.2 — Architecture Consistency & Phase Freezing
+
+## Recovery Release Note
+v1.1.2 is the release-recovery patch for Upgrade A. v1.1.1 resolved cross-platform test discovery, exposing a host-dependent path canonicalization defect in `TEST-CONSISTENCY-G01` when simulating Windows paths on Linux runners. v1.1.2 fixes that canonicalization using explicit path-flavor-aware Node.js path semantics (`path.win32` vs `path.posix`). No product architecture, contract semantics, or canonical P1 criteria were altered.
+
+## Highlights
+- **Architecture Consistency Engine**: Mechanically prevents AI models from hallucinating or introducing silent architectural contradictions downstream through 6 canonical contract types (`ENUM_SET`, `IDENTITY_TUPLE`, `PROVENANCE_RULE`, `BOOLEAN_INVARIANT`, `BOUNDARY`, `ROADMAP_LIMIT`).
+- **Cryptographic Phase Freezing**: SHA-256 canonical hashing of phase artifacts (`spec.md`, `plan.md`, `tasks.md`) with automatic mutation detection (`FROZEN_ARTIFACT_CHANGED`).
+- **Deterministic-First Validation**: Automated cross-phase inheritance (`SPEC` -> `PLAN` -> `TASKS`) resolving contradictions before human review.
+- **Canonical Finding Fingerprints**: Full 64-character lowercase SHA-256 digests with anti-loop lifecycle management (`OPEN`, `RESOLVED`, `ACCEPTED_EXCEPTION`, `SUPERSEDED`).
+- **Accepted Exceptions Bound to Context**: Exceptions require cryptographic `contextHash` binding; any change to compared artifacts or contracts invalidates suppression.
+- **Progressive LEGACY Mode**: Features without contracts continue without disruption or breaking changes.
+- **Zero-Dependency Core**: Pure Node.js standard library implementation (`node:crypto`, `node:fs`, `node:path`, `node:test`).
+
+## Compatibility
+- 100% backward compatible with existing Gemstack repositories.
+- Zero external runtime dependencies added.
+
+## Validation
+- 17/17 Upgrade A implementation tasks complete.
+- 25/25 canonical P1 acceptance tests passing.
+- 33/33 physical test suite passing.
+- `npm test` exit code 0.
+- `gemstack verify` exit code 0 with 0 open blockers.
+- Self-dogfooded on `specs/006-architecture-consistency-engine/`.
+
+## Upgrade Notes
+- Run `npx gemstack-ai update` to pull the latest agent skills and templates into your existing project.
+
+---
+
+# Gemstack v1.1.1 — Architecture Consistency & Phase Freezing
+
+## Recovery Release Note
+v1.1.1 is the publishable recovery release for Upgrade A. The original v1.1.0 tag completed development and closure, but its release CI workflow stopped prior to npm publication because the test command relied on shell-dependent recursive glob resolution on Linux runners. In v1.1.1, test execution is made strictly portable across all operating systems. No product architecture or contract semantics changed.
+
+## Highlights
+- **Architecture Consistency Engine**: Mechanically prevents AI models from hallucinating or introducing silent architectural contradictions downstream through 6 canonical contract types (`ENUM_SET`, `IDENTITY_TUPLE`, `PROVENANCE_RULE`, `BOOLEAN_INVARIANT`, `BOUNDARY`, `ROADMAP_LIMIT`).
+- **Cryptographic Phase Freezing**: SHA-256 canonical hashing of phase artifacts (`spec.md`, `plan.md`, `tasks.md`) with automatic mutation detection (`FROZEN_ARTIFACT_CHANGED`).
+- **Deterministic-First Validation**: Automated cross-phase inheritance (`SPEC` -> `PLAN` -> `TASKS`) resolving contradictions before human review.
+- **Canonical Finding Fingerprints**: Full 64-character lowercase SHA-256 digests with anti-loop lifecycle management (`OPEN`, `RESOLVED`, `ACCEPTED_EXCEPTION`, `SUPERSEDED`).
+- **Accepted Exceptions Bound to Context**: Exceptions require cryptographic `contextHash` binding; any change to compared artifacts or contracts invalidates suppression.
+- **Progressive LEGACY Mode**: Features without contracts continue without disruption or breaking changes.
+- **Zero-Dependency Core**: Pure Node.js standard library implementation (`node:crypto`, `node:fs`, `node:path`, `node:test`).
+
+## Compatibility
+- 100% backward compatible with existing Gemstack repositories.
+- Zero external runtime dependencies added.
+
+## Validation
+- 17/17 Upgrade A implementation tasks complete.
+- 25/25 canonical P1 acceptance tests passing.
+- 33/33 physical test suite passing.
+- `npm test` exit code 0.
+- `gemstack verify` exit code 0 with 0 open blockers.
+- Self-dogfooded on `specs/006-architecture-consistency-engine/`.
+
+## Upgrade Notes
+- Run `npx gemstack-ai update` to pull the latest agent skills and templates into your existing project.
+
+---
+
+# Gemstack v1.1.0 — Architecture Consistency & Phase Freezing
+
+## Highlights
+- **Architecture Consistency Engine**: Mechanically prevents AI models from hallucinating or introducing silent architectural contradictions downstream through 6 canonical contract types (`ENUM_SET`, `IDENTITY_TUPLE`, `PROVENANCE_RULE`, `BOOLEAN_INVARIANT`, `BOUNDARY`, `ROADMAP_LIMIT`).
+- **Cryptographic Phase Freezing**: SHA-256 canonical hashing of phase artifacts (`spec.md`, `plan.md`, `tasks.md`) with automatic mutation detection (`FROZEN_ARTIFACT_CHANGED`).
+- **Deterministic-First Validation**: Automated cross-phase inheritance (`SPEC` -> `PLAN` -> `TASKS`) resolving contradictions before human review.
+- **Canonical Finding Fingerprints**: Full 64-character lowercase SHA-256 digests with anti-loop lifecycle management (`OPEN`, `RESOLVED`, `ACCEPTED_EXCEPTION`, `SUPERSEDED`).
+- **Accepted Exceptions Bound to Context**: Exceptions require cryptographic `contextHash` binding; any change to compared artifacts or contracts invalidates suppression.
+- **Progressive LEGACY Mode**: Features without contracts continue without disruption or breaking changes.
+- **Zero-Dependency Core**: Pure Node.js standard library implementation (`node:crypto`, `node:fs`, `node:path`, `node:test`).
+
+## Compatibility
+- 100% backward compatible with existing Gemstack repositories.
+- Zero external runtime dependencies added.
+
+## Validation
+- 17/17 Upgrade A implementation tasks complete.
+- 25/25 canonical P1 acceptance tests passing.
+- 33/33 physical test suite passing.
+- `npm test` exit code 0.
+- `gemstack verify` exit code 0 with 0 open blockers.
+- Self-dogfooded on `specs/006-architecture-consistency-engine/`.
+
+## Upgrade Notes
+- Run `npx gemstack-ai update` to pull the latest agent skills and templates into your existing project.
+
+---
+
+# Gemstack v1.0.2
+
+## Highlights
+- **Zero Silent Failures**: Actualización al Article III de la Constitución prohibiendo `2>nul` y operadores de supresión de fallos en scripts de testing multiplataforma.
+- **Intent-Based Routing**: Detección semántica de intenciones en lenguaje natural en `01-gemstack-core.md`, auto-activando `gemstack-spec`, `gemstack-qa`, `gemstack-investigate` y `gemstack-handoff` sin requerir estrictamente `/comando`.
+- **Auto State Sync**: Sincronización automática de `.gemstack/state.json` en `gemstack-spec`, `gemstack-ship` y `gemstack-handoff` con control de ciclo de vida (`current_phase`, `active_spec`, `last_completed_feature`).
+- **Unified Health & Security Auditor (`gemstack verify`)**: Nuevo comando CLI y script `pnpm/npm run gemstack:verify` para validar en un solo paso archivos base, integridad de memoria (5 secciones de `handoff.md`), estado local y seguridad de scripts.
+
+## Validation
+- `npm test`: 8 tests unitarios pasando al 100%.
+- `npm run gemstack:verify`: Éxito total.
+- CI Scripts: frontmatter, template clean, mojibake, package contents y smoke CLI validados.
+
+---
+
 # Gemstack v0.3.0
 
 ## Highlights