create-quiver 0.15.4 → 0.16.0

package/docs/specs/01-spec/spec.md

@@ -0,0 +1,197 @@
+# Spec 01 - Recuperacion segura de ramas y extraccion incremental sin regresiones
+
+## 1. Resumen general
+
+Esta spec define el proceso para analizar ramas abiertas, recuperar valor tecnico de ramas antiguas o conflictivas y evitar que la integracion rompa el proyecto. La iniciativa no implementa codigo por si misma. Establece criterios, gates y handoffs para que cualquier implementacion futura sea incremental, verificable y reversible.
+
+La base operativa segura es `origin/main`, sujeta a verificacion de frescura del snapshot antes de ejecutar acciones finales. La rama local `main` no debe usarse como base mientras continue divergida de `origin/main`.
+
+La rama `feature/QUIVER-46-49-cli-modernization` se considera fuente de extraccion parcial, no candidata a merge completo. Cualquier rama con `ahead=0` debe tratarse como sin delta pendiente, pero no como automaticamente eliminable.
+
+## 2. Objetivo
+
+Crear un marco de decision y ejecucion para:
+
+- Clasificar ramas locales y remotas sin modificar el working tree.
+- Evitar merges grandes, cherry-picks amplios o cambios disruptivos.
+- Preservar toda funcionalidad existente.
+- Documentar cualquier modificacion de comportamiento con matriz antes/despues.
+- Extraer valor de ramas conflictivas en slices pequenos, revisables y testeables.
+- Requerir aprobacion explicita antes de eliminar ramas o implementar codigo.
+
+## 3. Contexto
+
+El repositorio tiene multiples ramas locales y remotas abiertas. Varias ramas ya estan incluidas en `origin/main`, otras estan atrasadas, algunas contienen backups, drafts o cambios conflictivos. El analisis inicial identifico que `feature/QUIVER-46-49-cli-modernization` contiene una modernizacion amplia de CLI con conflictos textuales y riesgo semantico.
+
+La prioridad es evitar fixes parciales. Antes de modificar parser, comandos, documentacion generada, tests o scripts, debe existir un baseline verificable del comportamiento actual.
+
+## 4. Problema u oportunidad que se aborda
+
+El problema es que integrar ramas antiguas o grandes puede:
+
+- Reintroducir decisiones obsoletas.
+- Romper comandos existentes sin conflicto textual.
+- Cambiar salidas `--json`, exit codes, aliases, flags o side effects.
+- Generar documentacion inconsistente con la CLI real.
+- Mezclar refactors con bumps de version o cambios de package.
+- Eliminar ramas utiles por interpretar `ahead=0` como eliminable.
+
+La oportunidad es convertir el estado de ramas en un backlog controlado, con extraccion selectiva y evidencia por slice.
+
+## 5. Alcance
+
+Incluye:
+
+- Snapshot verificable de ramas.
+- Clasificacion de ramas con estados diferenciados.
+- Baseline de comportamiento actual.
+- Contrato de no regresion.
+- Matriz de extraccion desde ramas conflictivas.
+- Plan de parser y command registry con compatibilidad completa.
+- Plan de extraccion de comandos y wrappers.
+- Plan de docs, tests y evidencia.
+- Plan de limpieza controlada de ramas con aprobacion explicita.
+- Handoffs por slice: `EXECUTION_BRIEF.md` y `CLOSURE_BRIEF.md`.
+
+## 6. Fuera de alcance
+
+No incluye:
+
+- Implementar codigo.
+- Hacer merge, rebase, push o cherry-pick.
+- Eliminar ramas.
+- Cambiar `package.json`, `package-lock.json` o version durante los slices de extraccion inicial.
+- Resolver conflictos automaticamente.
+- Ejecutar acciones destructivas.
+- Tomar decisiones remotas finales sin verificar frescura del snapshot.
+
+## 7. Actores involucrados
+
+- Tech Lead: define criterios, riesgos y aprobaciones.
+- Implementador futuro: ejecuta slices aprobados.
+- Reviewer: valida no regresion y coherencia de cambios.
+- Maintainer del repo: aprueba limpieza de ramas y cambios de comportamiento.
+- Usuarios de CLI: consumidores directos de comandos, flags, salidas y archivos generados.
+- Automatizaciones/CI: consumidores de exit codes, `--json`, scripts y outputs estables.
+
+## 8. Requerimientos funcionales
+
+- FR-01: El proceso debe identificar rama base, SHA base, fecha del snapshot y frescura del dato.
+- FR-02: Cada rama debe clasificarse como `sin delta`, `merge candidata`, `extraccion candidata`, `cerrable`, `eliminable con aprobacion`, `protegida/no tocar`, `historica` o `requiere revision`.
+- FR-03: Toda rama conflictiva debe distinguir conflicto textual, semantico y de contrato.
+- FR-04: Antes de extraer codigo debe existir baseline de comportamiento actual.
+- FR-05: El baseline debe cubrir comandos, aliases, flags, `--help`, `--json`, exit codes, stdout, stderr, archivos generados, scripts, exports internos, templates y docs generadas.
+- FR-06: Ninguna funcionalidad existente puede quitarse sin aprobacion explicita.
+- FR-07: Si una funcionalidad se modifica, debe documentarse que hacia antes, por que cambia, cual es la mejora y como se valida.
+- FR-08: La extraccion desde ramas viejas debe clasificar cada hallazgo como `extraer codigo`, `extraer concepto`, `rehacer` o `descartar`.
+- FR-09: Parser y command registry deben tratarse como cambios transversales de alto riesgo.
+- FR-10: Cualquier limpieza de ramas requiere aprobacion explicita por rama o grupo claramente listado.
+
+## 9. Requerimientos no funcionales
+
+- NFR-01: El proceso debe ser auditable y reproducible.
+- NFR-02: Los slices deben ser pequenos, revisables y con gates claros.
+- NFR-03: Los comandos Git sugeridos deben ser read-only salvo aprobacion explicita.
+- NFR-04: La documentacion debe ser apta para humanos y agentes.
+- NFR-05: La implementacion futura debe ser reversible mediante rollback definido por slice.
+- NFR-06: La evidencia debe distinguir validado, no validado y pendiente.
+
+## 10. Reglas de negocio
+
+- BR-01: `origin/main` es la unica base recomendada para nuevas ramas, sujeto a snapshot fresco.
+- BR-02: `main` local divergida no es base segura.
+- BR-03: `ahead=0` no autoriza eliminacion.
+- BR-04: `merge-tree` no es suficiente para declarar una rama segura.
+- BR-05: Cambios de parser, package, i18n, docs generadas, CI o tests son riesgo alto aunque no haya conflicto textual.
+- BR-06: No se deben mezclar refactors con bumps de version.
+- BR-07: No se debe hacer cherry-pick completo de commits grandes sin analisis previo.
+- BR-08: Cada cambio de comando requiere matriz antes/despues.
+- BR-09: Cada slice debe poder cerrarse con evidencia o quedar explicitamente bloqueado.
+- BR-10: Implementar codigo requiere pedido explicito posterior.
+
+## 11. Flujo general
+
+1. Tomar snapshot verificable de ramas y base.
+2. Clasificar ramas con evidencia y riesgo.
+3. Construir baseline del comportamiento actual.
+4. Definir contrato de no regresion.
+5. Evaluar ramas candidatas para extraccion parcial.
+6. Planificar parser/command registry contra baseline.
+7. Planificar comandos/wrappers con matriz antes/despues.
+8. Alinear docs, tests y evidencia.
+9. Proponer limpieza de ramas sin ejecutarla.
+
+## 12. Entradas y salidas relevantes
+
+Entradas:
+
+- Refs locales y remotos.
+- `origin/main` y su SHA.
+- Resultado de `git diff`, `git log`, `git cherry`, `git merge-base` y `git merge-tree`.
+- Baseline de comandos CLI.
+- Requerimientos aprobados por el usuario.
+
+Salidas:
+
+- Inventario de ramas clasificado.
+- Baseline de comportamiento actual.
+- Contrato de no regresion.
+- Matriz de extraccion.
+- Handoffs por slice.
+- Recomendaciones de limpieza pendientes de aprobacion.
+
+## 13. Dependencias
+
+- Git disponible localmente.
+- Refs remotos presentes en el repo local.
+- Posible `fetch` futuro si se aprueba verificar frescura remota.
+- Conocimiento de comandos CLI actuales.
+- Tests existentes y documentacion del repo.
+
+## 14. Riesgos, restricciones o consideraciones
+
+- Snapshot remoto puede estar desactualizado.
+- Algunas ramas pueden ser historicas o protegidas.
+- Ramas antiguas pueden contener ideas utiles con codigo obsoleto.
+- Parser/registry puede romper toda la CLI.
+- Tests nuevos pueden reemplazar cobertura vieja sin equivalencia.
+- Docs generadas pueden divergir de la CLI real.
+- Cambios de `--json`, exit codes o side effects pueden romper automatizaciones.
+
+## 15. Estrategia de slicing
+
+La estrategia prioriza reduccion de riesgo antes de extraccion tecnica. Primero se documenta el estado de ramas, despues se establece el baseline de comportamiento, luego el contrato de no regresion y recien despues se planifican extracciones.
+
+Los slices son documentales y preparatorios. No implementan codigo. Cada slice incluye handoffs para ejecucion futura.
+
+## 16. Roadmap de slices
+
+| Slice | Nombre | Objetivo |
+|---|---|---|
+| `01-slice` | Snapshot verificable de ramas | Crear inventario confiable y clasificable. |
+| `02-slice` | Baseline de comportamiento actual | Saber que no se puede romper. |
+| `03-slice` | Contrato de no regresion | Convertir compatibilidad en reglas verificables. |
+| `04-slice` | Matriz de extraccion por rama | Decidir que rescatar, rehacer o descartar. |
+| `05-slice` | Parser y command registry | Planificar cambio transversal con gates completos. |
+| `06-slice` | Comandos y wrappers | Planificar extraccion por comando con antes/despues. |
+| `07-slice` | Docs, tests y evidencia | Alinear pruebas y documentacion con comportamiento real. |
+| `08-slice` | Limpieza controlada de ramas | Proponer cierre/eliminacion solo con aprobacion. |
+
+## 17. Supuestos, pendientes y preguntas abiertas
+
+Supuestos:
+
+- El snapshot actual sirve para planificar, pero acciones finales requieren verificacion de frescura.
+- La prioridad es estabilidad sobre velocidad de integracion.
+- No se implementara codigo hasta una instruccion explicita posterior.
+
+Pendientes:
+
+- Confirmar si se permitira `fetch` antes de acciones remotas finales.
+- Definir si hay ramas protegidas por politica externa al repo local.
+- Definir comandos criticos de CLI si el baseline no puede cubrir todos en una primera pasada.
+
+Preguntas abiertas:
+
+- Que ramas deben conservarse como historicas aunque no tengan delta?
+- Que nivel de evidencia se exigira para aprobar cambios en `--json`?

