create-quiver 0.10.0 → 0.12.0

package/specs/quiver-v22-guided-ai-workflow/STATUS.md

@@ -0,0 +1,42 @@
+# Quiver v22 - Guided AI Workflow Status
+
+**Status:** Completed
+**Created:** 2026-05-21
+
+## Summary
+
+This spec implemented the guided AI workflow needed to move from project preparation to planner approvals, spec generation, slice execution, PR creation, and post-merge cleanup.
+
+## Current State
+
+- Requirements and acceptance criteria: approved in conversation.
+- Technical plan: approved in conversation after production-readiness review.
+- Spec and slice handoffs: created in this documentation pass.
+- `slice-00`: completed.
+- `slice-01`: completed.
+- `slice-02`: completed.
+- `slice-03`: completed.
+- `slice-04`: completed.
+- `slice-05`: completed.
+- `slice-06`: completed.
+- `slice-07`: completed.
+- `slice-08`: completed.
+- `slice-09`: completed.
+- `slice-10`: completed.
+
+## Execution Rules
+
+- `slice-00` must be executed and committed first.
+- Every later slice depends on `slice-00`.
+- One slice equals one commit.
+- One spec equals one worktree and one PR.
+- Planner phases cannot modify product code.
+- Executor phases can modify product code only inside approved slice scope.
+- Parallel slices may run only when dependencies and file scopes are safe.
+
+## Open Items
+
+- The canonical executable remains `npx create-quiver`; a short `quiver` binary was not introduced in this spec.
+- Approved planner artifacts are persisted under `.quiver/approvals` until generated specs and slices become versioned repo artifacts.
+- Commit automation is opt-in through `--commit`; real execution waves also require `--execute`.
+- Package publication is intentionally outside this slice and should be handled by the release workflow after review.

package/specs/quiver-v22-guided-ai-workflow/pr.md

@@ -0,0 +1,104 @@
+## Title
+
+Quiver v22 - Guided AI workflow
+
+## Summary
+
+Adds the plan for a guided AI workflow that takes Quiver from project preparation through planner approvals, spec generation, slice execution, PR creation, and post-merge cleanup.
+
+The goal is to make Quiver feel like an AI-first delivery assistant: the planner handles context and decisions, cheaper executors handle bounded slices, each slice becomes one commit, and the human remains responsible for approvals and PR merge.
+
+## Scope
+
+- Documentation source-of-truth sync
+- Guided project preparation command
+- AI context refresh with safe exclusions
+- Draft and approved planner artifact persistence
+- One spec per worktree lifecycle
+- Executor validation, recovery, and optional commit per slice
+- Execution waves for safe sequential and parallel slice work
+- PR creation with `gh` and SSH guidance
+- Post-merge cleanup
+- Package/release safety checks
+- Final docs, scripts, and smoke coverage
+
+## Files
+
+- `specs/quiver-v22-guided-ai-workflow/SPEC.md`
+- `specs/quiver-v22-guided-ai-workflow/STATUS.md`
+- `specs/quiver-v22-guided-ai-workflow/EVIDENCE_REPORT.md`
+- `specs/quiver-v22-guided-ai-workflow/EXECUTION_PLAN.md`
+- `specs/quiver-v22-guided-ai-workflow/pr.md`
+- `specs/quiver-v22-guided-ai-workflow/slices/**`
+
+Future implementation slices are expected to touch CLI source, AI orchestration modules, analyzer/context modules, worktree lifecycle code, PR helpers, tests, templates, generated docs, and smoke scripts as declared in each slice.
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+- Node.js supported by Quiver
+- npm
+- Git
+- `gh` for PR creation slices
+- Optional local provider CLIs for manual checks:
+  - `codex`
+  - `claude`
+  - `gemini`
+
+### Worktree Access
+
+Use one dedicated worktree for this spec PR. Parallel slices may use temporary slice worktrees only when the execution plan marks them safe and their changed-file scopes do not conflict.
+
+### Run the Project
+
+For documentation-only `slice-00`, validate files and JSON:
+
+```bash
+git diff --check
+find specs/quiver-v22-guided-ai-workflow -name "slice.json" -print -exec node -e "JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'))" {} \;
+```
+
+For implementation slices, run the validation commands declared in each `slice.json` and `EXECUTION_BRIEF.md`.
+
+### Use Cases
+
+- New user prepares a repo for AI-assisted work.
+- Planner creates and iterates acceptance criteria.
+- Planner creates and iterates the technical plan.
+- Approved plan generates spec, slices, handoffs, execution plan, and PR body.
+- Executor runs a bounded slice with reduced context.
+- Slice validation passes and one commit is created.
+- Failed slice leaves a recoverable report.
+- Ready slices are grouped into safe execution waves.
+- PR is created from `pr.md` after `gh` and SSH checks.
+- Merged spec worktree is closed and main local checkout is updated.
+
+### Technical Verification
+
+- Dry-run paths write nothing.
+- Approval transitions are explicit and persisted.
+- Context excludes secrets, env files, generated outputs, dependency folders, and local AI tool state.
+- Worktree cleanup refuses dirty or unmerged work.
+- PR creation uses `gh` without opening a PR in tests.
+- Release safety fails if unsafe local files would enter the npm package.
+
+## Evidence
+
+To be completed by implementation slices. Expected evidence includes:
+
+- `node --test tests/**/*.test.js`
+- `npm run smoke:create-quiver`
+- targeted smoke tests for guided prepare, approval flow, executor commit, execution waves, PR creation, cleanup, and release safety
+- `git diff --check`
+
+## Rollback
+
+Revert the smallest failing slice commit. Since the spec requires one slice per commit, rollback should target the affected slice commit rather than the full PR when possible.
+
+## Risks / Notes
+
+- This spec intentionally does not automate PR merge.
+- Short command naming must not conflict with the canonical `npx create-quiver` guidance.
+- Parallel execution must remain conservative until conflict detection is reliable.
+- Tool installation and SSH setup must require explicit user approval.

