create-quiver 0.15.3 → 0.16.0

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á:
@@ -71,10 +78,29 @@ Qué cambia:
 |---|---|
 | Probar Quiver rápidamente | `npx --yes create-quiver@latest` |
 | Inicializar un proyecto nuevo | `npx --yes create-quiver@latest init --name "Mi Proyecto"` |
+| Inicializar docs en espanol | `npx --yes create-quiver@latest --lang es init --name "Mi Proyecto"` |
 | Usar siempre la última versión publicada | `npx --yes create-quiver@latest` |
 | Fijar una versión para el equipo | `npm install --save-dev create-quiver` |
 | Evitar dependencia local de workflow | Usar `npx` |
 
+## Idioma del proyecto
+
+Quiver puede generar documentacion humana inicial en `en` o `es`.
+
+Para una ejecucion puntual:
+
+```bash
+npx --yes create-quiver@latest --lang es init --name "Mi Proyecto"
+```
+
+Para guardar el idioma del proyecto y no repetir flags:
+
+```bash
+npx --yes create-quiver@latest config language set es
+```
+
+El idioma configurado afecta la salida humana y los docs humanos generados. No traduce JSON, JSONL, `package.json`, `slice.json`, comandos, flags, rutas, providers, modelos ni otros artefactos machine-readable.
+
 ## Qué no hace Quiver
 
 Quiver no se instala globalmente por defecto, no modifica credenciales de npm y no agrega una dependencia runtime a tu app salvo que lo pidas explícitamente con npm.

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 |
@@ -29,19 +102,86 @@ Más detalle: [Instalación y uso con npx](../getting-started/installation.md).
 | `npx --yes create-quiver@latest version` | Muestra un reporte de versión con banner Quiver, runtime, package manager y proyecto detectado. |
 | `npx --yes create-quiver@latest version --json` | Emite el reporte de versión como JSON parseable para automatización. |
 | `npx --yes create-quiver@latest --help` | Muestra los comandos soportados. |
+| `npx --yes create-quiver@latest config language show` | Muestra el idioma efectivo y su fuente de configuración. |
+| `npx --yes create-quiver@latest config language show --json` | Emite el idioma efectivo como JSON estable. |
+| `npx --yes create-quiver@latest config language set es` | Guarda `es` como idioma del proyecto en `.quiver/config.json`. |
+| `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 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 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 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:
+
+1. `--lang en|es`
+2. variable de entorno `QUIVER_LANG`
+3. `.quiver/config.json`
+4. `~/.quiver/config.json`
+5. locale del entorno
+6. `en`
+
+Ejemplos:
+
+```bash
+npx --yes create-quiver@latest --lang es dashboard
+QUIVER_LANG=es npx --yes create-quiver@latest flow
+npx --yes create-quiver@latest config language set es
+npx --yes create-quiver@latest config language set en --global
+```
+
+`--json` conserva claves y estructura machine-readable en ingles tecnico; no traduce campos, codigos, comandos, flags, rutas, ids, providers ni modelos.
+
+## Nota de release i18n
+
+La superficie documentada del CLI soporta salida humana en `en` y `es` para comandos de inicializacion, configuracion, lectura de estado, dashboard, workflow de specs/slices, comandos IA, gates y PR. El idioma configurado al ejecutar `config language set es|en` se reutiliza en ejecuciones posteriores sin repetir flags; `--lang` y `QUIVER_LANG` siguen disponibles como overrides puntuales.
+
+La garantia de compatibilidad aplica a la salida humana. JSON/JSONL, nombres de campos, codigos, comandos, flags, rutas, ids, providers, modelos y snippets copiables se mantienen estables para automatizacion.
+
+## Idioma de docs generados
+
+El idioma configurado tambien aplica a documentacion humana generada por Quiver, como los docs creados por `init`.
+
+Ejemplos:
+
+```bash
+npx --yes create-quiver@latest --lang es init --name "Proyecto"
+npx --yes create-quiver@latest config language set es
+npx --yes create-quiver@latest init --name "Proyecto"
+```
+
+Reglas:
+
+- `--lang en|es` puede usarse como override para una ejecucion.
+- `.quiver/config.json` se usa como idioma por defecto del proyecto cuando no se pasa `--lang`.
+- Templates humanos Markdown pueden tener variantes localizadas, por ejemplo `docs/INDEX.md.es.template`.
+- Si falta una variante localizada, Quiver hace fallback explicito al template base en `en`.
+- Artefactos machine-readable como `package.template.json`, `slice.json`, JSON/JSONL, ids, comandos, flags, rutas, providers y modelos no se traducen.
+
 ## Planificación con IA
 
 | Comando | Para qué sirve |
@@ -85,10 +225,16 @@ Más detalle: [Instalación y uso con npx](../getting-started/installation.md).
 | `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. |
