gemstack-ai 1.0.1 → 1.1.2

package/src/lib/findings.js

@@ -0,0 +1,227 @@
+const crypto = require('node:crypto');
+const { normalizePath } = require('./hasher');
+
+/**
+ * Computes canonical 64-character lowercase hexadecimal SHA-256 fingerprint for a finding.
+ *
+ * @param {object} params
+ * @param {string} params.code - Finding error code
+ * @param {string|null} params.contractId - Optional contract id
+ * @param {string} params.phase - Phase where violation was found
+ * @param {string} params.location - File path of the violation
+ * @returns {string} 64-char lowercase hex SHA-256
+ */
+function computeFindingFingerprint({ code, contractId, phase, location }) {
+  const normLocation = normalizePath(location);
+  const payload = JSON.stringify({
+    code: code || 'UNKNOWN_ERROR',
+    contractId: contractId ?? null,
+    phase: phase || 'unknown',
+    location: normLocation || null
+  });
+
+  return crypto.createHash('sha256').update(payload, 'utf8').digest('hex');
+}
+
+/**
+ * Formats a cosmetic display string for a fingerprint (12-char prefix).
+ * Never used for internal storage, indexing or anti-loop logic.
+ *
+ * @param {string} fingerprint
+ * @returns {string} 12-char display token
+ */
+function formatDisplayFingerprint(fingerprint) {
+  if (typeof fingerprint !== 'string') return '';
+  return fingerprint.slice(0, 12);
+}
+
+/**
+ * Creates a structured Finding object.
+ *
+ * @param {object} params
+ * @returns {object} Finding
+ */
+function createFinding({ code, contractId, phase, location, delta = null, details = null }) {
+  const fp = computeFindingFingerprint({ code, contractId, phase, location });
+  return {
+    fingerprint: fp,
+    display_id: formatDisplayFingerprint(fp),
+    code,
+    contractId: contractId ?? null,
+    phase,
+    location: normalizePath(location),
+    delta,
+    details,
+    status: 'OPEN',
+    is_blocking: true,
+    detected_at: new Date().toISOString(),
+    resolved_at: null
+  };
+}
+
+/**
+ * Computes the full frozen contextHash for an accepted exception.
+ * Context identity = SHA-256(upstreamAcceptedPhaseHash + currentComparedPhaseHash + normalizedContractRepresentation).
+ *
+ * @param {object} params
+ * @param {string} params.upstreamAcceptedPhaseHash
+ * @param {string} params.currentComparedPhaseHash
+ * @param {string} params.normalizedContractRepresentation - Deterministically serialized contract JSON
+ * @returns {string} 64-character lowercase hex SHA-256
+ */
+function computeContextHash({ upstreamAcceptedPhaseHash, currentComparedPhaseHash, normalizedContractRepresentation }) {
+  const payload = JSON.stringify({
+    upstreamAcceptedPhaseHash: upstreamAcceptedPhaseHash || '',
+    currentComparedPhaseHash: currentComparedPhaseHash || '',
+    normalizedContractRepresentation: normalizedContractRepresentation || ''
+  });
+
+  return crypto.createHash('sha256').update(payload, 'utf8').digest('hex');
+}
+
+/**
+ * Reconciles findings between successive checks (Anti-Loop mechanism):
+ * - If an existing finding is no longer in current violations -> status becomes 'RESOLVED'.
+ * - If a finding was 'RESOLVED' but the violation recurs -> status reopens to 'OPEN'.
+ * - New violations are added as 'OPEN'.
+ *
+ * @param {Array<object>} existingFindings
+ * @param {Array<object>} currentViolations
+ * @returns {Array<object>} Reconciled findings
+ */
+function reconcileFindings(existingFindings = [], currentViolations = []) {
+  const reconciled = [];
+  const currentViolationFps = new Map();
+
+  for (const v of currentViolations) {
+    const fp = computeFindingFingerprint({
+      code: v.code,
+      contractId: v.contractId,
+      phase: v.phase,
+      location: v.location
+    });
+    currentViolationFps.set(fp, v);
+  }
+
+  // Process existing findings
+  for (const f of existingFindings) {
+    if (currentViolationFps.has(f.fingerprint)) {
+      const v = currentViolationFps.get(f.fingerprint);
+      currentViolationFps.delete(f.fingerprint); // Handled
+
+      // If it was RESOLVED, reopen it (anti-loop protection)
+      if (f.status === 'RESOLVED') {
+        reconciled.push({
+          ...f,
+          status: 'OPEN',
+          is_blocking: true,
+          delta: v.delta,
+          detected_at: new Date().toISOString(),
+          resolved_at: null
+        });
+      } else {
+        reconciled.push({
+          ...f,
+          delta: v.delta,
+          is_blocking: f.status !== 'ACCEPTED_EXCEPTION'
+        });
+      }
+    } else {
+      // Violation not present in current analysis -> mark RESOLVED if it was OPEN
+      if (f.status === 'OPEN') {
+        reconciled.push({
+          ...f,
+          status: 'RESOLVED',
+          is_blocking: false,
+          resolved_at: new Date().toISOString()
+        });
+      } else {
+        reconciled.push(f);
+      }
+    }
+  }
+
+  // Any remaining current violations are new
+  for (const [fp, v] of currentViolationFps.entries()) {
+    reconciled.push(createFinding(v));
+  }
+
+  return reconciled;
+}
+
+/**
+ * Evaluates accepted exceptions against current findings.
+ * If an exception matches the finding fingerprint AND has an identical full contextHash,
+ * it suppresses the blocker (is_blocking: false, status: 'ACCEPTED_EXCEPTION').
+ * If contextHash differs, the exception does NOT suppress and finding remains OPEN / blocking.
+ *
+ * @param {Array<object>} findings
+ * @param {Array<object>} acceptedExceptions
+ * @param {object} currentContext - { upstreamAcceptedPhaseHash, currentComparedPhaseHash, normalizedContractRepresentation }
+ * @returns {Array<object>} Evaluated findings
+ */
+function evaluateAcceptedExceptions(findings = [], acceptedExceptions = [], currentContext = {}) {
+  const currentContextHash = computeContextHash(currentContext);
+
+  const exceptionMap = new Map();
+  for (const ex of acceptedExceptions) {
+    if (ex && ex.fingerprint) {
+      exceptionMap.set(ex.fingerprint, ex);
+    }
+  }
+
+  return findings.map(f => {
+    if (exceptionMap.has(f.fingerprint)) {
+      const ex = exceptionMap.get(f.fingerprint);
+      if (ex.contextHash === currentContextHash) {
+        return {
+          ...f,
+          status: 'ACCEPTED_EXCEPTION',
+          is_blocking: false,
+          exceptionReason: ex.reason || 'Approved exception'
+        };
+      } else {
+        // Context mutated -> exception invalidated
+        return {
+          ...f,
+          status: 'OPEN',
+          is_blocking: true,
+          exceptionInvalidated: true
+        };
+      }
+    }
+    return f;
+  });
+}
+
+/**
+ * Marks findings as SUPERSEDED if associated contracts were formally amended or removed.
+ *
+ * @param {Array<object>} findings
+ * @param {Array<string>} activeContractIds
+ * @returns {Array<object>}
+ */
+function markSupersededFindings(findings = [], activeContractIds = []) {
+  const activeSet = new Set(activeContractIds);
+  return findings.map(f => {
+    if (f.contractId && !activeSet.has(f.contractId)) {
+      return {
+        ...f,
+        status: 'SUPERSEDED',
+        is_blocking: false,
+        superseded_at: new Date().toISOString()
+      };
+    }
+    return f;
+  });
+}
+
+module.exports = {
+  computeFindingFingerprint,
+  formatDisplayFingerprint,
+  createFinding,
+  computeContextHash,
+  reconcileFindings,
+  evaluateAcceptedExceptions,
+  markSupersededFindings
+};