package/specs/quiver-v22-guided-ai-workflow/slices/slice-00-spec-foundation/CLOSURE_BRIEF.md

@@ -0,0 +1,35 @@
+# CLOSURE BRIEF - slice-00: Spec foundation
+
+## Resumen de lo realizado
+
+Se creo la base documental completa de `quiver-v22-guided-ai-workflow`, incluyendo spec, estado, evidencia, plan de ejecucion, cuerpo de PR y handoffs por slice.
+
+## Validacion contra criterios de aceptacion
+
+- [x] Spec creada.
+- [x] `slice-00` creada.
+- [x] Handoffs creados para cada slice.
+- [x] `EXECUTION_PLAN.md` creado.
+- [x] `pr.md` creado.
+- [x] JSON validado.
+
+## Cambios relevantes
+
+- `specs/quiver-v22-guided-ai-workflow/SPEC.md`
+- `specs/quiver-v22-guided-ai-workflow/STATUS.md`
+- `specs/quiver-v22-guided-ai-workflow/EVIDENCE_REPORT.md`
+- `specs/quiver-v22-guided-ai-workflow/EXECUTION_PLAN.md`
+- `specs/quiver-v22-guided-ai-workflow/pr.md`
+- `specs/quiver-v22-guided-ai-workflow/slices/**`
+
+## Pendientes
+
+Ninguno para esta slice.
+
+## Riesgos remanentes
+
+El spec es amplio y debe ejecutarse en orden conservador. El plan marca paralelismo solo como opcional y condicionado a scopes disjuntos.
+
+## Recomendaciones futuras
+
+Ejecutar `slice-01-docs-source-of-truth-sync` antes de modificar comportamiento, para evitar que los proximos agentes lean documentacion desactualizada.

package/specs/quiver-v22-guided-ai-workflow/slices/slice-00-spec-foundation/EXECUTION_BRIEF.md

