gemstack-ai 1.0.1 → 1.1.2

package/handoff.md

@@ -1,45 +1,32 @@
-# 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 LIBERADO como v1.1.0 (`GEMSTACK UPGRADE A SHIPPED / DONE — ARCHITECTURE CLOSED`).
+- 17/17 tareas completadas, 25/25 tests canónicos P1 pasando (33/33 físicos), 0 bloqueadores.
+- Reglas `01-gemstack-core.md`, `02-gemstack-constitution.md`, plantillas y skills actualizados y sincronizados en `template/`.
+- Motor de consistencia integrado en `gemstack verify` (Paso 4/5).
 
-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/contracts.js`: Parser column-0 fenced, esquemas de 6 contratos, resolución de herencia y detección de contradicciones.
+- `src/lib/hasher.js`: Hashing canónico SHA-256 (64 hex lowercase) con normalización CRLF->LF y rechazo de BOM UTF-8.
+- `src/lib/findings.js`: Fingerprints canónicos SHA-256 de 64 caracteres, display token de 12 caracteres y excepciones con `contextHash`.
+- `src/lib/state.js`: Persistencia atómica de `state.json` (solo operativo) y sidecar histórico `.gemstack.json`.
+- `src/commands/verify.js`: Paso 4/5 de consistencia arquitectónica y hashes congelados.
+- `tests/`: 5 suites unitarias (`contracts.test.js`, `hasher.test.js`, `findings.test.js`, `init.test.js`, `verify.test.js`).
+- `docs/architecture-consistency.md`: Referencia técnica integral de consistencia y congelamiento de fases.
+- `CHANGELOG.md`, `README.md`, `RELEASE_NOTES.md`, `package.json`: Versión v1.1.0 documentada y preparada para release.
 
-## Ú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 (mencionando A04-A06, D03-D04, E03 y sugiriendo incorrectamente merge de múltiples bloques). Se restauró la correlación canónica estricta de 25 tests P1 aprobados (A=3, B=8, C=4, D=2, E=2, F=2, G=2, H=2) y la regla estricta de parser de 2+ bloques -> CONTRACT_PARSE_ERROR.
 
-## 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. Validar el nuevo ruteo semántico en sesiones de desarrollo reales.
+2. Considerar `npx gemstack verify` en los hooks o pipelines de CI de proyectos que consumen Gemstack.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gemstack-ai",
-  "version": "1.0.1",
+  "version": "1.1.2",
   "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",
+    "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`.

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

