gemstack-ai 1.0.1 → 1.1.2

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,6 @@ 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. Pide aprobación al usuario antes de permitir la ejecución de `/tasks`.
 

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

@@ -16,4 +16,9 @@ Invocado mediante `/ship`.
 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,7 @@ 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. Actualiza el archivo `.gemstack/state.json` para reflejar la rama activa y fase: `{"active_spec": "specs/[nombre-feature]/", "current_phase": "spec", "last_update": "<timestamp>"}`.
+9. 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,8 @@ 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. Aplica Test-First: Las tareas de escribir pruebas (y validarlas) deben ir ANTES que la implementación de código.
+5. Usa el marcador `[P]` para tareas independientes que se puedan paralelizar.
+6. 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,29 @@
 {
   "version": "0.1",
-  "current_phase": "idle",
+  "current_phase": "shipped",
+  "status": "SHIPPED",
+  "stop_reason": "UPGRADE_A_SHIPPED_DONE",
   "active_spec": null,
+  "completed_phases": [
+    "spec",
+    "plan",
+    "tasks",
+    "implement"
+  ],
+  "phase_hashes": {
+    "spec": "f5d423eaf508b06b663b39f467fba1d9ceff6db21f01e427500ad739a90c5be8",
+    "plan": "1ce0e58863427905022a6294f8683b9f508d72b171379c78807db19862c75004",
+    "tasks": "dfad2484ad112e26ef906ea851b12cf6ea090d6faf244a6fbd2650baee8e0d98"
+  },
+  "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-11T09:01:18.769Z",
+  "last_completed_feature": "specs/006-architecture-consistency-engine/"
 }

package/CHANGELOG.md

@@ -2,6 +2,58 @@
 
 All notable changes to this project will be documented in this file.
 
+## [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,33 @@ 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.
+
 ## 🐝 Advanced Autonomy (The WOW Update)
 
 Gemstack isn't just passive documents; it actively orchestrates agentic capabilities:
@@ -82,7 +109,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 +118,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 +131,7 @@ Add the following to your MCP client configuration:
   "mcpServers": {
     "gemstack": {
       "command": "npx",
-      "args": ["gemstack", "mcp"]
+      "args": ["gemstack-ai", "mcp"]
     }
   }
 }
@@ -115,6 +142,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,110 @@
 # Gemstack Release Notes
 
+# 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

package/docs/architecture-consistency.md