@@ -0,0 +1,61 @@
+# EXECUTION BRIEF - slice-00: Spec foundation
+
+**Spec:** quiver-v22-guided-ai-workflow
+**Slice:** slice-00-spec-foundation
+**Tipo:** docs
+
+## Contexto
+
+Esta slice sube al repo la base documental del nuevo flujo guiado de IA. Es obligatoria y debe ejecutarse antes de cualquier slice de implementacion.
+
+## Objetivo
+
+Crear y validar la estructura completa de spec, slices, handoffs, plan de ejecucion y cuerpo de PR para el guided AI workflow.
+
+## Alcance
+
+- Crear `SPEC.md`.
+- Crear `STATUS.md`.
+- Crear `EVIDENCE_REPORT.md`.
+- Crear `EXECUTION_PLAN.md`.
+- Crear `pr.md`.
+- Crear `slice.json`, `EXECUTION_BRIEF.md` y `CLOSURE_BRIEF.md` para cada slice.
+
+## Criterios de aceptacion
+
+- La carpeta `specs/quiver-v22-guided-ai-workflow/` existe.
+- `slice-00` existe y precede al resto.
+- Cada slice tiene `slice.json`, `EXECUTION_BRIEF.md` y `CLOSURE_BRIEF.md`.
+- Todos los JSON parsean correctamente.
+- No se modifica codigo de producto.
+
+## Plan tecnico resumido
+
+Crear artefactos documentales siguiendo el patron real del repo bajo `specs/`. Mantener `slice-00` como base documental y declarar dependencias para todas las slices posteriores.
+
+## Pasos sugeridos de ejecucion
+
+1. Revisar `README_FOR_AI.md`.
+2. Crear estructura `specs/quiver-v22-guided-ai-workflow/`.
+3. Agregar archivos top-level de spec.
+4. Agregar cada slice y handoff.
+5. Validar JSON y whitespace.
+6. Preparar commit unico de slice-00.
+
+## Restricciones
+
+- No tocar codigo de producto.
+- No resolver implementacion en esta slice.
+- No crear PR todavia.
+
+## Riesgos
+
+- Generar una spec demasiado amplia sin dependencias claras.
+- Dejar handoffs incompletos para agentes executor.
+
+## Checklist de finalizacion
+
+- [ ] `git diff --check` pasa.
+- [ ] Todos los `slice.json` parsean.
+- [ ] No hay cambios fuera de `specs/quiver-v22-guided-ai-workflow/`.
+- [ ] El commit representa solo slice-00.

package/specs/quiver-v22-guided-ai-workflow/slices/slice-00-spec-foundation/slice.json

@@ -0,0 +1,51 @@
+{
+  "slice_id": "slice-00-spec-foundation",
+  "ticket": "QUIVER-22-00",
+  "type": "docs",
+  "title": "Spec foundation and guided workflow planning artifacts",
+  "objective": "Create the complete documentation foundation for the guided AI workflow spec.",
+  "description": "Publish the spec, status, evidence report, execution plan, PR body, slice definitions, and handoffs before product implementation starts.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "guided-ai-workflow-spec-foundation",
+    "branch_name": "feature/QUIVER-22-00-guided-ai-workflow-spec-foundation"
+  },
+  "files": [
+    "specs/quiver-v22-guided-ai-workflow/**"
+  ],
+  "depends_on": [],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "slice-00 must land before every other slice.",
+  "must": [
+    "Create SPEC.md.",
+    "Create STATUS.md.",
+    "Create EVIDENCE_REPORT.md.",
+    "Create EXECUTION_PLAN.md.",
+    "Create pr.md.",
+    "Create slice.json, EXECUTION_BRIEF.md, and CLOSURE_BRIEF.md for every slice.",
+    "Avoid product code changes."
+  ],
+  "not_included": [
+    "Implementing commands.",
+    "Changing README or CHANGELOG.",
+    "Running AI providers.",
+    "Creating commits automatically."
+  ],
+  "acceptance": [
+    "Spec folder exists under specs/quiver-v22-guided-ai-workflow.",
+    "Mandatory slice-00 exists.",
+    "Every slice has slice.json, EXECUTION_BRIEF.md, and CLOSURE_BRIEF.md.",
+    "Every slice.json parses successfully.",
+    "No product code is modified."
+  ],
+  "tests": [
+    "git diff --check",
+    "find specs/quiver-v22-guided-ai-workflow -name \"slice.json\" -print -exec node -e \"JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'))\" {} \\;"
+  ],
+  "estimated_hours": 2,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 2,
+  "completed_at": "2026-05-21T11:16:22-0300"
+}

