create-quiver 0.15.4 → 0.16.0

package/copys-landing-page.md

@@ -0,0 +1,244 @@
+# Copys para Landing Page de Quiver
+
+> Basados exclusivamente en funcionalidades y propuesta de valor documentadas en el proyecto.  
+> Los campos marcados con `[Completar con información real del producto]` requieren datos del equipo.
+
+---
+
+## 1. Hero Section
+
+### Título principal
+
+**"Que la IA trabaje rápido. Pero con orden."**
+
+---
+
+### Subtítulo
+
+Los agentes de IA aceleran el desarrollo, pero sin estructura generan caos. Quiver convierte el trabajo asistido por IA en un flujo guiado: requerimientos, criterios, plan técnico, specs, slices, commits y pull requests — todo visible, todo verificable.
+
+---
+
+### CTA principal
+
+**Empezar ahora** → `npx create-quiver@latest init --name "Mi Proyecto"`
+
+---
+
+### CTA secundario
+
+**Ver la guía completa** → [docs/workflows/full-ai-spec-to-pr.md]
+
+---
+
+## 2. Propuesta de Valor
+
+### Bloque 1 — Del caos al flujo repetible
+
+**"Un proceso que se puede repetir, auditar y mejorar."**
+
+En lugar de pedirle a un agente "hacé esto y vemos qué pasa", Quiver define un camino repetible: entender el repositorio, preparar contexto, planificar con aprobaciones humanas, generar specs, ejecutar slice por slice, validar con evidencia y abrir el PR.
+
+---
+
+### Bloque 2 — El humano siempre aprueba lo importante
+
+**"IA rápida, decisiones humanas."**
+
+Quiver separa los pasos que necesitan aprobación humana (criterios de aceptación, plan técnico) de los que puede automatizar la IA (ejecución de slices, commits, validación). El humano mantiene el control sin perder velocidad.
+
+---
+
+### Bloque 3 — Contexto mínimo, resultados máximos
+
+**"El agente ejecutor solo lee lo que necesita."**
+
+Quiver entrega a cada agente un contexto acotado: el slice exacto, sus dependencias y su alcance aprobado. Sin ruido. Sin contexto incorrecto. Sin implementaciones que se desvían del plan.
+
+---
+
+### Bloque 4 — Documentación generada, no escrita
+
+**"El proyecto se documenta solo mientras se trabaja."**
+
+Quiver crea y mantiene `AI_CONTEXT.md`, `PROJECT_MAP.md`, `AGENTS.md`, briefs de ejecución y reportes de evidencia como parte del flujo normal de trabajo. No como tarea adicional.
+
+---
+
+### Bloque 5 — Compatible con tu stack y tu equipo
+
+**"Funciona donde ya trabajás."**
+
+Quiver se ejecuta con `npx` sin instalación. Soporta macOS, Linux y Windows. Compatible con npm, yarn, pnpm y bun. Funciona con Codex, Claude, Gemini y cualquier CLI de proveedor que soporte.
+
+---
+
+## 3. Beneficios Principales
+
+- **Trazabilidad completa:** cada cambio tiene una spec aprobada, un slice definido y evidencia de validación asociada.
+- **Sin sorpresas en el PR:** el alcance del pull request está definido antes de que el agente escriba una sola línea.
+- **Onboarding instantáneo para agentes:** `AGENTS.md` y `AI_ONBOARDING_PROMPT.md` generados automáticamente le dan a cualquier agente el contexto necesario en segundos.
+- **Independiente de cualquier proveedor de IA:** Quiver orquesta el flujo; los proveedores (Codex, Claude, Gemini) hacen el trabajo de generación.
+- **Flujo verificable en cualquier momento:** `quiver flow`, `quiver dashboard` y `quiver doctor` muestran el estado real del proyecto en cualquier momento.
+- **Sin API keys en el repositorio:** las credenciales viven en los CLIs de proveedor y en el sistema operativo, nunca en los archivos de Quiver.
+- **Soporte en inglés y español:** output del CLI, documentación generada y mensajes de error disponibles en ambos idiomas.
+- **Funciona con proyectos nuevos y existentes:** `init` para proyectos nuevos, `migrate` para los que ya tienen código.
+
+---
+
+## 4. Sección de Problema
+
+### "¿Por qué los agentes de IA fallan en proyectos reales?"
+
+Los agentes de IA pueden escribir código rápido. Pero suelen fallar por motivos sorprendentemente mundanos:
+
+- **Leen demasiado contexto o el contexto incorrecto.** El agente procesa miles de líneas que no tienen que ver con la tarea.
+- **Implementan antes de cerrar criterios de aceptación.** El equipo no sabe qué construyó el agente hasta que ya está hecho.
+- **Saltean la aprobación del plan.** No hay una fase donde el humano valide qué se va a cambiar antes de que se cambie.
+- **Mezclan cambios no relacionados en el mismo PR.** Un pull request que toca diez cosas distintas es imposible de revisar.
+- **Olvidan qué se decidió en fases anteriores.** Sin estado persistente, cada sesión empieza de cero.
+- **Generan código sin evidencia de validación.** Nadie puede auditar si los tests pasaron, cuánto tardaron o qué salida produjeron.
+- **Dejan al equipo reconstruyendo qué pasó.** El historial de chat se pierde. El contexto desaparece.
+
+El resultado: trabajo más rápido en el corto plazo, caos técnico que crece con cada iteración.
+
+---
+
+## 5. Sección de Solución
+
+### "Quiver convierte el trabajo asistido por IA en un flujo con estructura."
+
+Quiver no reemplaza al agente. Lo ordena.
+
+Combina dos metodologías complementarias:
+- **WDD (Workflow-Driven Development):** primero se define cómo se trabaja, después se trabaja.
+- **SDD (Spec-Driven Development):** el trabajo se describe como specs y slices antes de implementarse.
+
+En la práctica, Quiver separa dos roles de agentes:
+
+- Un **agente planificador** prepara criterios de aceptación, plan técnico, specs, slices, briefs y el cuerpo del PR. El humano aprueba en cada fase importante.
+- Un **agente ejecutor** recibe solo el contexto mínimo de un slice y modifica código dentro del alcance exacto que fue aprobado.
+
+El resultado es un flujo visible de principio a fin: requerimiento → criterios aprobados → plan aprobado → spec generada → slices ejecutados → evidencia validada → PR abierto → spec cerrada.
+
+Cada paso es verificable. Cada decisión es auditable. El equipo mantiene el control.
+
+---
+
+## 6. Features Destacadas
+
+### `quiver flow` — Tu brújula de workflow
+
+Ejecutá `quiver flow` en cualquier momento para saber exactamente en qué etapa está el proyecto y cuál es el próximo comando seguro. Funciona como un GPS para el flujo de trabajo: siempre te dice dónde estás y hacia dónde ir.
+
+---
+
+### `quiver ai plan` — El planner genera el plan, el humano lo aprueba
+
+En lugar de pedirle al agente que "haga algo", Quiver hace que el agente proponga criterios de aceptación y un plan técnico estructurado. Guardás los borradores, los revisás, y aprobás la versión que querés usar como base para la implementación. Sin aprobación, no hay avance.
+
+---
+
+### `quiver spec create` — De plan aprobado a spec lista para ejecutar
+
+Una vez aprobado el plan técnico, `spec create` genera automáticamente la estructura de spec: directorio, slices numerados, briefs de ejecución, cuerpo del PR y plan de ejecución en olas. Todo listo para que el ejecutor trabaje slice por slice.
+
+---
+
+### `quiver ai execute-slice` — Ejecución controlada, un slice por vez
+
+El agente ejecutor recibe solo el contexto del slice que tiene que implementar: archivos en scope, dependencias, criterios de validación. Ejecuta, valida y commitea. El alcance está definido de antemano; si el agente se desvía, Quiver lo detecta.
+
+---
+
+### `quiver evidence run` — Validación con registro
+
+Ejecutá cualquier comando (tests, builds, linters) y Quiver registra automáticamente el código de salida, la duración y el output redactado como archivo de evidencia Markdown. Sin capturas de pantalla, sin copy-paste. Evidencia reproducible por defecto.
+
+---
+
+### `quiver dashboard` — Estado consolidado en un vistazo
+
+Un resumen compacto de specs, slices, runs, aprobaciones y agentes configurados. Filtrable por sección, spec y cantidad de items. Con `--json` para integrarlo en dashboards externos.
+
+---
+
+### `quiver ai agent set` — Configura tus agentes una sola vez
+
+Configurá un perfil de planner, ejecutor, revisor y doctor con proveedor y modelo técnico. Quiver les pasa el modelo exacto al CLI del proveedor en cada ejecución. Sin configurar lo mismo en cada sesión. Sin guardar API keys en el repositorio.
+
+---
+
+### `quiver doctor` — Diagnóstico del contrato del proyecto
+
+Valida que la estructura del proyecto esté sana: archivos requeridos, scripts de `package.json`, estado de Quiver. Con `--fix` aplica reparaciones seguras y no destructivas. Con `--json` es integrable en pipelines de CI.
+
+---
+
+## 7. Sección de Confianza
+
+### Construido con el mismo flujo que describe
+
+Quiver se desarrolla usando Quiver. El repositorio es la demostración del producto: cada spec visible en `specs/`, cada slice ejecutado con evidencia, cada PR abierto siguiendo el flujo documentado.
+
+---
+
+### Transparencia de implementación
+
+Todo el código de Quiver es código abierto bajo licencia MIT. Los specs, slices y evidencias del desarrollo del framework están en el repositorio. Podés ver exactamente qué se implementó, cómo, y por qué.
+
+---
+
+### Independiente de cualquier proveedor
+
+Quiver no te ata a un proveedor de IA. Hoy podés usar Codex, mañana Claude, pasado Gemini. Las credenciales viven en los CLIs de cada proveedor. Quiver solo orquesta el flujo.
+
+---
+
+### Sin datos de proyecto enviados a servicios externos
+
+`quiver flow`, `quiver doctor`, `quiver plan` y `quiver dashboard` son comandos que solo leen el estado local del proyecto. No envían datos a ningún servicio externo. El código y el contexto de tu proyecto no salen de tu máquina salvo cuando vos explícitamente invocás un proveedor de IA.
+
+---
+
+### Disponible en npm desde el día uno
+
+```bash
+npx create-quiver@latest --help
+```
+
+Sin registro. Sin trial. Sin tarjeta de crédito. Ejecutable en segundos desde cualquier terminal con Node.js.
+
+---
+
+### Soporte en múltiples plataformas
+
+macOS · Linux · Windows PowerShell · Windows Git Bash · WSL
+
+Documentación de instalación paso a paso para cada plataforma.
+
+---
+
+## 8. CTA Final
+
+### "Tu próximo feature. Con IA. Con orden."
+
+No necesitás cambiar tu stack, tu repositorio ni tu equipo.
+
+Solo necesitás correr un comando desde la raíz de tu proyecto:
+
+```bash
+npx create-quiver@latest init --name "Mi Proyecto"
+```
+
+En minutos tenés el contexto de IA preparado, el flujo definido y el primer paso claro.
+
+**[Empezar gratis →]** `npx create-quiver@latest init`
+
+**[Leer la guía completa →]** Ver documentación
+
+**[Ver el código →]** [Completar con información real del producto: URL del repositorio]
+
+---
+
+> *Quiver es MIT. No hay costos de licencia. El único costo es el de los proveedores de IA que elijas usar.*

