gemstack-ai 1.0.1

package/RELEASE_NOTES.md

@@ -0,0 +1,149 @@
+# Gemstack Release Notes
+
+# Gemstack v0.3.0
+
+## Highlights
+- GitHub Actions CI
+- PR CI on Ubuntu with Node 18/20
+- Main CI cross-platform matrix on Ubuntu, Windows, macOS with Node 18/20
+- Manual release-readiness workflow
+- Zero-dependency CI scripts under scripts/ci/
+- Frontmatter validation
+- Template cleanliness validation
+- Mojibake detection
+- Package content validation
+- CLI smoke tests
+- SecureDocs smoke tests
+- Artifact generation for npm tarball
+- No npm publish automation
+
+## Validation
+- `npm test`: PASS
+- `npm run ci:all`: PASS
+- `npm run ci:demo`: PASS
+- `npm run pack:dry`: PASS
+- `main-ci` result: SUCCESS (expected)
+- `release-readiness` result: SUCCESS (expected)
+- artifact generated: `gemstack-npm-tarball`
+
+## Safety
+- no npm publish
+- no automatic GitHub Release
+- no automatic tag creation by workflow
+- no secrets printed in logs
+- package contents checked
+- template cleanliness checked
+
+## Known limitations
+- npm publish still manual/future
+- GitHub Release still manual/future
+- CI scripts are custom zero-deps, not full linters
+- release artifact downloads from GitHub UI may be zipped by GitHub
+
+## Next
+- v0.4 or future: npm publish planning
+- GitHub Release automation planning
+- better update diff UX
+- deeper symlink/path tests
+- optional browser QA automation
+
+---
+
+# Gemstack v0.2.0
+
+## Highlights
+- **Zero-dependency Node CLI**: `gemstack init` and `gemstack update` for easy local-first scaffolding.
+- **Installable Scaffold**: Separation of codebase in `src/` and cleanly replicable agents/skills in `template/`.
+- **Manifest & Safety**: Idempotent installation managed via `.gemstack/manifest.json` ensuring no overwritten custom files.
+- **Backups System**: Mandatory automatic rollback copy placed in `.gemstack/backups/<timestamp>/` when force updating Gemstack-owned files.
+- **Cryptography Checksums**: Used `crypto` module (SHA-256) to ensure template vs user-drift.
+- **Path Traversal Guard**: Deep node.js native hardening mapping absolute resolution strings `path.relative()` blocking malicious escalations.
+- **Node:Test**: Comprehensive local `node:test` suite for the `cli.js` installer without needing Jest or third party supply-chain vectors.
+- **Tested Packaging**: Verified local compatibility via `npm link` and `npm pack`.
+
+## Safety
+- No destructive overwrite by default.
+- No `stdin` blocking prompts in `v0.2.0` (fail-fast with `--yes` suggestion).
+- No `npm publish` executed yet.
+- Backups execute silently before replacement (no leaking secrets to stdout).
+- `handoff.md` and user files are strictly skipped.
+
+## Validation
+- `npm test` 100% passes native tests.
+- `npm run pack:dry` generated correct package structure strictly ignoring temporary dumps.
+- `npm link` tested efficiently.
+- `npm pack` (tarball) fully tested inside isolated dummy-project folder via `npx gemstack init --dry-run`.
+
+## Known limitations
+- Not published to npm yet.
+- No GitHub Actions yet.
+- Update conflict UX can be improved to feature rich diffs.
+- Symlink hardening may need more tests in v0.3.
+- Browser QA still manual/documented.
+
+---
+
+# Gemstack v0.1.0
+- Antigravity-native `.agents/rules` and `.agents/skills` structure
+- Spec-Driven Development workflow
+- Handoff memory system
+- Security/CSO checklist
+- SecureDocs demo app
+- Anti-IDOR smoke tests
+- PowerShell and Unix/Git Bash CLI helpers
+
+## Included Skills
+- gemstack-handoff
+- gemstack-resume
+- gemstack-office-hours
+- gemstack-spec
+- gemstack-plan
+- gemstack-tasks
+- gemstack-review
+- gemstack-investigate
+- gemstack-qa
+- gemstack-ship
+- gemstack-cso
+- gemstack-learn
+- gemstack-guard
+
+## Demo
+SecureDocs is included in `demo-app/` to validate the framework. Features:
+- Express + SQLite + Vanilla JS
+- CRUD de documentos
+- `X-Mock-User-Id` como mock auth
+- smoke tests anti-IDOR automáticos
+- `npm run smoke`
+
+## How to try
+**PowerShell:**
+```powershell
+.\bin\gemstack-doctor.ps1
+.\bin\gemstack.ps1 list
+cd demo-app
+npm install
+npm run smoke
+```
+
+**Unix/Git Bash:**
+```bash
+./bin/gemstack-doctor
+./bin/gemstack list
+cd demo-app
+npm install
+npm run smoke
+```
+
+## Known limitations
+- No npm package yet
+- Mock auth only in demo
+- No full automated routing tests yet
+- Browser QA is documented but not fully automated
+- No GitHub Actions yet
+
+## Next
+- v0.2 specs
+- installer/package distribution
+- GitHub Actions
+- more robust QA/browser automation
+- richer security checks

