create-quiver 0.15.4 → 0.17.0

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,8 @@ 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 analyze-project` | no | no | si | `--dry-run` es read-only y no ejecuta proveedor; `--review` exige JSON con evidencia, diff final, confirmacion, snapshot y validacion post-write. |
 | `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,8 +110,25 @@ 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
 
+Analisis profundo de un proyecto existente:
+
+```bash
+npx create-quiver ai analyze-project --deep --dry-run
+npx create-quiver ai analyze-project --deep --dry-run --json
+npx create-quiver ai analyze-project --deep --review
+```
+
+`ai analyze-project` debe mantener estas garantias: en `--dry-run` no escribe ni ejecuta proveedor; con proveedor no lee `.env`, dependencias, caches, binarios ni outputs generados; toda conclusion importante cita evidencia o queda como `unknown`; las escrituras se limitan a docs aprobados, usan bloques gestionados por Quiver, muestran diff y crean snapshot previo.
+
 Modo deterministico:
 
 ```bash

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)`

package/docs/GITFLOW_PR_GUIDE.md.template

@@ -1,21 +1,78 @@
 # Git and PR Guide
 
-**Version:** 2.0
+**Version:** 2.1
 **Last updated:** {{FECHA}}
 
 ## 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/INDEX.md

@@ -1,6 +1,6 @@
 # Quiver Documentation Index
 
-**Last updated:** 2026-05-29
+**Last updated:** 2026-06-10
 
 Use this file as the first documentation map before planning, implementing, reviewing, or opening PRs in this repository. Prefer the smallest set of linked documents that fits the task.
 
@@ -10,6 +10,7 @@ Use this file as the first documentation map before planning, implementing, revi
 - **AI guide:** [`../README_FOR_AI.md`](../README_FOR_AI.md)
 - **CLI UX standards:** [`./CLI_UX_GUIDE.md`](./CLI_UX_GUIDE.md)
 - **Command reference:** [`./reference/commands.md`](./reference/commands.md)
+- **Slice JSON schema:** [`./reference/slice-schema.md`](./reference/slice-schema.md)
 - **Troubleshooting:** [`./TROUBLESHOOTING.md`](./TROUBLESHOOTING.md)
 - **Git and PR workflow:** [`./GITFLOW_PR_GUIDE.md`](./GITFLOW_PR_GUIDE.md)
 
@@ -39,6 +40,10 @@ Canonical specs live outside `docs/` in [`../specs/`](../specs/).
 
 Recent specs:
 
+- [`../specs/quiver-v52-schema-docs-release-hygiene/SPEC.md`](../specs/quiver-v52-schema-docs-release-hygiene/SPEC.md)
+- [`../specs/quiver-v51-cli-ergonomics-automation-contracts/SPEC.md`](../specs/quiver-v51-cli-ergonomics-automation-contracts/SPEC.md)
+- [`../specs/quiver-v50-audit-trust-foundation/SPEC.md`](../specs/quiver-v50-audit-trust-foundation/SPEC.md)
+- [`../specs/quiver-v46-deep-project-analysis/SPEC.md`](../specs/quiver-v46-deep-project-analysis/SPEC.md)
 - [`../specs/quiver-v45-ci-actions-node24-readiness/SPEC.md`](../specs/quiver-v45-ci-actions-node24-readiness/SPEC.md)
 - [`../specs/quiver-v44-provider-live-output-tui-lite/SPEC.md`](../specs/quiver-v44-provider-live-output-tui-lite/SPEC.md)
 - [`../specs/quiver-v43-cli-i18n-audit-release-readiness/SPEC.md`](../specs/quiver-v43-cli-i18n-audit-release-readiness/SPEC.md)

package/docs/QUICK.md.template

@@ -15,7 +15,8 @@ Use `docs/PROJECT_MAP.md` for the package manager, project stack, test commands,
 ## Hard Rules
 
 - One slice = one commit.
