create-quiver 0.9.1 → 0.12.0

package/specs/quiver-v22-guided-ai-workflow/slices/slice-05-spec-worktree-lifecycle/EXECUTION_BRIEF.md

@@ -0,0 +1,56 @@
+# EXECUTION BRIEF - slice-05: Spec worktree lifecycle
+
+**Spec:** quiver-v22-guided-ai-workflow
+**Slice:** slice-05-spec-worktree-lifecycle
+**Tipo:** feature
+
+## Contexto
+
+El flujo deseado usa un worktree por SPEC, no una mezcla manual de ramas y worktrees por cada tarea.
+
+## Objetivo
+
+Agregar ciclo de vida de worktree a nivel spec y bloquear ejecucion hasta que `slice-00` este completada.
+
+## Alcance
+
+- Comandos de spec start/status.
+- Seleccion segura de base branch.
+- Reuso seguro de worktree existente.
+- Estado de slices dentro del spec.
+
+## Criterios de aceptacion
+
+- Un spec tiene un worktree dedicado.
+- `slice-00` es obligatoria primero.
+- El estado muestra rama, path y pendientes.
+- No se borra ni pisa trabajo local.
+
+## Plan tecnico resumido
+
+Extraer o extender helpers de lifecycle para soportar spec-level worktrees, manteniendo compatibilidad con start-slice existente.
+
+## Pasos sugeridos de ejecucion
+
+1. Revisar `lifecycle.js`, `slice.js` y `git.js`.
+2. Definir metadata de spec worktree.
+3. Agregar comando start/status.
+4. Cubrir main/develop y paths con espacios.
+5. Agregar tests.
+
+## Restricciones
+
+- No cerrar worktrees en esta slice.
+- No crear PR en esta slice.
+
+## Riesgos
+
+- Romper `start-slice` existente.
+- Mantener supuestos viejos de `develop` cuando el repo usa `main`.
+
+## Checklist de finalizacion
+
+- [ ] Spec worktree start/status listo.
+- [ ] Base branch segura.
+- [ ] Bloqueo de slice-00 cubierto.
+- [ ] Tests pasan.

package/specs/quiver-v22-guided-ai-workflow/slices/slice-05-spec-worktree-lifecycle/slice.json

@@ -0,0 +1,54 @@
+{
+  "slice_id": "slice-05-spec-worktree-lifecycle",
+  "ticket": "QUIVER-22-05",
+  "type": "feature",
+  "title": "Spec worktree lifecycle",
+  "objective": "Formalize one dedicated worktree per spec and make slice-00 the first executable step.",
+  "description": "Add commands and guardrails for starting, inspecting, and managing a spec-level worktree before slice execution.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "spec-worktree-lifecycle",
+    "branch_name": "feature/QUIVER-22-05-spec-worktree-lifecycle"
+  },
+  "files": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/lifecycle.js",
+    "src/create-quiver/lib/slice.js",
+    "src/create-quiver/lib/git.js",
+    "src/create-quiver/lib/spec-worktrees.js",
+    "tests/lib/lifecycle.test.js",
+    "tests/commands/spec-worktree.test.js"
+  ],
+  "depends_on": [
+    "slice-04-planner-approval-state"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Spec worktree behavior is required before execution and PR automation.",
+  "must": [
+    "Represent one spec as one worktree and one PR branch.",
+    "Start the spec worktree from the correct base branch.",
+    "Require slice-00 to be first.",
+    "Show spec status, worktree path, branch, and pending slices.",
+    "Avoid deleting or overwriting active worktrees."
+  ],
+  "not_included": [
+    "Post-merge cleanup.",
+    "PR creation.",
+    "Parallel slice execution."
+  ],
+  "acceptance": [
+    "Spec start creates or reuses one dedicated worktree for the spec.",
+    "Spec status shows branch, path, slice-00 status, and pending slices.",
+    "Commands refuse to start later slices before slice-00 is complete.",
+    "Base branch selection supports main or develop without hardcoding the wrong target.",
+    "Existing dirty worktrees are not overwritten."
+  ],
+  "tests": [
+    "node --test tests/lib/lifecycle.test.js tests/commands/spec-worktree.test.js",
+    "git diff --check"
+  ],
+  "estimated_hours": 8,
+  "status": "completed",
+  "blocked_reason": null
+}

package/specs/quiver-v22-guided-ai-workflow/slices/slice-06-executor-commit-recovery/CLOSURE_BRIEF.md

