gemstack-ai 1.0.1

package/scripts/ci/check-frontmatter.js

@@ -0,0 +1,54 @@
+const fs = require('fs');
+const path = require('path');
+
+const skillsDir = path.resolve(__dirname, '../../.agents/skills');
+if (!fs.existsSync(skillsDir)) {
+    console.error(`Skills directory not found at ${skillsDir}`);
+    process.exit(1);
+}
+
+let hasError = false;
+
+fs.readdirSync(skillsDir).forEach(folder => {
+    const stat = fs.statSync(path.join(skillsDir, folder));
+    if (!stat.isDirectory()) return;
+
+    const skillPath = path.join(skillsDir, folder, 'SKILL.md');
+    if (!fs.existsSync(skillPath)) {
+        console.error(`[FAIL] ${folder} missing SKILL.md`);
+        hasError = true;
+        return;
+    }
+
+    const content = fs.readFileSync(skillPath, 'utf8');
+    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!frontmatterMatch) {
+        console.error(`[FAIL] ${folder} missing valid frontmatter`);
+        hasError = true;
+        return;
+    }
+
+    const frontmatter = frontmatterMatch[1];
+    const nameMatch = frontmatter.match(/name:\s*(.+)/);
+    const descMatch = frontmatter.match(/description:\s*(.+)/);
+    const triggersMatch = frontmatter.match(/triggers:\s*\n((\s+-\s+.+\n?)+)/);
+
+    if (!nameMatch || nameMatch[1].trim() !== folder) {
+        console.error(`[FAIL] ${folder} name mismatch or missing. Expected: ${folder}`);
+        hasError = true;
+    }
+    if (!descMatch || descMatch[1].trim() === '') {
+        console.error(`[FAIL] ${folder} missing description`);
+        hasError = true;
+    }
+    if (!triggersMatch) {
+        console.error(`[FAIL] ${folder} missing triggers array`);
+        hasError = true;
+    }
+});
+
+if (hasError) {
+    process.exit(1);
+} else {
+    console.log('[OK] All skills have valid frontmatter.');
+}

package/scripts/ci/check-mojibake.js

@@ -0,0 +1,44 @@
+const fs = require('fs');
+const path = require('path');
+
+const rootDir = path.resolve(__dirname, '../../');
+let hasError = false;
+
+function walkDir(dir, callback) {
+    if (!fs.existsSync(dir)) return;
+    fs.readdirSync(dir).forEach(f => {
+        const dirPath = path.join(dir, f);
+        if (f === 'node_modules' || f === '.git' || f === 'temp dirs' || f.endsWith('.tgz') || f.endsWith('.zip') || f.endsWith('.sqlite')) return;
+        if (fs.statSync(dirPath).isDirectory()) {
+            walkDir(dirPath, callback);
+        } else {
+            if (/\.(md|js|json|yml|yaml|ps1|sh)$/.test(f)) {
+                callback(dirPath);
+            }
+        }
+    });
+}
+
+const mojibakePatterns = new RegExp('\\xC3|\\xC2|\\xE2\\x9C|\\xF0\\x9F');
+
+walkDir(rootDir, (filePath) => {
+    // skip this script and the specs directory
+    if (filePath.replace(/\\/g, '/').includes('scripts/ci/check-mojibake.js')) return;
+    if (filePath.replace(/\\/g, '/').includes('specs/')) return;
+    if (filePath.replace(/\\/g, '/').endsWith('handoff.md')) {
+        // Just skip handoff as it also logs the spec content
+        return;
+    }
+
+    const content = fs.readFileSync(filePath, 'utf8');
+    if (mojibakePatterns.test(content)) {
+        console.error(`[FAIL] Mojibake detected in: ${path.relative(rootDir, filePath)}`);
+        hasError = true;
+    }
+});
+
+if (hasError) {
+    process.exit(1);
+} else {
+    console.log('[OK] No mojibake detected.');
+}

package/scripts/ci/check-package-contents.js

