Roadmap, tickets y axon

Implementado. La vista viva del roadmap y de las decisiones es la sección generada roadmap y decisiones. Esta página explica cómo se trabaja con ellas, no las repite.

Una autoridad únicaCopiar enlace

styx.model.yml es la autoridad única del roadmap técnico: nodos, tipo, zona, dependencias, gates por item y referencias a decisiones. Todo lo demás se deriva o se archiva:

Si cualquier documento derivado discrepa con el model, gana el model. Y ningún CLAUDE.md congela estado de gates, colas de tickets o hashes: se leen de estas fuentes.

NodosCopiar enlace

Tres tipos: outcome (hitos globales), track (líneas de trabajo) y spike (experimentos). El id es tipo/slug y el prefijo es el tipo. Un track declara una zona (dataplane, client, services, interop o cross); un outcome no; un spike puede. Los hitos van anidados dentro de su nodo (track/byte-runtime/m4) y heredan la zona. phase es una clase prohibida.

Cada nodo tiene su espejo de artefactos en docs/<id>/ (tickets/, plans/, evidence/): la ruta es el id.

GatesCopiar enlace

Un gate es una lista de items, cada uno con su veredicto (pass, partial u open) y su clase. Reglas:

• El veredicto es por item. No existe un contador agregado.
• Un gate con items no abiertos es una proyección de un manifiesto de evidencia (gate.manifest.yml): el veredicto del model se copia de él y no al revés.
• Cada item no abierto lleva un comando ya ejecutado, su salida, un autor y un verificador distintos.
• La clase de cada item está congelada en un baseline para que no se reclasifique en silencio.

Las guardas que lo imponen están en guardas. Cómo se verifica de verdad un item está en evidencia adversarial.

Antes y después de tocar el roadmapCopiar enlace

bun run check:roadmap     # antes
# editar styx.model.yml / gates / manifiestos
axon gen --model styx.model.yml --out .   # regenerar ROADMAP.md
bun run check:roadmap     # después

No se inventan fases en silencio ni se ponen fechas o estimaciones sin acuerdo explícito del propietario del proyecto. El roadmap dice qué se construye y qué gates lo validan; la experiencia que emerge es otra cosa y está en el horizonte de producto.

Flujo de trabajoCopiar enlace

El proyecto está orquestado por axon. El flujo canónico es:

/planning-roadmap  →  @task-decomposer <ticket>  →  @task-executor <plan>

1. Planificar: elegir qué nodo y qué items del gate se persiguen.
2. Descomponer: el descomponedor convierte un ticket en un plan, y marca dónde un atajo sería tentador y prescribe el arreglo limpio o una parada.
3. Ejecutar: el ejecutor implementa el plan siguiendo la disciplina de abajo.
4. Verificar: otra persona o agente, distinto de quien implementó, comprueba contra el camino de producción.

Las zonas (.axon/zones.yml) reparten el trabajo en paralelo: cada zona tiene un directorio ancla, su CLAUDE.md y sus patrones de ficheros. Una sesión por zona carga sólo su contexto y su porción del roadmap (bun run axon:now); los nodos cross aparecen en todas y se coordinan desde la raíz. Hay agentes especialistas por frontera (data plane, servicios, cliente).

Disciplina del ejecutorCopiar enlace

Quien implementa:

1. No pone parches. Si la solución limpia exige tocar una abstracción o un contrato, la toca: se rompe limpio, se borra en vez de marcar como obsoleto, y no hay capas de compatibilidad.
2. Señala los fallos de arquitectura con un formato estructurado: síntoma, contrato o capa rota (con fichero y línea), arreglo limpio, por qué no un parche y gravedad.
3. Se detiene si es grave: si el arreglo limpio contradice una decisión bloqueada o excede el alcance, se para y se escala, sin «dejarlo verde» con un atajo.

Tripwires que obligan a parar: autoregistrar bajo un identificador mágico para saltar una carrera, un indicador que desactiva una validación, copiar datos para evitar un ownership roto, un catch que se traga el error, un predicado fijo que neutraliza una capa, o un comentario «de momento» sin ticket. Y una regla más: un comentario largo que explica por qué un parche está bien así indica que el código es malo; se borra el comentario y se arregla el código.

Diferir no está prohibido, ocultar sí: un aplazamiento legítimo está documentado, tiene ticket y no deja el contrato roto en el camino que el hito declara cerrado.

DecisionesCopiar enlace

Una decisión nueva se redacta como ADR en docs/decisions/ con estado propuesto; sólo el propietario del proyecto la bloquea, tras una pregunta explícita. La investigación informa las decisiones, no las sustituye. Cómo se documenta lo fija un ADR aún propuesto; su estado está en la vista de track/docs.