@@ -0,0 +1,32 @@
+# CLOSURE BRIEF - slice-06: Executor commit and recovery
+
+## Resumen de lo realizado
+
+Se extendio `ai execute-slice` para ejecutar validaciones declaradas, bloquear commits ante fallos y crear un unico commit del slice cuando el usuario habilita `--commit`.
+
+## Validacion contra criterios de aceptacion
+
+- [x] Commit unico post-validacion.
+- [x] Fallos bloquean commit.
+- [x] Recovery visible.
+- [x] Tests ejecutados.
+
+## Cambios relevantes
+
+- Nuevo flag `--commit` para commit opt-in despues de provider, scope y validaciones.
+- Nuevo flag `--allow-dirty` para permitir dirty worktree preexistente de forma explicita.
+- Validaciones declaradas en `slice.json.tests` se ejecutan antes del commit.
+- Fallos de provider, scope, validacion o commit agregan guia de retry/abort.
+- Tests cubren provider failure, scope violation, validation failure, dirty worktree, commit exitoso y dry-run CLI.
+
+## Pendientes
+
+Sin pendientes criticos para esta slice.
+
+## Riesgos remanentes
+
+Los comandos de validacion se ejecutan como comandos del proyecto; deben venir de `slice.json.tests` revisado por el equipo.
+
+## Recomendaciones futuras
+
+Las waves de `slice-07` deben reutilizar este ejecutor en vez de duplicar logica de validacion o commit.

package/specs/quiver-v22-guided-ai-workflow/slices/slice-06-executor-commit-recovery/EXECUTION_BRIEF.md

@@ -0,0 +1,58 @@
+# EXECUTION BRIEF - slice-06: Executor commit and recovery
+
+**Spec:** quiver-v22-guided-ai-workflow
+**Slice:** slice-06-executor-commit-recovery
+**Tipo:** feature
+
+## Contexto
+
+El executor debe poder modificar codigo dentro del slice, pero el flujo necesita validacion, reporte y un commit por slice.
+
+## Objetivo
+
+Agregar commit opcional post-validacion y recuperacion clara ante fallos.
+
+## Alcance
+
+- Ejecutar slice con contexto acotado.
+- Validar scope.
+- Ejecutar validaciones declaradas.
+- Crear commit unico si corresponde.
+- Reportar retry/abort cuando algo falla.
+
+## Criterios de aceptacion
+
+- No hay commit si falla provider, scope o validaciones.
+- Si todo pasa y commit esta habilitado, se crea un commit.
+- El usuario ve que hacer ante fallos.
+- El worktree sucio se bloquea por default.
+
+## Plan tecnico resumido
+
+Extender `ai execute-slice` y helpers del executor con una etapa posterior a validacion. Mantener commit automation explicita y testeada.
+
+## Pasos sugeridos de ejecucion
+
+1. Revisar `executor.js` y tests actuales.
+2. Agregar opcion de commit.
+3. Implementar commit message por slice.
+4. Agregar reporte de fallo recuperable.
+5. Cubrir casos happy/error.
+
+## Restricciones
+
+- No ejecutar multiples slices.
+- No abrir PR.
+- No hacer rollback destructivo automatico.
+
+## Riesgos
+
+- Commit accidental con cambios fuera de scope.
+- Mensajes de error poco accionables.
+
+## Checklist de finalizacion
+
+- [ ] Commit opt-in listo.
+- [ ] Scope bloquea commit.
+- [ ] Fallos reportan recovery.
+- [ ] Tests pasan.

package/specs/quiver-v22-guided-ai-workflow/slices/slice-06-executor-commit-recovery/slice.json