package/bin/gemstack

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# Gemstack CLI
+
+COMMAND=$1
+
+case $COMMAND in
+  init)
+    echo "🚀 Iniciando Gemstack v0.1..."
+    mkdir -p .agents/rules .agents/skills .gemstack specs/current specs/templates docs bin
+    echo "✅ Estructura creada."
+    ;;
+  list)
+    echo "📂 Skills instalados:"
+    ls -1 .agents/skills/
+    ;;
+  show)
+    cat ".agents/skills/$2/SKILL.md" 2>/dev/null || echo "❌ Skill no encontrado"
+    ;;
+  doctor)
+    bash ./bin/gemstack-doctor
+    ;;
+  handoff)
+    cat handoff.md
+    ;;
+  security-audit)
+    echo "Para correr un audit real, invoca /cso en tu chat con Antigravity."
+    ;;
+  *)
+    echo "Uso: gemstack {init|list|show <skill>|doctor|handoff|security-audit}"
+    ;;
+esac

package/bin/gemstack-doctor

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# Gemstack Doctor CLI
+echo "🩺 Gemstack Doctor"
+if command -v git >/dev/null 2>&1; then echo "✅ Git instalado"; else echo "❌ Git no instalado"; exit 1; fi
+if [ -d ".git" ]; then echo "✅ Repositorio Git detectado"; else echo "❌ No es un repositorio Git"; exit 1; fi
+if [ -d ".agents/rules" ]; then echo "✅ .agents/rules existe"; else echo "❌ Falta .agents/rules"; exit 1; fi
+if [ -d ".agents/skills" ]; then echo "✅ .agents/skills existe"; else echo "❌ Falta .agents/skills"; exit 1; fi
+if [ -d ".gemstack" ]; then echo "✅ .gemstack existe"; else echo "❌ Falta .gemstack"; exit 1; fi
+if [ -d "specs/current" ]; then echo "✅ specs/current existe"; else echo "❌ Falta specs/current"; exit 1; fi
+
+if [ -f "handoff.md" ]; then echo "✅ handoff.md existe"; else touch handoff.md && echo "✅ handoff.md creado"; fi
+if [ -f "handoff_archive.md" ]; then echo "✅ handoff_archive.md existe"; else touch handoff_archive.md && echo "✅ handoff_archive.md creado"; fi
+
+if command -v node >/dev/null 2>&1; then echo "✅ Node detectado"; else echo "⚠️ Node no detectado (opcional)"; fi
+echo "💡 Antigravity Browser nativo: Usa /browser en Antigravity, o instala Playwright si ejecutas headless."
+echo "✅ Diagnóstico completado."

package/bin/gemstack-doctor.ps1

