gemstack-ai 1.0.1 → 1.2.0

package/docs/architecture-consistency.md

@@ -0,0 +1,156 @@
+# 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/6** in the unified `gemstack verify` command:
+
+```text
+[INFO] --- 4/6 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.
+
+---
+
+## 10. Mechanical Test Matrix & Closure Evidence (Upgrade B)
+
+Beyond static contract consistency across phase files, Gemstack Upgrade B validates execution evidence against declared requirements:
+
+- **`acceptanceSignature`**: Full semantic record SHA-256 digest of the canonical test matrix in `spec.md`.
+- **Authoritative Execution**: Native test runners (such as `node:test`) execute bound tests without shell intermediaries. TAP output is parsed to extract executed canonical test tokens.
+- **Reconciliation & Set Equality**: Proves that all declared required canonical tests were physically executed and passed (`PASS + FAIL + SKIP + TODO + CANCELLED == TOTAL_PHYSICAL`). Detects `PHANTOM_TEST` (claimed but unexecuted) and `ORPHAN_TEST` (executed with unregistered canonical ID).
+- **`closureContextHash`**: Deterministic SHA-256 fingerprint binding repository state, phase hashes, test files, implementation files, and gate definitions. Prevents whole-repository scanning while detecting stale evidence.
+- **Progressive Legacy Compatibility**: Specifications lacking a test matrix operate seamlessly in legacy mode with an informational notice, preserving 100% backward compatibility.

package/docs/spec-driven-development.md

@@ -8,3 +8,29 @@ Inspirado en Spec Kit, Gemstack obliga a pensar antes de teclear.
 
 Usa `/specify` para comenzar este ciclo.
 Una vez que el spec esté aprobado por el usuario, usa `/plan` y luego `/tasks`.
+
+
+---
+
+## Mechanical Test Matrix & Closure Evidence (Upgrade B)
+
+Gemstack complements Architecture Consistency with mechanical closure verification:
+
+1. **Test Matrix in Spec (`spec.md`)**:
+   Declared in a ```gemstack-test-matrix``` block. Defines canonical acceptance tests with unique IDs (`TEST-[FEATURE]-[CAT][NUM]`), verification layers (`UNIT`, `INTEGRATION`, `E2E`, `CLI`), and enforcement gates (`REQUIRED`, `SUPPLEMENTAL`). Produces an immutable `acceptanceSignature`.
+
+2. **Physical Test Bindings in Plan (`plan.md`)**:
+   Declared in ```gemstack-test-bindings``` block mapping each canonical test ID 1:1 to a physical runner file (e.g. `tests/example.test.js` with runner `node:test`).
+   Also declares mandatory package script gates in ```gemstack-closure-gates```.
+
+3. **Task Traceability in Tasks (`tasks.md`)**:
+   Implementation tasks declare metadata:
+   `<!-- gemstack:validation_required=true|false -->`
+   `<!-- gemstack:tests=TEST-001,TEST-002 -->`
+   `<!-- gemstack:files=src/module.js,tests/module.test.js -->`
+   Ensures that every required canonical test is bound to at least one implementation task.
+
+4. **Lifecycle: COLLECT vs VERIFY vs SHIP**:
+   - `gemstack collect`: Mutating evidence collector. Executes test runners, evaluates package script gates, reconciles counts, computes `closureContextHash`, and generates feature-local `closure.json`.
+   - `gemstack verify`: Strictly read-only validator (6 stages). Evaluates existing `closure.json` against in-memory fresh `closureContextHash`. Never writes to disk.
+   - `gemstack ship`: Lifecycle gatekeeper. Enforces that `closure.json` is fresh and marked `VERIFIED` (or policy-waived `VERIFIED_WITH_EXCEPTIONS`) before transitioning state to `SHIPPED`.

package/handoff.md

@@ -1,45 +1,45 @@
-# Gemstack Handoff (v1.0.0)
+# Gemstack Handoff
 
-## Resumen del Proyecto
-Gemstack es un "Sistema Operativo para IA" de cero dependencias (Zero-Dependency) que inyecta reglas militares de ciberseguridad, autonomía y flujos de Spec-Driven Development en cualquier repositorio local, permitiendo a los desarrolladores pair-programar de forma estructurada con inteligencias artificiales como Antigravity o Cursor.
+## 1. Objetivo
+Evolucionar Gemstack incorporando el feedback de producción real de proyectos activos:
+1. Eliminar falsos positivos silenciosos en test runners en Windows/monorepos (Zero Silent Failures).
+2. Ruteo semántico por intención (Intent-Based Routing) para interacción natural sin requerir `/comando`.
+3. Sincronización automática del ciclo de vida en `.gemstack/state.json` al entregar (`/ship`) o documentar (`/handoff`).
+4. Comando unificado `gemstack verify` (alias `audit`) para auditoría integral en un solo paso.
 
-## Estado Actual
-El proyecto ha alcanzado oficialmente la **Versión 1.0.0 (Open-Source Ready)**.
-Durante el último sprint se añadieron las capacidades clave para transformar a Gemstack de un simple manejador de prompts en un verdadero ecosistema agentico:
+## 2. Estado actual
+- **Upgrade A (Consistency Core & Phase Freezing)**: CERRADO Y PUBLICADO OFICIALMENTE como `gemstack-ai@1.1.2` en npm y GitHub Release.
+- **Upgrade B (Mechanical Test Matrix & Closure Evidence)**: CERRADO Y PREPARADO PARA RELEASE como `gemstack-ai@1.2.0`.
+  - 20/20 pruebas canónicas P1 de Upgrade B pasando al 100% en 6 nuevas suites.
+  - 25/25 pruebas canónicas P1 de Upgrade A preservadas con 0 regresiones.
+  - 53/53 pruebas físicas totales ejecutadas y pasando con 0 errores en CI/CD local (`npm test`, `npm run ci:all`).
+  - Comando mutador `gemstack collect` implementado y probado en Feature 007, generando `closure.json` atómicamente.
+  - Comando `gemstack verify` ampliado a 6 etapas estrictamente read-only con validación de frescura contra `closureContextHash`.
+  - Compuerta de cierre `gemstack ship` ejecutada exitosamente con estado `VERIFIED` y transición de ciclo de vida formal.
+  - Zero dependencias externas añadidas en producción.
+  - Excluidos completamente Upgrade C y Upgrade D.
 
-1. **Military-Grade DevSecOps (Rules 03 & 04):**
-   - Actualización a AppSec Nivel 2 (Mitigación de Race Conditions, CSRF, SSRF, Rate Limiting).
-   - Nueva regla de Infraestructura (`04-gemstack-infrastructure.md`) exigiendo contenedores, VPCs y gestores de secretos cloud.
-2. **Git Hooks (Active Security):**
-   - Comando `npx gemstack hooks` implementado en `src/commands/hooks.js`. 
-   - Previene localmente (antes del commit) la subida de `.env`, llaves hardcodeadas, y marcadores de conflicto de git.
-3. **Ecosistema de Plugins y Skills:**
-   - Comando `npx gemstack install <url>` inyectado en `src/commands/install.js` usando `fetch` nativo de Node 18+. Permite descargar skills de la comunidad directamente a `.agents/skills/`.
-4. **Dashboard de Generative UI:**
-   - Skill `gemstack-dashboard` (`/dashboard`) creado para leer el estado del proyecto y renderizar un widget HTML interactivo con el progreso de `tasks.md`.
-5. **Servidor Nativo MCP (Model Context Protocol):**
-   - Implementado en `src/mcp-server.js`. Gemstack ahora actúa como un servidor MCP accesible vía `npx gemstack mcp`, exponiendo el SDD del proyecto a clientes IA externos mediante JSON-RPC sobre stdio.
-6. **Package Version:**
-   - El archivo `package.json` fue ascendido a `v1.0.0`.
+## 3. Archivos y cambios
+- `src/lib/test-matrix.js`: Parser de `gemstack-test-matrix`, validación de esquema de 20 tests canónicos y cálculo de `acceptanceSignature` canónico SHA-256.
+- `src/lib/closure-context.js`: Parser de bindings y gates de `plan.md`, metadatos de `tasks.md`, trazabilidad bidireccional, resolución de `RelevantClosureFiles`, `computeContentAggregateHash` y cálculo de `closureContextHash`.
+- `src/lib/runner-adapters.js`: Adaptador nativo seguro de runner `node:test`, parser TAP de resultados, motor de reconciliación aritmética canónica, ejecutor seguro de compuertas `PACKAGE_SCRIPT` y serializador atómico de `closure.json`.
+- `src/commands/collect.js`: Comando mutador dedicado que ejecuta tests y gates para generar `specs/<feature>/closure.json`.
+- `src/commands/ship.js`: Compuerta de transición a `SHIPPED` que exige evidencia de cierre fresca y verificada.
+- `src/commands/verify.js`: Etapa 5/6 agregada de verificación de evidencia mecánica de cierre en modo estrictamente de solo lectura (0 mutaciones en disco).
+- `src/cli.js`: Registro de comandos `collect` y `ship`.
+- `specs/007-mechanical-test-matrix-closure-evidence/`: Artefactos congelados `spec.md`, `plan.md`, `tasks.md` y evidencia de cierre generada `closure.json`.
+- `tests/`: 6 nuevas suites de prueba (`test-matrix.test.js`, `reconciliation.test.js`, `runner-adapter.test.js`, `traceability.test.js`, `closure-manifest.test.js`, `closure-gates.test.js`).
+- `specs/templates/`: Actualizadas plantillas de `spec.md`, `plan.md` y `tasks.md` con bloques canónicos de Upgrade B.
+- `.agents/skills/`: Actualizados skills (`gemstack-spec`, `gemstack-plan`, `gemstack-tasks`, `gemstack-qa`, `gemstack-ship`).
+- `docs/`, `README.md`, `package.json`: Documentación técnica y script de test con enumeración explícita de las 11 suites físicas.
 
-## Últimos Cambios Realizados
-- Creación de `.agents/rules/04-gemstack-infrastructure.md`
-- Modificación profunda de `.agents/rules/03-gemstack-security.md` (Level 2).
-- Evolución de `gemstack-cso` para revisar infraestructura.
-- Nuevo script `src/commands/hooks.js` y vinculación en `cli.js` e `init.js`.
-- Nuevo script `src/commands/install.js`.
-- Creación del Skill `gemstack-dashboard` y actualización de `.agents/rules/01-gemstack-core.md`.
-- Nuevo servidor `src/mcp-server.js` y vinculación CLI.
-- Todos los archivos `.agents/` nuevos fueron replicados en la carpeta `template/`.
-- Actualización mayor de `README.md` documentando todas las capacidades "v1.0".
+## 4. Intentos fallidos
+- Se confirmó en proyectos reales que scripts de prueba con sintaxis `2>nul` en `package.json` provocan que PowerShell/Bash enmascaren errores y retornen código de salida 0 con 0 tests ejecutados. Ahora esto es detectado como error por `gemstack verify` y prohibido en la Constitución.
+- **2026-09-11**: En el reporte de Upgrade A, se produjo un drift en la nomenclatura y categorización de la matriz P1 canónica. Se restauró la correlación canónica estricta de 25 tests P1 aprobados y la regla estricta de parser de 2+ bloques -> CONTRACT_PARSE_ERROR.
+- **Node 20+ Subprocess Recursion**: Al ejecutar `node --test` como subproceso desde un proceso de test runner, `process.env.NODE_TEST_CONTEXT` suprimía la ejecución de archivos hijos con warning de recursión. Se resolvió sanitizando las variables `NODE_TEST_CONTEXT` y `NODE_TEST_WORKER_ID` en el entorno del proceso hijo.
+- **Windows spawn 'npm.cmd' EINVAL**: Node 22+ en Windows genera `EINVAL` al invocar `spawn('npm.cmd', ..., { shell: false })`. Se resolvió ejecutando directamente el binario `npm-cli.js` vía `process.execPath` cuando se detecta en Windows, respetando la regla constitucional de `shell: false`.
+- **Closure Manifest Self-Reference**: Al incluir `specs/<feature>/closure.json` en los archivos de implementación de `tasks.md`, `closureContextHash` cambiaba cada vez que `closure.json` era escrito, provocando que la evidencia se marcara como `STALE` inmediatamente después de recolectarse. Se resolvió excluyendo explícitamente `closure.json` de la agregación de hashes de contexto de implementación (`implementationContextHash`).
 
-## Qué Sigue (Next Steps para futuras sesiones)
-1. **Adopción y Difusión:** El proyecto está listo para ser publicado abiertamente. Los usuarios pueden empezar a instalarlo en sus propios proyectos web.
-2. **Ampliar el Mercado de Skills:** Podríamos crear un repositorio independiente (`gemstack-skills`) donde la comunidad aloje sus skills compartidos.
-3. **Mantenimiento del Servidor MCP:** Actualmente el servidor MCP expone 2 herramientas (`get_current_tasks`, `get_security_rules`). En futuras iteraciones se podrían agregar herramientas de mutación (escribir specs a través de MCP).
-
-## Archivos Críticos a Tener en Cuenta
-- `src/cli.js`: El cerebro del enrutador de comandos.
-- `src/commands/*.js`: Cada comando de la CLI está encapsulado de forma nativa.
-- `template/`: Esta carpeta *debe* contener un espejo exacto de `.agents/`, `.gemstack/`, `docs/` y `specs/`. ¡Nunca modifiques reglas locales sin actualizarlas en el `template/`!
-- `scripts/ci/*.js`: Toda la validación CI depende de scripts cero-dependencias escritos en Node.
+## 5. Próximos pasos
+1. Completar la publicación de la versión minor v1.2.0 en GitHub Release y npm.
+2. Iniciar la fase de arquitectura de Upgrade C (Cost & Provider Safety Gates) en su ciclo correspondiente.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gemstack-ai",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Agentic Spec-Driven Development framework for Gemini/Antigravity",
   "main": "src/cli.js",
   "bin": {
@@ -10,7 +10,8 @@
     "node": ">=18.18.0"
   },
   "scripts": {
-    "test": "node --test tests/init.test.js",
+    "test": "node --test tests/contracts.test.js tests/hasher.test.js tests/findings.test.js tests/init.test.js tests/verify.test.js tests/test-matrix.test.js tests/reconciliation.test.js tests/runner-adapter.test.js tests/traceability.test.js tests/closure-manifest.test.js tests/closure-gates.test.js",
+    "gemstack:verify": "node src/cli.js verify",
     "pack:dry": "npm pack --dry-run",
     "ci:frontmatter": "node scripts/ci/check-frontmatter.js",
     "ci:template": "node scripts/ci/check-template-clean.js",

package/scripts/ci/smoke-cli.js

@@ -24,6 +24,7 @@ runSafe(`node "${path.join(rootDir, 'src/cli.js')}" show gemstack-handoff`, root
 runSafe(`node "${path.join(rootDir, 'src/cli.js')}" init --dry-run --target "${tmpDir}"`, tmpDir);
 runSafe(`node "${path.join(rootDir, 'src/cli.js')}" init --yes --target "${tmpDir}"`, tmpDir);
 runSafe(`node "${path.join(rootDir, 'src/cli.js')}" doctor --target "${tmpDir}"`, tmpDir);
+runSafe(`node "${path.join(rootDir, 'src/cli.js')}" verify --target "${tmpDir}"`, tmpDir);
 runSafe(`node "${path.join(rootDir, 'src/cli.js')}" update --dry-run --target "${tmpDir}"`, tmpDir);
 
 fs.rmSync(tmpDir, { recursive: true, force: true });

package/specs/006-architecture-consistency-engine/.gemstack.json

@@ -0,0 +1,9 @@
+{
+  "phase_hashes": {
+    "spec": "f5d423eaf508b06b663b39f467fba1d9ceff6db21f01e427500ad739a90c5be8",
+    "plan": "1ce0e58863427905022a6294f8683b9f508d72b171379c78807db19862c75004",
+    "tasks": "dfad2484ad112e26ef906ea851b12cf6ea090d6faf244a6fbd2650baee8e0d98"
+  },
+  "historical_findings": [],
+  "accepted_exceptions": []
+}

package/specs/006-architecture-consistency-engine/plan.md

@@ -0,0 +1,319 @@
+# Plan de Implementación: Architecture Consistency Engine & Phase Freezing (Upgrade A)
+
+**Feature Branch**: `006-architecture-consistency-engine`  
+**Spec**: [`specs/006-architecture-consistency-engine/spec.md`](file:///c:/CODES/Gemstack/specs/006-architecture-consistency-engine/spec.md)  
+**Lifecycle Status**: `PLAN_COMPLETE`  
+**Stop Reason**: `PLAN_COMPLETE_AWAITING_REVIEW`
+
+---
+
+## 1. Resumen y Contexto Técnico
+
+El objetivo de este plan es diseñar la arquitectura técnica para **Upgrade A**, transformando la especificación congelada en módulos de Node.js nativos sin dependencias externas (*Zero-Dependency Core*).
+
+### Restricciones Arquitectónicas Inmutables
+- **Runtime**: Node.js >= 18.18.0 nativo.
+- **Dependencias**: Cero paquetes npm de terceros (uso exclusivo de `crypto`, `fs`, `path`, `assert`, `node:test`).
+- **Compatibilidad**: Modo `LEGACY` transparente para specs previas (001 a 005) y retrocompatibilidad binaria de `.gemstack/state.json`.
+- **Multiplataforma**: Soporte idéntico en Windows (CRLF, backslashes), Linux y macOS.
+
+---
+
+## 2. Constitution Check (Phase -1 Gates)
+
+### Simplicity Gate (Article VII)
+- [x] **¿Se usan el mínimo número de carpetas/archivos posibles?** Sí: 4 librerías modulares en `src/lib/` (`hasher.js`, `contracts.js`, `findings.js`, `state.js`) y extensión quirúrgica de `src/commands/verify.js`.
+- [x] **¿No hay abstracciones prematuras?** Sí: No se crea un framework de AST ni compiladores genéricos; parsing directo de bloques JSON delimitados.
+
+### Anti-Abstraction Gate (Article VIII)
+- [x] **¿Se usan las APIs nativas del framework sin wrappers innecesarios?** Sí: `crypto.createHash('sha256')`, `fs.writeFileSync`, `path.relative`.
+
+### Test-First Imperative & Zero Silent Failures (Article III)
+- [x] **¿El plan incluye la creación de tests antes que el código fuente?** Sí: Matriz P1 de 25 tests estructurados en `tests/contracts.test.js`, `tests/hasher.test.js`, `tests/findings.test.js` y regresión en `tests/verify.test.js`.
+- [x] **¿Cero falsos positivos silenciosos?** Sí: Pruebas unitarias nativas sin `2>nul`.
+
+---
+
+## 3. Diseño Detallado de Arquitectura y Módulos
+
+```text
+c:\CODES\Gemstack\
+├── src\
+│   ├── lib\
+│   │   ├── hasher.js          <-- [NUEVO] Normalización LF, detección BOM y SHA-256
+│   │   ├── contracts.js       <-- [NUEVO] Parser ```gemstack-contracts, normalizador, comparador
+│   │   ├── findings.js        <-- [NUEVO] Fingerprints, deltas consolidados y anti-loop
+│   │   └── state.js           <-- [NUEVO] Lector/escritor atómico (tmp + rename) para state.json
+│   └── commands\
+│       └── verify.js          <-- [MODIFICAR] Incorporar paso 4: Consistencia y Hashes de Fase
+├── tests\
+│   ├── contracts.test.js      <-- [NUEVO] Tests categorías A y B (Parsing, Enums, Identity, Boundary, Herencia)
+│   ├── hasher.test.js         <-- [NUEVO] Tests categoría C (Freeze, CRLF/LF, Detección de mutación)
+│   └── findings.test.js       <-- [NUEVO] Tests categorías D, E, F y G (Fingerprints, Anti-loop, Legacy, Windows)
+```
+
+---
+
+### 3.1 Módulo `src/lib/hasher.js`
+
+#### Responsabilidad
+Calcular hashes deterministas de artefactos markdown garantizando invariancia de plataforma (Windows vs POSIX).
+
+#### Algoritmo de Hashing
+1. Leer buffer o string UTF-8.
+2. Comprobar presencia de UTF-8 BOM (`0xEF, 0xBB, 0xBF` o `\uFEFF`). Si existe, rechazar con error `CONTRACT_PARSE_ERROR: BOM detected in phase artifact`.
+3. Normalizar saltos de línea: reemplazar `\r\n` por `\n` y cualquier `\r` suelto por `\n`.
+4. Calcular SHA-256 sobre los bytes UTF-8 resultantes.
+5. Retornar digest hexadecimal en minúsculas (64 caracteres).
+
+#### Funciones Exportadas
+- `normalizeContent(content: string): string`
+- `hashArtifact(content: string): string`
+- `hashFile(filePath: string): string`
+
+---
+
+### 3.2 Módulo `src/lib/contracts.js`
+
+#### Responsabilidad
+Localizar, extraer, validar, normalizar y comparar contratos declarados en artefactos de fase.
+
+#### Delimitador Canónico y Reglas de Parsing
+- **Delimitador**:
+  ````markdown
+  ```gemstack-contracts
+  [
+    ...
+  ]
+  ```
+  ````
+- **Regla de Bloque Único**: Se permite **exactamente un bloque** `gemstack-contracts` por artefacto. Si se detectan dos o más bloques, emite `CONTRACT_PARSE_ERROR: Multiple gemstack-contracts blocks detected`.
+- **Bloque Vacío**: `[]` es válido y representa 0 contratos declarados.
+- **Sin Bloque**: Retorna `null` (activa modo `LEGACY`).
+
+#### Esquemas Exactos de Contratos
+
+1. **`ENUM_SET`**:
+   ```json
+   {
+     "id": "job-status",
+     "type": "ENUM_SET",
+     "values": ["QUEUED", "PROCESSING", "COMPLETED", "FAILED"],
+     "description": "Opcional"
+   }
+   ```
+   *Normalización:* Trim a cada string; rechazar miembros vacíos o duplicados. Comparación insensible al orden (`values.slice().sort()`).
+
+2. **`IDENTITY_TUPLE`**:
+   ```json
+   {
+     "id": "publication-identity",
+     "type": "IDENTITY_TUPLE",
+     "values": ["workspaceId", "recordingId", "languageTag", "kind"]
+   }
+   ```
+   *Normalización:* Trim a cada string; rechazar duplicados. Comparación es un conjunto semántico de miembros exactos (`order-insensitive`, `duplicate-sensitive`, `exact-member-sensitive`).
+
+3. **`PROVENANCE_RULE`**:
+   ```json
+   {
+     "id": "caption-provenance",
+     "type": "PROVENANCE_RULE",
+     "entity": "CaptionAsset",
+     "values": ["parentRecordingAssetId", "sourceMediaAssetType", "sourceRecordingExportAssetId"]
+   }
+   ```
+   *Normalización:* Requiere `entity` (string no vacío) y lista de campos requeridos exactos.
+
+4. **`BOOLEAN_INVARIANT`**:
+   ```json
+   {
+     "id": "zero-dependency-core",
+     "type": "BOOLEAN_INVARIANT",
+     "value": true
+   }
+   ```
+   *Normalización:* `value` debe ser estrictamente tipo booleano (`typeof value === 'boolean'`). Se rechazan `"true"` o `"false"` como strings.
+
+5. **`BOUNDARY`**:
+   ```json
+   {
+     "id": "eventalus-sync-dependency",
+     "type": "BOUNDARY",
+     "value": "FORBIDDEN"
+   }
+   ```
+   *Valores permitidos:* Exclusivamente `"FORBIDDEN"` y `"REQUIRED"`. Comparación estricta de string (`FORBIDDEN` vs `FORBIDDEN` ➔ `PASS`; `REQUIRED` vs `REQUIRED` ➔ `PASS`; `FORBIDDEN` vs `REQUIRED` o viceversa ➔ `FROZEN_CONTRACT_VIOLATION`).
+
+6. **`ROADMAP_LIMIT`**:
+   ```json
+   {
+     "id": "final-planned-mvp",
+     "type": "ROADMAP_LIMIT",
+     "value": 18
+   }
+   ```
+   *Normalización:* Escalar JSON (`number` o `string`). No hay coerción de tipo.
+
+#### Algoritmo de Herencia y Comparación
+```text
+effectiveSpecRegistry = spec contracts
+effectivePlanRegistry = effectiveSpecRegistry + additive plan contracts
+effectiveTasksRegistry = effectivePlanRegistry + additive tasks contracts
+```
+- Si un contrato de `spec.md` no se repite en `plan.md` ➔ `PASS` (heredado implícitamente, no requiere duplicación).
+- Si se re-declara con valor normalizado idéntico ➔ `PASS`.
+- Si se re-declara con valor diferente ➔ emite `FROZEN_CONTRACT_VIOLATION` (`BLOCKER`).
+- Si `plan.md` introduce un ID nuevo ➔ clasificado como aditivo ➔ `PASS`.
+
+---
+
+### 3.3 Módulo `src/lib/findings.js`
+
+#### Responsabilidad
+Gestión determinista de hallazgos, generación de huellas digitales (*fingerprints*), cálculo de deltas consolidados y supresión anti-loop.
+
+#### Granularidad de Hallazgos
+Para cada comparación de contrato, se genera **un único hallazgo consolidado** por `(contractId, phase, violationType)`.
+El payload del hallazgo incluye:
+```json
+{
+  "fingerprint": "c1f...",
+  "code": "FROZEN_CONTRACT_VIOLATION",
+  "severity": "BLOCKER",
+  "contractId": "transcription-job-status",
+  "phase": "plan",
+  "location": "specs/006-architecture-consistency-engine/plan.md",
+  "delta": {
+    "expected": ["COMPLETED", "FAILED", "PROCESSING", "QUEUED"],
+    "observed": ["CANCELLED", "COMPLETED", "FAILED", "PROCESSING", "QUEUED"],
+    "missing": [],
+    "added": ["CANCELLED"]
+  },
+  "status": "OPEN"
+}
+```
+
+#### Huella Digital (*Fingerprint*) Canónica vs Display
+```javascript
+function createFingerprint(finding) {
+    const raw = JSON.stringify({
+        code: finding.code,
+        contractId: finding.contractId ?? null,
+        phase: finding.phase,
+        location: finding.location ? finding.location.replace(/\\/g, '/') : null
+    });
+    return crypto.createHash('sha256').update(raw, 'utf8').digest('hex');
+}
+```
+- **Fingerprint Canónico (Identidad)**: Digest SHA-256 completo en hexadecimal en minúsculas de **64 caracteres**. Es la clave inmutable utilizada para persistencia, seguimiento de excepciones y motor anti-loop. **Nunca se trunca** en el almacenamiento.
+- **Display Fingerprint (Cosmético)**: Si se requiere para legibilidad en salida CLI, se puede derivar una representación corta visual (`displayFingerprint = fingerprint.slice(0, 12)`), pero jamás se usa como identidad ni como clave en `.gemstack.json`.
+
+#### Context Hash y Anti-Loop
+```javascript
+function computeContextHash(upstreamHash, currentHash, contractNormalized) {
+    return crypto.createHash('sha256')
+        .update(`${upstreamHash || ''}:${currentHash || ''}:${JSON.stringify(contractNormalized || {})}`)
+        .digest('hex');
+}
+```
+- **`RESOLVED`**: Significa que el defecto fue corregido en el código/artefacto. Si el validador vuelve a correr y la violación persiste, el hallazgo se reactiva automáticamente.
+- **`ACCEPTED_EXCEPTION`**: Requiere `approvedByHuman = true`. Suprime el bloqueo si `contextHash` permanece idéntico. Si el artefacto involucrado cambia, la excepción vuelve a requerir revisión.
+- **`SUPERSEDED`**: Ocurre cuando una enmienda oficial a la especificación vuelve obsoleto un hallazgo previo.
+
+#### Almacenamiento Persistente
+Para evitar sobrecargar `state.json` con listas ilimitadas de hallazgos, se almacenan en un sidecar por feature:
+`specs/<feature>/.gemstack.json`
+Contiene:
+```json
+{
+  "feature": "006-architecture-consistency-engine",
+  "phase_hashes": { "spec": "...", "plan": "...", "tasks": "..." },
+  "accepted_exceptions": [],
+  "resolved_findings": []
+}
+```
+
+---
+
+### 3.4 Módulo `src/lib/state.js`
+
+#### Responsabilidad
+Operaciones de lectura y escritura atómica sobre `.gemstack/state.json`.
+
+#### Algoritmo de Escritura Atómica (Planificado para `src/lib/state.js`)
+1. Resolver ruta absoluta con `fssafe.resolveSafe(targetDir, '.gemstack/state.json')`.
+2. Escribir primero en archivo temporal adyacente: `.gemstack/state.json.tmp.<pid>.<timestamp>`.
+3. Renombrar atómicamente (`fs.renameSync`) sobre `.gemstack/state.json`.
+4. En Windows, si existe bloqueo temporal transitorio, realizar reintento controlado (3 intentos con backoff de 50ms).
+
+---
+
+## 4. Integración en `src/commands/verify.js`
+
+El verificador actual de 4 pasos se expande a 5 pasos limpios:
+
+```text
+[INFO] --- 1/5 Verificación Estructural (Archivos Base) ---
+[INFO] --- 2/5 Verificación de Memoria e Integridad de Handoff ---
+[INFO] --- 3/5 Verificación de Estado Local (.gemstack/state.json) ---
+[INFO] --- 4/5 Consistencia Arquitectónica y Hashes de Fase (Upgrade A) ---
+[INFO] --- 5/5 Verificación de Seguridad y Test Runners ---
+```
+
+### Lógica del Paso 4 en `verify.js`
+1. Leer `.gemstack/state.json`. Obtener `active_spec`.
+2. Si `active_spec` es nulo o no existe: reportar `[OK] Sin spec activa (verificación de contratos omitida)` y continuar.
+3. Si `specs/<active_spec>/spec.md` existe:
+   - Extraer bloques `gemstack-contracts`. Si no tiene bloques, marcar `[INFO] Modo LEGACY (sin contratos estructurados)` y continuar.
+   - Si tiene `phase_hashes.spec` en `state.json` o sidecar:
+     - Calcular hash actual de `spec.md`.
+     - Si difiere del hash congelado: emitir error crítico `FROZEN_ARTIFACT_CHANGED`.
+4. Si existe `plan.md`:
+   - Validar herencia de contratos de `spec.md` contra `plan.md`.
+   - Reportar hallazgos de contradicciones (`ENUM_SET`, `IDENTITY_TUPLE`, `PROVENANCE_RULE`, `BOUNDARY`, `BOOLEAN_INVARIANT`, `ROADMAP_LIMIT`).
+   - Aplicar supresión anti-loop sobre hallazgos con `ACCEPTED_EXCEPTION` válidos.
+5. Si hay bloqueadores abiertos (`open_blockers > 0`): incrementar `totalErrors`.
+
+---
+
+## 5. Mapeo de Trazabilidad de Pruebas P1 (Exact Mechanical Total = 25)
+
+| ID | Categoría | Módulo Responsable | Aserción Técnica |
+|---|---|---|---|
+| `TEST-CONSISTENCY-A01` | Parsing | `src/lib/contracts.js` | Extracción correcta de array JSON dentro de ````gemstack-contracts. |
+| `TEST-CONSISTENCY-A02` | Parsing | `src/lib/contracts.js` | Emisión de `CONTRACT_PARSE_ERROR` ante JSON malformado o múltiples bloques. |
+| `TEST-CONSISTENCY-A03` | Parsing | `src/lib/contracts.js` | Emisión de `CONTRACT_DUPLICATE_ID` si dos contratos repiten `id`. |
+| `TEST-CONSISTENCY-B01` | Cross-Phase | `src/lib/contracts.js` | `ENUM_SET`: detecta miembro extra no aprobado (ej. `PURGED`) ➔ `BLOCKED`. |
+| `TEST-CONSISTENCY-B02` | Cross-Phase | `src/lib/contracts.js` | `ENUM_SET`: valida ordenación normalizada (`[A,B,C]` == `[C,B,A]`) ➔ `PASS`. |
+| `TEST-CONSISTENCY-B03` | Cross-Phase | `src/lib/contracts.js` | `IDENTITY_TUPLE`: detecta dimensión faltante (omite `kind`) ➔ `BLOCKED`. |
+| `TEST-CONSISTENCY-B04` | Cross-Phase | `src/lib/contracts.js` | `IDENTITY_TUPLE`: valida permutación de dimensiones idénticas ➔ `PASS`. |
+| `TEST-CONSISTENCY-B05` | Cross-Phase | `src/lib/contracts.js` | `PROVENANCE_RULE`: bloquea si entidad pierde campo de procedencia ➔ `BLOCKED`. |
+| `TEST-CONSISTENCY-B06` | Cross-Phase | `src/lib/contracts.js` | `BOOLEAN_INVARIANT` & `ROADMAP_LIMIT`: contradicciones directas ➔ `BLOCKED`. |
+| `TEST-CONSISTENCY-B07` | Cross-Phase | `src/lib/contracts.js` | `BOUNDARY`: valores estrictos `FORBIDDEN` y `REQUIRED`; detecta contradicción explícita (`FORBIDDEN` vs `REQUIRED` ➔ `BLOCKED`) y valida equivalencia como `PASS`. |
+| `TEST-CONSISTENCY-B08` | Cross-Phase | `src/lib/contracts.js` | Herencia: PLAN hereda SPEC y agrega compatibles sin duplicación ➔ `PASS`. |
+| `TEST-CONSISTENCY-C01` | Hashes | `src/lib/hasher.js` | Genera SHA-256 de 64 caracteres de `spec.md`. |
+| `TEST-CONSISTENCY-C02` | Hashes | `src/lib/hasher.js` | Detecta mutación no autorizada de artefacto congelado ➔ `FROZEN_ARTIFACT_CHANGED`. |
+| `TEST-CONSISTENCY-C03` | Hashes | `src/commands/verify.js`| Comprueba que `verify` valida contra hashes guardados sin mutarlos. |
+| `TEST-CONSISTENCY-C04` | Hashes | `src/lib/hasher.js` | Normalización CRLF a LF produce idéntico hash en Windows y POSIX. |
+| `TEST-CONSISTENCY-D01` | Fingerprints | `src/lib/findings.js` | Genera fingerprint determinista canónico de 64 caracteres hex SHA-256 con location relativa (/) inmune a colisiones; valida formato de display separado. |
+| `TEST-CONSISTENCY-D02` | Anti-Loop | `src/lib/findings.js` | Si el defecto persiste, no se suprime como RESOLVED; si se arregla, queda limpio. |
+| `TEST-CONSISTENCY-E01` | Excepciones | `src/lib/findings.js` | `ACCEPTED_EXCEPTION` suprime el bloqueo en `verify` si contextHash coincide. |
+| `TEST-CONSISTENCY-E02` | Excepciones | `src/lib/findings.js` | Mutación de artefacto relevante reactiva la excepción para re-evaluación. |
+| `TEST-CONSISTENCY-F01` | Legacy | `src/commands/verify.js`| Feature sin bloques de contratos opera en modo `LEGACY` sin errores. |
+| `TEST-CONSISTENCY-F02` | Legacy | `src/lib/state.js` | `state.json` versión 0.1 sin campos de Upgrade A se lee sin fallas. |
+| `TEST-CONSISTENCY-G01` | Windows | `src/lib/hasher.js` | Resuelve rutas con separadores `\` y normaliza internamente a `/`. |
+| `TEST-CONSISTENCY-G02` | Windows | `src/lib/state.js` | Escritura atómica previene corrupción de archivos en Windows. |
+| `TEST-CONSISTENCY-H01` | Regresión | Integration | `npm run gemstack:verify` mantiene todas las validaciones de salud intactas. |
+| `TEST-CONSISTENCY-H02` | Regresión | Integration | Las suites previas (`tests/init.test.js`, `tests/verify.test.js`) pasan al 100%. |
+
+**Total Mecánico de Tests P1**: **25**
+
+---
+
+## 6. Procedimiento de Dogfooding y Bootstrap
+
+Dado que la especificación `specs/006-architecture-consistency-engine/spec.md` ya declaró formalmente sus 5 contratos congelados (`zero-dependency-core`, `upgrade-a-contract-types`, etc.), el procedimiento de validación interna se ejecutará en 3 etapas:
+1. **Fase Bootstrap**: Los nuevos módulos `contracts.js`, `hasher.js`, `findings.js` se implementan y prueban con `node --test`.
+2. **Auto-Freeze de Feature 006**: Se congela el hash formal de `specs/006-architecture-consistency-engine/spec.md` en `.gemstack/state.json`.
+3. **Auto-Verificación**: Se ejecuta `node src/cli.js verify` contra el propio repositorio de Gemstack para certificar que el motor parsea y valida sus propios contratos con `PASS`.