@@ -0,0 +1,57 @@
+{
+  "slice_id": "slice-06-executor-commit-recovery",
+  "ticket": "QUIVER-22-06",
+  "type": "feature",
+  "title": "Executor validation, recovery, and commit per slice",
+  "objective": "Let executor agents modify approved slice scope and create one commit after validation passes.",
+  "description": "Extend slice execution with recoverable failure reporting, retry/abort guidance, optional commit automation, and strict one-slice-one-commit behavior.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "executor-commit-recovery",
+    "branch_name": "feature/QUIVER-22-06-executor-commit-recovery"
+  },
+  "files": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/executor.js",
+    "src/create-quiver/lib/scope.js",
+    "src/create-quiver/lib/git.js",
+    "src/create-quiver/lib/slice-runner.js",
+    "tests/commands/ai-execute-slice.test.js",
+    "tests/lib/ai-executor.test.js",
+    "tests/lib/scope.test.js"
+  ],
+  "depends_on": [
+    "slice-05-spec-worktree-lifecycle"
+  ],
+  "parallel_safe": "after_dependencies",
+  "parallel_safe_reason": "Can run in parallel with PR creation only if file scopes remain separate.",
+  "must": [
+    "Keep executor context limited to approved slice data.",
+    "Require a clean worktree before execution unless explicitly overridden by existing safe options.",
+    "Validate changed files against slice scope after execution.",
+    "Run declared validation commands or report why they were skipped.",
+    "Create exactly one commit when validation passes and commit automation is enabled.",
+    "Write or print a recovery report when execution fails."
+  ],
+  "not_included": [
+    "Parallel execution waves.",
+    "PR creation.",
+    "Post-merge cleanup."
+  ],
+  "acceptance": [
+    "Executor refuses to run with dirty worktree by default.",
+    "Executor reports provider failure without hiding local changes.",
+    "Scope violations block commit automation.",
+    "Validation failures block commit automation.",
+    "Successful execution with commit enabled creates one slice commit.",
+    "Retry and abort guidance is shown after failures."
+  ],
+  "tests": [
+    "node --test tests/commands/ai-execute-slice.test.js tests/lib/ai-executor.test.js tests/lib/scope.test.js",
+    "git diff --check"
+  ],
+  "estimated_hours": 8,
+  "status": "completed",
+  "blocked_reason": null
+}

package/specs/quiver-v22-guided-ai-workflow/slices/slice-07-execution-waves-delegation/CLOSURE_BRIEF.md

@@ -0,0 +1,32 @@
+# CLOSURE BRIEF - slice-07: Execution waves and safe delegation
+
+## Resumen de lo realizado
+
+Se agrego `ai execute-plan` para imprimir o ejecutar olas de slices. El plan detecta conflictos por archivos, scope desconocido y fuerza fallback secuencial cuando no es seguro paralelizar.
+
+## Validacion contra criterios de aceptacion
+
+- [x] Olas respetan dependencias.
+- [x] Paralelo bloqueado ante conflictos.
+- [x] Dry-run no ejecuta providers.
+- [x] Tests ejecutados.
+
+## Cambios relevantes
+
+- `execution-plan` ahora incluye `execution_groups`, `fallback_reason` y `unknown_scope_slices`.
+- `parallel_ready` solo queda activo si hay mas de un slice, todos declaran files y no hay overlap.
+- `ai execute-plan --dry-run --commit` imprime comandos de executor por slice.
+- `ai execute-plan --execute --commit` ejecuta slices usando el executor validado y corta ante el primer fallo.
+- La ejecucion real exige `--commit` para preservar un commit por slice.
+
+## Pendientes
+
+Sin pendientes criticos para esta slice.
+
+## Riesgos remanentes
+
+La ejecucion paralela real queda representada como grupos `parallel-ready`; la ejecucion local integrada corre de forma controlada para no mezclar agentes en el mismo worktree.
+
+## Recomendaciones futuras
+
+Si se agrega paralelismo real automatico, debe crear worktrees separados por slice antes de llamar providers en paralelo.

package/specs/quiver-v22-guided-ai-workflow/slices/slice-07-execution-waves-delegation/EXECUTION_BRIEF.md