@@ -0,0 +1,32 @@
+const { execSync } = require('child_process');
+const path = require('path');
+
+try {
+    const rootDir = path.resolve(__dirname, '../../');
+    const output = execSync('npm pack --dry-run --json', { cwd: rootDir, encoding: 'utf8' });
+    const result = JSON.parse(output);
+    const files = result[0].files.map(f => f.path.replace(/\\/g, '/'));
+    
+    const required = ['src/cli.js', 'template/handoff.md', 'README.md', 'LICENSE', 'CHANGELOG.md', 'RELEASE_NOTES.md', 'package.json'];
+    const forbidden = ['node_modules', 'securedocs.sqlite', 'demo-app/node_modules', '.git/', 'demo-app/securedocs.sqlite'];
+    
+    let hasError = false;
+    for (const req of required) {
+        if (!files.some(f => f === req || f.startsWith(req))) {
+            console.error(`[FAIL] Package missing required file/folder: ${req}`);
+            hasError = true;
+        }
+    }
+    for (const fbn of forbidden) {
+        if (files.some(f => f.includes(fbn))) {
+            console.error(`[FAIL] Package includes forbidden file/folder: ${fbn}`);
+            hasError = true;
+        }
+    }
+    
+    if (hasError) process.exit(1);
+    console.log('[OK] Package contents are valid.');
+} catch (err) {
+    console.error('[FAIL] Error parsing package contents:', err.message);
+    process.exit(1);
+}

package/scripts/ci/check-template-clean.js

@@ -0,0 +1,46 @@
+const fs = require('fs');
+const path = require('path');
+
+const templateDir = path.resolve(__dirname, '../../template');
+let hasError = false;
+
+function walkDir(dir, callback) {
+    if (!fs.existsSync(dir)) return;
+    fs.readdirSync(dir).forEach(f => {
+        const dirPath = path.join(dir, f);
+        if (fs.statSync(dirPath).isDirectory()) walkDir(dirPath, callback);
+        else callback(dirPath);
+    });
+}
+
+const forbiddenPatterns = [/node_modules/, /\.sqlite$/, /\.db$/, /\.tgz$/, /\.zip$/, /\.gemstack[\\\/]backups/, /temp dirs/, /\.log$/];
+walkDir(templateDir, (filePath) => {
+    for (const pattern of forbiddenPatterns) {
+        if (pattern.test(filePath)) {
+            console.error(`[FAIL] Forbidden file found in template: ${filePath}`);
+            hasError = true;
+        }
+    }
+});
+
+const handoffPath = path.join(templateDir, 'handoff.md');
+if (fs.existsSync(handoffPath)) {
+    const content = fs.readFileSync(handoffPath, 'utf8');
+    if (!content.includes('1. Objetivo') || !content.includes('5. Próximos pasos')) {
+        console.error('[FAIL] template/handoff.md is missing required sections.');
+        hasError = true;
+    }
+    if (content.match(/[a-f0-9]{40}/)) {
+        console.error('[FAIL] template/handoff.md contains what looks like real git hashes.');
+        hasError = true;
+    }
+} else {
+    console.error('[FAIL] template/handoff.md is missing.');
+    hasError = true;
+}
+
+if (hasError) {
+    process.exit(1);
+} else {
+    console.log('[OK] Template directory is clean.');
+}

package/scripts/ci/smoke-cli.js

@@ -0,0 +1,30 @@
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+function runSafe(cmd, cwd) {
+    try {
+        console.log(`Running: ${cmd}`);
+        execSync(cmd, { cwd, encoding: 'utf8', stdio: 'pipe' });
+    } catch (err) {
+        console.error(`[FAIL] Command failed: ${cmd}\n${err.stderr || err.message}`);
+        process.exit(1);
+    }
+}
+
+const rootDir = path.resolve(__dirname, '../../');
+const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gemstack-smoke-'));
+
+console.log(`[INFO] Smoke testing CLI in ${tmpDir}`);
+
+runSafe(`node "${path.join(rootDir, 'src/cli.js')}" --help`, tmpDir);
+runSafe(`node "${path.join(rootDir, 'src/cli.js')}" list`, rootDir);
+runSafe(`node "${path.join(rootDir, 'src/cli.js')}" show gemstack-handoff`, rootDir);
+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')}" update --dry-run --target "${tmpDir}"`, tmpDir);
+
+fs.rmSync(tmpDir, { recursive: true, force: true });
+console.log('[OK] CLI Smoke tests passed.');

