create-quiver 0.15.4 → 0.17.0

package/docs/reference/commands.md

@@ -21,6 +21,80 @@ 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 analyze-project` | Read and explain a bounded project sample without provider execution or writes. |
+| 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 +109,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:
@@ -96,8 +185,32 @@ Reglas:
 
 ## Planificación con IA
 
+### Análisis profundo de proyecto existente
+
+`ai analyze-project` transforma una muestra acotada del repo en contexto operativo para IA. El modo seguro es read-only:
+
+```bash
+npx --yes create-quiver@latest ai analyze-project --deep --dry-run
+npx --yes create-quiver@latest ai analyze-project --deep --dry-run --json
+```
+
+En `--dry-run`, Quiver no escribe archivos, no ejecuta proveedor y muestra qué seleccionó u omitió y por qué. Siempre excluye secretos, `.env`, `.git`, `.quiver`, dependencias, caches, binarios y outputs generados.
+
+Para generar docs desde IA:
+
+```bash
+npx --yes create-quiver@latest ai analyze-project --deep --review
+npx --yes create-quiver@latest ai analyze-project --deep --review --strict
+```
+
+El modo con proveedor exige JSON validado por schema, evidencia por conclusión, niveles `confirmed`, `inferred`, `unknown` o `conflict`, revisión editable, diff final, confirmación humana, snapshot previo en `.quiver/runs`, artefactos redactados y validación post-write. `--strict` convierte conflictos importantes de docs en error. El resultado puede quedar como `unknown` o `needs_confirmation` cuando el código no prueba una conclusión.
+
 | Comando | Para qué sirve |
 |---|---|
+| `npx --yes create-quiver@latest ai analyze-project --deep --dry-run` | Previsualiza descubrimiento y muestreo del repo sin escribir ni ejecutar proveedor. |
+| `npx --yes create-quiver@latest ai analyze-project --deep --dry-run --json` | Emite el plan de análisis como JSON parseable para automatización. |
+| `npx --yes create-quiver@latest ai analyze-project --deep --review` | Ejecuta proveedor, valida análisis JSON con evidencia, abre revisión humana y escribe solo docs permitidos tras confirmación. |
+| `npx --yes create-quiver@latest ai analyze-project --scope apps/web --max-files 80 --max-bytes 300000 --include-tests --dry-run` | Acota el análisis por workspace/ruta y presupuesto de muestra. |
 | `npx --yes create-quiver@latest ai prepare-context --dry-run` | Previsualiza actualizaciones documentales de contexto para IA. |
 | `npx --yes create-quiver@latest ai prepare-context` | Escribe actualizaciones documentales de contexto para IA. |
 | `npx --yes create-quiver@latest ai prepare-context --with-planner --dry-run` | Previsualiza una propuesta docs-only generada por el planner sin escribir archivos. |
@@ -137,10 +250,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,12 +275,22 @@ 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 |
 |---|---|
 | `--dry-run` | Previsualiza sin escribir archivos ni ejecutar proveedores. |
 | `--print-prompt` | Imprime el prompt del proveedor sin ejecutarlo. |
+| `--deep` | En `ai analyze-project`, incluye fuente y DB en la muestra representativa. |
+| `--max-files <n>` | En `ai analyze-project`, limita la cantidad de archivos seleccionados. |
+| `--max-bytes <n>` | En `ai analyze-project`, limita los bytes seleccionados para la muestra. |
+| `--include-source` | En `ai analyze-project`, incluye código fuente sin requerir `--deep`. |
+| `--include-tests` | En `ai analyze-project`, incluye tests en la muestra. |
+| `--include-db` | En `ai analyze-project`, incluye schemas, migraciones y archivos DB. |
+| `--scope <path\|name>` | En `ai analyze-project`, restringe el análisis a una ruta o workspace. |
+| `--strict` | En validaciones soportadas, convierte conflictos importantes en errores. |
 | `--with-planner` | Activa comportamiento asistido por planner solo en comandos que lo soportan. |
 | `--interactive` | Habilita prompts humanos de confirmación o elección. |
 | `--review` | Abre o prepara revisión humana antes de escrituras persistentes. |
@@ -171,7 +300,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,10 +310,13 @@ 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` |
 |---|---:|---:|---:|
