gemstack-ai 1.0.1

package/specs/current/tasks.md

@@ -0,0 +1,98 @@
+# Tareas de Implementación: Gemstack v0.3 (CI/CD & Release Automation)
+
+Este documento contiene el plan de ejecución ejectuable (checklist) para el ciclo v0.3.
+
+---
+
+### Fase 0: Preflight
+- [ ] **T0.1: Asegurar Entorno Limpio**
+  - **Descripción:** Verificar con `git status` que no existan implementaciones previas, archivos colgados, etiquetas recién creadas ni subidas a NPM publicadas.
+  - **Archivos:** Ninguno
+  - **Criterio de Aceptación:** Working tree clean.
+  - **Riesgo:** Bajo.
+  - **Requiere Aprobación Humana:** No.
+
+### Fase 1: `.gitattributes`
+- [ ] **T1.1: Estandarización de Line Endings**
+  - **Descripción:** Crear `.gitattributes` conservador para prevenir fallos de SHA-256 cross-platform. Ejecutar `git status` y pausar si se normaliza excesivamente.
+  - **Archivos:** `.gitattributes`
+  - **Criterio de Aceptación:** Archivo creado. El Churn de EOL no debe romper archivos binarios.
+  - **Riesgo:** Alto (Normalización masiva o corrupción de binarios si las reglas son muy globales).
+  - **Requiere Aprobación Humana:** **SÍ** (Si `git status` muestra más de 10 archivos modificados únicamente por EOL).
+
+### Fase 2: `scripts/ci/`
+- [ ] **T2.1: Validadores Nativos Zero-Deps**
+  - **Descripción:** Implementar validadores de calidad.
+    1. `check-frontmatter.js`: Revisa formato YAML en `.agents/skills/*/SKILL.md`.
+    2. `check-template-clean.js`: Revisa ausencia de contexto privado y secretos en `template/`.
+    3. `check-mojibake.js`: Busca caracteres rotos en UTF-8 (ej: `Ã`).
+    4. `check-package-contents.js`: Realiza inspección tras `npm pack --dry-run`.
+    5. `smoke-cli.js`: Prueba programática (e2e) en directorios temporales de todas las ramas del CLI (`help`, `doctor`, `init`, `update`).
+  - **Archivos:** `scripts/ci/*.js`
+  - **Criterio de Aceptación:** Cross-platform (Win/Mac/Linux), cero dependencias externas de npm.
+  - **Riesgo:** Moderado (Incompatibilidad en spawns de child processes en Windows vs Unix).
+  - **Requiere Aprobación Humana:** No.
+
+### Fase 3: Package Scripts
+- [ ] **T3.1: Configuración de npm run alias**
+  - **Descripción:** Extender el bloque `scripts` en `package.json` insertando `ci:frontmatter`, `ci:template`, `ci:mojibake`, `ci:package`, `ci:smoke` y un atajo `ci:all`.
+  - **Archivos:** `package.json`
+  - **Criterio de Aceptación:** Ejecutar `npm run ci:all` lanza secuencialmente la batería de checks.
+  - **Riesgo:** Bajo.
+  - **Requiere Aprobación Humana:** No.
+
+### Fase 4: Workflow `pr-ci.yml`
+- [ ] **T4.1: CI Eficiente para Pull Requests**
+  - **Descripción:** Workflow rápido basado en Ubuntu con Matrix en Node 18 y 20. Ejecuta las validaciones `ci:all`, `npm test` y el smoke test de la `demo-app`.
+  - **Archivos:** `.github/workflows/pr-ci.yml`
+  - **Criterio de Aceptación:** El YAML es sintácticamente válido para Actions y optimiza el uso de CPU.
+  - **Riesgo:** Bajo.
+  - **Requiere Aprobación Humana:** No.
+
+### Fase 5: Workflow `main-ci.yml`
+- [ ] **T5.1: CI Exhaustivo para la Rama Principal**
+  - **Descripción:** Se lanza tras merges y pushes a `main`. Emplea una Matrix completa (Windows, macOS, Ubuntu) en Node 18 y 20.
+  - **Archivos:** `.github/workflows/main-ci.yml`
+  - **Criterio de Aceptación:** Todos los tests y utilidades CI se mapean multiplataforma de forma estricta.
+  - **Riesgo:** Medio (Desviación en OS, comandos bash que fallen en el runner de Windows).
+  - **Requiere Aprobación Humana:** No.
+
+### Fase 6: Workflow `release-readiness.yml`
+- [ ] **T6.1: Generación y Validación de Tarball Manual**
+  - **Descripción:** Trigger exclusivo `workflow_dispatch`. Realiza un test cross-platform donde genera un `.tgz`, levanta un proyecto vacío en otra carpeta temporal, lo instala con NPM y realiza comprobaciones unitarias `npx gemstack` reales de punta a punta. Sube el `.tgz` como artefacto final.
+  - **Archivos:** `.github/workflows/release-readiness.yml`
+  - **Criterio de Aceptación:** NO efectúa tags, NPM publish, ni GitHub Releases automáticamente.
+  - **Riesgo:** Medio (Estructura de logs pesada o fallo en instalación del paquete local del tarball).
+  - **Requiere Aprobación Humana:** No.
+
+### Fase 7: Documentación
+- [ ] **T7.1: Badge CI y Notas**
+  - **Descripción:** Agregar badge de CI a la cabecera de `README.md`. Preparar borrador de notas en `RELEASE_NOTES.md` o `CHANGELOG.md` describiendo la infraestructura CI.
+  - **Archivos:** `README.md`, `CHANGELOG.md`, `docs/release.md`
+  - **Criterio de Aceptación:** Información asertiva y documentada.
+  - **Riesgo:** Bajo.
+  - **Requiere Aprobación Humana:** No.
+
+### Fase 8: Validación Local
+- [ ] **T8.1: Prueba del Suite Completo Local**
+  - **Descripción:** Correr `npm test`, `npm run ci:all`, comprobar si `demo-app` no sufre regresiones.
+  - **Archivos:** Ninguno.
+  - **Criterio de Aceptación:** Todos los scripts retornan un exit code `0`. Sin archivos `temp` huérfanos residuales.
+  - **Riesgo:** Medio (Tiempos de ejecución o errores no controlados si fallan limpiezas `tmp`).
+  - **Requiere Aprobación Humana:** **SÍ** (Aprobación si se detectan anomalías de basura en disco).
+
+### Fase 9: Revisión de Seguridad y QA Agentic
+- [ ] **T9.1: Emulación de Audits `/review` y `/cso`**
+  - **Descripción:** Evaluar los workflows implementados contra vulnerabilidades (Supply Chain, Secret Leaks, Privilegios del GITHUB_TOKEN). Actualizar los docs.
+  - **Archivos:** `docs/reviews/latest-review.md`, `docs/security/latest-security-audit.md`
+  - **Criterio de Aceptación:** Análisis honesto registrando deficiencias o limitantes de la CI.
+  - **Riesgo:** Bajo.
+  - **Requiere Aprobación Humana:** No.
+
+### Fase 10: Commit, Push y Handoff
+- [ ] **T10.1: Integración Final**
+  - **Descripción:** Confirmar árbol limpio mediante `git status -u`. Efectuar commit, push e incorporar memoria al `handoff.md`. Push final.
+  - **Archivos:** `handoff.md`
+  - **Criterio de Aceptación:** Sin rastros de builds. Versionado estable listo para activar en GitHub Actions.
+  - **Riesgo:** Bajo.
+  - **Requiere Aprobación Humana:** **SÍ** (Confirmar antes de commit y push).

package/specs/templates/plan.md

@@ -0,0 +1,38 @@
+# Plan de Implementación: [FEATURE]
+
+**Feature Branch**: `[###-feature-name]` | **Spec**: [ruta al spec.md]
+
+## 1. Summary & Technical Context
+- **Lenguaje/Versión**: [Ej. Node 18+ o NEEDS CLARIFICATION]
+- **Dependencias core**: [Ej. Express o NEEDS CLARIFICATION]
+- **Restricciones**: [Ej. Zero-deps en runtime]
+
+## 2. Constitution Check (Phase -1 Gates)
+<!-- VERIFICACIÓN DE REGLAS INMUTABLES -->
+### Simplicity Gate (Article VII)
+- [ ] ¿Se usan el mínimo número de carpetas/archivos posibles?
+- [ ] ¿No hay abstracciones prematuras (future-proofing)?
+
+### Anti-Abstraction Gate (Article VIII)
+- [ ] ¿Se usan las APIs nativas del framework sin wrappers innecesarios?
+
+### Test-First Imperative (Article III)
+- [ ] ¿El plan incluye la creación de tests antes que el código fuente?
+
+## 3. Entregables Satélites a Generar
+<!-- Además de este plan y las tareas, se deben documentar los siguientes si aplica: -->
+- `research.md`: [Opcional - Análisis de herramientas]
+- `data-model.md`: [Esquemas de datos y entidades]
+- `contracts/`: [Documentación de APIs y contratos (REST/Interfaces)]
+- `quickstart.md`: [Guía rápida de validación manual]
+
+## 4. Estructura de Archivos a Modificar / Crear
+```text
+ruta/archivo: [Razón]
+```
+
+## 5. Complexity Tracking
+<!-- Llenar SÓLO si las Gates de la Constitución fallan y se requiere justificar complejidad -->
+| Violación de Regla | Por qué es necesario | Alternativa simple rechazada por |
+|--------------------|----------------------|-----------------------------------|
+| [Ej. Wrapper]      | [Razón]              | [Razón]                           |

package/specs/templates/spec.md

@@ -0,0 +1,35 @@
+# Especificación de Funcionalidad: [NOMBRE_FEATURE]
+
+**Feature Branch**: `[###-feature-name]`
+
+## 1. User Scenarios & Testing (MVP)
+<!--
+  IMPORTANTE: Las historias de usuario deben estar PRIORIZADAS (P1, P2...).
+  Cada historia debe ser INDEPENDIENTEMENTE TESTEABLE, aportando un fragmento de valor MVP.
+-->
+### User Story 1 - [Título breve] (Prioridad: P1)
+[Describe el viaje del usuario en lenguaje claro]
+**Por qué esta prioridad:** [Valor que aporta]
+**Test Independiente:** [Cómo se prueba de forma autónoma]
+
+**Escenarios de Aceptación:**
+1. **Dado** [estado], **Cuando** [acción], **Entonces** [resultado]
+
+## 2. Requerimientos Funcionales
+<!--
+  Anota requerimientos explícitos.
+  SI HAY AMBIGÜEDAD, NO ADIVINES. Usa: [NEEDS CLARIFICATION: tu pregunta]
+-->
+- **FR-001**: El sistema DEBE [capacidad]
+- **FR-002**: [NEEDS CLARIFICATION: método de implementación no definido]
+
+## 3. Criterios de Éxito (Measurable Outcomes)
+<!-- Definir métricas que no dependan de la tecnología -->
+- **SC-001**: [Métrica medible, ej. El proceso termina en < 2 seg]
+
+## 4. Casos Extremos (Edge Cases)
+- ¿Qué pasa cuando [condición de borde]?
+
+## 5. Entidades Clave (Data / Models)
+- **[Entidad 1]**: [Representación abstracta]
+- **[Entidad 2]**: [Relación]

package/specs/templates/tasks.md

@@ -0,0 +1,21 @@
+# Tareas de Implementación
+
+<!--
+  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.
+-->
+
+## Fase 1: Tests (Test-First Imperative)
+- [ ] 1.1 Redactar Unit Tests para [Módulo A].
+- [ ] 1.2 [P] Redactar Tests de Contrato/API para [Contrato B].
+- [ ] 1.3 Comprobar que los tests fallen (Fase Roja).
+
+## Fase 2: Implementación
+- [ ] 2.1 Implementar [Módulo A] para hacer pasar 1.1.
+- [ ] 2.2 [P] Implementar [Controlador B] para hacer pasar 1.2.
+
+## Fase 3: Integración y Validación
+- [ ] 3.1 Integrar módulos.
+- [ ] 3.2 Ejecutar suite de validación completa.
+- [ ] 3.3 Revisión de seguridad y dependencias.

package/specs/v0.2-cli-distribution/plan.md

@@ -0,0 +1,112 @@
+# Plan Técnico: Gemstack v0.2 (CLI Distribution)
+
+## 1. Arquitectura Propuesta
+Gemstack se convertirá en una herramienta de CLI empaquetable vía NPM. El código se reestructurará aislando la lógica de la herramienta de CLI (`src/`) de los activos del framework (`template/`). Al instalarse e invocarse (`gemstack init`), el CLI usará la carpeta `template/` como fuente de verdad para inyectar los archivos de forma idempotente y segura en el repositorio destino.
+
+## 2. Estructura de Carpetas
+El repositorio Gemstack mutará a esta forma:
+```text
+src/
+  cli.js
+  commands/
+    init.js
+    update.js
+    doctor.js
+    list.js
+    show.js
+  lib/
+    copy-template.js
+    manifest.js
+    backup.js
+    filesystem-safe.js
+    gitignore.js
+    logger.js
+    paths.js
+template/
+  .agents/
+  .gemstack/
+  specs/
+  docs/
+  handoff.md
+  handoff_archive.md
+package.json
+```
+
+## 3. Cambios al package.json
+Se expondrá el ejecutable de forma global/local en NPM agregando:
+```json
+"bin": {
+  "gemstack": "src/cli.js"
+}
+```
+
+## 4. Comandos CLI
+- `gemstack init [--dry-run] [--yes] [--target <path>]`: Inyecta la estructura base de Gemstack de forma segura sin borrar archivos custom.
+- `gemstack update [--dry-run] [--yes] [--force]`: Sincroniza los archivos Gemstack-owned con la nueva versión del template local.
+- `gemstack doctor`: Revisa la salud de la instalación actual usando `.gemstack/manifest.json`.
+- `gemstack list`: Muestra los skills detectados en el repo destino.
+- `gemstack show <skill>`: Imprime el contenido de un skill en pantalla.
+
+## 5. Estrategia del Template
+Todos los archivos nativos (skills, reglas, docs) se almacenarán internamente en la carpeta `template/`. Durante un comando `init` o `update`, la herramienta usará `fs` recursivo mapeando `template/` -> `<target-dir>/`.
+
+## 6. Estrategia de Manifest
+Para rastrear qué pertenece a Gemstack y qué es custom del usuario, existirá un archivo `.gemstack/manifest.json` en el repositorio destino:
+```json
+{
+  "version": "0.2.0",
+  "installedAt": "2026-08-19T12:00:00Z",
+  "files": [
+    { "path": ".agents/rules/01-gemstack-core.md", "checksum": "abc123hash" }
+  ]
+}
+```
+
+## 7. Estrategia de Backups
+Toda operación destructiva o de overwrite sobre un archivo Gemstack-owned generará primero una copia en `.gemstack/backups/<timestamp>/`. Se acompañará con un `manifest.json` interno del backup indicando archivo original, comando que provocó el backup (`update` o `init --force`), fecha y motivo.
+
+## 8. Algoritmo de Inicialización (`init`)
+1. Determinar el directorio target (pwd o `--target`).
+2. Iterar sobre los archivos en `template/`.
+3. Si el archivo destino NO existe, copiarlo.
+4. Si el archivo destino SÍ existe:
+   - Si es `handoff.md`, `handoff_archive.md`, o `learnings.md`, ignorar (SKIP).
+   - Si es un skill `.agents/skills/gemstack-*`, verificar checksums/conflictos. Pedir confirmación o respaldar, según flags.
+5. Inyectar silenciosamente el manifiesto `.gemstack/manifest.json`.
+6. Actualizar `.gitignore` leyendo bloques existentes. Si no está Gemstack, agregar marcador `# Gemstack` y las exclusiones (`.gemstack/state.json`, `.gemstack/backups/`).
+
+## 9. Algoritmo de Actualización (`update`)
+1. Leer `.gemstack/manifest.json` destino.
+2. Comparar el checksum local vs el checksum del `template/` interno de Gemstack.
+3. Si difiere:
+   - **Gemstack-owned:** Preparar backup. Reemplazar.
+   - **No-Gemstack (Modificado por User):** Alertar. Omitir, a menos que se use `--force`.
+4. Mostrar listado pre-aplicación si está en `--dry-run`.
+5. Si no es dry-run, ejecutar los Backups -> Copiar archivos -> Actualizar manifest.
+
+## 10. Algoritmo de Doctor
+1. Validar existencia del `manifest.json`.
+2. Validar que los archivos marcados en el manifest existan realmente en disco.
+3. Validar presencia de entradas Gemstack en `.gitignore`.
+4. Emitir reportes `[OK]`, `[WARN]`, `[ERROR]`.
+
+## 11. Seguridad y Path Safety
+La función `filesystem-safe.js` usará `path.resolve` y `path.normalize` comparando siempre que el subdirectorio final inicie estrictamente con el `TARGET_DIR`. (Ej. `if (!resolvedPath.startsWith(targetDir)) throw Error("Path Traversal Bloqueado")`). Prohibida la ejecución de comandos externos (`exec`, `spawn` del SO). Todo debe ser `fs` en Node nativo.
+
+## 12. Plan de Pruebas (Tests)
+Usaremos el test-runner nativo de Node.js o Jest (si es permitido, sino zero-deps assertions).
+- `init` en vacía y en carpeta con `.agents/` preexistente.
+- `update` con y sin archivos modificados.
+- Confirmación de generación correcta del `manifest.json` y `backups`.
+- Bloqueo explícito de path traversal con payloads maliciosos (`../../`).
+
+## 13. Migración v0.1 a v0.2
+Usuarios que clonaron v0.1 pueden recibir v0.2 ejecutando `npx gemstack@latest update --force` que mapeará los archivos anteriores usando el nuevo sistema de manifiesto, sin tocar su `handoff.md`.
+
+## 14. Riesgos
+1. Desincronización del Manifest si el usuario modifica los archivos manualmente usando git o su IDE. (Se mitiga comparando checksum actual del archivo contra el checksum registrado en el manifest antes de hacer update).
+2. Complejidad en la resolución de dependencias relativas si se ejecuta el CLI globalmente (`npm install -g gemstack`). Node debe poder encontrar `template/` relativo a `__dirname` del paquete global.
+
+## 15. Decisiones Pendientes (Next Steps)
+- Se requiere aprobación de la arquitectura y el algoritmo de overwrite/backup.
+- Definir si se permitirá la adición de librerías de utilidad (ej. `commander` para los flags, `chalk` para colores) o si el CLI debe ser estricto "zero-dependencies".

package/specs/v0.2-cli-distribution/spec.md

@@ -0,0 +1,27 @@
+# Especificación de Funcionalidad: Gemstack v0.2 (Distribución)
+
+## 1. Idea / Requerimiento
+Evolucionar Gemstack de un repositorio "copiable" (template) a una herramienta distribuible e instalable de manera sencilla en cualquier proyecto existente. El objetivo principal es proveer un comando (`gemstack init`) que aplique el scaffolding de `.agents`, `specs`, `docs` y CLI helpers sin destruir configuraciones previas del usuario.
+
+## 2. Estrategia de Distribución Evaluada
+1. **Paquete NPM (`npx gemstack init`)**: Ideal, ya que el ecosistema Antigravity y gran parte de los usuarios usan Node.js. Permite empaquetar assets fácilmente y manejar el binario de forma nativa en Windows y Unix.
+2. **Scripts Nativos (`curl` / `Invoke-WebRequest`)**: Para proyectos no-Node (ej. Python, Go). Descarga un archivo `.tar.gz` de la release de GitHub y lo extrae.
+*Decisión recomendada:* Priorizar NPM (`npx gemstack@latest init`) como vía principal y mantener un script `install.ps1/sh` como fallback.
+
+## 3. Criterios de Aceptación
+- [ ] **Empaquetado Seguro**: El CLI de distribución contiene una carpeta `templates/` con los 13 skills, reglas y docs.
+- [ ] **Comando `init` Inteligente**: Al ejecutar `gemstack init` en un proyecto nuevo, se copia la estructura base.
+- [ ] **Protección de Overwrite (Idempotencia)**: Si el proyecto ya tiene `.agents/`, `handoff.md` o `specs/`:
+  - No sobrescribir nunca `handoff.md` o `handoff_archive.md`.
+  - Crear backups de archivos colisionantes (ej. `01-gemstack-core.md.bak`) o tener una política de `skip` por defecto con flag `--force`.
+- [ ] **CLI Unificado**: Mantener soporte para Windows (`.ps1`) y Unix (`bash`), gestionado preferiblemente por el engine binario de NPM o instaladores binarios.
+- [ ] **Nuevos Comandos CLI**: Añadir comando `update` para actualizar los skills locales a la última versión del framework.
+
+## 4. Tests y QA
+- [ ] **Unit Tests del CLI**: Tests locales usando `fs` (ej. en un entorno virtual) para validar que `init` no borra archivos, crea directorios faltantes, y hace los backups correctos.
+- [ ] **Routing Tests**: Scripts que simulan los prompts de Antigravity para verificar que la regla `01-gemstack-core.md` sigue matcheando los 26 comandos correctamente.
+
+## 5. Riesgos y Seguridad
+- **Pérdida de Datos:** Un bug en el comando `init` que sobrescriba el código fuente o los prompts customizados del usuario dentro de `.agents/`.
+- **Supply Chain:** Publicar un paquete en NPM conlleva el riesgo de compromiso de cuenta.
+- **Rutas Relativas:** Bugs en la resolución de directorios (ej. crear los archivos en el global de la máquina en lugar de la raíz del proyecto).

package/specs/v0.2-cli-distribution/tasks.md

@@ -0,0 +1,115 @@
+# Tareas de Implementación: Gemstack v0.2 (CLI Distribution)
+
+Este documento contiene el plan de ejecución ejecutable (checklist) para el ciclo v0.2.
+
+---
+
+### Fase 0: Safeguards y Preparación
+- [ ] **T0.1: Asegurar Entorno Base**
+  - **Descripción:** Verificar el estado de git (working tree clean), confirmar que Node 18+ está disponible, y configurar el `package.json` con `"engines": { "node": ">=18.18.0" }`. Asegurar estatus No-Publish/No-Tag.
+  - **Archivos:** `package.json`
+  - **Criterio de Aceptación:** Configurado sin dependencias externas en `dependencies`, versión 0.2.0-draft u omitida.
+  - **Riesgo:** Bajo.
+  - **Requiere Aprobación Humana:** No.
+
+### Fase 1: Estructura `template/`
+- [ ] **T1.1: Crear Carpeta Template**
+  - **Descripción:** Crear directorio `template/` y poblarlo con los skills y reglas estándar de `.agents/` del repositorio, omitiendo contenido custom o contexto privado de esta sesión.
+  - **Archivos:** `template/.agents/*`
+  - **Criterio de Aceptación:** Estructura clonada limpiamente sin borrar los `.agents` de la raíz del repo original.
+  - **Riesgo:** Bajo.
+  - **Requiere Aprobación Humana:** No.
+- [ ] **T1.2: Inicializar Placeholders**
+  - **Descripción:** Crear versiones limpias (placeholders) de `handoff.md`, `handoff_archive.md`, `.gemstack/learnings.md`, `.gemstack/state.json`, `specs/current/` (vacíos o con base) dentro de `template/`.
+  - **Archivos:** `template/handoff.md`, etc.
+  - **Criterio de Aceptación:** Los archivos reflejan estados "zero" sin historial privado del repo `Gemstack`.
+  - **Riesgo:** Moderado (riesgo de fugas de privacidad si se copia el handoff real).
+  - **Requiere Aprobación Humana:** No.
+
+### Fase 2: CLI Core Zero-Deps
+- [ ] **T2.1: Entrypoint y Parser**
+  - **Descripción:** Crear `src/cli.js` y parsear manualmente `process.argv` para soportar flags como `--dry-run`, `--yes`, `--target`, `--force`. Añadir un logger seguro (ASCII, sin moijibakes).
+  - **Archivos:** `src/cli.js`, `src/lib/logger.js`, `src/lib/parser.js`
+  - **Criterio de Aceptación:** Parser soporta los flags requeridos sin arrojar errores o requerir paquetes externos. Logger imprime `[OK]`, `[INFO]`, `[FAIL]`.
+  - **Riesgo:** Moderado (bugs de parsing de CLI manuales son comunes).
+  - **Requiere Aprobación Humana:** No.
+
+### Fase 3: Filesystem Safety
+- [ ] **T3.1: Path Safety**
+  - **Descripción:** Desarrollar librería nativa para prevenir directory traversals y operaciones inseguras (symlinks peligrosos).
+  - **Archivos:** `src/lib/filesystem-safe.js`
+  - **Criterio de Aceptación:** Toda escritura es analizada usando `path.resolve` e interrumpe con error si sale del target. No hay usos de `child_process.exec` para I/O.
+  - **Riesgo:** Crítico (Riesgo de seguridad para el host).
+  - **Requiere Aprobación Humana:** No.
+
+### Fase 4: Manifest
+- [ ] **T4.1: Mecanismo de Ownership**
+  - **Descripción:** Desarrollar generador de `.gemstack/manifest.json`. Rastrear archivos Gemstack-owned y generar un checksum (MD5 o SHA256 usando el módulo nativo `crypto`).
+  - **Archivos:** `src/lib/manifest.js`
+  - **Criterio de Aceptación:** Puede parsear manifiestos existentes, generar nuevos y evaluar si un archivo mutó desde la última ejecución. Solo marca los propios.
+  - **Riesgo:** Alto (Falsa detección de mutaciones puede asustar al usuario).
+  - **Requiere Aprobación Humana:** No.
+
+### Fase 5: Backup
+- [ ] **T5.1: Gestor de Respaldo Seguro**
+  - **Descripción:** Desarrollar creador automático de `.gemstack/backups/<timestamp>/manifest.json` y carpetas de copia física antes de sobrescribir. Evitar logging del contenido en pantalla.
+  - **Archivos:** `src/lib/backup.js`
+  - **Criterio de Aceptación:** Las colisiones previas a un over-write terminan copiadas intactas aquí. El log en consola solo menciona el PATH.
+  - **Riesgo:** Alto (Errores aquí conllevan data loss irrecuperable).
+  - **Requiere Aprobación Humana:** No.
+
+### Fase 6: Comando `init`
+- [ ] **T6.1: Lógica de Inicialización**
+  - **Descripción:** Crear `src/commands/init.js`. Copia el framework desde `template/` usando la safety layer. Responde dinámicamente a `--dry-run` y `--target`. Patch a `.gitignore` sin duplicar.
+  - **Archivos:** `src/commands/init.js`, `src/lib/gitignore.js`
+  - **Criterio de Aceptación:** No sobrescribe NADA custom. Evita `handoff.md` si ya existe. Marca bloques `# Gemstack` en `gitignore`.
+  - **Riesgo:** Alto.
+  - **Requiere Aprobación Humana:** No.
+
+### Fase 7: Comando `update`
+- [ ] **T7.1: Lógica de Sincronización Segura**
+  - **Descripción:** Crear `src/commands/update.js`. Usa el manifest para sincronizar. Fuerza backup antes de reemplazar. Protege `handoff.md` explícitamente. Usa `--force` para saltarse rechazos en archivos drifteados.
+  - **Archivos:** `src/commands/update.js`
+  - **Criterio de Aceptación:** Nunca reemplaza código ajeno al manifest. Maneja bien `--dry-run`.
+  - **Riesgo:** Alto (Destructivo si el safety falla).
+  - **Requiere Aprobación Humana:** No.
+
+### Fase 8: Comandos Auxiliares
+- [ ] **T8.1: Portar Scripts Bash/PS a Node.js**
+  - **Descripción:** Recrear `list.js`, `show.js` y `doctor.js` de la v0.1 leyendo los archivos instalados localmente.
+  - **Archivos:** `src/commands/list.js`, `src/commands/show.js`, `src/commands/doctor.js`
+  - **Criterio de Aceptación:** Operan de manera cross-platform 100% nativa.
+  - **Riesgo:** Bajo.
+  - **Requiere Aprobación Humana:** No.
+
+### Fase 9: Pruebas `node:test`
+- [ ] **T9.1: Testing Exhaustivo (Zero Deps)**
+  - **Descripción:** Implementar suite en `tests/`. Cubrir todos los requerimientos críticos (Path Traversal Bloqueado, Init idempotente, Backup existoso, Dry-Run no muta).
+  - **Archivos:** `tests/init.test.js`, `tests/update.test.js`, `tests/safety.test.js`
+  - **Criterio de Aceptación:** 100% Passing tests.
+  - **Riesgo:** Medio (Asegurar que los mocks de fs temp sean limpios).
+  - **Requiere Aprobación Humana:** No.
+
+### Fase 10: Documentación
+- [ ] **T10.1: Actualizar Docs de Distribución**
+  - **Descripción:** Documentar uso vía NPM (Link/Pack). Escribir Draft de Release Notes para futura v0.2.
+  - **Archivos:** `README.md`, `docs/release.md`
+  - **Criterio de Aceptación:** Instrucciones claras advirtiendo que `npm publish` no está habilitado todavía, pero puede usarse `npm pack`.
+  - **Riesgo:** Bajo.
+  - **Requiere Aprobación Humana:** No.
+
+### Fase 11: Validation
+- [ ] **T11.1: Verificación End-to-End Local**
+  - **Descripción:** Correr `npm test`. Usar `npm pack` y luego instalar ese pack local en una carpeta temporal con un dummy. Validar el CLI desde fuera.
+  - **Archivos:** Ninguno
+  - **Criterio de Aceptación:** Empaquetado Node funciona sin emitir warnings de symlinks rotos, todos los tests pasan local.
+  - **Riesgo:** Bajo.
+  - **Requiere Aprobación Humana:** **SÍ (Aprobación del dev sobre el resultado reportado).**
+
+### Fase 12: Commit, Push y Handoff
+- [ ] **T12.1: Finalización Segura**
+  - **Descripción:** Validar `git status` (no logs, node_modules ni tarballs), hacer Commit, Push y actualizar Handoff Final de Sesión.
+  - **Archivos:** `handoff.md`
+  - **Criterio de Aceptación:** Working tree limpio, versionado correcto.
+  - **Riesgo:** Bajo.
+  - **Requiere Aprobación Humana:** **SÍ (Se requiere confirmación para commit y fin).**

package/specs/v0.3-ci-cd/plan.md

@@ -0,0 +1,83 @@
+# Plan Técnico: Gemstack v0.3 (CI/CD & Release Automation)
+
+## 1. Arquitectura de Workflows
+El sistema de CI/CD constará de dos archivos YAML independientes en `.github/workflows/`:
+1. `ci.yml`: Encargado de la validación continua para proteger la rama principal (`main`).
+2. `release.yml`: Encargado del empaquetado, pruebas reales sobre el tarball y preparación de release artifacts (solo manual).
+
+## 2. Jobs, Triggers y Matrix Strategy
+
+### A. CI Workflow (`ci.yml`)
+- **Triggers:** `push` a ramas (idealmente con target main) y `pull_request`.
+- **Estrategia Matrix Condicional:**
+  - **Quick-CI Job:** Se dispara en `pull_request` y `push` normal. Matrix: `ubuntu-latest`, Node `[18.x, 20.x]`.
+  - **Full-CI Job:** Se dispara solo en `push` directo a `main`. Matrix: `[ubuntu-latest, windows-latest, macos-latest]`, Node `[18.x, 20.x]`.
+- **Pasos:** Checkout -> Setup Node -> Run CI Scripts -> Run Native Tests -> Run Demo App Smoke.
+
+### B. Release Readiness Workflow (`release.yml`)
+- **Trigger:** `workflow_dispatch` (Manual).
+- **Matrix:** `[ubuntu-latest, windows-latest]`, Node `[20.x]`.
+- **Pasos:** Checkout -> Setup Node -> Tests & CI Scripts -> `npm pack` -> Test Dummy Tarball -> Upload Artifact (`gemstack-*.tgz`).
+- **Restricción Estricta:** NO habrá paso de `npm publish` ni tag automation.
+
+## 3. Scripts CI Propuestos (`scripts/ci/`)
+Se implementarán 5 scripts Zero-Deps nativos de Node.js que fallarán la ejecución (`process.exit(1)`) si se violan las reglas:
+
+1. **`check-frontmatter.js`**: Lee `.agents/skills/*/SKILL.md`. Parsea el bloque YAML superior delimitado por `---`. Valida propiedades requeridas (`name`, `description`, `triggers` como array no vacío) y que el `name` coincida con el nombre del directorio padre.
+2. **`check-template-clean.js`**: Revisa recursivamente `template/`. Valida que `handoff.md` tenga las 5 secciones, `state.json` no tenga flags privadas. Asegura la total ausencia de `node_modules`, `sqlite`, `tgz`, `.gemstack/backups/` o archivos ajenos.
+3. **`check-mojibake.js`**: Analiza todos los textos y scripts en búsqueda exclusiva de cadenas asociadas a error UTF-8 como `Ã`, `Â`, `âœ`, `ðŸ`, y el replacement character ``. Permite acentos normativos en español (`áéíóúñ`).
+4. **`check-package-contents.js`**: Llama a `npm pack --dry-run --json` o parsea la salida de consola, garantizando la inclusión de `src/`, `template/`, `README.md`, `LICENSE`, `CHANGELOG.md`, `package.json`, y la omisión estricta de bases de datos de la demo o configuraciones de github.
+5. **`smoke-cli.js`**: Recrea programáticamente el uso real. Crea un temp dir con `fs.mkdtempSync`, ejecuta llamadas a `node src/cli.js` probando `--help`, `list`, `show`, `doctor`, `init --dry-run`, `init --yes` y `update --dry-run`.
+
+## 4. Manejo de Line Endings
+Se añadirá un `.gitattributes` conservador para forzar terminaciones en el checkout y commit, protegiendo los hashes SHA-256 de ser adulterados por Git en Windows:
+```text
+* text=auto
+*.js text eol=lf
+*.json text eol=lf
+*.md text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+*.sh text eol=lf
+*.ps1 text eol=crlf
+*.bat text eol=crlf
+*.cmd text eol=crlf
+
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.sqlite binary
+*.db binary
+*.tgz binary
+*.zip binary
+```
+
+## 5. Tarball Validation (`release.yml`)
+1. Generar `.tgz` con `npm pack`.
+2. Crear un temp dir (fuera del workspace de github).
+3. `cd temp-dir && npm init -y && npm install <path-to-tgz>`.
+4. Ejecutar comandos `npx gemstack` (`--help`, `init`, `doctor`, `update`).
+5. Tras el test exitoso, subir el `.tgz` con la acción `actions/upload-artifact`.
+
+## 6. Demo-app Smoke Strategy
+Un job independiente o un step correrá:
+`cd demo-app && npm install && npm run smoke`. Confirmará la salida exitosa del servidor y su bloqueo IDOR, validando que cambios genéricos en el framework no han roto la app de referencia.
+
+## 7. README Badge Strategy
+Se ubicará un badge oficial estándar en `README.md`, inmediatamente debajo del título principal, enrutado al action de CI de `main`.
+
+## 8. Seguridad, Secrets y Logging
+- Se forzará la asignación de permisos `permissions: contents: read` en los Workflows para prevenir writes accidentales al repositorio por cuenta del GITHUB_TOKEN.
+- Los logs limitarán las salidas de variables de entorno u operacionales. No se invocarán scripts que tiren volcados de memoria masivos.
+
+## 9. Test Plan
+- Se creará un branch temporal para probar empíricamente los flujos de GitHub actions (`ci.yml`) insertando fallos intencionales (ej. introducir un mojibake adrede) y observando el bloqueo, para finalmente revertir y subir limpio.
+
+## 10. Riesgos Principales
+1. **Conflicto Line Endings Activos:** Instaurar un `.gitattributes` retrospectivo forzará la re-normalización del repo si hay archivos existentes en CRLF. Esto podría generar diffs falsos la próxima vez que se haga checkout.
+2. **Dependencias del Smoke CLI:** El script de humo interactuando con procesos hijos en Windows puede quedar huérfano (zombie) si los subprocesos de Node no se terminan limpiamente tras error.
+
+## 11. Decisiones Pendientes antes de /tasks
+- **Implementación Matrix Condicional:** En GitHub Actions no se puede tener un array matricial "dinámico" trivial. Lo más limpio es dividir `ci.yml` en dos flujos/jobs explícitos: un Workflow para PRs (Ubuntu) y otro Workflow para Pushes (Full Matrix). ¿Autorizas crear dos YAMLs (`pr-ci.yml` y `main-ci.yml`) o mantenemos un solo YAML con jobs condicionados mediante `if: github.event_name == 'pull_request'`?