package/specs/004-release-automation/plan.md

@@ -0,0 +1,52 @@
+# Plan de Implementación: Release Automation (NPM & GitHub)
+
+**Feature Branch**: `004-release-automation` | **Spec**: `specs/004-release-automation/spec.md`
+
+## 1. Summary & Technical Context
+Se implementará un workflow automatizado de CI/CD para publicar Gemstack en NPM y generar un GitHub Release al hacer push de un tag (`v*`).
+
+- **Lenguaje/Versión**: YAML (GitHub Actions), Node.js 18+ y 20+.
+- **Dependencias core**: Acciones de GitHub `actions/checkout@v4`, `actions/setup-node@v4` y `softprops/action-gh-release@v1` (o usando `gh` CLI directo).
+- **Restricciones**: Las publicaciones deben ser idempotentes, seguras (Zero dependencies externas en nuestro runtime local), y se debe proveer protección contra errores de publicación si los tests fallan antes.
+
+## 2. Constitution Check (Phase -1 Gates)
+<!-- VERIFICACIÓN DE REGLAS INMUTABLES -->
+### Simplicity Gate (Article VII)
+- [x] ¿Se usan el mínimo número de carpetas/archivos posibles? *(Sí, un solo archivo `.yml` de workflow)*
+- [x] ¿No hay abstracciones prematuras (future-proofing)? *(Se usarán las herramientas directas de npm y gh-cli)*
+
+### Anti-Abstraction Gate (Article VIII)
+- [x] ¿Se usan las APIs nativas del framework sin wrappers innecesarios? *(Usaremos `npm publish` nativo)*
+
+### Test-First Imperative (Article III)
+- [x] ¿El plan incluye la creación de tests antes que el código fuente? *(Como es automatización YAML, el test será probar con `--dry-run` o validar el parsing antes de la publicación real)*
+
+## 3. Entregables Satélites a Generar
+- `research.md`: [Opcional] No aplica (la tecnología de actions ya fue definida y documentada).
+- `data-model.md`: No aplica.
+- `contracts/`: No aplica.
+- `quickstart.md`: No aplica.
+
+## 4. Estructura de Archivos a Modificar / Crear
+```text
+.github/workflows/publish.yml: [NUEVO] Workflow para automatizar la publicación tras push de un tag.
+package.json: [MODIFICAR] Opcional, configuración extra si necesitamos scripts de validación pre-publicación.
+```
+
+### Flujo Técnico en `publish.yml`
+1. **Trigger**: `on: push: tags: - 'v*'`
+2. **Setup**: Checkout del código, Setup de Node.js.
+3. **CI Gate**: Ejecutar `npm run ci:all` para evitar publicar versiones defectuosas.
+4. **NPM Publish**: 
+   - Ejecutar `npm pack` (opcionalmente guardar el .tgz en var temporal).
+   - Configurar registry a `registry.npmjs.org` con `NODE_AUTH_TOKEN`.
+   - Ejecutar `npm publish --access public`.
+5. **GitHub Release**:
+   - Usar comando `gh release create` o la acción oficial para crear el release.
+   - Apuntar el `body` (notas) a `RELEASE_NOTES.md`.
+   - Adjuntar el artefacto `.tgz` generado en el paso 4.
+
+## 5. Complexity Tracking
+| Violación de Regla | Por qué es necesario | Alternativa simple rechazada por |
+|--------------------|----------------------|-----------------------------------|
+| Ninguna            | N/A                  | N/A                               |

package/specs/004-release-automation/spec.md