package/src/lib/hasher.js

@@ -0,0 +1,103 @@
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Normalizes content for canonical hashing:
+ * - Checks and rejects UTF-8 BOM by throwing CONTRACT_PARSE_ERROR
+ * - Normalizes CRLF and lone CR to standard LF
+ * Does NOT trim or alter whitespace/markdown/json formatting.
+ *
+ * @param {string} content
+ * @returns {string} normalized string
+ */
+function normalizeContent(content) {
+  if (typeof content !== 'string') {
+    throw new TypeError('Content must be a string');
+  }
+
+  // Reject UTF-8 BOM
+  if (content.charCodeAt(0) === 0xFEFF) {
+    const err = new Error('UTF-8 BOM is forbidden in phase artifacts.');
+    err.code = 'CONTRACT_PARSE_ERROR';
+    throw err;
+  }
+
+  // Normalize newlines: CRLF -> LF, then lone CR -> LF
+  return content.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+}
+
+/**
+ * Computes canonical 64-character lowercase hexadecimal SHA-256 hash of normalized content.
+ *
+ * @param {string} content
+ * @returns {string} 64-char lowercase hex SHA-256
+ */
+function hashContent(content) {
+  const normalized = normalizeContent(content);
+  return crypto.createHash('sha256').update(normalized, 'utf8').digest('hex');
+}
+
+/**
+ * Reads a file as UTF-8 and computes its canonical hash.
+ *
+ * @param {string} filePath
+ * @returns {string} 64-char lowercase hex SHA-256
+ */
+function hashFile(filePath) {
+  const raw = fs.readFileSync(filePath, 'utf8');
+  return hashContent(raw);
+}
+
+const WINDOWS_DRIVE_RE = /^[A-Za-z]:[\\/]/;
+const WINDOWS_UNC_RE = /^\\\\[^\\/]+[\\/][^\\/]+/;
+
+/**
+ * Checks if a path string has Windows structure (drive letter, UNC, or backslashes).
+ *
+ * @param {string} p
+ * @returns {boolean}
+ */
+function isWindowsPath(p) {
+  if (typeof p !== 'string') return false;
+  return WINDOWS_DRIVE_RE.test(p) || WINDOWS_UNC_RE.test(p) || p.includes('\\');
+}
+
+/**
+ * Normalizes file paths to repository-relative POSIX format (using forward slashes '/').
+ * Uses explicit path.win32 or path.posix based on input path flavor rather than host OS.
+ *
+ * @param {string} filePath
+ * @param {string} [rootPath] - optional repository root
+ * @returns {string} normalized POSIX relative path
+ */
+function normalizePath(filePath, rootPath) {
+  if (!filePath) return '';
+  if (!rootPath) {
+    return filePath.replace(/\\/g, '/');
+  }
+
+  const fileIsWindows = isWindowsPath(filePath);
+  const rootIsWindows = isWindowsPath(rootPath);
+
+  const isPosixAbs = (p) => typeof p === 'string' && p.startsWith('/') && !WINDOWS_DRIVE_RE.test(p);
+  if ((fileIsWindows && isPosixAbs(rootPath)) || (isPosixAbs(filePath) && rootIsWindows)) {
+    throw new Error(`Incompatible mixed path flavors: filePath="${filePath}", rootPath="${rootPath}"`);
+  }
+
+  const impl = (fileIsWindows || rootIsWindows) ? path.win32 : path.posix;
+  const rel = impl.relative(rootPath, filePath);
+
+  if (rel.startsWith('..\\') || rel.startsWith('../') || rel === '..') {
+    throw new Error(`Path "${filePath}" is outside root directory "${rootPath}"`);
+  }
+
+  return rel.replace(/\\/g, '/');
+}
+
+module.exports = {
+  normalizeContent,
+  hashContent,
+  hashFile,
+  normalizePath
+};