@@ -0,0 +1,38 @@
+[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new()
+$OutputEncoding = [System.Text.UTF8Encoding]::new()
+
+$ErrorActionPreference = "Continue"
+
+Write-Host "[INFO] Gemstack Doctor"
+
+# Git check
+try {
+    $gitVer = git --version 2>$null
+    if ($gitVer -match "git version") { Write-Host "[OK] Git instalado" } else { Write-Host "[ERROR] Git no instalado"; exit 1 }
+} catch {
+    Write-Host "[ERROR] Git no instalado"
+    exit 1
+}
+
+if (Test-Path ".git") { Write-Host "[OK] Repositorio Git detectado" } else { Write-Host "[ERROR] No es un repositorio Git"; exit 1 }
+if (Test-Path ".agents/rules") { Write-Host "[OK] .agents/rules existe" } else { Write-Host "[ERROR] Falta .agents/rules"; exit 1 }
+if (Test-Path ".agents/skills") { Write-Host "[OK] .agents/skills existe" } else { Write-Host "[ERROR] Falta .agents/skills"; exit 1 }
+if (Test-Path ".gemstack") { Write-Host "[OK] .gemstack existe" } else { Write-Host "[ERROR] Falta .gemstack"; exit 1 }
+if (Test-Path "specs/current") { Write-Host "[OK] specs/current existe" } else { Write-Host "[ERROR] Falta specs/current"; exit 1 }
+
+if (Test-Path "handoff.md") { Write-Host "[OK] handoff.md existe" } else { New-Item -ItemType File -Path "handoff.md" | Out-Null; Write-Host "[OK] handoff.md creado" }
+if (Test-Path "handoff_archive.md") { Write-Host "[OK] handoff_archive.md existe" } else { New-Item -ItemType File -Path "handoff_archive.md" | Out-Null; Write-Host "[OK] handoff_archive.md creado" }
+
+# Node
+try {
+    $nodeVer = node -v 2>$null
+    if ($nodeVer -match "v") { Write-Host "[OK] Node detectado" } else { Write-Host "[WARN] Node no detectado (opcional)" }
+} catch {
+    Write-Host "[WARN] Node no detectado (opcional)"
+}
+
+# PowerShell
+Write-Host "[OK] PowerShell funcional"
+
+Write-Host "[INFO] Antigravity Browser nativo: Usa /browser en Antigravity, o instala Playwright si ejecutas headless."
+Write-Host "[OK] Diagnostico completado."

package/bin/gemstack.ps1

@@ -0,0 +1,49 @@
+param(
+    [string]$Command = "",
+    [string]$Arg1 = ""
+)
+
+[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new()
+$OutputEncoding = [System.Text.UTF8Encoding]::new()
+
+$ErrorActionPreference = "Stop"
+
+switch ($Command) {
+    "init" {
+        Write-Host "[INIT] Iniciando Gemstack v0.1..."
+        New-Item -ItemType Directory -Force -Path ".agents/rules", ".agents/skills", ".gemstack", "specs/current", "specs/templates", "docs", "bin" | Out-Null
+        Write-Host "[OK] Estructura creada."
+    }
+    "list" {
+        Write-Host "[LIST] Skills instalados:"
+        Get-ChildItem -Path ".agents/skills" -Directory | Select-Object -ExpandProperty Name
+    }
+    "show" {
+        if (-not [string]::IsNullOrWhiteSpace($Arg1)) {
+            $path = ".agents/skills\$Arg1\SKILL.md"
+            if (Test-Path $path) {
+                Get-Content $path -Encoding UTF8
+            } else {
+                Write-Host "[ERROR] Skill no encontrado: $Arg1"
+            }
+        } else {
+            Write-Host "[ERROR] Debes especificar un skill."
+        }
+    }
+    "doctor" {
+        & (Join-Path $PSScriptRoot "gemstack-doctor.ps1")
+    }
+    "handoff" {
+        if (Test-Path "handoff.md") {
+            Get-Content "handoff.md" -Encoding UTF8
+        } else {
+            Write-Host "[ERROR] handoff.md no existe aun."
+        }
+    }
+    "security-audit" {
+        Write-Host "[INFO] Para correr un audit real, invoca /cso en tu chat con Antigravity."
+    }
+    default {
+        Write-Host "Uso: .\bin\gemstack.ps1 {init|list|show <skill>|doctor|handoff|security-audit}"
+    }
+}

package/docs/antigravity.md

@@ -0,0 +1,6 @@
+# Integración con Google Antigravity
+
+Gemstack aprovecha el ecosistema nativo de Antigravity:
+- **Rules (`.agents/rules/`)**: Mapea pseudo-comandos (ej. `/handoff`) para guiar a Gemini.
+- **Skills (`.agents/skills/`)**: Utiliza *Progressive Disclosure* mediante validaciones de frontmatter `triggers`.
+- **Compatibilidad Dual**: Scripts integrados garantizan que puedes testear el contexto y estado tanto desde Unix (`./bin/gemstack`) como de Windows de forma nativa (`.\bin\gemstack.ps1`).

package/docs/handoff.md

@@ -0,0 +1,9 @@
+# El Sistema Handoff
+
+El archivo `handoff.md` es la memoria de tu proyecto. 
+
+## Reglas
+1. Siempre se genera o actualiza al final de la sesión.
+2. Contiene 5 partes: Objetivo, Estado actual, Archivos tocados, Intentos fallidos y Próximos pasos.
+3. **Intentos Fallidos NUNCA se borran**: Previenen que Gemini cometa el mismo error (loops de debugging).
+4. **Archive**: Para evitar que consuma toda la ventana de contexto, el agente mueve las entradas antiguas a `handoff_archive.md` cuando la lista crece demasiado, pero mantiene siempre viva la referencia.

package/docs/qa/latest-qa.md

@@ -0,0 +1,25 @@
+# Latest QA Report
+**Date:** 2026-08-19
+
+## QA Flow: SecureDocs
+
+### Entorno de Prueba
+- Node.js (v18+)
+- Automatizado vía `npm run smoke`
+
+### Resultados de Smoke Tests
+Los smoke tests ejecutaron exitosamente los siguientes escenarios:
+- `[OK]` Users fetched correctly
+- `[OK]` Alice created document
+- `[OK]` Bob blocked from reading Alice's doc (Status 404)
+- `[OK]` Bob blocked from deleting Alice's doc (Status 404)
+- `[OK]` Bob created doc with malicious payload
+- `[OK]` Malicious payload ignored: Doc does not belong to Alice
+- `[OK]` Malicious payload ignored: Doc belongs to Bob safely
+
+### Casos de Prueba Ejecutados Manualmente / API
+1. **[PASS] Selección de Usuario:** Cambiar en el `<select>` entre Alice y Bob recarga exitosamente la lista de documentos (`loadDocs`).
+2. **[PASS] Testing XSS Básico:** Se inyectó `<script>alert("Hacked")</script>` en el título. El documento se listó en la UI de Alice como un string literal gracias a la codificación DOM generada por `textContent`.
+
+### Conclusión
+- Todos los smoke tests pasan con exit code `0`. Sin bugs bloqueantes detectados. El QA confirma la mitigación de IDOR.

package/docs/qa-browser.md

@@ -0,0 +1,7 @@
+# QA & Browser Testing
+
+Usa `/qa` o `/qa-only` para validar tu código contra el `spec.md`.
+
+## Herramientas Visuales
+Si desarrollas frontend, puedes pedirle a Antigravity que abra el navegador usando su comando nativo `/browser` para navegar por el sitio local y validar el UI manualmente.
+Alternativamente, si tienes pruebas e2e automatizadas con **Playwright** o **Cypress**, Gemstack puede ejecutarlas y parsear sus resultados durante la fase de QA.

package/docs/quickstart.md

@@ -0,0 +1,21 @@
+# Gemstack Quickstart
+
+1. **Inicializa el entorno**: 
+   - *Unix:* `./bin/gemstack init`
+   - *Windows:* `.\bin\gemstack.ps1 init`
+2. **Valida la instalación**:
+   - *Unix:* `./bin/gemstack doctor`
+   - *Windows:* `.\bin\gemstack-doctor.ps1`
+3. **Tu primera sesión**:
+   - Inicia con `/office-hours` para discutir la arquitectura.
+   - Escribe `/specify quiero añadir autenticación con JWT`.
+   - Revisa `specs/current/spec.md`.
+   - Escribe `/plan` para generar la estrategia técnica.
+   - Escribe `/tasks` para desglosar la implementación.
+   - Escribe `/review` para chequear tu código.
+4. **Validación y Cierre**:
+   - Corre `/cso` y `/qa`.
+   - Escribe `/ship` para preparar los commits.
+5. **Pausa**: Escribe `/handoff` al final de la sesión.
+6. **Retorno**: Abre chat limpio y escribe:
+   > "Lee handoff.md y continúa desde los próximos pasos"

package/docs/release.md

@@ -0,0 +1,29 @@
+# Gemstack Release Process
+
+Gemstack is protected by a multi-stage CI/CD pipeline using GitHub Actions. No release process is entirely automated for NPM publishing (for security reasons), so all `npm publish` executions are strictly manual post-verification.
+
+## CI Workflows
+
+1. **`pr-ci.yml`**: Runs on `pull_request` to `main`. This is a fast verification matrix running strictly on `ubuntu-latest` with Node 18.x and 20.x. It executes all unit tests, CLI smoke tests, and cleanliness verifications.
+2. **`main-ci.yml`**: Runs on `push` to `main`. Full multi-OS matrix (`ubuntu-latest`, `windows-latest`, `macos-latest`) verifying absolute cross-platform integrity.
+3. **`release-readiness.yml`**: A `workflow_dispatch` manual action. It tests the creation of a `.tgz` via `npm pack`, installs it in a dummy project to guarantee tarball structure, and exposes the `gemstack-npm-tarball` as a downloadable GitHub Artifact. Note: GitHub zips this artifact, so you will extract it to get the inner `.tgz`.
+
+## Local Verifications
+
+Before merging or triggering release readiness, you can test everything locally using:
+
+```bash
+# Run unit tests
+npm test
+
+# Run all zero-deps CI validators
+npm run ci:all
+
+# Run Demo-App smoke tests (IDOR validation)
+npm run ci:demo
+
+# Validate tarball contents
+npm run pack:dry
+```
+
+*(Note: We never automatically tag or publish to NPM via CI. The framework focuses entirely on robust local-first scaffolding).*

package/docs/reviews/latest-review.md

@@ -0,0 +1,24 @@
+# Latest Review
+**Date:** 2026-08-19
+
+## Overview
+Revisión arquitectónica de Gemstack CLI v0.2 (Zero-dependency installer).
+
+## Archivos Revisados
+- `src/cli.js`, `src/lib/*.js`, `src/commands/*.js`
+- `tests/init.test.js`
+
+## Latest Review (v0.3.0)
+- **Workflows**: Implementados `pr-ci.yml`, `main-ci.yml` y `release-readiness.yml` para validación automatizada cross-platform sin auto-publish.
+- **Scripts CI**: Creados scripts en `scripts/ci/` zero-deps para parseo de YAML (`check-frontmatter`), limpieza de estado (`check-template-clean`), detección de mojibake (`check-mojibake`), análisis del npm pack (`check-package-contents`) y smoke testing interactivo (`smoke-cli.js`).
+- **Line Endings**: Inyectado `.gitattributes` conservador forzando CR/LF de forma predictiva y cuidando hashes SHA-256.
+- **Cross-Platform**: Verificadas APIs node agnósticas a OS en lugar de bash scripts. `smoke-cli.js` usa `os.tmpdir()`.
+- **Demo Smoke**: El workflow prueba las defensas IDOR con `npm run ci:demo` en cada iteración.
+
+## Hallazgos
+- **Fixed:** Parser CLI manual procesa correctamente banderas binarias sin dependencias externas. 
+- **Fixed:** Test suite de Node.js corre rápido (~200ms) aisladamente, y las pruebas validan comportamiento de dry-run.
+- **Fixed:** `.npmignore` se añadió excluyendo directorios ajenos (`demo-app/`, `tests/`) logrando un paquete eficiente.
+- **Follow-up for v0.2 Release:** Cuando estemos listos para publicar, necesitaremos documentar o preparar automatización GitHub Actions para testing continuo.
+
+**Decisión**: APPROVED. El CLI mantiene filosofía "safety-first" y "zero-deps".

package/docs/security/latest-security-audit.md

@@ -0,0 +1,35 @@
+# Latest Security Audit
+**Date:** 2026-08-19
+
+## CSO Report: Gemstack CLI v0.2 Installer
+
+### 1. Path Traversal & Symlinks
+- **Status:** [Fixed]
+- **Severity:** Critical
+- **Detail:** Verificado en `src/lib/filesystem-safe.js`. `resolveSafe` verifica con `startsWith()` que el directorio resultante nunca escape la carpeta target, bloqueando `../../` payloads o configuraciones ambiguas.
+
+### 2. Supply Chain Risks
+- **Status:** [Fixed]
+- **Severity:** High
+- **Detail:** Se decidió implementar CLI con **cero dependencias**. `package.json` está libre de packages externos en runtime. Elimina 100% ataques de cadena de suministro vía NPM sobre Gemstack CLI actual.
+
+### 3. Ejecución de código arbitrario
+- **Status:** [Fixed]
+- **Severity:** High
+- **Detail:** El comando `init` realiza operaciones FS puras de lectura y escritura. No emite llamadas a `child_process.exec`, impidiendo Remote Code Execution en el target.
+
+### 4. Overwrite de data y backups sin secretos
+- **Status:** [Fixed]
+- **Severity:** Medium
+- **Detail:** `src/lib/backup.js` realiza el traslado físico en caso de colisión. El logging de backup fue revisado para sólo imprimir en consola el *path* y no el contenido del archivo, lo que protege contra fugas de credenciales locales hacia CI/CD logs. 
+
+## Latest Security Audit (v0.3.0)
+- **Secrets Leakage**: `npm pack --dry-run` and smoke tests run locally within temporary paths blocking any hardcoded secrets. `GITHUB_TOKEN` is constrained. No variables dumped.
+- **Artifact Leakage**: The template cleanliness check strictly blocks any real project history, DBs (`.sqlite`), or logs from being bundled into the tarball.
+- **NPM Publish**: NPM Publishing remains entirely manual; no GitHub Action has publish permissions, neutralizing automated supply-chain contamination.
+- **Path Safety (Indirect)**: Workflows rely on standard Actions avoiding risky user-input reflection in shells.
+- **CI Permissions**: Standard read-only intent. No aggressive caching strategies introduced that would leak secure payloads across branches.
+
+All checks passed.
+
+**Decisión General**: APPROVED. El diseño priorizó defensibilidad por encima de comodidad, resultando en un instalador aséptico.

package/docs/security.md

@@ -0,0 +1,17 @@
+# Seguridad Práctica en Gemstack (CSO)
+
+Gemstack incluye el skill `gemstack-cso`, que actúa como tu Chief Security Officer virtual.
+
+Invócalo mediante `/cso` (para una revisión general) o mediante sus sub-comandos para revisiones específicas.
+
+## Módulos de Revisión:
+1. `/security-idor`: Control de acceso y pertenencia de recursos.
+2. `/security-api`: CORS, Rate Limiting, y autenticación.
+3. `/security-deps`: Análisis de `package.json` o `requirements.txt`.
+4. `/security-uploads`: Validación rigurosa de magic bytes en subidas.
+5. `/security-sql`: Prevención de Inyección SQL.
+6. `/security-sessions`: Revisión de estrategias de tokens y cookies.
+7. `/security-webhooks`: Verificación de firmas de Stripe/PayPal.
+8. `/security-headers`: CSP y protección XSS.
+
+**Guardrail:** El CSO puede corregir código trivial de seguridad, pero cambios mayores (migraciones, auth) requieren un Plan de Seguridad y tu aprobación explícita.

package/docs/skills.md

@@ -0,0 +1,17 @@
+# Skills & Pseudo-comandos
+
+Gemstack vincula pseudo-comandos a Skills específicos:
+
+- `/handoff` -> `gemstack-handoff`
+- `/resume` -> `gemstack-resume`
+- `/office-hours` -> `gemstack-office-hours`
+- `/specify` -> `gemstack-spec`
+- `/plan` -> `gemstack-plan`
+- `/tasks` -> `gemstack-tasks`
+- `/review` -> `gemstack-review`
+- `/investigate` -> `gemstack-investigate`
+- `/cso`, `/security-*` -> `gemstack-cso`
+- `/qa`, `/qa-only` -> `gemstack-qa`
+- `/ship` -> `gemstack-ship`
+- `/learn` -> `gemstack-learn`
+- `/careful`, `/freeze`, `/guard`, `/unfreeze` -> `gemstack-guard`

package/docs/spec-driven-development.md

@@ -0,0 +1,10 @@
+# Spec-Driven Development (SDD) en Gemstack
+
+Inspirado en Spec Kit, Gemstack obliga a pensar antes de teclear.
+
+1. **El Qué (`spec.md`)**: Requisitos funcionales, criterios de aceptación (checkboxes) y casos límite. No tiene detalles de implementación.
+2. **El Cómo (`plan.md`)**: Arquitectura, esquema de base de datos, rutas, y dependencias necesarias.
+3. **El Cuándo (`tasks.md`)**: Pasos lógicos a seguir para construirlo.
+
+Usa `/specify` para comenzar este ciclo.
+Una vez que el spec esté aprobado por el usuario, usa `/plan` y luego `/tasks`.

package/handoff.md

@@ -0,0 +1,45 @@
+# Gemstack Handoff (v1.0.0)
+
+## Resumen del Proyecto
+Gemstack es un "Sistema Operativo para IA" de cero dependencias (Zero-Dependency) que inyecta reglas militares de ciberseguridad, autonomía y flujos de Spec-Driven Development en cualquier repositorio local, permitiendo a los desarrolladores pair-programar de forma estructurada con inteligencias artificiales como Antigravity o Cursor.
+
+## Estado Actual
+El proyecto ha alcanzado oficialmente la **Versión 1.0.0 (Open-Source Ready)**.
+Durante el último sprint se añadieron las capacidades clave para transformar a Gemstack de un simple manejador de prompts en un verdadero ecosistema agentico:
+
+1. **Military-Grade DevSecOps (Rules 03 & 04):**
+   - Actualización a AppSec Nivel 2 (Mitigación de Race Conditions, CSRF, SSRF, Rate Limiting).
+   - Nueva regla de Infraestructura (`04-gemstack-infrastructure.md`) exigiendo contenedores, VPCs y gestores de secretos cloud.
+2. **Git Hooks (Active Security):**
+   - Comando `npx gemstack hooks` implementado en `src/commands/hooks.js`. 
+   - Previene localmente (antes del commit) la subida de `.env`, llaves hardcodeadas, y marcadores de conflicto de git.
+3. **Ecosistema de Plugins y Skills:**
+   - Comando `npx gemstack install <url>` inyectado en `src/commands/install.js` usando `fetch` nativo de Node 18+. Permite descargar skills de la comunidad directamente a `.agents/skills/`.
+4. **Dashboard de Generative UI:**
+   - Skill `gemstack-dashboard` (`/dashboard`) creado para leer el estado del proyecto y renderizar un widget HTML interactivo con el progreso de `tasks.md`.
+5. **Servidor Nativo MCP (Model Context Protocol):**
+   - Implementado en `src/mcp-server.js`. Gemstack ahora actúa como un servidor MCP accesible vía `npx gemstack mcp`, exponiendo el SDD del proyecto a clientes IA externos mediante JSON-RPC sobre stdio.
+6. **Package Version:**
+   - El archivo `package.json` fue ascendido a `v1.0.0`.
+
+## Últimos Cambios Realizados
+- Creación de `.agents/rules/04-gemstack-infrastructure.md`
+- Modificación profunda de `.agents/rules/03-gemstack-security.md` (Level 2).
+- Evolución de `gemstack-cso` para revisar infraestructura.
+- Nuevo script `src/commands/hooks.js` y vinculación en `cli.js` e `init.js`.
+- Nuevo script `src/commands/install.js`.
+- Creación del Skill `gemstack-dashboard` y actualización de `.agents/rules/01-gemstack-core.md`.
+- Nuevo servidor `src/mcp-server.js` y vinculación CLI.
+- Todos los archivos `.agents/` nuevos fueron replicados en la carpeta `template/`.
+- Actualización mayor de `README.md` documentando todas las capacidades "v1.0".
+
+## Qué Sigue (Next Steps para futuras sesiones)
+1. **Adopción y Difusión:** El proyecto está listo para ser publicado abiertamente. Los usuarios pueden empezar a instalarlo en sus propios proyectos web.
+2. **Ampliar el Mercado de Skills:** Podríamos crear un repositorio independiente (`gemstack-skills`) donde la comunidad aloje sus skills compartidos.
+3. **Mantenimiento del Servidor MCP:** Actualmente el servidor MCP expone 2 herramientas (`get_current_tasks`, `get_security_rules`). En futuras iteraciones se podrían agregar herramientas de mutación (escribir specs a través de MCP).
+
+## Archivos Críticos a Tener en Cuenta
+- `src/cli.js`: El cerebro del enrutador de comandos.
+- `src/commands/*.js`: Cada comando de la CLI está encapsulado de forma nativa.
+- `template/`: Esta carpeta *debe* contener un espejo exacto de `.agents/`, `.gemstack/`, `docs/` y `specs/`. ¡Nunca modifiques reglas locales sin actualizarlas en el `template/`!
+- `scripts/ci/*.js`: Toda la validación CI depende de scripts cero-dependencias escritos en Node.

package/handoff_archive.md

@@ -0,0 +1,61 @@
+# Handoff Archive
+
+Histórico de intentos fallidos antiguos movidos desde `handoff.md`.
+
+## Archivo
+# Handoff
+
+## 1. Objetivo
+**[Fin de Jornada]** Integrar las metodologías y entregables de Spec-Driven Development (SDD) dentro del motor de agentes de Gemstack, formalizando la creación de especificaciones inmutables, Test-First Development y arquitecturas orientadas a interfaces.
+
+## 2. Estado actual
+Hemos analizado el repositorio de referencia de `spec-kit` y actualizado todas nuestras habilidades y plantillas base de Gemstack para alinear los pseudo-comandos `/specify`, `/plan` y `/tasks`. 
+Se implementó la **Constitución de Gemstack (The 9 Articles)** para prevenir alucinaciones de LLM (`[NEEDS CLARIFICATION]`), forzar implementaciones modulares (Library-First) y establecer la filosofía TDD (Test-First Imperative). Además, el flujo ha migrado de una sola carpeta `current` hacia el uso de **Feature Branches** (ej. `specs/004-nueva-feature/`) junto a artefactos satélites (modelos de datos, contratos, y quickstarts). Todo el trabajo ha sido pusheado a `main`.
+
+## 3. Archivos y cambios
+- **Reglas (Constitution):** Creado `.agents/rules/02-gemstack-constitution.md`.
+- **Plantillas (Templates):** Refactorizados fuertemente `specs/templates/spec.md`, `specs/templates/plan.md`, y `specs/templates/tasks.md` introduciendo prioridades (P1, P2), Constitution Checks y métricas de éxito (Measurable Outcomes).
+- **Skills:** Actualizados `gemstack-spec`, `gemstack-plan` y `gemstack-tasks` para reconocer la constitución, forzar el uso de `[NEEDS CLARIFICATION]`, soportar entregables satélites y soportar tareas paralelizables con el marcador `[P]`.
+
+## 4. Intentos fallidos
+<!-- NUNCA BORRES ESTA SECCIÓN. Si crece mucho, mueve entradas antiguas a handoff_archive.md. -->
+- Ejecución directa de scripts bash a través de Antigravity `run_command` (WSL execvpe failed). El CLI fue saneado para que al menos funcione correctamente en bash/git-bash nativo o entornos Unix y se previno el falso positivo en la detección de git.
+- PowerShell arrojó error de "Expresión de asignación no válida" en el bloque `param()` de `gemstack.ps1` al inyectar líneas antes de dicho bloque. Solución: Se corrigió dejando el bloque `param()` obligatoriamente como lo primero en el script.
+- Caracteres de codificación (Diagnóstico) persistieron en PowerShell console a pesar del reemplazo UTF-8 automatizado. Solución: reescritura directa del archivo usando las herramientas nativas del agente y ASCII labels por seguridad.
+- Conflicto en el globbing de la test suite predeterminada (`node --test`). Ejecutaba involuntariamente el servidor de SecureDocs (`smoke-test.js`) lo que bloqueaba la suite. Solución: Se restringió explícitamente en el `package.json` a correr sobre la ruta `tests/*.test.js`.
+- Parser manual de `--help` no captaba globalmente si se ponía como segundo o primer argumento tras Node (`argv[2]`). Solución: Parser refactorizado para inferencia temprana.
+
+## 5. Próximos pasos
+El framework interno de agentes de Gemstack ahora es capaz de desarrollar con rigor bajo Spec-Driven Development. El próximo paso natural es:
+1. Poner a prueba la nueva arquitectura de plantillas creando una nueva funcionalidad (Feature 004) utilizando `/specify`.
+2. Continuar con el roadmap oficial hacia v0.4, abordando la publicación de NPM y la automatización de GitHub Releases.
+3. Explorar la automatización de QA Testing de navegadores ahora que las tareas soportan el desglose satelital de `[P]` (Paralelización) y la validación MVP temprana.
+# Gemstack - Handoff
+
+**Fecha:** 30 de Agosto de 2026
+**Fase Actual:** Desarrollo Continuo (v0.4/Open-Source Ready)
+**Estado:** Idle
+
+## 1. Resumen de la Sesión
+Durante esta sesión intensiva se completaron 4 grandes hitos ("Features") que transformaron a Gemstack en un framework agentico maduro, seguro y listo para su distribución Open Source:
+
+- **Feature 004 (Release Automation):** Se implementó un flujo CI/CD en `.github/workflows/publish.yml` que empaqueta y publica la herramienta en NPM y genera un GitHub Release automático cada vez que se empuja un tag `v*`.
+- **Feature 005 (The "WOW" Update - Advanced Autonomy):** Se crearon los skills `/qa-visual`, `/swarm`, `/heal` y `/sandbox`. Ahora el agente tiene instrucciones nativas para hacer UI testing autónomo, delegar subagentes en paralelo, auto-sanar builds de CI rotos y correr código riesgoso en Docker.
+- **Feature 006 (Military-Grade Security Shield):** Se integró el documento `SEGURIDAD.MD` del usuario creando la regla inmutable `.agents/rules/03-gemstack-security.md`. El `/cso` y `/review` ahora bloquean activamente vulnerabilidades como IDOR, exposición de llaves y falta de firmas en webhooks.
+- **Feature 007 (Open Source Readiness):** Se reescribió por completo el `README.md` (con badges y estructura profesional), se añadieron `CONTRIBUTING.md` y `CODE_OF_CONDUCT.md`. Se estabilizó `demo-app` cambiando el puerto de pruebas a 3001.
+
+## 2. Archivos Modificados Recientemente
+- `package.json` (bump a 0.3.0, scripts ci)
+- `.github/workflows/publish.yml`
+- `.agents/rules/01-gemstack-core.md`, `03-gemstack-security.md`
+- `.agents/skills/gemstack-*` (Múltiples skills creados y editados)
+- `template/` (Toda la distribución sincronizada)
+- `README.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`
+- `demo-app/server.js`, `demo-app/scripts/smoke-test.js`
+
+## 3. Trabajo Pendiente o Bloqueos
+- **Bloqueos:** Ninguno. La pipeline `ci:all` está en verde y el código está subido a la rama `main`.
+- **Tests Faltantes:** Durante el análisis previo, se identificó que comandos como `list`, `show`, `doctor` y `parser` podrían beneficiarse de cobertura unitaria más profunda en v0.4.
+
+## 4. Próximos Pasos (Next Steps)
+- Esperando las próximas instrucciones del usuario para continuar la evolución del framework, posiblemente explorando la publicación oficial a NPM o mejoras de arquitectura.

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "gemstack-ai",
+  "version": "1.0.1",
+  "description": "Agentic Spec-Driven Development framework for Gemini/Antigravity",
+  "main": "src/cli.js",
+  "bin": {
+    "gemstack": "src/cli.js"
+  },
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "scripts": {
+    "test": "node --test tests/init.test.js",
+    "pack:dry": "npm pack --dry-run",
+    "ci:frontmatter": "node scripts/ci/check-frontmatter.js",
+    "ci:template": "node scripts/ci/check-template-clean.js",
+    "ci:mojibake": "node scripts/ci/check-mojibake.js",
+    "ci:package": "node scripts/ci/check-package-contents.js",
+    "ci:smoke": "node scripts/ci/smoke-cli.js",
+    "ci:demo": "npm --prefix demo-app install && npm --prefix demo-app run smoke",
+    "ci:all": "npm test && npm run ci:frontmatter && npm run ci:template && npm run ci:mojibake && npm run ci:package && npm run ci:smoke && npm run ci:demo"
+  },
+  "dependencies": {},
+  "devDependencies": {}
+}