@@ -0,0 +1,179 @@
+# Especificación de Funcionalidad: Architecture Consistency Engine & Phase Freezing (Upgrade A)
+
+**Feature Branch**: `006-architecture-consistency-engine`  
+**Feature Slug**: `specs/006-architecture-consistency-engine/`  
+**Lifecycle Status**: `SPEC_COMPLETE`  
+**Stop Reason**: `SPEC_COMPLETE_AWAITING_REVIEW`
+
+---
+
+## 1. Contexto y Objetivos (Upgrade A)
+
+El framework Gemstack opera como un motor de disciplina para desarrollo con IA basado en Spec-Driven Development (SDD):
+`SPEC → PLAN → TASKS → IMPLEMENT → QA / REVIEW → SHIP → HANDOFF`.
+
+El objetivo de **Upgrade A** es incorporar una capa determinista de **detección de desviaciones arquitectónicas (Architecture Drift)** y **congelamiento de fases (Phase Freezing)** sin alterar el flujo existente, sin rediseñar el core y sin agregar dependencias externas (preservando el principio Zero-Dependency Node.js).
+
+### Dogfooding & Bootstrap Contracts
+Esta especificación define formalmente sus propios contratos congelados (`gemstack-contracts`), los cuales operan en modo auto-hospedado (*bootstrap mode*) y serán validados por el propio motor una vez implementado:
+
+```gemstack-contracts
+[
+  {
+    "id": "zero-dependency-core",
+    "type": "BOOLEAN_INVARIANT",
+    "value": true,
+    "description": "El runtime de Gemstack debe mantener cero dependencias externas de producción en Node.js."
+  },
+  {
+    "id": "upgrade-a-contract-types",
+    "type": "ENUM_SET",
+    "values": [
+      "ENUM_SET",
+      "IDENTITY_TUPLE",
+      "PROVENANCE_RULE",
+      "BOOLEAN_INVARIANT",
+      "BOUNDARY",
+      "ROADMAP_LIMIT"
+    ],
+    "description": "Tipos de contrato deterministas soportados canónicamente en Upgrade A."
+  },
+  {
+    "id": "verify-does-not-mutate-hashes",
+    "type": "BOOLEAN_INVARIANT",
+    "value": true,
+    "description": "El comando gemstack verify valida contra hashes congelados pero nunca actualiza ni sobreescribe los hashes de fase."
+  },
+  {
+    "id": "contract-amendment-requires-human-approval",
+    "type": "BOOLEAN_INVARIANT",
+    "value": true,
+    "description": "Cualquier enmienda a un contrato congelado o artefacto inmutable requiere aprobación humana explícita."
+  },
+  {
+    "id": "legacy-mode-supported",
+    "type": "BOOLEAN_INVARIANT",
+    "value": true,
+    "description": "Features sin bloques de contratos operan en modo legacy sin romper compatibilidad ni generar falsos bloqueos."
+  }
+]
+```
+
+---
+
+## 2. User Scenarios & Testing (MVP)
+
+### User Story 1 — Detección Determinista de Contradicciones Arquitectónicas (P1)
+Como desarrollador o revisor técnico, quiero que Gemstack bloquee el avance de fase si un PLAN o TASKS introduce valores en enums no aprobados, altera tuplas de identidad o descarta campos de procedencia definidos en SPEC.  
+**Test Independiente**: `TEST-CONSISTENCY-B01`, `TEST-CONSISTENCY-B02`, `TEST-CONSISTENCY-B03`.
+
+### User Story 2 — Congelamiento y Detección de Mutación de Artefactos (P1)
+Como arquitecto de software, quiero que cada artefacto aprobado (`spec.md`, `plan.md`, `tasks.md`) quede sellado con un hash criptográfico SHA-256 en `.gemstack/state.json`, de modo que cualquier mutación posterior sin enmienda formal detenga el avance con `FROZEN_ARTIFACT_CHANGED`.  
+**Test Independiente**: `TEST-CONSISTENCY-C01`, `TEST-CONSISTENCY-C02`, `TEST-CONSISTENCY-C03`.
+
+### User Story 3 — Anti-Loop y Huella Digital de Hallazgos (P1)
+Como agente de IA y usuario humano, quiero que los hallazgos tengan una huella determinista (*fingerprint*) y que las observaciones resueltas o aceptadas como excepción no se reabran indefinidamente si el artefacto no ha mutado.  
+**Test Independiente**: `TEST-CONSISTENCY-D01`, `TEST-CONSISTENCY-E01`.
+
+### User Story 4 — Compatibilidad Transparente con Proyectos Legados (P1)
+Como usuario con especificaciones existentes (001 a 005), quiero que `gemstack verify` y el flujo SDD sigan funcionando con total normalidad sin requerir migración obligatoria.  
+**Test Independiente**: `TEST-CONSISTENCY-F01`.
+
+---
+
+## 3. Requerimientos Funcionales
+
+### RF-001: Sintaxis Canónica de Declaración (`gemstack-contracts`)
+- Los contratos congelados se declaran exclusivamente dentro de bloques delimitados ````gemstack-contracts ... ```` en formato JSON en el artefacto de fase (`spec.md` o `plan.md`).
+- La prosa libre fuera del bloque NO se convierte implícitamente en contrato determinista.
+
+### RF-002: Tipos de Contrato Soportados en Upgrade A
+1. **`ENUM_SET`**: Conjunto de valores discretos. La comparación es insensible al orden (`normalizeSort`). Los duplicados son inválidos. Bloquea si aparecen miembros nuevos o faltan miembros aprobados.
+2. **`IDENTITY_TUPLE`**: Conjunto semántico de dimensiones de identidad (*semantic set of identity dimensions*). La comparación es insensible al orden (*order-insensitive*), sensible a duplicados (*duplicate-sensitive*) y sensible a miembros exactos (*exact-member-sensitive*). Por ejemplo, `[w, r, l, k]` vs `[k, l, r, w]` ➔ `PASS`; `[w, r, l, k]` vs `[w, r, l]` ➔ `BLOCKED`; `[w, r, l, k]` vs `[w, r, l, k, x]` ➔ `BLOCKED`. El orden original de declaración se preserva exclusivamente para renderizado, visualización de diffs y legibilidad humana, no como semántica arquitectónica de orden en Upgrade A.
+3. **`PROVENANCE_RULE`**: Lista de campos obligatorios para trazabilidad/linaje entre entidades. Bloquea si una entidad posterior omite un campo de procedencia congelado.
+4. **`BOOLEAN_INVARIANT`**: Invariante booleano estricto (`true`/`false`). Bloquea cualquier contradicción directa.
+5. **`BOUNDARY`**: Límites de aislamiento o dependencias arquitectónicas explícitas (ej. `FORBIDDEN` vs `REQUIRED`). Bloquea deterministamente contradicciones explícitas (ej. SPEC declara `FORBIDDEN` y PLAN declara `REQUIRED` ➔ `FROZEN_CONTRACT_VIOLATION`), mientras que declaraciones equivalentes resultan en `PASS`.
+6. **`ROADMAP_LIMIT`**: Límite numérico o escalar inmutable (ej. `FINAL_PLANNED_MVP = 18`).
+
+### RF-003: Modelo de Herencia de Contratos y Extensión Aditiva
+- `spec.md` es la raíz y declara los contratos base.
+- `plan.md` hereda automáticamente todos los contratos de `spec.md` y puede añadir nuevos contratos aditivos y compatibles específicos de arquitectura técnica sin requerir duplicar los bloques de contratos heredados.
+- `tasks.md` hereda el registro consolidado (`spec.md` + `plan.md`).
+- El validador distingue extensiones **aditivas no conflictivas** (`PASS`) de **contradicciones o mutaciones no aprobadas** (`BLOCKED`).
+
+### RF-004: Hashing Determinista y Normalización CRLF/LF
+- El hash de fase (`specHash`, `planHash`, `tasksHash`) se calcula usando SHA-256 sobre el contenido del archivo con saltos de línea normalizados a LF (`\r\n` ➔ `\n`) y codificación UTF-8.
+- Esto garantiza idéntico hash en Windows, macOS y Linux.
+- `gemstack verify` NUNCA actualiza los hashes de fase; solo la acción formal de freeze/aprobación lo hace.
+
+### RF-005: Enmienda Formal de Contratos (`ContractAmendment`)
+- Si la arquitectura cambia legítimamente, se requiere aprobación humana explícita.
+- Al aprobar una enmienda en `spec.md`, el hash de `spec.md` se actualiza y las fases subsiguientes (`plan.md`, `tasks.md`) se marcan como `REQUIRES_REVIEW`.
+
+### RF-006: Huellas Digitales (*Fingerprints*), Granularidad y Anti-Loop
+- **Regla de granularidad de hallazgos:** Para una comparación de contratos se genera un único hallazgo consolidado por `contractId + phase + violationType`, conteniendo el delta normalizado completo (ej. miembros faltantes y agregados consolidados en un único hallazgo).
+- **Huella determinista (*fingerprint*):** Cada hallazgo genera un hash: `SHA256(violationType + contractId + phase + normalizedLocation)`. No incluye texto volátil ni timestamps.
+- **Anti-Loop:** Si un hallazgo tiene estado `RESOLVED` o `ACCEPTED_EXCEPTION` y el hash del artefacto no ha cambiado, no se vuelve a generar el bloqueo.
+
+### RF-007: Extensiones Aditivas a `.gemstack/state.json`
+- Se preservan todos los campos existentes de `state.json`.
+- Se añade opcionalmente la sección de hashes y consistencia:
+  ```json
+  {
+    "phase_hashes": {
+      "spec": "<sha256-or-null>",
+      "plan": "<sha256-or-null>",
+      "tasks": "<sha256-or-null>"
+    },
+    "consistency": {
+      "status": "PASS | BLOCKED | LEGACY",
+      "open_blockers": 0
+    }
+  }
+  ```
+
+---
+
+## 4. Criterios de Éxito y Matriz de Aceptación P1 (Exact Mechanical Count = 25)
+
+| ID de Prueba | Categoría | Capa de Ejecución | Aserción de Aceptación |
+|---|---|---|---|
+| `TEST-CONSISTENCY-A01` | A — Parsing | Unit (Node) | Parsea correctamente bloques válidos `gemstack-contracts` en JSON. |
+| `TEST-CONSISTENCY-A02` | A — Parsing | Unit (Node) | Emite `CONTRACT_PARSE_ERROR` si el bloque JSON es sintácticamente inválido. |
+| `TEST-CONSISTENCY-A03` | A — Parsing | Unit (Node) | Bloquea con `CONTRACT_DUPLICATE_ID` si dos contratos comparten el mismo `id`. |
+| `TEST-CONSISTENCY-B01` | B — Cross-Phase | Unit (Node) | `ENUM_SET`: detecta adición no aprobada (ej. `PURGED`) y emite `BLOCKED`. |
+| `TEST-CONSISTENCY-B02` | B — Cross-Phase | Unit (Node) | `ENUM_SET`: valida ordenación normalizada (`[A,B,C]` == `[C,B,A]`) como `PASS`. |
+| `TEST-CONSISTENCY-B03` | B — Cross-Phase | Unit (Node) | `IDENTITY_TUPLE`: detecta dimensión faltante (omisión de `kind`) y emite `BLOCKED`. |
+| `TEST-CONSISTENCY-B04` | B — Cross-Phase | Unit (Node) | `IDENTITY_TUPLE`: valida tupla equivalente en orden permutado como `PASS`. |
+| `TEST-CONSISTENCY-B05` | B — Cross-Phase | Unit (Node) | `PROVENANCE_RULE`: bloquea si entidad posterior omite campo de procedencia requerido. |
+| `TEST-CONSISTENCY-B06` | B — Cross-Phase | Unit (Node) | `BOOLEAN_INVARIANT` & `ROADMAP_LIMIT`: bloquea contradicción directa (`true` vs `false`, `18` vs `20`). |
+| `TEST-CONSISTENCY-B07` | B — Cross-Phase | Unit (Node) | `BOUNDARY`: valores estrictos `FORBIDDEN` y `REQUIRED`; detecta contradicción explícita (`FORBIDDEN` vs `REQUIRED` ➔ `BLOCKED`) y valida equivalencia como `PASS`. |
+| `TEST-CONSISTENCY-B08` | B — Cross-Phase | Unit (Node) | Herencia y extensión aditiva: PLAN hereda contratos de SPEC y agrega compatibles sin duplicación; TASKS hereda SPEC + PLAN como `PASS`. |
+| `TEST-CONSISTENCY-C01` | C — Freeze & Hashes | Unit (Node) | Almacena `specHash` SHA-256 al congelar la fase SPEC. |
+| `TEST-CONSISTENCY-C02` | C — Freeze & Hashes | Unit (Node) | Detecta mutación no autorizada de `spec.md` con `FROZEN_ARTIFACT_CHANGED`. |
+| `TEST-CONSISTENCY-C03` | C — Freeze & Hashes | Unit (Node) | `verify` valida contra hashes almacenados y NO los reescribe silenciosamente. |
+| `TEST-CONSISTENCY-C04` | C — Freeze & Hashes | Unit (Node) | Normalización CRLF/LF produce idéntico hash en Windows y POSIX. |
+| `TEST-CONSISTENCY-D01` | D — Fingerprints | Unit (Node) | 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` | D — Anti-Loop | Unit (Node) | Hallazgo en estado `RESOLVED` con hash de artefacto sin cambios no se reabre. |
+| `TEST-CONSISTENCY-E01` | E — Excepciones | Unit (Node) | `ACCEPTED_EXCEPTION` aprobado por humano suprime el bloqueo en `verify`. |
+| `TEST-CONSISTENCY-E02` | E — Excepciones | Unit (Node) | Modificación del artefacto relevante reabre la excepción para nueva revisión. |
+| `TEST-CONSISTENCY-F01` | F — Legacy | Unit (Node) | Feature sin bloque `gemstack-contracts` opera en modo `LEGACY` sin error. |
+| `TEST-CONSISTENCY-F02` | F — Legacy | Unit (Node) | Proyecto con `state.json` versión previa inicializa campos faltantes de forma segura. |
+| `TEST-CONSISTENCY-G01` | G — Windows | Unit (Node) | Manejo de rutas con barras invertidas (`\`) normalizadas de forma segura en Windows. |
+| `TEST-CONSISTENCY-G02` | G — Windows | Unit (Node) | Operaciones de lectura y hashing atómicas sin colisión de descriptores de archivo. |
+| `TEST-CONSISTENCY-H01` | H — Regression | Integration | `npm run gemstack:verify` mantiene todas las validaciones estructurales existentes intactas. |
+| `TEST-CONSISTENCY-H02` | H — Regression | Integration | Las suites previas (`tests/init.test.js`, `tests/verify.test.js`) continúan pasando al 100%. |
+
+---
+
+## 5. Non-Goals Explícitos (Fuera de Alcance en Upgrade A)
+
+- **NO** cálculo mecánico de matrices de prueba P1 ni conteo aritmético de tests (Upgrade B).
+- **NO** trazabilidad tarea ↔ test (Upgrade B).
+- **NO** manifiesto `closure.json` ni puertas de comandos canónicos (Upgrade B).
+- **NO** `BillableActionGate` ni libro de costos de proveedores (Upgrade C).
+- **NO** `ProviderCapabilityGate` ni adaptadores fail-closed (Upgrade C).
+- **NO** generador de cápsulas de contexto (`context-capsule.json`) (Upgrade D).
+- **NO** ejecutores de bases de datos o runners de migraciones.
+- **NO** frameworks de AST o paquetes npm externos (Zero-Dependency estricto).
+- **NO** herramientas de gestión de proyectos genéricos (Kanban, time tracking).