@@ -0,0 +1,49 @@
+# Especificación de Funcionalidad: Release Automation (NPM & GitHub)
+
+**Feature Branch**: `004-release-automation`
+
+## 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 - Publicación Automatizada en NPM (Prioridad: P1)
+Como mantenedor del framework Gemstack, quiero que el sistema publique automáticamente el paquete en el registro público de NPM cuando se apruebe una nueva versión.
+**Por qué esta prioridad:** Reduce el error humano, estandariza los empaquetados y evita la necesidad de credenciales locales en las máquinas de los desarrolladores.
+**Test Independiente:** Ejecutar el flujo de publicación con un flag dry-run (o hacia un registry de pruebas/local) y verificar que el paquete se empaqueta y publica correctamente.
+
+**Escenarios de Aceptación:**
+1. **Dado** que se ha configurado un token de NPM válido, **Cuando** se dispara el proceso de release, **Entonces** el paquete se publica en npmjs.com bajo el nombre correcto.
+
+### User Story 2 - Generación de GitHub Releases (Prioridad: P2)
+Como mantenedor del framework, quiero que el sistema cree automáticamente un "GitHub Release" formal asociado al tag de la versión, incluyendo las notas de lanzamiento y el artefacto (`tarball`).
+**Por qué esta prioridad:** Mantiene a los usuarios informados sobre los cambios (Changelog) y centraliza la distribución segura de binarios o empaquetados históricos.
+**Test Independiente:** Disparar la acción y validar que aparece un Release en la pestaña de Releases de GitHub con el texto correcto extraído de las notas.
+
+**Escenarios de Aceptación:**
+1. **Dado** un nuevo tag de versión en el repositorio, **Cuando** se ejecuta la automatización, **Entonces** se crea un Release en GitHub adjuntando el `gemstack-x.y.z.tgz`.
+
+## 2. Requerimientos Funcionales
+<!--
+  Anota requerimientos explícitos.
+  SI HAY AMBIGÜEDAD, NO ADIVINES. Usa: [NEEDS CLARIFICATION: tu pregunta]
+-->
+- **FR-001**: El sistema DEBE empaquetar el framework de forma limpia y publicarlo en NPM.
+- **FR-002**: El sistema DEBE generar un GitHub Release adjuntando el código fuente y el `tarball` empaquetado.
+- **FR-003**: El flujo DEBE dispararse automáticamente cuando se empuja al repositorio un tag semántico de Git (ej. `git push origin v0.4.0`).
+- **FR-004**: El GitHub Release DEBE crearse en estado de Publicado (Published) inmediatamente para maximizar la automatización.
+- **FR-005**: Se DEBE utilizar el contenido del archivo `RELEASE_NOTES.md` como cuerpo (body) del GitHub Release.
+
+## 3. Criterios de Éxito (Measurable Outcomes)
+<!-- Definir métricas que no dependan de la tecnología -->
+- **SC-001**: El proceso de release completo requiere cero comandos manuales de `npm publish` en las computadoras de los desarrolladores.
+- **SC-002**: El tiempo desde la aprobación del release hasta la disponibilidad pública en NPM y GitHub es inferior a 5 minutos.
+
+## 4. Casos Extremos (Edge Cases)
+- ¿Qué pasa si la versión declarada en `package.json` ya existe en el registro público de NPM (colisión de versiones)?
+- ¿Qué pasa si el NPM_TOKEN ha expirado o no tiene permisos de publicación?
+- ¿Qué pasa si las pruebas de integración (`ci:all`) fallan justo antes de intentar publicar?
+
+## 5. Entidades Clave (Data / Models)
+- **[NPM Registry]**: Sistema de distribución público donde vivirá el paquete.
+- **[GitHub Release]**: Entidad oficial del repositorio que enlaza un tag, un commit, notas de texto y archivos (assets).

package/specs/004-release-automation/tasks.md

