gemstack-ai 1.0.1 → 1.2.0

package/src/lib/test-matrix.js

@@ -0,0 +1,187 @@
+const crypto = require('node:crypto');
+const { normalizeContent } = require('./hasher');
+
+const CANONICAL_LAYERS = ['UNIT', 'INTEGRATION', 'E2E', 'CLI'];
+const CANONICAL_GATES = ['REQUIRED', 'SUPPLEMENTAL'];
+const CANONICAL_ID_REGEX = /^TEST-[A-Z0-9]+-[A-Z0-9]+$/;
+const REQUIRED_FIELDS = ['id', 'category', 'layer', 'description', 'pass_criteria', 'gate'];
+
+/**
+ * Extracts the single column-0 gemstack-test-matrix block from markdown.
+ *
+ * @param {string} markdownContent
+ * @returns {{ matrix: Array<object>|null, isLegacy: boolean }}
+ */
+function extractTestMatrixBlock(markdownContent) {
+  const normalized = normalizeContent(markdownContent);
+  const lines = normalized.split('\n');
+  const fence = '```';
+  const header = '```gemstack-test-matrix';
+
+  const blocks = [];
+  let inBlock = false;
+  let blockLines = [];
+
+  for (const line of lines) {
+    if (!inBlock) {
+      if (line.trimEnd() === header) {
+        inBlock = true;
+        blockLines = [];
+      }
+    } else {
+      if (line.trimEnd() === fence) {
+        inBlock = false;
+        blocks.push(blockLines.join('\n'));
+      } else {
+        blockLines.push(line);
+      }
+    }
+  }
+
+  if (blocks.length === 0) {
+    return { matrix: null, isLegacy: true };
+  }
+
+  if (blocks.length > 1) {
+    const err = new Error(`Multiple gemstack-test-matrix blocks detected (${blocks.length}). Exactly one is permitted.`);
+    err.code = 'TEST_MATRIX_PARSE_ERROR';
+    throw err;
+  }
+
+  const jsonRaw = blocks[0].trim();
+  let parsed;
+  try {
+    parsed = JSON.parse(jsonRaw);
+  } catch (parseErr) {
+    const err = new Error(`Failed to parse gemstack-test-matrix JSON: ${parseErr.message}`);
+    err.code = 'TEST_MATRIX_PARSE_ERROR';
+    throw err;
+  }
+
+  return { matrix: parsed, isLegacy: false };
+}
+
+/**
+ * Validates a canonical test matrix array.
+ *
+ * @param {any} matrix
+ * @returns {Array<object>} Sanitized array of canonical test objects
+ */
+function validateTestMatrix(matrix) {
+  if (!Array.isArray(matrix)) {
+    const err = new Error('gemstack-test-matrix must be a JSON array of test objects');
+    err.code = 'TEST_MATRIX_INVALID_SHAPE';
+    throw err;
+  }
+
+  const seenIds = new Set();
+  const validated = [];
+
+  for (let i = 0; i < matrix.length; i++) {
+    const item = matrix[i];
+    if (!item || typeof item !== 'object' || Array.isArray(item)) {
+      const err = new Error(`Item at index ${i} in gemstack-test-matrix must be a non-null object`);
+      err.code = 'TEST_MATRIX_INVALID_SHAPE';
+      throw err;
+    }
+
+    // Check unknown fields
+    const keys = Object.keys(item);
+    for (const k of keys) {
+      if (!REQUIRED_FIELDS.includes(k)) {
+        const err = new Error(`Item at index ${i} contains unknown field: "${k}"`);
+        err.code = 'TEST_MATRIX_INVALID_SHAPE';
+        throw err;
+      }
+    }
+
+    // Check required fields and empty values
+    for (const rf of REQUIRED_FIELDS) {
+      if (!(rf in item)) {
+        const err = new Error(`Item at index ${i} missing required field: "${rf}"`);
+        err.code = 'TEST_MATRIX_INVALID_SHAPE';
+        throw err;
+      }
+      if (typeof item[rf] !== 'string' || item[rf].trim().length === 0) {
+        const err = new Error(`Item at index ${i} field "${rf}" must be a non-empty string`);
+        err.code = 'TEST_MATRIX_INVALID_SHAPE';
+        throw err;
+      }
+    }
+
+    // Validate ID regex
+    if (!CANONICAL_ID_REGEX.test(item.id)) {
+      const err = new Error(`Item at index ${i} has invalid ID "${item.id}". Must match ^TEST-[A-Z0-9]+-[A-Z0-9]+$`);
+      err.code = 'TEST_MATRIX_INVALID_SHAPE';
+      throw err;
+    }
+
+    // Validate duplicate ID
+    if (seenIds.has(item.id)) {
+      const err = new Error(`Duplicate test ID detected in gemstack-test-matrix: "${item.id}"`);
+      err.code = 'TEST_MATRIX_DUPLICATE_ID';
+      throw err;
+    }
+    seenIds.add(item.id);
+
+    // Validate enum fields
+    if (!CANONICAL_LAYERS.includes(item.layer)) {
+      const err = new Error(`Item "${item.id}" has invalid layer "${item.layer}". Must be one of: ${CANONICAL_LAYERS.join(', ')}`);
+      err.code = 'TEST_MATRIX_INVALID_SHAPE';
+      throw err;
+    }
+
+    if (!CANONICAL_GATES.includes(item.gate)) {
+      const err = new Error(`Item "${item.id}" has invalid gate "${item.gate}". Must be one of: ${CANONICAL_GATES.join(', ')}`);
+      err.code = 'TEST_MATRIX_INVALID_SHAPE';
+      throw err;
+    }
+
+    validated.push({
+      id: item.id,
+      category: item.category,
+      layer: item.layer,
+      description: item.description,
+      pass_criteria: item.pass_criteria,
+      gate: item.gate
+    });
+  }
+
+  return validated;
+}
+
+/**
+ * Computes deterministic SHA-256 acceptanceSignature digest over canonical test matrix.
+ *
+ * @param {Array<object>} matrix
+ * @returns {string} 64-character lowercase hexadecimal digest
+ */
+function computeAcceptanceSignature(matrix) {
+  const validated = validateTestMatrix(matrix);
+
+  // Sort canonical records by id using deterministic code-unit ordering
+  const sorted = [...validated].sort((a, b) => (a.id < b.id ? -1 : (a.id > b.id ? 1 : 0)));
+
+  // Normalize each record with ASCII-sorted keys: category, description, gate, id, layer, pass_criteria
+  const normalizedRecords = sorted.map(rec => ({
+    category: rec.category,
+    description: rec.description,
+    gate: rec.gate,
+    id: rec.id,
+    layer: rec.layer,
+    pass_criteria: rec.pass_criteria
+  }));
+
+  const canonicalJson = JSON.stringify(normalizedRecords);
+  return crypto.createHash('sha256').update(canonicalJson, 'utf8').digest('hex');
+}
+
+module.exports = {
+  CANONICAL_LAYERS,
+  CANONICAL_GATES,
+  CANONICAL_ID_REGEX,
+  REQUIRED_FIELDS,
+  extractTestMatrixBlock,
+  validateTestMatrix,
+  computeAcceptanceSignature
+};