+| `ai analyze-project` | no | no | sí |
 | `ai prepare-context` | sí | sí | sí |
 | `ai plan` | sí | sí | sí |
 | `spec create` | sí | sí | sí |

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

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

@@ -0,0 +1,106 @@
+# 01-slice - Snapshot verificable de ramas
+
+## 1. Nombre del slice
+
+Snapshot verificable de ramas.
+
+## 2. Objetivo del slice
+
+Crear un inventario auditable de ramas locales y remotas con base, SHA, fecha, ahead/behind, frescura del dato y clasificacion inicial.
+
+## 3. Problema puntual que resuelve
+
+Evita tomar decisiones sobre ramas usando informacion incompleta, stale o ambigua.
+
+## 4. Valor observable que entrega
+
+Un reporte de ramas que permite decidir que revisar, extraer, cerrar o conservar sin modificar el repo.
+
+## 5. Alcance especifico
+
+Incluye analisis read-only de refs y clasificacion documental. No ejecuta acciones destructivas.
+
+## 6. Que incluye
+
+- Rama base probable.
+- SHA de base y de cada rama.
+- Fecha de ultimo commit.
+- Autor principal.
+- Ahead/behind.
+- Tipo local/remota.
+- Frescura del snapshot.
+- Clasificacion inicial.
+
+## 7. Que no incluye
+
+- Fetch sin aprobacion.
+- Merge, rebase, push o delete.
+- Implementacion de codigo.
+- Limpieza de ramas.
+
+## 8. Actores involucrados
+
+Tech Lead, maintainer, reviewer e implementador futuro.
+
+## 9. Precondiciones
+
+Repositorio Git disponible y refs locales/remotos presentes en el snapshot local.
+
+## 10. Entradas necesarias
+
+Refs de Git, `origin/HEAD`, `origin/main`, logs y metadatos de commits.
+
+## 11. Flujo operativo paso a paso
+
+1. Detectar rama base desde `origin/HEAD` o convenciones conocidas.
+2. Listar refs locales y remotos.
+3. Calcular SHA, fecha, ahead/behind y merge-base.
+4. Identificar si el dato remoto requiere verificacion de frescura.
+5. Clasificar cada rama con estado no destructivo.
+6. Registrar riesgos y dudas por rama.
+
+## 12. Salidas esperadas
+
+Inventario de ramas con clasificacion y evidencia suficiente para planificar slices posteriores.
+
+## 13. Reglas de negocio aplicables
+
+- `ahead=0` significa sin delta pendiente, no eliminable automaticamente.
+- `main` local divergida no es base segura.
+- Toda recomendacion de eliminacion queda pendiente de aprobacion.
+
+## 14. Validaciones
+
+- Cada rama tiene SHA, fecha y base probable.
+- Cada rama local/remota esta diferenciada.
+- Cada estado de limpieza distingue cerrable, eliminable, protegida e historica.
+
+## 15. Manejo de errores o edge cases
+
+- Si no hay `origin/HEAD`, usar candidato documentado y marcar supuesto.
+- Si una rama no tiene merge-base, marcar `requiere revision manual`.
+- Si refs remotos estan stale, marcar `requiere verificacion remota`.
+
+## 16. Criterios de aceptacion
+
+- Todas las ramas abiertas aparecen en el inventario.
+- Ninguna rama se clasifica como eliminable sin condicion de aprobacion.
+- El reporte incluye fecha y SHA del snapshot.
+- Las ramas con `ahead=0` quedan como `sin delta`, no como borrables.
+- Las ramas conflictivas quedan marcadas para analisis posterior.
+
+## 17. Dependencias tecnicas, funcionales o externas
+
+Git local y refs existentes.
+
+## 18. Depende de slices
+
+Ninguno.
+
+## 19. Riesgos / decisiones abiertas
+
+El snapshot puede quedar obsoleto si no se actualizan refs remotos.
+
+## 20. Pendientes / preguntas abiertas
+
+Definir si se autorizara `fetch` antes de tomar decisiones remotas finales.