package/specs/quiver-v22-guided-ai-workflow/slices/slice-01-docs-source-of-truth-sync/CLOSURE_BRIEF.md

@@ -0,0 +1,31 @@
+# CLOSURE BRIEF - slice-01: Documentation source-of-truth sync
+
+## Resumen de lo realizado
+
+Se sincronizaron los documentos raiz con la version `0.10.0` y con el estado real de los specs v20, v21 y v22.
+
+## Validacion contra criterios de aceptacion
+
+- [x] Docs sincronizadas con `0.10.0`.
+- [x] Flujo actual y futuro diferenciados.
+- [x] No se modifico codigo de producto.
+
+## Cambios relevantes
+
+- `README.md`: corregida la seccion de informacion confirmada/pendiente para reflejar `0.10.0`.
+- `README_FOR_AI.md`: agregado recordatorio de que v20/v21 estan completos y v22 sigue planificado.
+- `CHANGELOG.md`: agregada entrada `0.10.0`.
+- `ROADMAP.md`: alineado v20/v21 con los specs reales completados y v22 como plan activo.
+- `BACKLOG.md`: promovida la entrada de orquestacion al spec v22 y marcada la parte diferida como dependiente de demanda real.
+
+## Pendientes
+
+Ninguno para esta slice.
+
+## Riesgos remanentes
+
+La documentacion todavia mantiene una nota de deuda sobre `engines` de Node y scripts legacy del repo fuente; no forman parte de esta slice.
+
+## Recomendaciones futuras
+
+Ejecutar `slice-02-prepare-command-diagnostics` para agregar el primer comando guiado del workflow.

package/specs/quiver-v22-guided-ai-workflow/slices/slice-01-docs-source-of-truth-sync/EXECUTION_BRIEF.md

@@ -0,0 +1,58 @@
+# EXECUTION BRIEF - slice-01: Documentation source-of-truth sync
+
+**Spec:** quiver-v22-guided-ai-workflow
+**Slice:** slice-01-docs-source-of-truth-sync
+**Tipo:** docs
+
+## Contexto
+
+Quiver depende de sus docs para onboarding de agentes. Hay drift entre la version publicada `0.10.0` y algunos documentos raiz.
+
+## Objetivo
+
+Sincronizar la documentacion antes de implementar mas automatizacion.
+
+## Alcance
+
+- `README.md`
+- `README_FOR_AI.md`
+- `CHANGELOG.md`
+- `ROADMAP.md`
+- `BACKLOG.md`
+- traducciones relevantes bajo `i18n/es/`
+
+## Criterios de aceptacion
+
+- No quedan contradicciones conocidas con `0.10.0`.
+- El flujo actual se describe como actual.
+- El guided workflow nuevo se describe como plan futuro, no como funcionalidad ya disponible.
+- No se modifica codigo de producto.
+
+## Plan tecnico resumido
+
+Leer los documentos raiz, comparar contra package/version y specs v20/v21, y corregir solo texto desactualizado o ambiguo.
+
+## Pasos sugeridos de ejecucion
+
+1. Revisar `package.json`, `README_FOR_AI.md`, `SPEC.md` de v20 y v21.
+2. Actualizar README y changelog.
+3. Limpiar roadmap/backlog para evitar señales viejas.
+4. Alinear i18n si aplica.
+5. Ejecutar validaciones documentales y tests acotados.
+
+## Restricciones
+
+- No tocar CLI ni tests salvo que una referencia documental rota lo requiera.
+- No cambiar version de paquete.
+
+## Riesgos
+
+- Presentar comportamiento futuro como disponible.
+- Eliminar contexto util del roadmap/backlog.
+
+## Checklist de finalizacion
+
+- [ ] Docs sincronizadas.
+- [ ] Drift de version corregido.
+- [ ] Futuro vs actual queda claro.
+- [ ] `git diff --check` pasa.

package/specs/quiver-v22-guided-ai-workflow/slices/slice-01-docs-source-of-truth-sync/slice.json

@@ -0,0 +1,55 @@
+{
+  "slice_id": "slice-01-docs-source-of-truth-sync",
+  "ticket": "QUIVER-22-01",
+  "type": "docs",
+  "title": "Documentation source-of-truth sync",
+  "objective": "Synchronize Quiver's visible documentation with the current 0.10.0 AI-first workflow before behavior changes.",
+  "description": "Update README, CHANGELOG, ROADMAP, BACKLOG, and AI guidance so future agents do not plan from stale information.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "guided-ai-docs-sync",
+    "branch_name": "feature/QUIVER-22-01-guided-ai-docs-sync"
+  },
+  "files": [
+    "README.md",
+    "README_FOR_AI.md",
+    "CHANGELOG.md",
+    "ROADMAP.md",
+    "BACKLOG.md",
+    "i18n/es/README.md",
+    "i18n/es/README_FOR_AI.md"
+  ],
+  "depends_on": [
+    "slice-00-spec-foundation"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Documentation source of truth must be corrected before later slices depend on it.",
+  "must": [
+    "Remove stale references that contradict package version 0.10.0.",
+    "Explain the guided AI workflow as planned work, not already shipped behavior.",
+    "Keep README_FOR_AI aligned with README guidance.",
+    "Mark unresolved decisions explicitly instead of inventing them."
+  ],
+  "not_included": [
+    "Implementing commands.",
+    "Changing package version.",
+    "Publishing npm."
+  ],
+  "acceptance": [
+    "Root docs no longer say package.json is still 0.9.0.",
+    "CHANGELOG includes the 0.10.0 release status or clearly marks the missing entry as resolved.",
+    "ROADMAP and BACKLOG do not present shipped v20/v21 behavior as merely future work.",
+    "README explains current AI-first commands and clearly separates future guided workflow work.",
+    "No product code is modified."
+  ],
+  "tests": [
+    "git diff --check",
+    "node --test tests/commands/analyze.test.js tests/commands/ai-plan.test.js tests/commands/ai-pr.test.js"
+  ],
+  "estimated_hours": 3,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 1,
+  "completed_at": "2026-05-21T11:21:08-0300"
+}

package/specs/quiver-v22-guided-ai-workflow/slices/slice-02-prepare-command-diagnostics/CLOSURE_BRIEF.md

@@ -0,0 +1,30 @@
+# CLOSURE BRIEF - slice-02: Prepare command and setup diagnostics
+
+## Resumen de lo realizado
+
+Se implemento `npx create-quiver prepare` como comando de diagnostico no destructivo con soporte de `--dry-run`, preflight opcional de provider, guia de GitHub CLI, validacion de identidad SSH y siguientes comandos seguros.
+
+## Validacion contra criterios de aceptacion
+
+- [x] `prepare --dry-run` no escribe.
+- [x] Diagnosticos implementados.
+- [x] Guia cross-platform cubierta.
+- [x] Tests ejecutados.
+
+## Cambios relevantes
+
+- `src/create-quiver/index.js`
+- `src/create-quiver/commands/prepare.js`
+- `tests/commands/prepare.test.js`
+
+## Pendientes
+
+Ninguno para esta slice.
+
+## Riesgos remanentes
+
+El comando reporta herramientas faltantes como guia y no como bloqueo duro. Esto es intencional para mantener `prepare` seguro y util en proyectos parcialmente configurados.
+
+## Recomendaciones futuras
+
+Conectar `prepare` con el refresco de contexto de `slice-03` para que el onboarding de IA quede mas completo.

package/specs/quiver-v22-guided-ai-workflow/slices/slice-02-prepare-command-diagnostics/EXECUTION_BRIEF.md