@@ -0,0 +1,144 @@
+# Architecture Consistency & Phase Freezing
+
+Gemstack includes a native, deterministic **Architecture Consistency Engine** and **Phase Freezing** protocol. It prevents AI agents from silently introducing contradictions, architectural drift, or unauthorized mutations across the Spec-Driven Development lifecycle.
+
+---
+
+## 1. The Architecture Consistency Problem
+
+In complex AI coding projects, language models often agree to constraints in a specification (such as "zero external dependencies" or "single tenant isolation"), but later quietly contradict them in implementation or tasks (e.g. installing unauthorized packages). 
+
+Gemstack solves this mechanically at the framework layer:
+1. Architectural decisions are declared as formal, machine-verifiable **contracts**.
+2. Upstream phases (`SPEC`, `PLAN`, `TASKS`) are cryptographically **frozen**.
+3. Downstream phases inherit contracts and are mechanically compared for contradictions.
+4. Any contradiction or mutation immediately halts execution as a deterministic blocker.
+
+---
+
+## 2. Canonical Contract Block Format
+
+Contracts are declared inside phase markdown files (`spec.md`, `plan.md`, `tasks.md`) within a column-0 fenced code block:
+
+```gemstack-contracts
+[
+  {
+    "id": "zero-dependency-core",
+    "type": "BOOLEAN_INVARIANT",
+    "value": true
+  },
+  {
+    "id": "database-engine",
+    "type": "ENUM_SET",
+    "values": ["sqlite", "postgres"]
+  },
+  {
+    "id": "external-sync",
+    "type": "BOUNDARY",
+    "value": "FORBIDDEN"
+  }
+]
+```
+
+### Block Parsing Rules
+- **Exactly One Block**: Each phase document may contain at most one `gemstack-contracts` block. Multiple blocks trigger a `CONTRACT_PARSE_ERROR`.
+- **Legacy Mode**: Phase documents with 0 contract blocks operate in **LEGACY** mode without errors or blocking.
+- **Strict Encoding**: UTF-8 without BOM is required; CRLF and LF line endings are canonically normalized to LF.
+
+---
+
+## 3. The Six Canonical Contract Types
+
+Gemstack enforces six deterministic contract types:
+
+| Contract Type | Value Shape | Description / Evaluation |
+|---|---|---|
+| `ENUM_SET` | `values: string[]` | Closed set of allowed identifiers. Order-insensitive. Downstream cannot add unapproved values. |
+| `IDENTITY_TUPLE` | `tuple: string[]` | Immutable composite tuple. Order-insensitive, duplicate-sensitive, exact-member matching. |
+| `PROVENANCE_RULE` | `source: string, rule: string` | Origin and lineage constraints. Downstream cannot omit or alter provenance. |
+| `BOOLEAN_INVARIANT` | `value: boolean` | Strict binary invariant (e.g. `true` for zero-dependency). Downstream contradiction is blocked. |
+| `BOUNDARY` | `value: "FORBIDDEN" | "REQUIRED"` | Hard system boundary. Only `FORBIDDEN` and `REQUIRED` are valid. |
+| `ROADMAP_LIMIT` | `value: string | number` | Milestone or scope bound (e.g. max task count). Downstream cannot expand beyond the limit. |
+
+---
+
+## 4. Cross-Phase Contract Inheritance
+
+Contracts follow a strict unidirectional inheritance hierarchy:
+
+```
+SPEC (declares base contracts)
+  │
+  ▼
+PLAN (inherits SPEC contracts + may add technical contracts)
+  │
+  ▼
+TASKS (inherits consolidated SPEC + PLAN contracts)
+```
+
+- **Inheritance**: Downstream phases automatically inherit all upstream contracts. An inherited contract does not need to be re-declared downstream unless adding specific attributes.
+- **Equivalence**: Redeclaring an inherited contract with identical semantics passes validation.
+- **Contradiction**: Redeclaring an inherited contract with contradictory values triggers `FROZEN_CONTRACT_VIOLATION` and blocks execution.
+- **Additive Extension**: Downstream phases may introduce new contract IDs as long as they do not conflict with existing contracts.
+
+---
+
+## 5. Phase Freezing & Mutation Detection
+
+When a phase is completed and approved by the human supervisor, its artifact is cryptographically sealed:
+- **Canonical Hash**: Normalized SHA-256 (64 lowercase hexadecimal characters).
+- **CRLF Normalization**: All line breaks are normalized to LF (`\n`) prior to hashing, ensuring identical digests across Windows, macOS, and Linux.
+- **UTF-8 BOM Forbidden**: Leading Byte Order Marks trigger `CONTRACT_PARSE_ERROR`.
+- **Mutation Detection**: If an upstream artifact (`spec.md` or `plan.md`) is modified after approval, `gemstack verify` detects the hash mismatch and halts with `FROZEN_ARTIFACT_CHANGED`.
+
+> **VERIFY != FREEZE**: `gemstack verify`, `gemstack doctor`, and agent reviews are strictly read-only and **never** overwrite or mutate accepted phase hashes.
+
+---
+
+## 6. Findings & Anti-Loop Lifecycle
+
+When a consistency rule is violated, Gemstack generates a structured **Finding**:
+- **Canonical Fingerprint**: Full 64-character lowercase SHA-256 digest computed over `{ code, contractId, phase, location }`.
+- **Display Token**: First 12 characters of the fingerprint for human-readable CLI display.
+- **Finding Lifecycle**:
+  - `OPEN`: Active blocker preventing shipping.
+  - `RESOLVED`: Violation was corrected in artifacts.
+  - `ACCEPTED_EXCEPTION`: Formally approved human exception.
+  - `SUPERSEDED`: Replaced by a subsequent finding.
+- **Anti-Loop Protection**: If a previously `RESOLVED` defect re-appears in subsequent runs, it is immediately re-opened to `OPEN`.
+
+---
+
+## 7. Accepted Exceptions & Context Hash
+
+When an architectural deviation is intentionally approved by a human supervisor, it is recorded in the feature sidecar with a cryptographic `contextHash`:
+
+`contextHash = SHA-256(upstreamAcceptedHash + currentComparedHash + normalizedContract)`
+
+If the upstream phase artifact, compared phase artifact, or contract representation changes, the suppression is automatically invalidated and the violation re-opens as a blocking finding.
+
+---
+
+## 8. State & Persistence Boundary
+
+Gemstack strictly separates operational state from historical audit trails:
+- **`.gemstack/state.json`**: Lightweight operational state only (active feature, completed phases, guard mode, verification summary). Historical finding arrays are forbidden in this file.
+- **`specs/<feature>/.gemstack.json`**: Per-feature sidecar hosting the complete audit log, phase hash history, finding fingerprints, and accepted exceptions.
+- **Atomic Operations**: All state writes use temporary file creation and atomic file renaming to prevent corruption during unexpected shutdowns or process kills.
+
+---
+
+## 9. Verification Integration (`gemstack verify`)
+
+Architectural consistency is embedded as **Step 4/5** in the unified `gemstack verify` command:
+
+```text
+[INFO] --- 4/5 Verificación de Consistencia de Arquitectura y Hashes de Fase ---
+[OK] [STRUCTURED] 5 contrato(s) base declarados en spec.md.
+[OK] Hash congelado de spec.md verificado: f5d423eaf508...
+[OK] Hash congelado de plan.md verificado: 1ce0e5886342...
+[OK] Hash congelado de tasks.md verificado: dfad2484ad11...
+[OK] Verificación de consistencia arquitectónica aprobada (0 bloqueadores).
+```
+
+If any contracts contradict, artifacts mutate, or unapproved blockers exist, `gemstack verify` exits with code 1, halting CI/CD pipelines.