@@ -0,0 +1,58 @@
+# EXECUTION BRIEF - slice-07: Execution waves and safe delegation
+
+**Spec:** quiver-v22-guided-ai-workflow
+**Slice:** slice-07-execution-waves-delegation
+**Tipo:** feature
+
+## Contexto
+
+El usuario quiere que Quiver indique que slices van secuenciales y cuales pueden ir en paralelo con agentes ejecutores baratos.
+
+## Objetivo
+
+Agregar ejecucion por olas con fallback seguro a secuencial.
+
+## Alcance
+
+- Planificar olas desde dependencias.
+- Validar conflictos por archivos.
+- Imprimir comandos en dry-run.
+- Ejecutar olas cuando este habilitado.
+- Respetar un commit por slice.
+
+## Criterios de aceptacion
+
+- `slice-00` siempre va primero.
+- Paralelo solo se permite sin conflictos.
+- Scope desconocido cae a secuencial.
+- Una falla corta la ola requerida.
+- Dry-run no llama providers.
+
+## Plan tecnico resumido
+
+Extender `execution-plan` y agregar un comando de execute-plan que use el executor ya validado. Mantener primero modo print-only/dry-run.
+
+## Pasos sugeridos de ejecucion
+
+1. Revisar `execution-plan.js` y `slice-graph.js`.
+2. Agregar deteccion de conflicto por files.
+3. Agregar comando dry-run.
+4. Integrar ejecucion real con flags explicitos.
+5. Agregar tests de waves y conflictos.
+
+## Restricciones
+
+- No asumir que paralelo es seguro sin files declarados.
+- No abrir PR.
+
+## Riesgos
+
+- Ejecutar dos agentes que toquen la misma zona.
+- Dejar un wave a medio completar sin reporte claro.
+
+## Checklist de finalizacion
+
+- [ ] Olas generadas.
+- [ ] Conflictos detectados.
+- [ ] Dry-run print-only listo.
+- [ ] Tests pasan.

package/specs/quiver-v22-guided-ai-workflow/slices/slice-07-execution-waves-delegation/slice.json

@@ -0,0 +1,55 @@
+{
+  "slice_id": "slice-07-execution-waves-delegation",
+  "ticket": "QUIVER-22-07",
+  "type": "feature",
+  "title": "Execution waves and safe delegation",
+  "objective": "Execute or print execution waves that respect dependencies, slice-00, and file-scope conflicts.",
+  "description": "Turn the existing execution plan into a guided flow that can run sequential waves and safely identify parallel-ready slices for cheaper executor agents.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "execution-waves-delegation",
+    "branch_name": "feature/QUIVER-22-07-execution-waves-delegation"
+  },
+  "files": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/execution-plan.js",
+    "src/create-quiver/lib/ai/executor.js",
+    "src/create-quiver/lib/slice-graph.js",
+    "src/create-quiver/lib/slice-runner.js",
+    "tests/lib/ai-execution-plan.test.js",
+    "tests/commands/ai-execute-plan.test.js"
+  ],
+  "depends_on": [
+    "slice-06-executor-commit-recovery"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "This slice coordinates multi-slice execution and should not be developed alongside executor changes.",
+  "must": [
+    "Always put slice-00 before all implementation slices.",
+    "Group ready slices into waves.",
+    "Detect file-scope conflicts before suggesting parallel execution.",
+    "Fall back to sequential execution when scope is unknown or conflicting.",
+    "Support a dry-run or print-only mode before real execution.",
+    "Keep one commit per slice when execution is enabled."
+  ],
+  "not_included": [
+    "Provider account billing controls.",
+    "Fully autonomous merge.",
+    "PR creation."
+  ],
+  "acceptance": [
+    "Execution plan shows waves with sequential and parallel groups.",
+    "Unknown or overlapping file scopes force sequential mode.",
+    "Dry-run prints commands and does not call providers.",
+    "Real execution stops the wave on failed required slice.",
+    "Successful slices keep one commit per slice."
+  ],
+  "tests": [
+    "node --test tests/lib/ai-execution-plan.test.js tests/commands/ai-execute-plan.test.js",
+    "git diff --check"
+  ],
+  "estimated_hours": 9,
+  "status": "completed",
+  "blocked_reason": null
+}

package/specs/quiver-v22-guided-ai-workflow/slices/slice-08-pr-create-gh-ssh/CLOSURE_BRIEF.md

@@ -0,0 +1,32 @@
+# CLOSURE BRIEF - slice-08: PR creation with gh and SSH guidance
+
+## Resumen de lo realizado
+
+Se extendio `ai pr` para validar setup, leer `pr.md`, mostrar el plan de `gh pr create` en dry-run y crear el PR solo cuando el usuario pasa `--create`.
+
+## Validacion contra criterios de aceptacion
+
+- [x] Dry-run no crea PR.
+- [x] PR se crea con `gh` en setup valido.
+- [x] Faltantes bloquean.
+- [x] Tests ejecutados.
+
+## Cambios relevantes
+
+- `ai pr --dry-run` imprime comando planificado y no ejecuta `gh pr create`.
+- `ai pr --create --input specs/<spec-slug>/pr.md` ejecuta `gh pr create` con argumentos seguros.
+- El cuerpo del PR se toma de `pr.md`; si hay multiples `pr.md`, se exige `--input`.
+- Se mantiene la validacion de gh, auth, remote, branch, worktree limpio, guia GitFlow, alias SSH e identity file.
+- Tests mockean `gh` y cubren dry-run, create, faltantes y fallos de `gh pr create`.
+
+## Pendientes
+
+Sin pendientes criticos para esta slice.
+
+## Riesgos remanentes
+
+La deteccion automatica de `pr.md` requiere que haya uno solo; si hay varios specs en el repo, el usuario debe pasar `--input`.
+
+## Recomendaciones futuras
+
+Mantener el merge fuera de `ai pr`; el merge queda como decision humana.