@@ -0,0 +1,57 @@
+# EXECUTION BRIEF - slice-02: Prepare command and setup diagnostics
+
+**Spec:** quiver-v22-guided-ai-workflow
+**Slice:** slice-02-prepare-command-diagnostics
+**Tipo:** feature
+
+## Contexto
+
+El usuario necesita un primer comando seguro que le diga si el proyecto esta listo para trabajar con IA.
+
+## Objetivo
+
+Agregar un comando de preparacion guiada con diagnosticos claros y modo dry-run.
+
+## Alcance
+
+- Registrar el comando en el CLI.
+- Agregar `prepare`.
+- Reutilizar checks existentes de doctor, provider preflight y GitHub preflight donde convenga.
+- Reportar herramientas faltantes y proximos pasos.
+
+## Criterios de aceptacion
+
+- `prepare --dry-run` no escribe archivos.
+- `prepare` informa checks ejecutados y proximos pasos.
+- Faltantes de `gh`, auth, provider CLI o SSH se explican con guia para macOS, Linux y Windows.
+- No se instalan herramientas ni se modifica SSH sin autorizacion explicita.
+
+## Plan tecnico resumido
+
+Crear un comando fino que orqueste checks existentes y produzca un reporte humano. Mantener escritura deshabilitada en dry-run y evitar automatizaciones destructivas.
+
+## Pasos sugeridos de ejecucion
+
+1. Revisar parser de `src/create-quiver/index.js`.
+2. Crear `commands/prepare.js`.
+3. Componer checks existentes.
+4. Agregar salida clara para success/warn/fail.
+5. Cubrir dry-run y faltantes con tests.
+
+## Restricciones
+
+- No refrescar todavia docs de contexto profundas.
+- No crear specs.
+- No crear commits.
+
+## Riesgos
+
+- Duplicar logica de doctor.
+- Hacer que prepare parezca que instala herramientas cuando solo guia.
+
+## Checklist de finalizacion
+
+- [ ] Comando registrado.
+- [ ] Dry-run cubierto.
+- [ ] Guia cross-platform cubierta.
+- [ ] Tests pasan.

package/specs/quiver-v22-guided-ai-workflow/slices/slice-02-prepare-command-diagnostics/slice.json

@@ -0,0 +1,57 @@
+{
+  "slice_id": "slice-02-prepare-command-diagnostics",
+  "ticket": "QUIVER-22-02",
+  "type": "feature",
+  "title": "Prepare command and setup diagnostics",
+  "objective": "Add a guided preparation command that tells users whether the project is ready for AI-assisted work.",
+  "description": "Create the safe first command for project preparation: analysis, diagnostics, missing-tool guidance, dry-run, and next-step reporting.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "guided-prepare-diagnostics",
+    "branch_name": "feature/QUIVER-22-02-guided-prepare-diagnostics"
+  },
+  "files": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/commands/prepare.js",
+    "src/create-quiver/lib/doctor.js",
+    "src/create-quiver/lib/ai/preflight.js",
+    "src/create-quiver/lib/ai/github.js",
+    "src/create-quiver/lib/init-layout.js",
+    "tests/commands/prepare.test.js",
+    "tests/lib/doctor.test.js"
+  ],
+  "depends_on": [
+    "slice-01-docs-source-of-truth-sync"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "This establishes the public entrypoint used by later workflow slices.",
+  "must": [
+    "Add a dry-run mode that writes nothing.",
+    "Report project readiness, missing docs, missing tools, provider CLI availability, gh availability, gh auth, and SSH alias guidance.",
+    "Support macOS, Linux, and Windows guidance.",
+    "Print clear next commands.",
+    "Avoid installing tools or editing credentials automatically."
+  ],
+  "not_included": [
+    "Refreshing rich context docs.",
+    "Persisting approvals.",
+    "Creating specs or worktrees."
+  ],
+  "acceptance": [
+    "prepare dry-run reports planned checks and writes nothing.",
+    "prepare reports missing gh with OS-specific guidance.",
+    "prepare reports missing provider CLI with actionable guidance.",
+    "prepare does not install tools or edit SSH config.",
+    "prepare recommends the next safe command after success."
+  ],
+  "tests": [
+    "node --test tests/commands/prepare.test.js tests/lib/doctor.test.js tests/lib/ai-github.test.js tests/lib/ai-providers.test.js",
+    "git diff --check"
+  ],
+  "estimated_hours": 6,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 2,
+  "completed_at": "2026-05-21T11:28:26-0300"
+}