package/src/lib/state.js

@@ -0,0 +1,143 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Reads .gemstack/state.json with legacy fallback defaults.
+ * Preserves all unknown existing fields.
+ *
+ * @param {string} rootPath - Workspace root path
+ * @returns {object} State object
+ */
+function readState(rootPath) {
+  const statePath = path.join(rootPath, '.gemstack', 'state.json');
+  if (!fs.existsSync(statePath)) {
+    return {
+      version: '0.1',
+      current_phase: null,
+      status: null,
+      stop_reason: null,
+      active_spec: null,
+      completed_phases: [],
+      phase_hashes: null,
+      consistency: null,
+      guard_mode: { careful: false, freeze: false, allowed_paths: [] }
+    };
+  }
+
+  try {
+    const raw = fs.readFileSync(statePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    const { findings, accepted_exceptions, ...cleanParsed } = parsed;
+    return {
+      version: cleanParsed.version || '0.1',
+      current_phase: cleanParsed.current_phase ?? null,
+      status: cleanParsed.status ?? null,
+      stop_reason: cleanParsed.stop_reason ?? null,
+      active_spec: cleanParsed.active_spec ?? null,
+      completed_phases: Array.isArray(cleanParsed.completed_phases) ? cleanParsed.completed_phases : [],
+      phase_hashes: cleanParsed.phase_hashes ?? null,
+      consistency: cleanParsed.consistency ?? null,
+      guard_mode: cleanParsed.guard_mode || { careful: false, freeze: false, allowed_paths: [] },
+      ...cleanParsed // preserve any extra operational fields (excluding findings / accepted_exceptions)
+    };
+  } catch (err) {
+    throw new Error(`Failed to parse .gemstack/state.json: ${err.message}`);
+  }
+}
+
+/**
+ * Writes an object atomically to disk by writing to a temporary file in the same directory
+ * and renaming it over the destination. Bounded retry for Windows locks.
+ *
+ * @param {string} filePath - Absolute path to destination file
+ * @param {object} data - Object to serialize
+ */
+function writeJsonAtomic(filePath, data) {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  const tmpPath = `${filePath}.tmp.${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+  const serialized = JSON.stringify(data, null, 2) + '\n';
+  fs.writeFileSync(tmpPath, serialized, 'utf8');
+
+  // Bounded retry for Windows transient file locks
+  let attempts = 0;
+  const maxAttempts = 5;
+  while (attempts < maxAttempts) {
+    try {
+      fs.renameSync(tmpPath, filePath);
+      return;
+    } catch (err) {
+      attempts++;
+      if (attempts >= maxAttempts) {
+        // cleanup tmp
+        try { fs.unlinkSync(tmpPath); } catch (_) {}
+        throw err;
+      }
+      // Busy wait short sleep
+      const start = Date.now();
+      while (Date.now() - start < 20) {}
+    }
+  }
+}
+
+/**
+ * Writes .gemstack/state.json atomically.
+ * Strips historical findings and accepted_exceptions to enforce persistence boundary.
+ *
+ * @param {string} rootPath - Workspace root path
+ * @param {object} stateObj - State data
+ */
+function writeStateAtomic(rootPath, stateObj) {
+  const statePath = path.join(rootPath, '.gemstack', 'state.json');
+  const { findings, accepted_exceptions, ...operationalState } = stateObj;
+  writeJsonAtomic(statePath, operationalState);
+}
+
+/**
+ * Reads feature sidecar .gemstack.json with safe defaults.
+ *
+ * @param {string} featureDir - Path to specs/<feature>
+ * @returns {object} Sidecar data
+ */
+function readSidecar(featureDir) {
+  const sidecarPath = path.join(featureDir, '.gemstack.json');
+  if (!fs.existsSync(sidecarPath)) {
+    return {
+      phase_hashes: {},
+      historical_findings: [],
+      accepted_exceptions: []
+    };
+  }
+  try {
+    const raw = fs.readFileSync(sidecarPath, 'utf8');
+    return JSON.parse(raw);
+  } catch (err) {
+    return {
+      phase_hashes: {},
+      historical_findings: [],
+      accepted_exceptions: []
+    };
+  }
+}
+
+/**
+ * Writes feature sidecar .gemstack.json atomically.
+ *
+ * @param {string} featureDir - Path to specs/<feature>
+ * @param {object} sidecarObj - Data to write
+ */
+function writeSidecarAtomic(featureDir, sidecarObj) {
+  const sidecarPath = path.join(featureDir, '.gemstack.json');
+  writeJsonAtomic(sidecarPath, sidecarObj);
+}
+
+module.exports = {
+  readState,
+  writeStateAtomic,
+  readSidecar,
+  writeSidecarAtomic,
+  writeJsonAtomic
+};

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]`.