package/docs/AI_CONTEXT.md.es.template

@@ -20,7 +20,9 @@ Este archivo comprime el contrato de trabajo para agentes IA. Usa los documentos
 ## Reglas criticas
 
 - Un slice equivale a un commit.
-- Un spec equivale a un PR.
+- Un slice equivale a un PR por defecto.
+- Un spec puede generar multiples PRs.
+- Los PRs agrupados son excepciones y deben cumplir `docs/GITFLOW_PR_GUIDE.md`.
 - No inventes archivos, rutas, flags ni reglas de negocio.
 - No sobrescribas contenido humano sin revisar si debe preservarse.
 - Usa `TODO`, `Assumption` o `Pending confirmation` para incertidumbre.

package/docs/AI_CONTEXT.md.template

@@ -34,7 +34,9 @@ This file is the main context pack after `AGENTS.md` and `docs/PROJECT_MAP.md`.
 ## Critical Rules
 
 - One slice maps to one commit.
-- One spec maps to one PR.
+- One slice maps to one PR by default.
+- One spec can produce multiple PRs.
+- Grouped PRs are exceptions and must follow `docs/GITFLOW_PR_GUIDE.md`.
 - Slice numbering resets inside each spec.
 - Do not invent files that the bootstrap did not generate.
 - Use canonical paths when a path matters.

package/docs/CLI_UX_GUIDE.md

@@ -7,7 +7,7 @@ Este documento define el estandar de experiencia para los comandos de Quiver. La
 - Los comandos deben explicar que modo estan usando: deterministico, planner-assisted, dry-run, review, interactive, JSON o CI.
 - `--dry-run` debe ser el primer paso recomendado antes de escrituras, proveedores externos, worktrees, PRs o reparaciones.
 - La salida humana puede usar jerarquia visual, loaders y color; la salida JSON debe permanecer limpia y parseable.
-- Los prompts interactivos son opt-in. Ningun comando debe bloquear automatizaciones si `--interactive` no fue pedido.
+- Los prompts interactivos son opt-in, salvo confirmaciones de seguridad para comandos destructivos como `migrate`. Ningun comando debe quedar esperando input en CI/no-TTY; debe fallar con guia accionable o aceptar un bypass explicito como `--yes`.
 - Las revisiones humanas ocurren antes de escrituras persistentes siempre que el comando soporte `--review`.
 - Las credenciales viven en los CLIs de proveedor, `gh`, Git o el sistema operativo. Quiver no debe guardarlas.
 
@@ -93,6 +93,7 @@ Reglas:
 | Comando | `--with-planner` | `--interactive` | `--review` | Notas |
 |---|---:|---:|---:|---|
 | `init` | no | si | no | Interactive guia modo de proyecto, metodologia `wdd-sdd`, perfil inicial y proximo paso de perfiles de agentes. |
+| `migrate` | no | no | no | En TTY confirma antes de escribir; en CI/no-TTY requiere `--yes`. `--dry-run` no pide confirmacion ni escribe. |
 | `ai prepare-context` | si | si | si | Modo deterministico por defecto; planner opcional con contrato docs-only. |
 | `ai plan` | si | si | si | El planner ya es implicito; `--with-planner` se acepta por consistencia. |
 | `spec create` | si | si | si | Consume un plan tecnico aprobado del planner; no vuelve a ejecutar proveedor. Review previsualiza el paquete antes de escribir. |
@@ -108,6 +109,13 @@ Reglas:
 | `flow`, `dashboard`, `next`, `graph`, `version` | no | no | no | Lectura/inspeccion; `dashboard` puede acotarse con `--details`, `--section` y `--limit`, pero no acepta flags decorativas. |
 | `ai inspect`, `ai export`, `ai specs list`, `ai slices list`, `ai trace report` | no | no | no | Superficies read-only o machine-readable. |
 
+## Contratos read-only de plan, graph y next
+
+- `next --auto-start` requiere TTY interactiva; en CI/no-TTY falla antes de iniciar un slice y no emite JSON parcial.
+- `plan` mantiene JSON limpio. Las advertencias sobre slices sin `estimated_hours` positivo aparecen solo en salida humana y esos slices cuentan como `0h`.
+- `graph --level <n>` mantiene JSON limpio. Si el nivel no existe, la salida humana muestra un estado vacio localizado y `--json` emite `levels: []` / `conflicts: []`.
+- `graph --json` tiene precedencia sobre `--format tree|mermaid|dot`; con ambos flags, la salida sigue siendo JSON parseable.
+
 ## Flujo recomendado para contexto de IA
 
 Modo deterministico:

package/docs/COMMANDS.md.template

@@ -21,7 +21,7 @@ This document is the canonical command reference for the orchestration roadmap.
 | `npx create-quiver flow` | Shows the read-only guided flow entrypoint, context source/freshness, package-manager-aware script guidance, and next safe command | macOS, Linux, Windows | v0.11 | `npx create-quiver flow` |
 | `npx create-quiver dashboard` | Shows a compact read-only summary of project, spec, slice, run, approval, and agent status | macOS, Linux, Windows | next | `npx create-quiver dashboard --spec <spec>` |
 | `npx create-quiver dashboard --details` | Shows the full human dashboard report for audit/debug sessions | macOS, Linux, Windows | next | `npx create-quiver dashboard --details` |
-| `npx create-quiver dashboard --section <name>` | Shows one human dashboard section such as `specs`, `slices`, `blockers`, `warnings`, `agents`, `approvals`, `runs`, `active-slice`, or `next-steps` | macOS, Linux, Windows | next | `npx create-quiver dashboard --section slices --limit 10` |
+| `npx create-quiver dashboard --section <name>` | Shows one human dashboard section such as `overview`, `specs`, `slices`, `blockers`, `warnings`, `agents`, `approvals`, `runs`, `active-slice`, or `next-steps` | macOS, Linux, Windows | next | `npx create-quiver dashboard --section slices --limit 10` |
 | `npx create-quiver analyze --dry-run` | Previews scan, project-map, and AI context writes without creating files | macOS, Linux, Windows | v0.13 | `npx create-quiver analyze --dry-run` |
 | `quiver:analyze` | Writes raw analyzer data to `.quiver/scans/PROJECT_SCAN.json`, the visible project map to `docs/PROJECT_MAP.md`, and refreshed AI context | macOS, Linux, Windows | v0.8 | `npm run quiver:analyze` |
 | `quiver:flow` | Runs the guided flow entrypoint through the generated npm script | macOS, Linux, Windows | v0.11 | `npm run quiver:flow` |