@@ -104,6 +250,8 @@ Más detalle: [Instalación y uso con npx](../getting-started/installation.md).
 | `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 |
@@ -116,8 +264,10 @@ Más detalle: [Instalación y uso con npx](../getting-started/installation.md).
 | `--methodology wdd-sdd` | Declara la metodología soportada por comandos interactivos o automatizados. |
 | `--no-color` | Desactiva colores ANSI en salida humana. |
 | `--json` | Emite salida machine-readable en comandos que lo soportan, incluyendo `dashboard` y `version`. |
+| `--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. |
@@ -127,6 +277,8 @@ Más detalle: [Instalación y uso con npx](../getting-started/installation.md).
 | `--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.

package/docs/schema/slice.schema.json

@@ -0,0 +1,221 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://quiver.dev/schemas/slice.schema.json",
+  "title": "Quiver slice.json",
+  "description": "Schema for executable Quiver slice contracts. It is derived from current runtime validation in src/create-quiver/commands/spec.js, src/create-quiver/lib/slice.js, src/create-quiver/lib/readiness.js, and generated slice output in src/create-quiver/lib/ai/spec-generator.js.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "slice_id",
+    "ticket",
+    "type",
+    "title",
+    "objective",
+    "description",
+    "git",
+    "must",
+    "not_included",
+    "acceptance",
+    "files",
+    "tests",
+    "estimated_hours",
+    "status"
+  ],
+  "properties": {
+    "slice_id": {
+      "type": "string",
+      "pattern": "^slice-[A-Za-z0-9][A-Za-z0-9._-]*$",
+      "description": "Directory-local slice id. Runtime spec validation also requires this value to match the parent slice directory name."
+    },
+    "ticket": {
+      "$ref": "#/definitions/nonEmptyString"
+    },
+    "type": {
+      "$ref": "#/definitions/nonEmptyString"
+    },
+    "title": {
+      "$ref": "#/definitions/nonEmptyString"
+    },
+    "objective": {
+      "$ref": "#/definitions/nonEmptyString"
+    },
+    "description": {
+      "$ref": "#/definitions/nonEmptyString"
+    },
+    "git": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "branch_type",
+        "base_branch",
+        "branch_slug",
+        "branch_name"
+      ],
+      "properties": {
+        "branch_type": {
+          "$ref": "#/definitions/gitRefPart",
+          "description": "Current slice start runtime supports feature, bugfix, and hotfix; historical slices may use other non-empty types."
+        },
+        "base_branch": {
+          "$ref": "#/definitions/gitRefPart"
+        },
+        "branch_slug": {
+          "$ref": "#/definitions/gitRefPart"
+        },
+        "branch_name": {
+          "$ref": "#/definitions/gitRef"
+        }
+      }
+    },
+    "ui_scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "routes": {
+          "$ref": "#/definitions/stringList"
+        },
+        "components": {
+          "$ref": "#/definitions/stringList"
+        },
+        "layouts": {
+          "$ref": "#/definitions/stringList"
+        }
+      }
+    },
+    "must": {
+      "$ref": "#/definitions/stringList"
+    },
+    "not_included": {
+      "$ref": "#/definitions/stringList"
+    },
+    "acceptance": {
+      "$ref": "#/definitions/stringList"
+    },
+    "files": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/pathList"
+        },
+        {
+          "type": "array",
+          "minItems": 1
+        }
+      ],
+      "description": "Legacy and still-required write scope. Current check-slice local validation requires this array to exist."
+    },
+    "expected_read_paths": {
+      "$ref": "#/definitions/pathList"
+    },
+    "allowed_write_paths": {
+      "$ref": "#/definitions/pathList",
+      "description": "Preferred write scope for graph and executor tooling. When present and non-empty, runtime scope logic prefers this over files."
+    },
+    "tests": {
+      "$ref": "#/definitions/stringList"
+    },
+    "documentation": {
+      "$ref": "#/definitions/pathList"
+    },
+    "dependencies": {
+      "$ref": "#/definitions/stringList",
+      "description": "Legacy dependency field used by older slice graph input."
+    },
+    "depends_on": {
+      "$ref": "#/definitions/stringList",
+      "description": "Preferred dependency field. Runtime graph validation normalizes bare slice ids and full spec/slice refs."
+    },
+    "parallel_safe": {
+      "type": "string",
+      "enum": [
+        "after_dependencies",
+        "conditional",
+        "maybe",
+        "never",
+        "no",
+        "yes"
+      ]
+    },
+    "parallel_safe_reason": {
+      "$ref": "#/definitions/nonEmptyString"
+    },
+    "validation_hints": {
+      "$ref": "#/definitions/stringList"
+    },
+    "assumptions": {
+      "$ref": "#/definitions/stringList"
+    },
+    "estimated_hours": {
+      "type": "number",
+      "minimum": 0
+    },
+    "actual_hours": {
+      "type": [
+        "number",
+        "null"
+      ],
+      "minimum": 0
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "blocked",
+        "cancelled",
+        "completed",
+        "draft",
+        "planned",
+        "ready"
+      ]
+    },
+    "blocked_reason": {
+      "$ref": "#/definitions/nullableString"
+    },
+    "ready_at": {
+      "$ref": "#/definitions/nullableString"
+    },
+    "started_at": {
+      "$ref": "#/definitions/nullableString"
+    },
+    "completed_at": {
+      "$ref": "#/definitions/nullableString"
+    }
+  },
+  "definitions": {
+    "nonEmptyString": {
+      "type": "string",
+      "pattern": "\\S"
+    },
+    "nullableString": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "stringList": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/nonEmptyString"
+      },
+      "uniqueItems": true
+    },
+    "projectRelativePath": {
+      "type": "string",
+      "pattern": "^(?!file:)(?!/)(?![A-Za-z]:[\\\\/])(?!.*(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)).*\\S.*$",
+      "description": "Project-relative path without file URLs, absolute paths, drive roots, or traversal segments. Runtime normalizes Windows separators to POSIX."
+    },
+    "pathList": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/projectRelativePath"
+      },
+      "uniqueItems": true
+    },
+    "gitRefPart": {
+      "type": "string",
+      "pattern": "^(?!/)(?!.*\\.\\.)(?!.*\\\\)(?!.*//)(?!.*\\/$)[A-Za-z0-9._/-]+$"
+    },
+    "gitRef": {
+      "type": "string",
+      "pattern": "^(?!/)(?!.*\\.\\.)(?!.*\\\\)(?!.*//)(?!.*\\/$)[A-Za-z0-9._/-]+$"
+    }
+  }
+}

package/docs/specs/01-spec/01-slice/01-slice.json

@@ -0,0 +1,36 @@
+{
+  "slice_id": "01-slice",
+  "slice_number": "01",
+  "title": "Snapshot verificable de ramas",
+  "objective": "Crear un inventario auditable de ramas locales y remotas con base, SHA, fecha, ahead/behind, frescura del dato y clasificacion inicial.",
+  "problem": "Evita tomar decisiones sobre ramas usando informacion incompleta, stale o ambigua.",
+  "value_outcome": "Reporte de ramas que permite decidir que revisar, extraer, cerrar o conservar sin modificar el repo.",
+  "scope": {
+    "includes": ["Analisis read-only de refs", "Clasificacion documental", "Registro de frescura del snapshot"],
+    "excludes": ["Fetch sin aprobacion", "Merge", "Rebase", "Push", "Eliminacion de ramas", "Implementacion de codigo"]
+  },
+  "actors": ["Tech Lead", "Maintainer", "Reviewer", "Implementador futuro"],
+  "preconditions": ["Repositorio Git disponible", "Refs locales/remotos presentes en snapshot local"],
+  "inputs": ["Refs de Git", "origin/HEAD", "origin/main", "Logs", "Metadatos de commits"],
+  "outputs": ["Inventario de ramas", "Clasificacion inicial", "Riesgos por rama"],
+  "workflow": [
+    {"step": 1, "name": "Detectar base", "description": "Detectar rama base desde origin/HEAD o convenciones conocidas."},
+    {"step": 2, "name": "Listar refs", "description": "Listar ramas locales y remotas."},
+    {"step": 3, "name": "Calcular metadata", "description": "Calcular SHA, fecha, ahead/behind y merge-base."},
+    {"step": 4, "name": "Clasificar", "description": "Asignar estado no destructivo a cada rama."}
+  ],
+  "business_rules": ["ahead=0 no autoriza eliminacion", "main local divergida no es base segura", "Toda eliminacion requiere aprobacion"],
+  "validations": ["Cada rama tiene SHA", "Cada rama tiene fecha", "Local/remota diferenciado", "Frescura registrada"],
+  "error_cases": ["Sin origin/HEAD", "Sin merge-base", "Refs remotos stale"],
+  "acceptance_criteria": ["Todas las ramas abiertas aparecen", "Ninguna rama se marca eliminable sin aprobacion", "Se registra fecha y SHA del snapshot", "ahead=0 queda como sin delta"],
+  "dependencies": {
+    "functional": [],
+    "technical": ["Git"],
+    "external": [],
+    "depends_on_slices": []
+  },
+  "implementation_order": 1,
+  "slicing_rationale": "Un snapshot confiable reduce riesgo antes de cualquier decision tecnica.",
+  "risks": ["Snapshot remoto stale"],
+  "open_questions": ["Se autorizara fetch antes de acciones finales?"]
+}