create-quiver 0.10.0 → 0.12.1

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

@@ -0,0 +1,228 @@
+# Quiver v22 - Guided AI Workflow
+
+**Date:** 2026-05-21
+**Status:** Completed
+
+Slice numbering resets here. This spec intentionally starts at `slice-00`.
+
+## Problem
+
+Quiver already has an AI-first foundation: it can initialize a project, analyze it, generate context artifacts, run planner phases, generate specs/slices/handoffs, execute one slice with reduced context, and run GitHub PR preflight checks.
+
+The current experience still requires too much manual coordination. A user must remember which command comes next, manually preserve approved criteria and plans, decide when a worktree is safe, decide when parallel execution is safe, create slice commits by hand, and open or close the PR outside the guided flow.
+
+The desired workflow is a guided AI delivery line:
+
+1. Install or run Quiver.
+2. Prepare the project for AI onboarding.
+3. Choose a planner agent.
+4. Run planner onboarding with generated context.
+5. Turn requirements into acceptance criteria.
+6. Iterate criteria until approved.
+7. Turn approved criteria into a development plan.
+8. Iterate the plan until approved.
+9. Generate spec, slices, handoffs, and `pr.md`.
+10. Build an execution plan with sequential and parallel slices.
+11. Execute slices through cheaper executor agents, one slice per commit.
+12. Open the PR from the generated body.
+13. Let the human review and merge.
+14. Close the worktree and pull merged changes back into the main local checkout.
+
+## Objective
+
+Make Quiver guide the full AI-assisted workflow from project preparation to post-merge cleanup while preserving human approvals, one spec per worktree, one slice per commit, token-efficient executor context, and safe defaults.
+
+## Core Decisions
+
+- `README_FOR_AI.md` remains the source of truth for Quiver workflow guidance in this repo.
+- This repo uses `specs/quiver-vNN-*` as the real spec location, even though some reusable skills mention `docs/specs/`.
+- `slice-00` is mandatory and only establishes the spec foundation.
+- One spec maps to one dedicated worktree and one PR.
+- One slice maps to one commit.
+- Planner agents use broad context and do not modify product code while creating criteria or plans.
+- Executor agents may modify product code only inside the approved slice scope.
+- AI outputs that influence implementation must be saved and explicitly approved before they become inputs for the next phase.
+- Parallel slice execution is allowed only when dependencies and touched files make it safe.
+- Quiver validates or guides setup for `gh`, SSH aliases, provider CLIs, and auth. It must not silently rewrite credentials.
+- PR creation is allowed after checks pass, but PR merge remains a human decision.
+- Worktree cleanup is allowed only after the PR merge is confirmed and no local changes would be lost.
+
+## Scope
+
+### Included
+
+- Sync documentation that drifted after `0.10.0`.
+- Define the official command experience for guided workflows, including whether a short `quiver` command exists or commands remain under `npx create-quiver`.
+- Add a safe project preparation command that combines analysis, diagnostics, context refresh, and setup guidance.
+- Improve project analysis so it produces useful AI onboarding context without exposing secrets or noisy generated files.
+- Persist planner outputs and approvals for acceptance criteria and technical plans.
+- Generate specs, slices, handoffs, execution plans, and `pr.md` only from approved inputs.
+- Formalize one spec per worktree.
+- Add status, retry, abort, and recovery surfaces for slices.
+- Add optional commit automation after slice validation.
+- Add execution waves for sequential and parallel slices.
+- Add safe delegation guidance for cheap executor agents.
+- Create PRs with `gh` from generated `pr.md` after preflight passes.
+- Add post-merge cleanup that removes the spec worktree and pulls the main local checkout.
+- Add release/package safety checks so local settings or secrets are not published.
+- Cover macOS, Linux, and Windows guidance for `gh`, SSH, providers, and paths.
+
+### Excluded
+
+- Fully autonomous PR merge.
+- Silent installation of tools without explicit user approval.
+- Silent SSH config rewriting.
+- Direct provider API integrations.
+- Guaranteeing identical behavior across Codex, Claude, and Gemini CLIs.
+- Running real paid AI providers in CI.
+- Replacing human approval for acceptance criteria, plans, or PR review.
+
+## Acceptance Criteria
+
+1. Given the root docs drift from the published package version, when the docs-sync slice runs, then README, CHANGELOG, ROADMAP, BACKLOG, and AI guidance no longer contradict the current package state.
+2. Given a user wants to start safely, when the preparation command runs in dry-run mode, then it reports planned checks and writes nothing.
+3. Given a user runs preparation for real, when the repo is valid, then Quiver refreshes project context docs and reports assumptions, risks, missing tools, and next commands.
+4. Given a project has secrets, env files, generated files, large artifacts, or dependency folders, when context is prepared, then those files are excluded from AI-facing context.
+5. Given `gh`, provider CLIs, auth, or SSH aliases are missing, when diagnostics run, then Quiver gives OS-specific guidance for macOS, Linux, and Windows.
+6. Given a planner produces acceptance criteria, when the user does not approve them, then Quiver keeps them as draft and does not create a technical plan or spec.
+7. Given acceptance criteria are approved, when the next phase starts, then Quiver uses the approved criteria as the source input.
+8. Given a planner produces a technical plan, when the user does not approve it, then Quiver keeps it as draft and does not create spec artifacts.
+9. Given a technical plan is approved, when the spec phase runs, then Quiver creates `SPEC.md`, `STATUS.md`, `EVIDENCE_REPORT.md`, `EXECUTION_PLAN.md`, `pr.md`, mandatory `slice-00`, and per-slice handoffs.
+10. Given generated slices, when the execution plan is built, then `slice-00` is first and every later slice is blocked until `slice-00` is committed.
+11. Given a spec starts, when Quiver creates or selects its worktree, then it uses one dedicated worktree/branch for that spec.
+12. Given a slice executor runs, when it receives context, then it receives only the slice, handoff, allowed files, criteria, and validation commands.
+13. Given a slice executor modifies files outside scope, when validation runs, then Quiver stops and reports the scope violation.
+14. Given a slice passes validation and commit automation is enabled, when the slice completes, then Quiver creates exactly one commit for that slice.
+15. Given a slice fails validation, when the command exits, then Quiver leaves a clear report and supports retry or abort without hiding local changes.
+16. Given multiple slices are ready, when execution waves are requested, then Quiver only runs slices in parallel if dependencies and file scopes do not conflict.
+17. Given execution waves include conflicts or unknown file scopes, when Quiver plans execution, then it falls back to sequential execution.
+18. Given all required slices are complete, when PR creation runs, then Quiver validates `gh`, auth, remote, branch, worktree, identity file, SSH alias, clean state, and generated `pr.md`.
+19. Given PR checks pass, when the user confirms PR creation, then Quiver creates the PR with `gh` using `pr.md`.
+20. Given a PR is not merged, when cleanup is requested, then Quiver refuses normal cleanup and explains the safe options.
+21. Given a PR is merged and the worktree is clean, when cleanup runs, then Quiver removes the spec worktree and pulls the merged changes into the main local checkout.
+22. Given package release validation runs, when local settings, env files, npm credentials, or AI tool local state would be included, then Quiver fails before packaging or publishing.
+
+## Approved Technical Plan
+
+### Objective
+
+Turn Quiver's current AI commands into a guided workflow that is safer, more recoverable, and easier to use end to end.
+
+### Architecture
+
+Add a lightweight workflow state layer under `.quiver/` and keep versioned project contracts under visible docs and `specs/`.
+
+Recommended areas:
+
+```text
+src/create-quiver/commands/prepare.js
+src/create-quiver/commands/ai.js
+src/create-quiver/commands/spec.js
+src/create-quiver/lib/workflow-state.js
+src/create-quiver/lib/context-writer.js
+src/create-quiver/lib/approvals.js
+src/create-quiver/lib/spec-worktrees.js
+src/create-quiver/lib/slice-runner.js
+src/create-quiver/lib/pr-create.js
+src/create-quiver/lib/package-safety.js
+```
+
+The exact file names can change during implementation if the existing codebase points to a better local pattern.
+
+### Workflow State
+
+Persist workflow progress in `.quiver/`:
+
+- selected provider and role;
+- current spec;
+- current worktree;
+- draft and approved acceptance criteria;
+- draft and approved technical plan;
+- generated spec path;
+- slice statuses;
+- execution wave status;
+- PR status;
+- cleanup status.
+
+Only durable team contracts belong in visible docs or `specs/`.
+
+### Command Experience
+
+The command surface should be simple for humans:
+
+```bash
+npx create-quiver prepare
+npx create-quiver ai planner onboard
+npx create-quiver ai planner acceptance
+npx create-quiver ai approve acceptance
+npx create-quiver ai planner technical-plan
+npx create-quiver ai approve technical-plan
+npx create-quiver ai planner spec
+npx create-quiver spec start
+npx create-quiver ai execute-plan
+npx create-quiver ai pr create
+npx create-quiver spec close
+```
+
+If a short `quiver` binary is introduced, it must be documented as an alias or project-local script and must not contradict the canonical `npx create-quiver` entrypoint until that decision is made.
+
+### Safety Rules
+
+- Dry-run support comes before write support.
+- No product code changes before an approved slice.
+- No commit before validation.
+- No parallel execution when files or dependencies are unclear.
+- No PR creation with dirty worktree or missing generated PR body.
+- No cleanup before merge confirmation.
+- No publishing if local settings or secrets enter the package tarball.
+
+### Validation Strategy
+
+- Unit tests for state persistence and approval transitions.
+- Unit tests for context exclusion and secret/path filters.
+- Unit tests for missing tools and cross-platform install guidance.
+- Unit tests for spec worktree lifecycle and cleanup guardrails.
+- Unit tests for slice commit success/failure behavior.
+- Unit tests for execution wave grouping and conflict fallback.
+- Unit tests for PR creation command construction with mocked `gh`.
+- Smoke tests for `prepare`, planner approval flow, executor dry-run, PR dry-run, and release/package safety.
+- Existing tests for `ai plan`, `ai execute-slice`, `plan`, `graph`, and `next` must remain green.
+
+## Slicing Strategy
+
+`slice-00` lands first and only publishes this spec foundation. The rest of the work is split so Quiver becomes useful earlier while high-risk automation, such as parallel execution and cleanup, is introduced after state, approvals, and single-slice execution are reliable.
+
+## Slice Roadmap
+
+| Slice | Title | Status | Dependencies |
+|-------|-------|--------|--------------|
+| slice-00 | Spec foundation and guided workflow planning artifacts | Completed | none |
+| slice-01 | Documentation source-of-truth sync | Completed | slice-00 |
+| slice-02 | Prepare command and setup diagnostics | Completed | slice-01 |
+| slice-03 | Context documentation refresh and safe analyzer output | Completed | slice-02 |
+| slice-04 | Planner approval state for criteria and technical plans | Completed | slice-03 |
+| slice-05 | Spec worktree lifecycle | Completed | slice-04 |
+| slice-06 | Executor validation, recovery, and commit per slice | Completed | slice-05 |
+| slice-07 | Execution waves and safe delegation | Completed | slice-06 |
+| slice-08 | PR creation with gh and SSH guidance | Completed | slice-05 |
+| slice-09 | Post-merge cleanup and release safety | Completed | slice-07, slice-08 |
+| slice-10 | Final docs, smokes, and release readiness | Completed | slice-09 |
+
+## Risks
+
+- A short `quiver` command can confuse users if it is introduced before the canonical command decision is documented.
+- Persisted approval state can drift from visible spec artifacts if not validated.
+- More automation increases the cost of recovering from failed provider runs.
+- Parallel executor runs can create conflicts or overlapping edits.
+- Cross-platform setup guidance can become stale if it is duplicated in several files.
+- PR creation can target the wrong account if `gh` auth and SSH alias point to different identities.
+- Cleanup can delete useful local work if merge and cleanliness checks are incomplete.
+- Packaging can leak local tool state unless tarball checks are enforced.
+
+## Open Questions
+
+- Should the short command be `quiver`, a project-local npm script, or only documented as future sugar over `npx create-quiver`?
+- Should approval artifacts be versioned in `specs/` or stored internally in `.quiver/` until the spec is generated?
+- Should commit automation default to confirmation prompts or require an explicit `--commit` flag?
+- Should execution waves initially print commands for manual execution before running multiple providers automatically?
+- Should `gh` installation remain guidance-only or include optional installer helpers behind explicit approval?

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"
+}