@@ -32,6 +32,8 @@ This document is the canonical command reference for the orchestration roadmap.
 | `quiver:doctor -- --fix --dry-run` | Previews safe non-destructive repairs without writing files | macOS, Linux, Windows | v0.11 | `npm run quiver:doctor -- --fix --dry-run` |
 | `quiver:doctor -- --fix` | Applies safe idempotent repairs after review | macOS, Linux, Windows | v0.11 | `npm run quiver:doctor -- --fix` |
 | `quiver:evidence -- run -- <command>` | Captures command validation evidence with exit code, duration, redacted/truncated output, and a local Markdown record | macOS, Linux, Windows | v0.11 | `npm run quiver:evidence -- run -- npm test` |
+| `quiver:evidence -- list --json` | Lists local evidence records as parseable JSON for automation | macOS, Linux, Windows | next | `npm run quiver:evidence -- list --json` |
+| `quiver:evidence -- show <path> --json` | Shows one local evidence record with content and metadata as parseable JSON | macOS, Linux, Windows | next | `npm run quiver:evidence -- show .quiver/evidence/evidence.md --json` |
 | `npx create-quiver ai run create --input <requirements.md>` | Creates a persistent AI lifecycle run under `.quiver/runs/` | macOS, Linux, Windows | v0.12 | `npx create-quiver ai run create --input requirements.md` |
 | `npx create-quiver ai status` | Shows the current AI lifecycle phase and next safe command | macOS, Linux, Windows | v0.12 | `npx create-quiver ai status` |
 | `npx create-quiver ai resume` | Resumes guidance from the last valid AI lifecycle phase | macOS, Linux, Windows | v0.12 | `npx create-quiver ai resume` |
@@ -85,8 +87,13 @@ This document is the canonical command reference for the orchestration roadmap.
 | `quiver:spec:status` | Shows spec worktree, branch, `slice-00`, and pending slices | macOS, Linux, Windows | v0.10 | `npm run quiver:spec:status -- specs/<spec>` |
 | `quiver:spec:validate` | Validates spec docs, slices, briefs, evidence, status, dependencies, and safe paths | macOS, Linux, Windows | v0.13 | `npm run quiver:spec:validate -- specs/<spec>` |
 | `quiver:spec:close` | Closes a merged clean spec worktree and pulls the main checkout | macOS, Linux, Windows | v0.10 | `npm run quiver:spec:close -- specs/<spec> --dry-run` |
+| `quiver:start-slice` | Starts one slice through the canonical `slice start` namespace without requiring Bash | macOS, Linux, Windows | next | `npm run quiver:start-slice -- specs/<spec>/slices/<slice>/slice.json` |
 | `quiver:check-slice -- --local <slice.json>` | Runs local structural slice validation without remote/base checks | macOS, Linux, Windows | v0.11 | `npm run quiver:check-slice -- --local specs/<spec>/slices/<slice>/slice.json` |
+| `quiver:check-pr` | Validates PR readiness through the canonical `slice pr` namespace without requiring Bash | macOS, Linux, Windows | next | `npm run quiver:check-pr -- specs/<spec>/slices/<slice>/slice.json` |
+| `quiver:check-scope` | Compares changed files with the declared slice scope without requiring Bash | macOS, Linux, Windows | next | `npm run quiver:check-scope -- specs/<spec>/slices/<slice>/slice.json --base main` |
+| `quiver:cleanup-slice` | Cleans active-slice state through the canonical `slice cleanup` namespace without requiring Bash | macOS, Linux, Windows | next | `npm run quiver:cleanup-slice -- specs/<spec>/slices/<slice>/slice.json --dry-run` |
 | `quiver:check-handoff -- <handoff-or-brief.md>` | Validates legacy `HANDOFF.md` files and per-slice `EXECUTION_BRIEF.md` / `CLOSURE_BRIEF.md` files | macOS, Linux, Windows | v0.12.1 | `npm run quiver:check-handoff -- specs/<spec>/slices/<slice>/EXECUTION_BRIEF.md` |
