create-quiver 0.15.4 → 0.16.0

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

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

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/ai/ACTIVE_SLICE.md

@@ -0,0 +1,61 @@
+---
+purpose: "Active slice execution brief"
+applies_when: "implementation"
+token_cost: 409
+last_updated: "2026-06-09"
+supersedes: null
+---
+
+# Active Slice
+
+## Slice ID
+
+slice-01-json-schema-for-slice-json
+
+## Title
+
+JSON Schema for slice.json
+
+## Objective
+
+Publish a slice.json JSON Schema aligned with runtime behavior.
+
+## allowed_files
+- docs/INDEX.md
+- docs/reference/slice-schema.md
+- docs/schema/**
+- package.json
+- package-lock.json
+- scripts/ci/check-slice-schema.js
+- scripts/package-quiver.sh
+- tests/fixtures/slice-schema/invalid/empty-files.json
+- tests/fixtures/slice-schema/invalid/missing-git-field.json
+- tests/fixtures/slice-schema/invalid/missing-slice-id.json
+- tests/fixtures/slice-schema/invalid/unsafe-allowed-write-path.json
+- tests/schema/slice-schema.test.js
+- specs/quiver-v52-schema-docs-release-hygiene/SPEC.md
+- specs/quiver-v52-schema-docs-release-hygiene/STATUS.md
+- specs/quiver-v52-schema-docs-release-hygiene/EVIDENCE_REPORT.md
+- specs/quiver-v52-schema-docs-release-hygiene/slices/slice-01-json-schema-for-slice-json/CLOSURE_BRIEF.md
+- specs/quiver-v52-schema-docs-release-hygiene/slices/slice-01-json-schema-for-slice-json/slice.json
+- specs/quiver-v52-schema-docs-release-hygiene/slices/slice-01-json-schema-for-slice-json/pr.md
+
+## Validation Commands
+- npm ci
+- npm run schema:slice:check
+- node --test tests/schema/slice-schema.test.js
+- npm run docs:check
+- node --test
+- npm run package:quiver
+- git diff --check
+
+## Definition of Done
+- Schema is valid JSON Schema Draft-07 or higher.
+- Schema validates existing valid slice fixtures.
+- Schema rejects representative invalid fixtures.
+- Docs reference the schema.
+- Package smoke includes the schema if it is public.
+
+## Prohibition
+
+Do not edit any file outside allowed_files.

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á:

package/docs/reference/commands.md

@@ -21,6 +21,79 @@ npx create-quiver <comando>
 
 Más detalle: [Instalación y uso con npx](../getting-started/installation.md).
 
+## Referencia generada desde el CLI
+
+El bloque siguiente se actualiza con `npm run docs:commands:write` y se verifica con `npm run docs:commands:check`.
+
+El contenido curado fuera de los marcadores se mantiene manual y no debe ser reescrito por el generador.
+
+<!-- quiver:generated-cli-reference:start -->
+> Generated by `npm run docs:commands:write` from `COMMAND_HELP_GROUPS` and checked against `node bin/create-quiver.js --lang en --help --no-color`. Do not edit this block manually.
+
+| Group | Command | Runtime help |
+|---|---|---|
+| Bootstrap and project context | `init` | Create the default AI-first Quiver contract in the current project. |
+| Bootstrap and project context | `analyze` | Scan the project and write docs/PROJECT_MAP.md plus .quiver scan data. |
+| Bootstrap and project context | `doctor` | Validate the Quiver layout, generated docs, environment, and next safe steps. |
+| Bootstrap and project context | `flow` | Show the read-only guided workflow stage, blockers, and next safe command. |
+| Bootstrap and project context | `dashboard` | Show compact read-only project, spec, slice, run, approval, and agent status. |
+| Bootstrap and project context | `version` | Show a Quiver-branded version report; use --json for metadata. |
+| Bootstrap and project context | `changelog` | Show recent local CHANGELOG.md release entries; use --json for metadata. |
+| Bootstrap and project context | `config language show\|set` | Inspect or update the effective Quiver language without editing JSON by hand. |
+| Bootstrap and project context | `prepare` | Run setup diagnostics for providers, GitHub, SSH, and project readiness. |
+| Bootstrap and project context | `migrate` | Upgrade an already initialized Quiver project to the current contract. |
+| Planning and slice navigation | `plan` | List slices in execution order with critical path and optional JSON output. |
+| Planning and slice navigation | `graph` | Render slice dependencies as tree, Mermaid, DOT, or JSON-ready graph output. |
+| Planning and slice navigation | `next` | Print the next ready slice or every ready slice with --all-ready. |
+| AI lifecycle | `ai run create\|close` | Create a durable AI lifecycle run or close/archive a completed or stale run without deleting evidence. |
+| AI lifecycle | `ai active-slice status\|reconcile` | Inspect or dry-run reconcile local active-slice state from every supported source. |
+| AI lifecycle | `ai status` | Show current AI lifecycle phase, approved versions, blockers, and next command. |
+| AI lifecycle | `ai resume` | Resume guidance from the last valid lifecycle phase without chat memory. |
+| AI lifecycle | `ai onboard` | Run or print the planner onboarding prompt with a token-aware context pack. |
+| AI lifecycle | `ai prepare-context` | Preview or write docs-only AI context updates with assumptions and risks. |
+| AI lifecycle | `ai agent set\|list\|show\|doctor\|repair` | Manage, diagnose, and dry-run repair planner, executor, reviewer, and doctor provider profiles without secrets. |
+| AI lifecycle | `ai models list` | List provider/model ids known by Quiver without claiming account availability. |
+| AI lifecycle | `ai plan` | Generate versioned planner drafts for acceptance criteria, technical plan, or spec phase. |
+| AI lifecycle | `ai revise` | Create a new planner draft from human feedback without approving it. |
+| AI lifecycle | `ai repair-plan` | Repair an approved technical plan into a new structured draft without mutating the approved artifact. |
+| AI lifecycle | `ai review-plan` | Review the technical-plan draft for production readiness before approval. |
+| AI lifecycle | `ai approve` | Approve a concrete saved draft version for the next planner phase. |
+| AI lifecycle | `ai approvals` | Inspect approval status and saved planner drafts. |
+| AI lifecycle | `ai prompt-slice` | Print a minimal executor prompt for one slice without provider execution. |
+| AI lifecycle | `ai execute-slice` | Execute one slice with scope checks, redacted evidence, closure updates, and optional commit. |
+| AI lifecycle | `ai execute-plan` | Print or execute dependency-safe waves in manual or delegated mode. |
+| AI lifecycle | `ai doctor` | Run GitHub, SSH, and PR readiness preflight checks. |
+| AI lifecycle | `ai pr` | Validate and optionally create a GitHub PR from the generated PR body. |
+| Inspection and export | `ai inspect` | Show dashboard-friendly lifecycle state for specs, slices, runs, agents, and blockers. |
+| Inspection and export | `ai export` | Export lifecycle state as JSON or Markdown for dashboards, PRs, or other agents. |
+| Inspection and export | `ai specs list` | List specs with status, progress, slice counts, and paths. |
+| Inspection and export | `ai slices list` | List slices with status, dependencies, blockers, and optional JSON. |
+| Inspection and export | `ai trace report` | Report AI runs, execution waves, and migration guidance. |
+| Specs, slices, and validation | `spec create` | Create the real spec tree from a reviewed approved technical plan. |
+| Specs, slices, and validation | `spec start` | Create or reuse the dedicated worktree and branch for one spec. |
+| Specs, slices, and validation | `spec status` | Show spec worktree, branch, slice-00 state, and pending slices. |
+| Specs, slices, and validation | `spec validate` | Validate spec docs, slices, briefs, evidence, status, dependencies, and safe paths. |
+| Specs, slices, and validation | `spec close` | Close a merged clean spec worktree and guide local sync. |
+| Specs, slices, and validation | `slice start\|check\|pr\|scope\|cleanup\|refresh-active` | Canonical namespace for slice lifecycle, validation, scope, and board commands. |
+| Specs, slices, and validation | `handoff check\|new` | Canonical namespace for validating or scaffolding handoff artifacts. |
+| Specs, slices, and validation | `start-slice` | Start work on one slice and mark it active. |
+| Specs, slices, and validation | `check-slice` | Validate slice structure, dependencies, scope, and readiness. |
+| Specs, slices, and validation | `check-pr` | Validate PR readiness for a slice/spec workflow. |
+| Specs, slices, and validation | `check-scope` | Compare changed files against a slice scope. |
+| Specs, slices, and validation | `cleanup-slice` | Clean active-slice state after a slice finishes or is discarded. |
+| Specs, slices, and validation | `refresh-active-slices` | Refresh generated active-slice boards. |
+| Specs, slices, and validation | `check-handoff` | Validate a transfer handoff or per-slice execution/closure brief. |
+| Specs, slices, and validation | `new-handoff` | Create a handoff scaffold for exceptional context transfer. |
+| Evidence and demos | `evidence run` | Run a command and record exit code, duration, redacted output, and Markdown evidence. |
+| Evidence and demos | `evidence list` | List local evidence records; use --json for automation. |
+| Evidence and demos | `evidence show` | Show one local evidence record; use --json for automation. |
+| Evidence and demos | `demo create spec-viewer` | Create or preview the optional static Quiver Spec Viewer demo scaffold. |
+| Shortcuts and compatibility | `--name "<project>"` | Compatibility alias for init when bootstrapping a project. |
+| Shortcuts and compatibility | `--version / -V` | Print the installed create-quiver package version. |
+| Shortcuts and compatibility | `--help / help` | Show this command reference. |
+| Shortcuts and compatibility | `quiver` | Local installed alias to the same CLI; use npx create-quiver for bootstrap. |
+<!-- quiver:generated-cli-reference:end -->
+
 ## Configuración inicial
 
 | Comando | Para qué sirve |
@@ -35,17 +108,32 @@ Más detalle: [Instalación y uso con npx](../getting-started/installation.md).
 | `npx --yes create-quiver@latest config language set en --global` | Guarda `en` como idioma global en `~/.quiver/config.json`. |
 | `npx --yes create-quiver@latest init --name "Proyecto"` | Inicializa Quiver en un proyecto. |
 | `npx --yes create-quiver@latest init --interactive` | Abre una guía interactiva para elegir idioma del proyecto, modo de proyecto, metodología `wdd-sdd`, perfil inicial y próximos pasos de agentes. |
-| `npx --yes create-quiver@latest migrate --dry-run` | Previsualiza migración de un proyecto Quiver anterior. |
-| `npx --yes create-quiver@latest migrate` | Aplica la migración. |
+| `npx --yes create-quiver@latest migrate --dry-run` | Previsualiza migración de un proyecto Quiver anterior sin pedir confirmación ni escribir archivos. |
+| `npx --yes create-quiver@latest migrate` | En TTY pide confirmación antes de escribir; en no-TTY falla con guía para usar `--dry-run` o `--yes`. |
+| `npx --yes create-quiver@latest migrate --yes` | Aplica la migración sin prompt para automatización. |
 | `npx --yes create-quiver@latest analyze` | Genera mapa del proyecto y datos de escaneo. |
 | `npx --yes create-quiver@latest doctor` | Valida la salud de Quiver. |
 | `npx --yes create-quiver@latest doctor --json` | Emite el mismo diagnóstico de Doctor como JSON parseable para automatización. |
 | `npx --yes create-quiver@latest flow` | Muestra el próximo paso seguro. |
+| `npx --yes create-quiver@latest flow --json` | Emite el próximo paso seguro como JSON parseable; incluye `nextCommand` y el alias compatible `next_command` con el mismo valor. |
 | `npx --yes create-quiver@latest dashboard` | Muestra un resumen compacto read-only del proyecto, specs, slices, runs, approvals y agentes. |
 | `npx --yes create-quiver@latest dashboard --details` | Muestra el reporte humano completo cuando se necesita auditoría sin perder el resumen por defecto. |
-| `npx --yes create-quiver@latest dashboard --section <name>` | Muestra una sección humana puntual como `specs`, `slices`, `blockers`, `warnings`, `agents`, `approvals`, `runs`, `active-slice` o `next-steps`. |
+| `npx --yes create-quiver@latest dashboard --section <name>` | Muestra una sección humana puntual como `overview`, `specs`, `slices`, `blockers`, `warnings`, `agents`, `approvals`, `runs`, `active-slice` o `next-steps`. |
 | `npx --yes create-quiver@latest dashboard --limit <n>` | Ajusta el límite de listas del dashboard compacto entre 1 y 100. |
 
+## Evidencia de validaciones
+
+| Comando | Para qué sirve |
+|---|---|
+| `npx --yes create-quiver@latest evidence run -- <command>` | Ejecuta un comando, preserva su exit code y escribe evidencia Markdown con duración, salida redactada y truncada. |
+| `npx --yes create-quiver@latest evidence run --output .quiver/evidence/test.md -- <command>` | Escribe la evidencia en una ruta explícita dentro del proyecto. |
+| `npx --yes create-quiver@latest evidence list --json` | Lista los archivos locales de evidencia como JSON parseable para automatización. |
+| `npx --yes create-quiver@latest evidence show .quiver/evidence/test.md --json` | Muestra un archivo de evidencia como JSON parseable con contenido y metadatos. |
+
+`evidence run` conserva el exit code del comando envuelto incluso cuando falla y escribe evidencia de la falla antes de salir. Si el proceso termina por señal, el registro incluye `Signal` y el CLI devuelve el exit code estándar `128 + signal`.
+
+Las rutas explícitas de `--output` y las rutas pasadas a `evidence show` deben permanecer dentro del root del proyecto. Quiver rechaza traversal (`..`) y escapes por symlink antes de ejecutar el comando o leer el archivo. La salida se redacta y trunca como defensa de seguridad, pero no reemplaza la revisión humana cuando un comando imprime secretos deliberadamente.
+
 ## Idioma del CLI
 
 Quiver resuelve el idioma de salida humana en este orden:
@@ -137,10 +225,16 @@ Reglas:
 | `npx --yes create-quiver@latest spec create --interactive` | Guía la selección de metodología `wdd-sdd`, input aprobado y modo de revisión antes de escribir. |
 | `npx --yes create-quiver@latest spec validate specs/<spec> --strict` | Valida el paquete de spec. |
 | `npx --yes create-quiver@latest spec start specs/<spec>` | Crea o reutiliza el worktree de una spec. |
-| `npx --yes create-quiver@latest plan --spec <spec>` | Muestra el orden de ejecución de slices. |
+| `npx --yes create-quiver@latest slice start specs/<spec>/slices/<slice>/slice.json` | Inicia trabajo sobre un slice usando el namespace canónico. |
+| `npx --yes create-quiver@latest slice check --local specs/<spec>/slices/<slice>/slice.json` | Valida estructura local de un slice usando el namespace canónico. |
+| `npx --yes create-quiver@latest slice pr specs/<spec>/slices/<slice>/slice.json` | Valida preparación de PR de un slice usando el namespace canónico. |
+| `npx --yes create-quiver@latest slice scope specs/<spec>/slices/<slice>/slice.json` | Compara archivos modificados contra el scope declarado usando el namespace canónico. |
+| `npx --yes create-quiver@latest handoff check specs/<spec>/slices/<slice>/EXECUTION_BRIEF.md` | Valida un handoff o brief usando el namespace canónico. |
+| `npx --yes create-quiver@latest handoff new <spec-slug>` | Crea un handoff excepcional usando el namespace canónico. |
+| `npx --yes create-quiver@latest plan --spec <spec>` | Muestra el orden de ejecución de slices; la salida humana avisa si algun slice no tiene `estimated_hours` positivo y lo cuenta como `0h`. |
 | `npx --yes create-quiver@latest dashboard --spec <spec>` | Muestra estado consolidado read-only para una spec sin ocultar el progreso global. |
 | `npx --yes create-quiver@latest dashboard --section slices --spec <spec>` | Inspecciona solo slices de la spec seleccionada. |
-| `npx --yes create-quiver@latest graph --spec <spec>` | Muestra dependencias entre slices. |
+| `npx --yes create-quiver@latest graph --spec <spec>` | Muestra dependencias entre slices; `--level <n>` acota un nivel y muestra un estado vacio humano si no hay slices en ese nivel. |
 | `npx --yes create-quiver@latest next --all-ready --spec <spec>` | Lista slices listos para ejecutar. |
 | `npx --yes create-quiver@latest ai prompt-slice --slice <slice.json> --dry-run` | Imprime un prompt mínimo para el ejecutor. |
 | `npx --yes create-quiver@latest ai execute-slice --slice <slice.json> --commit` | Ejecuta un slice y commitea después de validar. |
@@ -156,6 +250,8 @@ Reglas:
 | `npx --yes create-quiver@latest spec close specs/<spec> --dry-run` | Previsualiza limpieza del worktree después del merge. |
 | `npx --yes create-quiver@latest spec close specs/<spec>` | Cierra el worktree de la spec mergeada. |
 
+Base branch policy: `--base <branch>` always wins. Without `--base`, slice readiness commands prefer `slice.json` `git.base_branch`, then Remote HEAD, then `main`, `master`, and `develop`. `ai pr`, `spec start`, and `spec close` use Remote HEAD before the same fallback list when no slice-specific base applies.
+
 ## Opciones útiles
 
 | Opción | Para qué sirve |
@@ -171,7 +267,7 @@ Reglas:
 | `--lang en\|es` | Sobrescribe el idioma efectivo de la salida humana para una ejecución. |
 | `--global` | En `config language set`, escribe la configuración global de usuario en `~/.quiver/config.json`. |
 | `--details` | Expande el dashboard humano completo; no combina con `--json` ni `--section`. |
-| `--section <name>` | Muestra una sección humana del dashboard; no combina con `--json` ni `--details`. |
+| `--section <name>` | Muestra una sección humana del dashboard: `overview`, `specs`, `slices`, `blockers`, `warnings`, `agents`, `approvals`, `runs`, `active-slice` o `next-steps`; no combina con `--json` ni `--details`. |
 | `--limit <n>` | Limita listas del dashboard compacto entre 1 y 100; no combina con `--json`. |
 | `--provider codex\|claude\|gemini` | Selecciona CLI local de proveedor. |
 | `--model <model-id>` | Selecciona el identificador técnico del modelo para `ai agent set` o ejecución de proveedor. Quiver normaliza alias conocidos, pero no garantiza acceso en la cuenta del proveedor. |
@@ -181,6 +277,8 @@ Reglas:
 | `--ssh-host-alias <alias>` | Alias SSH de GitHub para validaciones de PR. |
 | `--identity-file <path>` | Ruta de la clave SSH para validaciones de PR. |
 
+`graph --json` mantiene precedencia sobre `--format <tree|mermaid|dot>` cuando ambos se pasan: la salida sigue siendo JSON parseable y no render Mermaid/DOT. Los formatos humanos siguen disponibles sin `--json`.
+
 ## Matriz de flags UX
 
 | Comando | `--with-planner` | `--interactive` | `--review` |

package/docs/reference/slice-schema.md

@@ -0,0 +1,37 @@
+# Slice JSON Schema
+
+Quiver publishes a JSON Schema for executable `slice.json` files:
+
+- Schema file: [`../schema/slice.schema.json`](../schema/slice.schema.json)
+- Check command: `npm run schema:slice:check`
+
+## Source Of Truth
+
+The schema follows the current runtime contract instead of an aspirational model:
+
+- `src/create-quiver/commands/spec.js` validates spec and slice structure.
+- `src/create-quiver/lib/slice.js` reads slice metadata for lifecycle commands.
+- `src/create-quiver/lib/readiness.js` validates local execution and PR readiness.
+- `src/create-quiver/lib/ai/spec-generator.js` generates and validates generated slice JSON.
+
+`check-slice --local` still requires a non-empty `files` array. Newer scope tooling can prefer `allowed_write_paths` when it is present, but `files` remains part of the executable contract for now.
+
+## Validate Local Slices
+
+Run:
+
+```bash
+npm run schema:slice:check
+```
+
+The check validates runtime-valid `specs/**/slices/**/slice.json` and `examples/**/slices/**/slice.json` fixtures, skips placeholder templates, and verifies representative invalid fixtures fail.
+
+## Editor Usage
+
+Use this schema in editors or external validation tools by pointing them at:
+
+```txt
+docs/schema/slice.schema.json
+```
+
+The schema rejects unsafe path values such as absolute paths, `file:` URLs, drive-root paths, and `..` traversal segments.