package/specs/quiver-v22-guided-ai-workflow/slices/slice-08-pr-create-gh-ssh/EXECUTION_BRIEF.md

@@ -0,0 +1,58 @@
+# EXECUTION BRIEF - slice-08: PR creation with gh and SSH guidance
+
+**Spec:** quiver-v22-guided-ai-workflow
+**Slice:** slice-08-pr-create-gh-ssh
+**Tipo:** feature
+
+## Contexto
+
+`ai pr` hoy valida preflight, pero el flujo final necesita crear el PR con `gh` usando `pr.md`.
+
+## Objetivo
+
+Agregar creacion de PR segura, con dry-run y guia clara para gh/SSH.
+
+## Alcance
+
+- Leer `pr.md`.
+- Validar setup.
+- Construir y ejecutar `gh pr create`.
+- Mantener dry-run.
+- No mergear PRs.
+
+## Criterios de aceptacion
+
+- Dry-run no crea PR.
+- Faltantes bloquean con mensaje claro.
+- Setup valido crea PR usando `pr.md`.
+- Tests mockean `gh`.
+
+## Plan tecnico resumido
+
+Extender preflight existente y agregar una capa de creacion que use argumentos seguros, cuerpo desde archivo y confirmacion explicita.
+
+## Pasos sugeridos de ejecucion
+
+1. Revisar `ai/github.js` y `ai-pr.test.js`.
+2. Definir flags de create.
+3. Leer y validar `pr.md`.
+4. Construir llamada segura a `gh`.
+5. Agregar tests de dry-run y success mockeado.
+
+## Restricciones
+
+- No instalar `gh`.
+- No modificar SSH config.
+- No mergear.
+
+## Riesgos
+
+- Crear PR contra base incorrecta.
+- Confundir alias SSH con identity file.
+
+## Checklist de finalizacion
+
+- [ ] Dry-run listo.
+- [ ] Create listo con mocks.
+- [ ] Faltantes bloquean.
+- [ ] Tests pasan.

package/specs/quiver-v22-guided-ai-workflow/slices/slice-08-pr-create-gh-ssh/slice.json

@@ -0,0 +1,53 @@
+{
+  "slice_id": "slice-08-pr-create-gh-ssh",
+  "ticket": "QUIVER-22-08",
+  "type": "feature",
+  "title": "PR creation with gh and SSH guidance",
+  "objective": "Create GitHub PRs from generated pr.md after validating gh, auth, branch, worktree, remote, and SSH inputs.",
+  "description": "Upgrade GitHub PR preflight into PR creation while keeping dry-run, explicit confirmation, and cross-platform setup guidance.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "pr-create-gh-ssh",
+    "branch_name": "feature/QUIVER-22-08-pr-create-gh-ssh"
+  },
+  "files": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/github.js",
+    "src/create-quiver/lib/pr-create.js",
+    "tests/commands/ai-pr.test.js",
+    "tests/lib/ai-github.test.js"
+  ],
+  "depends_on": [
+    "slice-05-spec-worktree-lifecycle"
+  ],
+  "parallel_safe": "conditional",
+  "parallel_safe_reason": "Conceptually independent after spec worktree lifecycle, but it currently overlaps command-router files with executor and execution-wave slices. Run sequentially unless file ownership is split first.",
+  "must": [
+    "Read the generated pr.md body.",
+    "Validate gh is installed and authenticated.",
+    "Validate remote, branch, worktree, clean state, SSH alias, and identity file.",
+    "Support dry-run without creating a PR.",
+    "Create a PR with gh only after checks pass and user intent is explicit.",
+    "Keep PR merge out of scope."
+  ],
+  "not_included": [
+    "Merging PRs.",
+    "Post-merge cleanup.",
+    "Installing gh automatically."
+  ],
+  "acceptance": [
+    "Dry-run prints the gh command plan and creates no PR.",
+    "Missing gh/auth/identity/GitFlow guide/remote/dirty worktree blocks creation with clear guidance.",
+    "Valid setup creates a PR using pr.md.",
+    "The command never merges the PR.",
+    "Tests mock gh and do not require real GitHub auth."
+  ],
+  "tests": [
+    "node --test tests/commands/ai-pr.test.js tests/lib/ai-github.test.js",
+    "git diff --check"
+  ],
+  "estimated_hours": 7,
+  "status": "completed",
+  "blocked_reason": null
+}

package/specs/quiver-v22-guided-ai-workflow/slices/slice-09-post-merge-cleanup-release-safety/CLOSURE_BRIEF.md

@@ -0,0 +1,33 @@
+# CLOSURE BRIEF - slice-09: Post-merge cleanup and release safety
+
+## Resumen de lo realizado
+
+Se agrego cierre seguro de worktrees por spec con `spec close` y un gate de package safety para bloquear archivos locales sensibles antes del release.
+
+## Validacion contra criterios de aceptacion
+
+- [x] Cleanup bloquea PR no mergeado.
+- [x] Cleanup bloquea worktree sucio.
+- [x] Main local se actualiza.
+- [x] Package safety cubierto.
+
+## Cambios relevantes
+
+- Nuevo comando `npx create-quiver spec close <spec-dir>`.
+- `spec close` bloquea worktrees sucios y ramas de spec no mergeadas, salvo descarte explicito.
+- `spec close --dry-run` muestra la limpieza planeada sin remover worktrees.
+- `spec close` remueve el worktree mergeado y hace `git pull --ff-only` cuando hay remote base.
+- Nuevo modulo `package-safety` para validar paths del tarball.
+- `scripts/package-quiver.sh` ejecuta package safety sobre el contenido real de `npm pack`.
+
+## Pendientes
+
+Sin pendientes criticos para esta slice.
+
+## Riesgos remanentes
+
+Package safety valida nombres/rutas dentro del tarball; no inspecciona secretos embebidos dentro de archivos aparentemente seguros.
+
+## Recomendaciones futuras
+
+Mantener cleanup destructivo separado de PR merge. Si se agrega borrado de ramas remotas, debe quedar detras de un flag explicito distinto.

package/specs/quiver-v22-guided-ai-workflow/slices/slice-09-post-merge-cleanup-release-safety/EXECUTION_BRIEF.md

@@ -0,0 +1,59 @@
+# EXECUTION BRIEF - slice-09: Post-merge cleanup and release safety
+
+**Spec:** quiver-v22-guided-ai-workflow
+**Slice:** slice-09-post-merge-cleanup-release-safety
+**Tipo:** feature
+
+## Contexto
+
+Despues del merge, el usuario quiere cerrar el worktree y actualizar el checkout principal. Ademas, la publicacion npm debe bloquear archivos locales sensibles.
+
+## Objetivo
+
+Agregar cierre seguro de spec y guardas de packaging/release.
+
+## Alcance
+
+- Cleanup post-merge.
+- Validacion de PR mergeado.
+- Proteccion ante worktree sucio.
+- Pull del checkout principal.
+- Guardas para `npm pack`/release.
+
+## Criterios de aceptacion
+
+- No se limpia si el PR no esta mergeado.
+- No se limpia worktree sucio por default.
+- El cierre exitoso elimina worktree y actualiza main.
+- Packaging falla si entran archivos sensibles.
+
+## Plan tecnico resumido
+
+Extender lifecycle a nivel spec y agregar un chequeo de paquete que inspeccione el resultado de `npm pack --dry-run` o equivalente antes de publicar.
+
+## Pasos sugeridos de ejecucion
+
+1. Revisar cleanup actual y supuestos de base branch.
+2. Definir cierre de spec.
+3. Agregar validaciones de merge/dirty.
+4. Agregar package safety.
+5. Cubrir tests y smoke.
+
+## Restricciones
+
+- No mergear PR.
+- No publicar npm.
+- No descartar cambios sin flag explicito.
+
+## Riesgos
+
+- Borrar trabajo local no mergeado.
+- Fallar en repos con base branch distinta.
+- Falsos positivos en package safety.
+
+## Checklist de finalizacion
+
+- [ ] Cleanup seguro listo.
+- [ ] Main/develop sin hardcode incorrecto.
+- [ ] Package safety listo.
+- [ ] Tests pasan.