package/docs/workflows/full-ai-spec-to-pr.md

@@ -236,6 +236,7 @@ Qué hace:
 ## 14. Validar antes del PR
 
 ```bash
+npx --yes create-quiver@latest check-pr specs/<spec-slug>/slices/<slice-id>/slice.json
 npx --yes create-quiver@latest spec validate specs/<spec-slug> --strict
 npx --yes create-quiver@latest next --all-ready --spec <spec-slug>
 git diff --check
@@ -243,8 +244,9 @@ git diff --check
 
 Qué hace:
 
+- valida que el slice tenga cuerpo de PR y secciones requeridas;
 - confirma que el paquete de spec esté completo;
-- confirma que no queden slices listos sin ejecutar;
+- confirma el estado de los slices de la spec;
 - revisa whitespace.
 
 También corré validaciones propias del proyecto:
@@ -257,7 +259,26 @@ npm run lint
 
 Usá solo los scripts que existan en el proyecto.
 
-## 15. Previsualizar creación del PR
+## 15. Preparar el PR
+
+Regla de política:
+
+- un slice equivale a un PR por defecto;
+- un PR agrupado sólo aplica a 2-3 slices docs-only, research-only o limpieza mecánica de bajo riesgo;
+- no agrupes cambios de comportamiento, UI, backend, refactor, performance, Supabase, Edge Functions, auth, storage, preview, tests o CI que afecten gates.
+
+Para PR individual de slice, usá el `pr.md` del slice como cuerpo del PR y mantené evidencia separada:
+
+```bash
+gh pr create \
+  --draft \
+  --title "<slice title>" \
+  --body-file specs/<spec-slug>/slices/<slice-id>/pr.md \
+  --base <base-branch> \
+  --head <current-branch>
+```
+
+Para PRs agrupados permitidos o PRs documentales que usan el cuerpo generado de spec, primero previsualizá con Quiver:
 
 ```bash
 npx --yes create-quiver@latest ai pr \
@@ -280,6 +301,18 @@ Adaptá `--identity-file` a la ruta real de tu máquina, por ejemplo `~/ssh/gith
 
 ## 16. Crear el pull request
 
+Para PR individual de slice, crealo con `gh` usando el cuerpo del slice:
+
+```bash
+gh pr create \
+  --title "<slice title>" \
+  --body-file specs/<spec-slug>/slices/<slice-id>/pr.md \
+  --base <base-branch> \
+  --head <current-branch>
+```
+
+Para PRs agrupados permitidos o documentales que usan `specs/<spec-slug>/pr.md`, podés usar Quiver:
+
 ```bash
 npx --yes create-quiver@latest ai pr \
   --create \
@@ -293,10 +326,20 @@ Qué hace:
 
 - abre el PR usando `gh`;
 - usa el cuerpo generado en `pr.md`;
-- bloquea la creación si todavía quedan slices abiertos.
+- aplica preflight antes de crear el PR.
+
+Merge:
+
+- el merge humano es el default;
+- el agente puede crear el PR, corregir CI, monitorear checks y marcarlo como listo;
+- no uses auto-merge asistido salvo autorización explícita para ese PR o para una categoría documentada;
+- el auto-merge asistido sólo aplica a docs-only o chore-only de bajo riesgo, sin runtime, sin configuración productiva, con checks verdes y sin comentarios pendientes;
+- el auto-merge asistido está prohibido para UI, Supabase, Edge Functions, auth, storage, preview, performance, refactors y cambios con rollback dudoso.
 
 ## 17. Después del merge
 
+Usá este cierre sólo después de que el último PR de la spec haya sido mergeado.
+
 ```bash
 npx --yes create-quiver@latest spec close specs/<spec-slug> --dry-run
 npx --yes create-quiver@latest spec close specs/<spec-slug>

package/i18n/es/docs/GITFLOW_PR_GUIDE.md.template

@@ -1,4 +1,41 @@
 # Guía de Git y PR
 
-Usá un branch, un worktree y un PR por slice.
+Usá un branch, un worktree y un PR por slice por defecto.
 
+## Regla base
+
+- Un slice equivale a un commit.
+- Un slice equivale a un PR por defecto.
+- Un spec puede generar múltiples PRs.
+- Los PRs agrupados son excepciones y deben cumplir la política de agrupación.
+
+## PR individual obligatorio
+
+Abrí un PR individual para cualquier slice que incluya:
+
+- código funcional;
+- UI/UX;
+- Supabase, Edge Functions, auth o storage;
+- preview o comportamiento de deploy;
+- performance o code-splitting;
+- refactors;
+- tests o CI que afecten gates.
+
+## PR agrupado permitido
+
+Un PR agrupado está permitido sólo si:
+
+- incluye como máximo 2-3 slices;
+- todos los slices son docs-only, research-only o limpieza mecánica de bajo riesgo;
+- no cambia comportamiento;
+- no mezcla docs con UI, backend, refactor o performance;
+- cada slice mantiene evidencia separada;
+- el PR completo puede revertirse sin dejar estado parcial.
+
+## Merge y auto-merge
+
+- El merge humano es el default.
+- Los agentes IA pueden crear PRs, corregir CI, monitorear checks y marcar PRs como listos.
+- El auto-merge asistido sólo está permitido con autorización humana explícita para ese PR o para una categoría documentada.
+- El auto-merge asistido sólo aplica a PRs docs-only o chore-only de bajo riesgo, sin runtime, sin configuración productiva, con checks verdes y sin comentarios pendientes.
+- El auto-merge asistido está prohibido para UI, Supabase, Edge Functions, auth, storage, preview, performance, refactors y cambios con rollback dudoso.

package/package.json

@@ -1,20 +1,33 @@
 {
   "name": "create-quiver",
-  "version": "0.15.4",
+  "version": "0.16.0",
   "private": false,
   "description": "Quiver CLI for scaffolding projects from the packaged template",
   "license": "MIT",
+  "engines": {
+    "node": ">=20.12.0"
+  },
   "bin": {
     "create-quiver": "bin/create-quiver.js",
     "quiver": "bin/create-quiver.js"
   },
   "scripts": {
+    "test": "node scripts/ci/run-node-tests.js",
+    "test:ci": "node scripts/ci/run-node-tests.js",
+    "docs:lint": "node scripts/ci/check-docs-markdown.js",
+    "docs:links": "node scripts/ci/check-doc-links.js",
+    "docs:commands:write": "node scripts/ci/check-command-reference.js --write",
+    "docs:commands:check": "node scripts/ci/check-command-reference.js --check",
+    "docs:check": "npm run docs:lint && npm run docs:links && npm run docs:commands:check",
+    "changelog:check": "node scripts/ci/check-changelog.js",
+    "schema:slice:check": "node scripts/ci/check-slice-schema.js",
     "check:slice": "bash tools/scripts/check-slice-readiness.sh",
     "check:pr": "bash tools/scripts/check-pr-readiness.sh",
     "start:slice": "bash tools/scripts/start-slice.sh",
     "cleanup:slice": "bash tools/scripts/cleanup-slice.sh",
     "migrate": "bash tools/scripts/migrate-project.sh",
     "quiver:version": "npx create-quiver version",
+    "quiver:migrate": "node bin/create-quiver.js migrate",
     "quiver:analyze": "npx create-quiver analyze",
     "quiver:flow": "npx create-quiver flow",
     "quiver:dashboard": "npx create-quiver dashboard",
@@ -45,6 +58,14 @@
     "quiver:spec:status": "npx create-quiver spec status",
     "quiver:spec:validate": "npx create-quiver spec validate",
     "quiver:spec:close": "npx create-quiver spec close",
+    "quiver:start-slice": "node bin/create-quiver.js slice start",
+    "quiver:check-slice": "node bin/create-quiver.js slice check",
+    "quiver:check-pr": "node bin/create-quiver.js slice pr",
+    "quiver:check-scope": "node bin/create-quiver.js slice scope",
+    "quiver:cleanup-slice": "node bin/create-quiver.js slice cleanup",
+    "quiver:refresh-active-slices": "node bin/create-quiver.js slice refresh-active",
+    "quiver:check-handoff": "node bin/create-quiver.js handoff check",
+    "quiver:new-handoff": "node bin/create-quiver.js handoff new",
     "package:quiver": "bash scripts/package-quiver.sh",
     "smoke:create-quiver": "bash scripts/ci/smoke-create-quiver.sh",
     "smoke:doctor-fixtures": "node scripts/ci/smoke-doctor-fixtures.js",
@@ -55,5 +76,10 @@
   "dependencies": {
     "@clack/prompts": "^1.4.0",
     "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "ajv": "^8.18.0",
+    "markdown-link-check": "^3.14.2",
+    "markdownlint-cli2": "^0.22.1"
   }
 }

package/pr.md

@@ -0,0 +1,154 @@
+## Title
+
+chore(release): 0.16.0
+
+## Summary
+
+Prepares `create-quiver` `0.16.0` for publication. This release bumps package metadata from `0.15.3` to `0.16.0` and updates the changelog with the newly integrated read-only `changelog` command, parser/registry extraction, Spec 01 closure package, and release-readiness command-role audit.
+
+## PR Policy
+
+- One release = one commit.
+- Base branch: `main`.
+- Branch: `release/create-quiver-0.16.0`.
+- Human merge required.
+- This PR does not publish to npm.
+- Publishing remains explicitly guarded by `QUIVER_ALLOW_NPM_PUBLISH=1` and npm auth.
+
+## Scope
+
+Includes:
+
+- Bump `package.json` to `0.16.0`.
+- Bump `package-lock.json` root/package versions to `0.16.0`.
+- Update `CHANGELOG.md` with release notes for the command wrapper, parser/registry extraction, evidence gates, and Spec 01 closure.
+- Validate the CLI command surface and release gates before opening the PR.
+
+Excludes:
+
+- No `npm publish`.
+- No npm tag creation.
+- No Git tag creation.
+- No branch cleanup.
+- No runtime code changes beyond already-merged slices.
+
+## Files
+
+- `package.json`
+- `package-lock.json`
+- `CHANGELOG.md`
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+- Node.js and npm installed.
+- Dependencies installed with `npm ci` or existing `node_modules` available.
+- Git checkout of this PR branch.
+- npm publish credentials are not required for PR validation.
+
+### Worktree Access
+
+1. Checkout `release/create-quiver-0.16.0`.
+2. Confirm the package version is `0.16.0`:
+
+   ```bash
+   node -e "const p=require('./package.json'); const l=require('./package-lock.json'); console.log(p.version, l.version, l.packages[''].version)"
+   ```
+
+3. Confirm only release metadata files changed:
+
+   ```bash
+   git diff --stat origin/main...HEAD
+   ```
+
+### Run the Project
+
+No server is required. This is a CLI package release PR.
+
+### Use Cases
+
+1. Confirm release version metadata.
+
+   Expected:
+
+   - `package.json` reports `0.16.0`.
+   - `package-lock.json` reports `0.16.0` at root and package entry.
+
+2. Confirm changelog explains why the release exists.
+
+   Expected:
+
+   - `CHANGELOG.md` includes `changelog` command notes.
+   - `CHANGELOG.md` includes parser/registry extraction and release-readiness evidence notes.
+
+3. Confirm the new command role.
+
+   Expected:
+
+   - `changelog` is read-only.
+   - Human output explains packaged release notes.
+   - JSON output is parseable for automation.
+
+4. Confirm public command roles are understood before publish.
+
+   Expected:
+
+   - Help/version/changelog/config are direct inspection commands.
+   - Init/analyze/migrate/demo/evidence write only in explicit or fixture-safe modes.
+   - Flow/dashboard/plan/graph/next/spec/slice/handoff commands describe workflow state and validation.
+   - AI commands are lifecycle, planning, provider-profile, execution, inspection, and PR-preflight surfaces.
+   - Commands with missing prerequisites fail with actionable, controlled errors instead of crashes.
+
+### Technical Verification
+
+Run:
+
+```bash
+npm run changelog:check
+npm run docs:check
+npm run schema:slice:check
+npm test
+```
+
+Optional release dry-run from a clean worktree:
+
+```bash
+npm ci
+bash scripts/release-quiver.sh patch
+```
+
+Expected:
+
+- Changelog validation passes.
+- Docs lint/link/generated command reference checks pass.
+- Slice schema validation passes.
+- Full test suite passes.
+- Release dry-run passes through changelog/docs/schema, installer smoke, package artifact, and installed CLI smoke.
+
+## Evidence
+
+Validated locally before PR:
+
+- `npm run changelog:check`: OK, `Unreleased entries: 26`.
+- `npm run docs:check`: OK.
+- `npm run schema:slice:check`: OK.
+- `npm test`: OK, `655/655` pass.
+- Manual command-role audit: OK after correcting fixtures/preconditions.
+- `changelog` human output: OK.
+- `changelog --json`: OK, parseable JSON.
+- `status --json`: controlled unsupported top-level command, as intended.
+- Release dry-run in clean temporary worktree with `npm ci`: OK.
+- Package smoke: OK, `create-quiver-0.16.0.tgz` installed CLI smoke passed.
+
+## Rollback
+
+Revert the single release commit before merge. If already merged but not published, revert the release commit on `main`. If already published, do not unpublish by default; publish a corrective patch release instead.
+
+## Risks / Notes
+
+- npm `latest` is currently `0.15.4`; this PR intentionally prepares `0.16.0` because the public CLI surface changed with `changelog`.
+- Local `npm whoami` previously returned `401 Unauthorized`; publishing requires npm login before the final publish step.
+- `QUIVER_ALLOW_NPM_PUBLISH=1` must be explicitly set for guarded publish flows.
+- The release script does not publish in this PR.
+- Local `pr.md` is not part of the PR commit.

package/scripts/package-quiver.sh

@@ -6,6 +6,9 @@ repo_root="$(git rev-parse --show-toplevel)"
 temp_root="$(mktemp -d "${TMPDIR:-/tmp}/quiver-pack.XXXXXX")"
 pack_dir="$temp_root/pack"
 npm_cache="$temp_root/npm-cache"
+install_root="$temp_root/install-root"
+dry_run_target="$temp_root/dry-run-project"
+cli_version="$(node -p 'require(process.argv[1]).version' "$repo_root/package.json")"
 
 cleanup() {
   rm -rf "$temp_root"
@@ -15,13 +18,14 @@ trap cleanup EXIT
 
 mkdir -p "$pack_dir"
 mkdir -p "$npm_cache"
+mkdir -p "$install_root"
 
 pack_json="$(
   cd "$repo_root" && npm_config_cache="$npm_cache" npm pack --json --pack-destination "$pack_dir"
 )"
 
 tarball_name="$(
-  node -e 'const data = JSON.parse(process.argv[1]); process.stdout.write(data[0].filename);' "$pack_json"
+  printf '%s\n' "$pack_json" | node -e 'const fs = require("node:fs"); const data = JSON.parse(fs.readFileSync(0, "utf8")); process.stdout.write(data[0].filename);'
 )"
 tarball_path="$pack_dir/$tarball_name"
 
@@ -68,6 +72,41 @@ require_absent() {
   fi
 }
 
+reject_forbidden_content_patterns() {
+  local path
+
+  while IFS= read -r path; do
+    case "$path" in
+      package/package-lock.json|\
+      package/CLI_ANALYSIS.md|\
+      package/REQUERIMIENTOS_DERIVADOS_DE_AUDITORIA.md|\
+      package/Documentation_Report.pdf|\
+      package/WORKTREE_CONTEXT.md|\
+      package/.DS_Store|\
+      package/*/.DS_Store|\
+      package/*.pdf|\
+      package/.env|\
+      package/.env.*|\
+      package/.npmrc|\
+      package/.npm/*|\
+      package/.ssh/*|\
+      package/ssh/*|\
+      package/*.pem|\
+      package/*.key|\
+      package/.claude/*|\
+      package/.codex/*|\
+      package/.quiver/*|\
+      package/.worktrees/*|\
+      package/tests/*|\
+      package/examples/*|\
+      package/scripts/ci/*)
+        echo "FAIL: el paquete incluye contenido fuera del contrato: $path" >&2
+        exit 1
+        ;;
+    esac
+  done <<<"$contents"
+}
+
 required_paths=(
   "package/package.json"
   "package/bin/create-quiver.js"
@@ -93,6 +132,9 @@ required_paths=(
   "package/.github/ISSUE_TEMPLATE/feature_request.md"
   "package/.github/workflows/ci.yml"
   "package/docs/INDEX.md.template"
+  "package/docs/reference/commands.md"
+  "package/docs/schema/slice.schema.json"
+  "package/docs/reference/slice-schema.md"
   "package/docs/DOCUMENTATION_GUIDE.md.template"
   "package/docs/WORKFLOW.md.template"
   "package/docs/SUPPORT_MATRIX.md.template"
@@ -127,8 +169,16 @@ done
 
 excluded_paths=(
   "package/package-lock.json"
+  "package/CLI_ANALYSIS.md"
+  "package/REQUERIMIENTOS_DERIVADOS_DE_AUDITORIA.md"
+  "package/Documentation_Report.pdf"
+  "package/.DS_Store"
+  "package/WORKTREE_CONTEXT.md"
   "package/tests/"
   "package/examples/"
+  "package/.claude/"
+  "package/.codex/"
+  "package/.quiver/"
   "package/.worktrees/"
   "package/specs/quiver-v01/"
   "package/specs/quiver-v02-bootstrap-hardening/"
@@ -144,4 +194,34 @@ for path in "${excluded_paths[@]}"; do
   fi
 done
 
-printf 'Package smoke passed: %s\n' "$tarball_name"
+reject_forbidden_content_patterns
+
+npm_config_cache="$npm_cache" npm install --prefix "$install_root" "$tarball_path" --ignore-scripts --no-audit --no-fund >/dev/null
+installed_cli="$install_root/node_modules/create-quiver/bin/create-quiver.js"
+
+if [[ ! -f "$installed_cli" ]]; then
+  echo "FAIL: no se encontró el CLI instalado en $installed_cli" >&2
+  exit 1
+fi
+
+installed_semver="$(node "$installed_cli" --version)"
+if [[ "$installed_semver" != "$cli_version" ]]; then
+  echo "FAIL: el CLI instalado devolvió versión '$installed_semver', esperada '$cli_version'" >&2
+  exit 1
+fi
+
+installed_help="$(node "$installed_cli" --help)"
+if [[ "$installed_help" != *"version [--json]"* ]] \
+  || [[ "$installed_help" != *"spec create"* ]] \
+  || [[ "$installed_help" != *"slice start|check|pr|scope|cleanup|refresh-active"* ]]; then
+  echo "FAIL: la ayuda del CLI instalado no expone comandos públicos esperados" >&2
+  exit 1
+fi
+
+node "$installed_cli" init --dry-run --name "Package Smoke" --dir "$dry_run_target" --skip-install >/dev/null
+if [[ -e "$dry_run_target" ]]; then
+  echo "FAIL: init --dry-run del CLI instalado escribió en $dry_run_target" >&2
+  exit 1
+fi
+
+printf 'Package smoke passed: %s (installed CLI smoke passed)\n' "$tarball_name"