@@ -0,0 +1,25 @@
+# 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: Pruebas y Validación (Test-First Imperative)
+- [x] 1.1 Redactar prueba de validación sintáctica YAML para el nuevo workflow (`publish.yml`) usando `actionlint` o similar, o al menos validar la estructura estáticamente.
+- [x] 1.2 [P] Validar localmente (dry-run) que `npm pack` genera el empaquetado esperado sin errores antes de la publicación remota.
+- [x] 1.3 Comprobar que los tests fallen (Fase Roja) - en este contexto, asegurarse de que sin el YAML, el CI no reacciona a los tags.
+
+## Fase 2: Implementación
+- [x] 2.1 Crear archivo `.github/workflows/publish.yml`.
+- [x] 2.2 Configurar el trigger para `on: push: tags: ['v*']`.
+- [x] 2.3 Añadir trabajo `publish` que ejecute `actions/checkout` y configure Node.js usando la caché de NPM.
+- [x] 2.4 Añadir paso de compuerta de seguridad: ejecución de `npm run ci:all`.
+- [x] 2.5 Añadir paso para ejecutar `npm publish --access public` usando `NODE_AUTH_TOKEN`.
+- [x] 2.6 Añadir paso para capturar el nombre del `.tgz` empaquetado y ejecutar `gh release create` usando el CLI nativo, adjuntando el changelog desde `RELEASE_NOTES.md`.
+
+## Fase 3: Integración y Validación
+- [x] 3.1 Revisar permisos del token de GitHub (asegurar que el GITHUB_TOKEN tenga permisos de escritura `contents: write` para crear releases).
+- [x] 3.2 Marcar los cambios, hacer commit bajo la rama actual y fusionar a main.
+- [x] 3.3 Revisión de seguridad y dependencias (CSO).

package/specs/005-the-wow-update/plan.md

@@ -0,0 +1,29 @@
+# Plan de Implementación: The "WOW" Update
+
+**Feature Branch**: `005-the-wow-update` | **Spec**: `specs/005-the-wow-update/spec.md`
+
+## 1. Summary & Technical Context
+Se introducirán 4 nuevas capacidades de autonomía extrema en el motor de Gemstack: QA Visual (`/qa-visual`), Swarm Multiplexing (`/swarm`), Auto-Sanación CI/CD (`/heal`) y Seguridad de Contenedores (`/sandbox`). Esto se implementa añadiendo los SKILLs correspondientes.
+
+- **Lenguaje/Versión**: Markdown + YAML (Arquitectura SDD nativa del agente).
+- **Dependencias core**: Ninguna adicional localmente. (Docker, Playwright y CLI de GitHub se asumen como externos si la IA los necesita).
+
+## 2. Constitution Check (Phase -1 Gates)
+### Simplicity Gate (Article VII)
+- [x] ¿Se usan el mínimo número de carpetas/archivos posibles? *(Sí, un archivo de skill MD por feature).*
+### Anti-Abstraction Gate (Article VIII)
+- [x] ¿Se usan las APIs nativas del framework sin wrappers innecesarios? *(Los skills orquestarán comandos nativos).*
+### Test-First Imperative (Article III)
+- [x] ¿El plan incluye la creación de tests antes que el código fuente? *(Como es configuración AI, el framework central verificará la inicialización de estos nuevos skills).*
+
+## 3. Entregables Satélites a Generar
+- No aplican modelos de datos nuevos.
+
+## 4. Estructura de Archivos a Modificar / Crear
+```text
+.agents/rules/01-gemstack-core.md: [MODIFICADO] Añadir mapeo de nuevos comandos.
+.agents/skills/gemstack-qa-visual/SKILL.md: [NUEVO] Skill.
+.agents/skills/gemstack-swarm/SKILL.md: [NUEVO] Skill.
+.agents/skills/gemstack-heal/SKILL.md: [NUEVO] Skill.
+.agents/skills/gemstack-sandbox/SKILL.md: [NUEVO] Skill.
+```

package/specs/005-the-wow-update/spec.md

