# Roadmap

El roadmap contiene el horizonte de intención del proyecto: resultados grandes, observables y todavía no
convertidos por completo en trabajo inmediato. El frontmatter de cada épica es la fuente de verdad y `ops tree`
es su índice derivado; no se mantiene una tabla manual paralela.

## Ciclo de vida

```text
roadmap (open) → BACKLOG (active) → DONE → done/epic-NNN.md (closed)
```

- `open`: candidata editable que aún no fue promovida al backlog.
- `active`: sus historias están en ejecución o pendientes dentro del backlog.
- `closed`: todas sus historias tienen evidencia verificable y la épica puede archivarse.

La prioridad predeterminada es el número ascendente entre las épicas `open`. Cualquier excepción debe quedar
como una decisión explícita, no como una segunda lista de prioridad escondida en este README.

## Autoridad y curación

Una persona crea, divide, reordena o descarta épicas. Los runners pueden consumirlas y cambiar su estado durante
el ciclo acordado, pero no inventan objetivos de producto. Las propuestas provenientes de una integración o del
INBOX requieren promoción humana.

Antes de promover una épica se verifican en el repositorio las rutas, capacidades y datos que sus criterios
suponen. Promover es `node tools/ops.js promote planning epic-NNN-slug`: escribe un `backlog/<hito>.md` por
cada hito de `## Hitos` —o uno solo, con el slug de la épica, si no los declara— con sus historias como
tareas, y pasa la épica a `active`. Se niega, sin escribir nada, con un marcador sin resolver, un reparto
que `check` rechaza o un hito que ya existe. Los resultados, reglas y criterios describen el qué; el cómo ejecutable se decide al planificar cada
historia y no se congela prematuramente en la especificación.

## Formas admitidas

Una épica pequeña usa un único archivo:

```text
epic-NNN-slug.md
```

Una épica cuyo contexto ya no sea legible en un archivo puede graduarse a carpeta:

```text
epic-NNN-slug/
├── spec.md       # obligatorio: contrato del resultado
├── research.md   # opcional: fuentes, evidencia y supuestos
├── plan.md       # opcional: orientación provisional, no fuente de verdad
└── notes.md      # opcional: contexto complementario
```

Para graduarla, se mueve el contenido contractual a `spec.md` sin cambiar el número ni el slug. No se crean
archivos auxiliares vacíos ni se usa una carpeta si la épica sigue siendo fácil de entender en un solo archivo.

## Número

Una épica nueva toma el siguiente al número más alto. Dos líneas de trabajo en paralelo pueden tomar el
mismo, porque ninguna ve la de la otra hasta traerla: git no choca —los archivos se llaman distinto— y
`check` lo marca. Se mueve la que todavía no llegó a la rama principal, con

```text
node tools/ops.js renumber-epic planning epic-NNN-slug <número libre>
```

que renombra el archivo o la carpeta, cambia el frontmatter y el encabezado, y reescribe el `(epic: NNN)`
de sus tareas y las rutas que la citan. Las tareas de la otra épica no se tocan.

## Contrato de una épica

- Frontmatter: `epic`, `title`, `status` y `service`.
- Resultado: cambio esperado para el usuario o sistema.
- Fuera de alcance: lo que se decidió no hacer, para que no entre solo.
- Criterios `CN`: disparador, sujeto y resultado observable. Los bordes —input vacío, permiso ajeno,
  dependencia caída— se escriben como criterios y no como prosa, porque sólo así se rastrean y se prueban.
- Contexto relevante: rutas existentes verificadas, patrones, y los ADR e invariantes de
  `../business-rules/` que rigen el resultado.
- Historias: incrementos de hasta cuatro horas, con slug, servicio y referencias `(→ CN)`.
- Hitos, optativa: cómo se reparten las historias al promover. Una viñeta por hito —`**slug** (line: nombre)
  — Título`, sin `(line: …)` si es del árbol principal— y, anidada, una viñeta por historia con su slug.
  Con la sección, `check` exige que cada historia esté en exactamente un hito y que la línea tenga nombre
  de línea. `flow` la propone entre las líneas que la instancia tiene; quien promueve la corrige o la
  deja.
- Riesgos y decisiones humanas: lo que no se puede decidir acá — supuestos, dependencias y acciones que
  un runner no puede resolver. Lo que sí se decidió y queda afuera va en Fuera de alcance.

Lo que todavía no se decidió se escribe con el marcador `Por definir`, en la sección que corresponda.
Una épica `open` puede llevarlos —es un borrador—; `check` los rechaza al pasar a `active`. Por eso la
plantilla no trae ninguno: lo que se copia no puede incluir algo que haya que borrar para poder
activar la épica.

Cada criterio debe estar cubierto por al menos una historia. Una historia puede cubrir varios criterios y todo
slug debe ser estable y único en el roadmap.