+| `quiver:new-handoff` | Creates an exceptional handoff through the canonical `handoff new` namespace without requiring Bash | macOS, Linux, Windows | next | `npm run quiver:new-handoff -- <spec-slug>` |
 
 ## CLI Flags
 
@@ -101,9 +108,9 @@ This document is the canonical command reference for the orchestration roadmap.
 | `--output <file>` | `evidence run` | Write the evidence Markdown file to an explicit path instead of `.quiver/evidence/` |
 | `--max-output <n>` | `evidence run` | Limit captured stdout and stderr characters per section |
 | `--dir <target>` | `demo create spec-viewer` | Select the demo target directory; default is `./quiver-spec-viewer` |
-| `--json` | `dashboard`, `version`, `plan`, `graph`, `next` | Emit machine-readable JSON |
+| `--json` | `dashboard`, `version`, `plan`, `graph`, `next`, `evidence list`, `evidence show` | Emit machine-readable JSON |
 | `--details` | `dashboard` | Show the full human dashboard report instead of the compact default; incompatible with `--json` and `--section` |
-| `--section <name>` | `dashboard` | Show one human dashboard section; incompatible with `--json` and `--details` |
+| `--section <name>` | `dashboard` | Show one human dashboard section: `overview`, `specs`, `slices`, `blockers`, `warnings`, `agents`, `approvals`, `runs`, `active-slice`, or `next-steps`; incompatible with `--json` and `--details` |
 | `--limit <n>` | `dashboard` | Limit compact dashboard lists between 1 and 100; incompatible with `--json` |
 | `--all-ready` | `next` | List all ready slices instead of just the next one |
 | `--only-ready` | `plan` | Show only slices with no pending dependencies |
@@ -131,7 +138,7 @@ This document is the canonical command reference for the orchestration roadmap.
 | `--execute` | `ai execute-plan` | Execute the planned waves instead of printing commands |
 | `--mode <auto\|manual\|delegated>` | `ai execute-plan` | Choose compatible sequential execution, manual prompt output, or delegated worktree execution |
 | `--create` | `ai pr` | Create the GitHub PR after preflight and plan review |
-| `--base <branch>` | `ai pr`, `spec close` | Select PR base or cleanup base branch |
+| `--base <branch>` | `check-slice`, `check-scope`, `check-pr`, `ai pr`, `spec start`, `spec close` | Override base branch resolution; explicit values win before Remote HEAD and fallback branches |
 | `--allow-dirty` | `ai execute-slice`, `ai execute-plan` | Allow pre-existing dirty files and ignore them for scope diff |
 | `--ssh-host-alias <alias>` | `ai doctor`, `ai pr` | SSH host alias from the user's Git config, for example `github-work` |
 | `--identity-file <path>` | `ai doctor`, `ai pr` | SSH key path to validate separately from the host alias |
@@ -143,10 +150,15 @@ This document is the canonical command reference for the orchestration roadmap.
 - The `quiver` binary is an alias to the same package CLI after local installation. Keep `npx create-quiver` as the bootstrap command.
 - Keep the table concise and cross-platform.
 - Shared graph library: `src/create-quiver/lib/slice-graph.js`.
+- `quiver:plan` shows a human-only note when slices have no positive `estimated_hours`; JSON remains machine-readable and reports those hours as `0`.
 - `quiver:graph --format mermaid` is the PR-friendly Mermaid export; `--format dot` is for Graphviz/DOT consumers.
-- `quiver:next` prints the next ready slice and can auto-start it behind a confirmation prompt.
+- `quiver:graph --json` takes precedence over `--format tree|mermaid|dot`, so combined flags still emit parseable JSON.
+- `quiver:graph --level <n>` reports a localized human empty state when the level has no slices; JSON emits empty `levels` and `conflicts` arrays.
+- `quiver:next` prints the next ready slice and can auto-start it behind a confirmation prompt in interactive TTY sessions only.
 - `check-slice` validates `depends_on` targets and requires `parallel_safe_reason` when `parallel_safe` is `never`.
 - `check-handoff` validates both exceptional `HANDOFF.md` transfers and current slice-local `EXECUTION_BRIEF.md` / `CLOSURE_BRIEF.md` contracts.