-- One spec = one PR.
+- One slice = one PR by default.
+- Grouped PRs are exceptions and must follow `docs/GITFLOW_PR_GUIDE.md`.
 - Read `./STANDARD.md` for workflow details.
 - Read `./DEEP.md` for history and context.
 - Do not edit files outside the active slice.

package/docs/STANDARD.md.template

@@ -19,7 +19,8 @@ This is the default context pack for everyday AI work.
 - Use maps, metadata, and diffs before opening full source files.
 - Keep scope inside the active slice.
 - Make one commit per slice.
-- Open one PR per spec.
+- Open one PR per slice by default.
+- Group slices in one PR only when `docs/GITFLOW_PR_GUIDE.md` allows it.
 - Record durable decisions in `docs/DECISIONS.md`.
 - Treat `docs/PROJECT_MAP.md` as the single source of truth for stack, package manager, and command references.
 

package/docs/WORKFLOW.md.es.template

@@ -8,7 +8,9 @@ Este documento define el workflow canonico de implementacion del proyecto.
 
 - No implementar sin slice.
 - 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`.
 - El spec define el plan; el slice define la ejecucion.
 - Ningun slice debe ejecutarse hasta estar listo.
 - La salida JSON y los artefactos machine-readable no se traducen.

package/docs/WORKFLOW.md.template

@@ -8,7 +8,9 @@ This document is the canonical implementation workflow for the project.
 
 - Do not implement without a slice.
 - 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 is local to each spec. Every spec starts with mandatory `slice-00` as the documentary foundation; `slice-01` is the first implementation slice.
 - The spec defines the plan; the slice defines the execution.
 - No slice should enter execution until it is `ready`.
@@ -63,9 +65,9 @@ Use maps, metadata, diffs, and summaries first. Open full files only when the sm
    - `ai execute-slice` updates `CLOSURE_BRIEF.md`, `EVIDENCE_REPORT.md`, `COMMAND_LOG.md`, `STATUS.md`, and `slice.json` only after the provider changes in-scope files and validation passes.
 9. Validate with `npx create-quiver check-slice <slice.json>` or `npm run quiver:check-slice -- <slice.json>`.
 10. Write evidence. Prefer `npx create-quiver evidence run -- <command>` when you need a compact local Markdown record of validation output.
-11. Repeat for the next slice until the spec is complete.
-12. Open one PR for the spec. Use `npx create-quiver ai pr --dry-run --input specs/<spec-slug>/pr.md --ssh-host-alias <alias> ...` first, then add `--create` only after review. Quiver blocks PR creation while slices in that spec remain open.
-13. After the PR is merged and the spec worktree is clean, close it with `npx create-quiver spec close specs/<spec-slug>`.
+11. Open one PR for the completed slice by default. Use `npx create-quiver ai pr --dry-run --input specs/<spec-slug>/pr.md --ssh-host-alias <alias> ...` first when the generated spec PR body is the intended body, then add `--create` only after review. For slice-level PR bodies, keep the PR aligned with the slice `pr.md` and validate the slice evidence before creating the PR.
+12. Repeat for the next slice until the spec is complete.
+13. After the final PR for the spec is merged and the spec worktree is clean, close it with `npx create-quiver spec close specs/<spec-slug>`.
 
 ## Support Contract
 

package/docs/getting-started/installation.md

@@ -2,6 +2,13 @@
 
 Esta guía explica por qué Quiver normalmente se ejecuta con `npx`, cuándo aparece en `node_modules` y cuándo conviene instalarlo como dependencia del proyecto.
 
+## Requisitos previos
+
+- Node.js `>=20.12.0`.
+- npm compatible con esa versión de Node.
+
+El mínimo está declarado en `package.json` y se valida en CI. También coincide con el requisito de dependencias del CLI como `@clack/prompts`.
+
 ## Uso recomendado
 
 Para usar la última versión publicada de Quiver, ejecutá: