create-quiver 0.15.4 → 0.17.0

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

@@ -0,0 +1,87 @@
+# CLOSURE_BRIEF - Spec 01
+
+## Resultado
+
+Spec 01 cerrada como iniciativa de recuperacion segura de ramas y extraccion incremental sin regresiones.
+
+El cierre es documental y operativo. No ejecuta limpieza de ramas, no elimina refs, no hace merge adicional, no hace rebase y no cambia comportamiento runtime.
+
+## Base de cierre
+
+| Dato | Valor |
+|---|---|
+| Fecha de cierre | 2026-06-09 |
+| Base usada | `origin/main` |
+| SHA base al crear rama de cierre | `fd62e8b` |
+| Rama de cierre | `chore/QUIVER-01-final-closure` |
+| Estado local relevante | `pr.md` sigue untracked y queda fuera del cierre |
+
+## Estado por slice
+
+| Slice | Estado | Evidencia |
+|---|---|---|
+| `01-slice` | Cerrado | Snapshot inicial de ramas documentado |
+| `02-slice` | Cerrado | Baseline de comportamiento documentado |
+| `03-slice` | Cerrado | Contrato de no regresion documentado |
+| `04-slice` | Cerrado | Matriz de extraccion documentada |
+| `05-slice` | Mergeado | Commit `96b9fad` contenido en `origin/main` |
+| `06-slice` | Mergeado | PR `#110`; commit `28e6e8b` contenido en `origin/main` |
+| `07-slice` | Mergeado | PR `#111`; commit `564b37d` contenido en `origin/main` |
+| `08-slice` | Mergeado | PR `#112`; commit `dde1347` contenido en `origin/main` |
+
+## Cambios integrados
+
+- Parser y command registry extraidos de forma incremental.
+- Wrapper read-only `changelog` integrado con help, docs generadas y tests contractuales.
+- Gate de docs/tests/evidencia formalizado para futuros cambios de CLI.
+- Plan de limpieza controlada de ramas documentado con snapshot remoto fresco.
+
+## Funcionalidad existente
+
+- No se quito funcionalidad existente.
+- No se eliminaron aliases.
+- No se modifico `package.json` ni versionado dentro del cierre.
+- `status` top-level sigue sin habilitarse para evitar colision con `ai status` y `spec status`.
+- Las acciones destructivas sobre ramas siguen bloqueadas hasta aprobacion explicita.
+
+## Validaciones y evidencia consolidada
+
+| Area | Evidencia |
+|---|---|
+| Parser/registry | Tests contractuales del `05-slice` ejecutados antes de merge |
+| `changelog` | `node --test tests/commands/parser-contract.test.js tests/commands/cli-contract.test.js` paso con `17/17` |
+| Docs generadas | `npm run docs:commands:check` paso antes del PR `#110` |
+| Changelog | `npm run changelog:check` paso antes del PR `#110` |
+| Limpieza de ramas | Solo snapshot y propuesta; no se ejecuto delete/prune |
+
+## Decisiones finales
+
+- `origin/main` queda como base segura para ramas nuevas.
+- `main` local no debe usarse como base mientras siga divergida.
+- `feature/QUIVER-46-49-cli-modernization` sigue siendo fuente historica y tiene manejo separado por PR abierto detectado en el `08-slice`.
+- Ramas con `ahead=0` no quedan automaticamente autorizadas para eliminar.
+- Cualquier limpieza local/remota requiere aprobacion posterior por rama o grupo claramente listado.
+
+## Acciones no ejecutadas
+
+No se ejecuto ninguno de estos comandos:
+
+```bash
+git branch -d <branch>
+git branch -D <branch>
+git push origin --delete <branch>
+git remote prune origin
+git merge
+git rebase
+```
+
+## Pendientes o riesgos residuales
+
+- `pr.md` queda local sin trackear como archivo auxiliar de PR; no fue eliminado.
+- La limpieza de ramas sigue pendiente de aprobacion explicita.
+- El estado de PRs abiertos y ramas remotas puede cambiar; antes de limpiar, repetir `git fetch origin`, `git ls-remote --heads origin` y `gh pr list`.
+- Politicas externas de proteccion de ramas no son completamente visibles desde Git local.
+
+## Recomendacion
+
+Cerrar esta spec con un PR documental. Despues del merge, decidir por separado si se autoriza limpieza de ramas por grupo, empezando por `git remote prune origin --dry-run` y sin borrar nada hasta nueva aprobacion.

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.17.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/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"

package/scripts/release-quiver.sh

@@ -11,12 +11,15 @@ usage() {
 Usage: scripts/release-quiver.sh [patch|minor|major|x.y.z] [--publish | --publish-current]
 
 By default the script performs a release dry run:
+  - validates changelog, docs, and schema gates
   - validates the installer smoke
-  - validates the package artifact
+  - validates the package artifact and installed CLI smoke
   - prints the versioning and publish commands to run next
 
-Pass --publish to run npm version and npm publish after the smoke checks pass.
-Pass --publish-current to publish the current package version without forcing a patch bump.
+Publishing remains manually guarded. Pass --publish only with
+QUIVER_ALLOW_NPM_PUBLISH=1 to run npm version and npm publish after the smoke
+checks pass. Pass --publish-current with the same environment guard to publish
+the current package version without forcing a patch bump.
 EOF
 }
 
@@ -50,6 +53,14 @@ if [[ -n "$(git status --porcelain)" ]]; then
   exit 1
 fi
 
+if [[ "$publish" == "true" && "${QUIVER_ALLOW_NPM_PUBLISH:-}" != "1" ]]; then
+  echo "FAIL: publishing requires QUIVER_ALLOW_NPM_PUBLISH=1. Run the dry-run first and publish manually unless this release is explicitly authorized." >&2
+  exit 1
+fi
+
+npm run changelog:check
+npm run docs:check
+npm run schema:slice:check
 bash scripts/ci/smoke-create-quiver.sh
 bash scripts/package-quiver.sh
 

package/specs/[project-name]/slices/pr.md.template

@@ -8,6 +8,25 @@
 
 [Brief summary of what was implemented and why]
 
+## PR Policy
+
+- [ ] One slice only.
+- [ ] Grouped PR exception: at most 2-3 slices, all docs-only, research-only, or low-risk mechanical cleanup.
+- [ ] No behavior changes in a grouped PR.
+- [ ] No mixed docs with UI, backend, refactor, or performance work.
+- [ ] Separate evidence for each included slice.
+- [ ] Whole PR is revertible without leaving partial state.
+
+Individual PR required when this slice includes functional code, UI/UX, Supabase, Edge Functions, auth, storage, preview, performance/code-splitting, refactors, or tests/CI changes that affect gates.
+
+### Merge Policy
+
+- [ ] Human merge expected.
+- [ ] Assisted auto-merge explicitly authorized for this PR or documented category.
+- [ ] Assisted auto-merge conditions met: docs-only or chore-only, low risk, no runtime changes, no production configuration changes, green checks, and no pending comments.
+
+Assisted auto-merge is prohibited for UI, Supabase, Edge Functions, auth, storage, preview, performance, refactors, and changes with doubtful rollback.
+
 ## Scope
 
 - [Included change 1]