+- Prefer canonical namespaces for new usage: `slice start|check|pr|scope|cleanup|refresh-active` and `handoff check|new`. Legacy aliases such as `start-slice`, `check-slice`, and `check-handoff` remain available and warn only on stderr.
+- On Windows PowerShell, use `npx create-quiver ...` directly or generated `quiver:*` npm scripts. Bash-only scripts such as `start:slice` and `check:slice` are legacy compatibility paths for Bash-capable shells.
 - `quiver:ai:onboard`, `quiver:ai:plan`, `quiver:ai:revise`, `quiver:ai:review-plan`, and `quiver:ai:execute-slice` support `codex`, `claude`, and `gemini` through local CLIs. Use `--dry-run` first to inspect the invocation without requiring provider auth, or `--print-prompt` to print the exact planner/reviewer prompt without executing a provider.
 - `quiver:ai:prepare-context -- --dry-run` previews deterministic docs-only context drafts, diff snippets, assumptions, risks, contradictions, and omitted paths. Write mode stores snapshots under `.quiver/runs/<run-id>/snapshots/` and preserves human-authored content by appending or refreshing a Quiver-managed block.
 - `quiver:ai:prepare-context -- --with-planner` invokes a planner provider and only accepts a validated docs-only proposal. Use `--print-prompt` for external planners, `--review` to inspect the proposal before writing, and `--interactive` to require confirmation.
@@ -169,7 +181,9 @@ This document is the canonical command reference for the orchestration roadmap.
 - `quiver:ai:approvals`, `quiver:flow`, `quiver:ai:status`, `quiver:ai:resume`, and `quiver:spec:create -- --interactive` use the same approval-candidate data so next-step guidance stays consistent.
 - `quiver:ai:prompt-slice -- --dry-run` prints a paste-ready manual executor prompt and does not call a provider.
 - For commands pasted into another AI agent, prefer a non-interactive pinned form such as `npx --yes create-quiver@<version> ai prompt-slice --slice specs/<spec>/slices/<slice>/slice.json --dry-run`.
-- `quiver:evidence -- run -- <command>` preserves the wrapped command exit code. Redaction is best effort; avoid commands that intentionally print secrets.
+- `quiver:evidence -- run -- <command>` preserves the wrapped command exit code, writes failure evidence, records signal termination as `Signal`, and returns the standard `128 + signal` exit code for signaled processes.
+- Explicit `quiver:evidence -- run --output <file>` targets and `quiver:evidence -- show <path>` reads must stay inside the project root; Quiver rejects path traversal and symlink escapes before command execution or file reads.
+- Evidence output redaction/truncation is best effort; avoid commands that intentionally print secrets.
 - `demo create spec-viewer` is optional and static; it must stay outside default `init`.
 - `quiver:spec:start -- --dry-run specs/<spec>` previews the spec worktree path and branch without creating a worktree.
 - `quiver:ai:execute-slice -- --commit` creates exactly one commit only after provider, branch/worktree, scope, and validation commands pass. Commit mode refuses pre-existing dirty files even if `--allow-dirty` is set. Successful execution updates `CLOSURE_BRIEF.md`, `EVIDENCE_REPORT.md`, `COMMAND_LOG.md`, `STATUS.md`, and `slice.json`; likely secrets in captured stdout/stderr are redacted.

package/docs/GITFLOW_PR_GUIDE.md

@@ -1,21 +1,78 @@
 # Git and PR Guide
 
-**Version:** 2.0
-**Last updated:** 2026-05-26
+**Version:** 2.1
+**Last updated:** 2026-06-02
 
 ## Purpose
 
-This guide explains how to open and review spec PRs without breaking the canonical workflow.
+This guide explains how to open, review, and merge slice PRs without breaking the canonical workflow.
 
 ## Core Rule
 
-- One slice = one commit
-- One spec = one PR
-- One spec should be worked from one dedicated worktree/branch.
+- One slice = one commit.
+- One slice = one PR by default.
+- One spec can produce multiple PRs. Grouped PRs are exceptions and must meet the grouped PR policy below.
+- One active PR should be worked from one dedicated worktree/branch.
 - Slice numbers reset per spec. `slice-01` is the first slice in each spec.
-- Do not commit directly to `develop`
-- Open and merge the documentation PR before the first slice starts execution
-- Do not open the spec PR before the documentation PR is merged
+- Do not commit directly to `develop` or any protected base branch.
+- Open and merge the documentation PR that establishes `slice-00` before runtime slices start execution.
+- Do not open runtime slice PRs before the documentation foundation is merged.
+
+## PR Sizing Policy
+
+### Individual PR Required
+
+Open an individual PR for any slice that includes:
+
+- Functional code.
+- UI/UX changes.
+- Supabase, Edge Functions, auth, or storage changes.
+- Preview or deployment behavior.
+- Performance or code-splitting changes.
+- Refactors.
+- Tests or CI changes that affect gates.
+
+### Grouped PR Exception
+
+A grouped PR is allowed only when all conditions are true:
+
+- It contains at most 2-3 slices.
+- Every included slice is docs-only, research-only, or low-risk mechanical cleanup.
+- It does not change behavior.
+- It does not mix docs with UI, backend, refactor, or performance work.
+- Each slice keeps separate evidence.
+- The whole PR can be reverted without leaving partial state.
+
+If any condition fails, split the work into individual slice PRs.
+
+## Merge Policy
+
+- Human merge is the default.
+- AI agents may create PRs, fix CI, monitor checks, and mark PRs as ready.
+- Assisted auto-merge is allowed only when explicitly authorized by a human for that PR or for a documented category.
+
+## Assisted Auto-Merge Policy
+
+Assisted auto-merge is allowed only when all conditions are true:
+
+- The PR is docs-only or chore-only.
+- Risk is low.
+- There are no runtime changes.
+- There are no production configuration changes.
+- Checks are green.
+- There are no pending comments.
+
+Assisted auto-merge is prohibited for:
+
+- UI.
+- Supabase.
+- Edge Functions.
+- Auth.
+- Storage.
+- Preview.
+- Performance.
+- Refactors.
+- Changes with doubtful rollback.
 
 ## AI PR Preflight
 
@@ -36,10 +93,11 @@ Use the SSH host alias from your Git remote separately from the key path. Quiver
 
 ## Required PR Headings
 
-All spec PR notes must use:
+All slice PR notes must use:
 
 - `## Title`
 - `## Summary`
+- `## PR Policy`
 - `## Scope`
 - `## Files`
 - `## How to Test (DETAILED - REQUIRED)`
@@ -66,5 +124,9 @@ Inside `How to Test`, use:
 ## Anti-Patterns
 
 - Pushing directly to `develop`
-- Reusing the same branch for multiple specs
+- Reusing the same branch for unrelated PRs
+- Grouping behavior-changing slices
+- Mixing docs-only slices with UI, backend, refactor, or performance work
+- Auto-merging without explicit human authorization
+- Auto-merging prohibited categories
 - Writing PR bodies outside `pr.md`

package/docs/GITFLOW_PR_GUIDE.md.es.template

@@ -3,10 +3,68 @@
 ## Reglas principales
 
 - Un slice equivale a un commit.
-- Un spec equivale a un PR.
-- No mezclar specs en la misma branch.
+- Un slice equivale a un PR por defecto.
+- Un spec puede generar multiples PRs.
+- Los PRs agrupados son excepciones y deben cumplir la politica de agrupacion.
+- No mezclar PRs no relacionados en la misma branch.
 - No abrir PR sin evidencia de validacion.
 
+## Politica de tamano de PR
+
+### PR individual obligatorio
+
+Abri un PR individual para cualquier slice que incluya:
+
+- codigo 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 esta permitido solo si:
+
+- incluye como maximo 2-3 slices;
+- todos los slices son docs-only, research-only o limpieza mecanica 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.
+
+Si una condicion falla, separa el trabajo en PRs individuales por slice.
+
+## Politica de 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 solo esta permitido con autorizacion humana explicita para ese PR o para una categoria documentada.
+
+## Politica de auto-merge asistido
+
+El auto-merge asistido esta permitido solo si:
+
+- el PR es docs-only o chore-only;
+- el riesgo es bajo;
+- no hay cambios runtime;
+- no hay cambios de configuracion productiva;
+- los checks estan verdes;
+- no hay comentarios pendientes.
+
+El auto-merge asistido esta prohibido para:
+
+- UI;
+- Supabase;
+- Edge Functions;
+- auth;
+- storage;
+- preview;
+- performance;
+- refactors;
+- cambios con rollback dudoso.
+
 ## Preflight de PR
 
 ```bash
@@ -17,6 +75,7 @@ npx create-quiver ai pr --dry-run --ssh-host-alias <alias> --identity-file <key>
 
 - `## Title`
 - `## Summary`
+- `## PR Policy`
 - `## Scope`
 - `## Files`
 - `## How to Test (DETAILED - REQUIRED)`