@@ -0,0 +1,32 @@
+# Especificación de Funcionalidad: The "WOW" Update (Autonomía Avanzada)
+
+**Feature Branch**: `005-the-wow-update`
+
+## 1. User Scenarios & Testing (MVP)
+
+### User Story 1 - QA Visual Autónomo (P1)
+Como desarrollador, quiero invocar `/qa-visual` para que la IA genere y ejecute scripts de UI testing en un sandbox, verificando visualmente los Criterios de Aceptación.
+**Test Independiente**: Ejecutar `/qa-visual` en un proyecto con frontend simulado y obtener un reporte de QA basado en interacción DOM.
+
+### User Story 2 - Enjambre de Subagentes (Swarm) (P1)
+Como líder técnico, quiero que el comando `/tasks` delegue automáticamente las tareas marcadas con `[P]` a múltiples subagentes paralelos para reducir el tiempo de implementación.
+**Test Independiente**: Procesar un `tasks.md` con 2 tareas `[P]`, verificando que se invocan subagentes en paralelo.
+
+### User Story 3 - Auto-Sanación de CI/CD (P2)
+Como mantenedor, quiero invocar `/heal` cuando un workflow de GitHub falle, para que el agente lea los logs, repare el código y haga un push automáticamente.
+**Test Independiente**: Romper un test a propósito, subirlo, esperar que falle CI y correr `/heal` para ver cómo se auto-repara.
+
+### User Story 4 - Ejecución Segura en Sandbox (P2)
+Como ingeniero de seguridad, quiero usar `/sandbox` para aislar pruebas de dependencias dudosas dentro de un contenedor Docker efímero.
+**Test Independiente**: Ejecutar un test con `/sandbox` y confirmar que corre dentro de un contenedor de Node.js sin acceso al host raíz.
+
+## 2. Requerimientos Funcionales
+- **FR-001**: Añadir skill `gemstack-qa-visual`.
+- **FR-002**: Añadir skill `gemstack-swarm` y actualizar `gemstack-tasks` para orquestar `invoke_subagent`.
+- **FR-003**: Añadir skill `gemstack-heal` que consuma logs vía CLI (`gh run view`).
+- **FR-004**: Añadir skill `gemstack-sandbox` que use `docker run`.
+- **FR-005**: Registrar todos los comandos en `01-gemstack-core.md`.
+
+## 3. Criterios de Éxito (Measurable Outcomes)
+- **SC-001**: El framework soporta delegación multiproceso nativa.
+- **SC-002**: El flujo de resolución de bugs de CI pasa de requerir intervención humana a requerir solo 1 comando (`/heal`).

package/specs/005-the-wow-update/tasks.md

@@ -0,0 +1,16 @@
+# Tareas de Implementación
+
+## Fase 1: Pruebas y Validación (Test-First Imperative)
+- [x] 1.1 Verificar que `01-gemstack-core.md` y la estructura base soportan nuevos skills sin fallar el CLI.
+
+## Fase 2: Implementación
+- [x] 2.1 Mapear los comandos `/qa-visual`, `/swarm`, `/heal`, `/sandbox` en `01-gemstack-core.md`.
+- [x] 2.2 Crear `.agents/skills/gemstack-qa-visual/SKILL.md`.
+- [x] 2.3 Crear `.agents/skills/gemstack-swarm/SKILL.md`.
+- [x] 2.4 Crear `.agents/skills/gemstack-heal/SKILL.md`.
+- [x] 2.5 Crear `.agents/skills/gemstack-sandbox/SKILL.md`.
+
+## Fase 3: Integración y Validación
+- [x] 3.1 Sincronizar todos los archivos modificados hacia la carpeta de distribución `template/`.
+- [x] 3.2 Ejecutar `npm run ci:all` para garantizar que la nueva estructura no corrompe la inicialización.
+- [ ] 3.3 Hacer commit bajo la rama actual.

package/specs/README.md

@@ -0,0 +1,12 @@
+# Spec-Driven Development (SDD) en Gemstack
+
+Este directorio maneja el flujo de diseño antes del código.
+
+## `specs/current/`
+Aquí residen los documentos de la funcionalidad en desarrollo actual. Siempre deben estar sincronizados.
+- `spec.md`: El "Qué" y "Por qué".
+- `plan.md`: El diseño técnico ("Cómo").
+- `tasks.md`: El desglose ejecutable.
+
+## `specs/templates/`
+Contiene las plantillas base utilizadas por los skills `/specify`, `/plan` y `/tasks` para inicializar los documentos en `current/`.

package/specs/current/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/current/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.