package/specs/quiver-v22-guided-ai-workflow/slices/slice-03-context-doc-refresh/CLOSURE_BRIEF.md

@@ -0,0 +1,32 @@
+# CLOSURE BRIEF - slice-03: Context documentation refresh
+
+## Resumen de lo realizado
+
+Se mejoro `analyze` para refrescar `docs/AI_CONTEXT.md` con un resumen AI-facing, mantener `docs/PROJECT_MAP.md` como mapa visible y preservar el raw scan interno en `.quiver/scans/PROJECT_SCAN.json`.
+
+## Validacion contra criterios de aceptacion
+
+- [x] Contexto AI-facing actualizado.
+- [x] Secretos y ruido excluidos.
+- [x] Supuestos documentados.
+- [x] Tests ejecutados.
+
+## Cambios relevantes
+
+- `src/create-quiver/index.js`
+- `src/create-quiver/lib/init-docs.js`
+- `src/create-quiver/lib/ai/safety.js`
+- `tests/commands/analyze.test.js`
+- `tests/lib/ai-context-packs.test.js`
+
+## Pendientes
+
+Ninguno para esta slice.
+
+## Riesgos remanentes
+
+`analyze` refresca `docs/AI_CONTEXT.md`; si un equipo lo edita manualmente, debe considerar ese archivo como regenerable o revisar el diff antes de commitear.
+
+## Recomendaciones futuras
+
+Implementar `slice-04` para persistir criterios y planes aprobados, usando el contexto refrescado como input del planner.

package/specs/quiver-v22-guided-ai-workflow/slices/slice-03-context-doc-refresh/EXECUTION_BRIEF.md

@@ -0,0 +1,56 @@
+# EXECUTION BRIEF - slice-03: Context documentation refresh
+
+**Spec:** quiver-v22-guided-ai-workflow
+**Slice:** slice-03-context-doc-refresh
+**Tipo:** feature
+
+## Contexto
+
+El analisis actual genera mapa y scan, pero el flujo ideal necesita docs de contexto mas utiles para onboarding de IA con menos tokens.
+
+## Objetivo
+
+Mejorar la generacion/refresco de contexto sin exponer secretos ni archivos ruidosos.
+
+## Alcance
+
+- Mejorar scan/map/contexto visible.
+- Reutilizar exclusiones de seguridad.
+- Reportar supuestos y faltantes.
+- Mantener raw scan en `.quiver/scans/`.
+
+## Criterios de aceptacion
+
+- Contexto AI-facing queda actualizado y conciso.
+- Secretos y ruido quedan fuera.
+- Supuestos y faltantes quedan visibles.
+- Tests cubren exclusiones principales.
+
+## Plan tecnico resumido
+
+Extender el analizador/context writer con filtros seguros y salidas humanas. No inferir dominio si el repo no lo declara.
+
+## Pasos sugeridos de ejecucion
+
+1. Revisar `runAnalyze`, `project-scan` y context packs.
+2. Definir salidas a refrescar.
+3. Aplicar exclusiones compartidas.
+4. Agregar tests con fixtures de archivos sensibles/ruidosos.
+5. Actualizar docs necesarias.
+
+## Restricciones
+
+- No persistir aprobaciones.
+- No ejecutar proveedores IA.
+
+## Riesgos
+
+- Generar contexto demasiado largo.
+- Ocultar informacion util por filtros demasiado agresivos.
+
+## Checklist de finalizacion
+
+- [ ] Context docs refrescados.
+- [ ] Exclusiones cubiertas.
+- [ ] Supuestos reportados.
+- [ ] Tests pasan.