package/src/mcp-server.js

@@ -7,7 +7,7 @@
 const fs = require('fs');
 const path = require('path');
 const readline = require('readline');
-const manifest = require('../lib/manifest');
+const manifest = require('./lib/manifest');
 
 // MCP Protocol structures
 function sendResponse(id, result, error = null) {

package/template/.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/template/.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/template/.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/template/.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/template/.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/template/.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/template/.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/template/.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/template/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.

package/template/specs/templates/plan.md

@@ -36,3 +36,14 @@ ruta/archivo: [Razón]
 | Violación de Regla | Por qué es necesario | Alternativa simple rechazada por |
 |--------------------|----------------------|-----------------------------------|
 | [Ej. Wrapper]      | [Razón]              | [Razón]                           |
+
+## 6. Contratos Aditivos del Plan (Opcional - Upgrade A)
+<!--
+  Hereda automáticamente los contratos de spec.md.
+  Si se requieren contratos técnicos adicionales compatibles, declararlos aquí en un bloque canónico.
+  No modifiques contratos de spec sin aprobación explícita de enmienda.
+-->
+```gemstack-contracts
+[
+]
+```

package/template/specs/templates/spec.md

@@ -33,3 +33,20 @@
 ## 5. Entidades Clave (Data / Models)
 - **[Entidad 1]**: [Representación abstracta]
 - **[Entidad 2]**: [Relación]
+
+## 6. Contratos Arquitectónicos Congelados (Opcional - Upgrade A)
+<!--
+  Declara decisiones arquitectónicas congeladas usando el bloque canónico.
+  Tipos soportados: ENUM_SET, IDENTITY_TUPLE, PROVENANCE_RULE, BOOLEAN_INVARIANT, BOUNDARY, ROADMAP_LIMIT.
+  Si no se incluye este bloque, la feature operará en modo LEGACY.
+-->
+```gemstack-contracts
+[
+  {
+    "id": "feature-invariants",
+    "type": "BOOLEAN_INVARIANT",
+    "value": true,
+    "description": "Invariante principal congelada para este feature"
+  }
+]
+```

package/template/specs/templates/tasks.md

@@ -4,6 +4,7 @@
   Instrucciones:
   - Marca con `[P]` las tareas que sean seguras de paralelizar (por ej. si usas múltiples subagentes).
   - Incluye la redacción y validación de TESTS ANTES de la implementación real.
+  - Hereda los contratos congelados de SPEC y PLAN por defecto (no se requiere bloque de contratos).
 -->
 
 ## Fase 1: Tests (Test-First Imperative)