package/specs/v0.3-ci-cd/spec.md

@@ -0,0 +1,57 @@
+# Spec: Gemstack v0.3 (CI/CD & Release Automation)
+
+## 1. Goal
+Diseñar e implementar un sistema robusto de integración y entrega continua (CI/CD) utilizando GitHub Actions para validar y proteger la calidad de Gemstack en cada cambio, asegurando compatibilidad multiplataforma y previniendo el filtrado accidental de secretos o contextos privados, todo esto sin habilitar despliegues automatizados no supervisados (ej. `npm publish`).
+
+## 2. Core Requirements
+
+### 2.1. Workflows
+Se dividirán las responsabilidades lógicas en, idealmente, dos flujos:
+1. **CI Normal (Push / PR):** Validaciones exhaustivas que bloquean la integración de código roto o contaminado.
+2. **Release Readiness (Workflow Dispatch):** Flujo de preparación manual que empaca el proyecto y potencialmente crea un GitHub Release, pero que bajo ninguna circunstancia ejecuta `npm publish`.
+
+### 2.2. Matrix Testing
+- **Sistemas Operativos:** `ubuntu-latest`, `windows-latest`, `macos-latest`.
+- **Node.js Versions:** `18.18.0` (mínimo exigido) y `20.x` (LTS actual) / `22.x` (Latest).
+
+### 2.3. CI Validation Steps (Checks)
+- **Unit & Packaging Tests:**
+  - `npm test` (pruebas nativas).
+  - `npm run pack:dry` (validación del bundle).
+- **CLI Smoke Tests (Cross-platform):**
+  - `node src/cli.js --help`
+  - `node src/cli.js list`
+  - `node src/cli.js show gemstack-handoff`
+  - `node src/cli.js init --dry-run --target <temp-dir>`
+  - `node src/cli.js init --yes --target <temp-dir>`
+  - `node src/cli.js update --dry-run --target <temp-dir>`
+- **Demo App Verification:**
+  - `cd demo-app && npm install`
+  - `npm run smoke` (valida defensas anti-IDOR).
+- **Cleanliness & Integrity Assertions:**
+  - **No Forbidden Files:** Asegurar que el repo (y el paquete) no contengan `node_modules`, `*.sqlite`, `*.tgz`, backups (`.gemstack/backups/`) o archivos temporales no ignorados.
+  - **Package Contents:** Analizar la salida del tarball para confirmar ausencia de assets restringidos.
+  - **YAML Frontmatter:** Analizar todos los `.agents/skills/*/SKILL.md` asegurando que el YAML inicial es sintácticamente válido.
+  - **Template Sandbox:** Comprobar que `template/handoff.md`, `template/handoff_archive.md` y `template/.gemstack/state.json` contengan estados limpios y no el texto real de la memoria de Gemstack.
+  - **No Mojibake:** Búsqueda simple de caracteres rotos (ej. `ó`) en docs/scripts que indican falla de encoding.
+
+### 2.4. Seguridad y Caching
+- Configurar cachés seguros para Node Modules de la `demo-app` (`actions/cache`).
+- Activar enmascaramiento automático de salidas y uso estricto de secretos (`${{ secrets.GITHUB_TOKEN }}`).
+- Deshabilitar triggers automáticos de publicación en NPM.
+
+### 2.5. Artifacts y Badges
+- **Artifacts:** Se subirá el archivo `gemstack-*.tgz` resultante de un `npm pack` como un Build Artifact para ser descargable desde la tab de Actions.
+- **Badges:** Se añadirá el Badge dinámico de GitHub Actions en el `README.md`.
+
+## 3. Edge Cases & Risks
+- **Diferencias de File System (Windows vs Unix):** El manejo de rutas relativas y saltos de línea (CRLF vs LF) puede fallar las validaciones de checksum en Git o CI si no están configurados los `.gitattributes`.
+- **Rutas Largas en Windows:** `npm` a veces sufre en Windows con anidamientos profundos, los paths de los tests temporales deben ser cortos.
+- **Falsos Positivos en la Verificación de "Mojibake":** Restringir la validación de encoding a patrones conocidos (`Ã`, ``) sin bloquear caracteres legítimos en UTF-8 o en español.
+
+## 4. Acceptance Criteria
+- Todos los Pull Requests hacia `main` disparan el flujo CI.
+- Los tests corren en las 3 plataformas y 2 versiones de Node de forma paralela.
+- Cualquier detección de un archivo `.sqlite` o `handoff.md` sucio en la carpeta `template/` rompe automáticamente el build.
+- Existe un trigger manual que genera un `.tgz` y lo adjunta como Release Draft en GitHub.
+- NPM Publish no está configurado de forma autónoma.