serhii-nochevnyi/shipyard

Reglas de la cinta transportadora de entrega

Este proyecto ejecuta una cinta transportadora de entrega por ticket sobre GSD (ver docs/gsd_multilevel_delivery_pipeline.md). Los planes sirven como tickets; estas reglas los mantienen consumibles por máquina a través de la capa determinista de la cinta transportadora.

Idioma. Todos los artefactos — planes, frontmatter, commits, código, cuerpos de PR — se redactan en inglés. Al dirigirse al usuario directamente, responda en el idioma del usuario; el inglés es para los artefactos, el idioma del usuario es para la conversación.

Para planificadores (escribiendo PLAN.md)

1. Frontmatter completo, siempre: phase, plan, title, type, wave, depends_on: [], files_modified: [], requirements: []. Un requirements vacío es un BLOQUEO — tanto el verificador de planes de GSD como la Compuerta 2 (validate-graph) lo rechazan; referencie los IDs de requisitos de ROADMAP, o el ID del rastreador externo cuando el plan fue importado. wave es documentación para el lector humano: el grafo es autoritativo y el validador recalcula la profundidad real de dependencia, advirtiendo cuando su valor discrepa. Manténgalo veraz en lugar de decorativo.

2. Bloque de entrega (aditivo, nunca reemplaza los campos de GSD):

   delivery:
     ticket: T-<fase>-<plan>
     risk: baja|media|alta        # alta REQUIERE human_checkpoint: true
     human_checkpoint: false
     repo: propietario/nombre     # SOLO cuando el trabajo reside en otro repositorio
   

   repo es obligatorio para cualquier ticket que no toque este repositorio. Omítalo y la cinta transportadora rastrea el ticket contra el repositorio incorrecto: su PR puede estar verde y fusionado al lado mientras el tablero dice pending para siempre, y cada dependiente permanece bloqueado detrás de un ticket que nunca se moverá. Las rutas en files_modified son entonces relativas a ESE repositorio — nunca ../other-repo/x.ts, que ningún worktree puede alcanzar (la Compuerta 2 advierte, state-sync estaciona el ticket). Las dependencias entre repositorios no se cascan: el padre debe fusionar PRIMERO, así que divida el lado del contrato (tipos/nombres de herramientas) en su propio ticket en lugar de hacer que el consumidor espere una función completa.

3. No invente nombres de rama. La rama canónica es ticket/<ID>-<slug> donde el slug es el título del ticket sanitizado (minúsculas, transliterado, no alfanumérico colapsado a guiones simples, ≤40 caracteres). Omita delivery.branch — el validador de grafo lo genera; un valor explícito se valida contra la misma regla.

4. files_modified es un contrato, no una adivinanza — enumere cada ruta que el plan toque. Un files_modified VACÍO falla la Compuerta 2 (es lo que hace que "los tickets sin orden de dependencia nunca colisionen" sea comprobable, y es el ámbito del ejecutor). Los planes sin orden de dependencia con rutas superpuestas también fallan la Compuerta 2; resuelva con una dependencia o un nuevo corte, nunca ampliando globs (un glob simple que coincida con todo se marca).

5. Nombra lo que ya hace esto, antes de planear escribirlo. Las lecturas de Contexto de cada plan deben apuntar a la implementación existente que el ticket extiende (ruta:línea — el transformador, clasificador, middleware, helper, endpoint sobre el que construye), o registrar la verificación que no encontró ninguna: qué comportamiento buscó y los dos o tres lugares plausibles donde miró. Busque por COMPORTAMIENTO, no por el nombre que pretende dar al nuevo código — un duplicado casi siempre se llama de otra manera, que es exactamente por qué sobrevive a la revisión. "No vi uno" no es la misma afirmación que "miré"; solo la segunda es un plan en el que un lector puede confiar. Esta es la compuerta más barata en la cinta transportadora: un duplicado inadvertido es encontrado por el integrador una fase completa después, cuando otros tickets ya han construido sobre él, y para entonces eliminarlo es su propio ticket. A diferencia de §4, esto no se puede verificar automáticamente desde el frontmatter — la Compuerta 2 nunca lo ve, drift-check solo respalda los tickets que vuelve a juzgar, así que escribirlo es el control.

6. Los comandos de verificación están limitados al ticket, no al proyecto. Escriba los comandos más específicos que realmente cubran files_modified — los archivos de prueba o filtros específicos, el typecheck y lint sobre las rutas tocadas. Un simple npm test / make test / toda la suite e2e NO es un comando de verificación aquí: pertenece a CI, que lo ejecuta una vez por push en hardware diseñado para ello. El ejecutor ejecuta estos en CADA intento y los roles de corrección los re-ejecutan en cada ronda, por lo que un comando sin ámbito no es lento una vez — es la frecuencia de tic de toda la cinta transportadora, multiplicada por cada ticket ejecutándose en paralelo en su propio worktree. Dos propiedades hacen que un comando sea utilizable: debe ejecutarse en un worktree simple sin servicios externos, y debe fallar por los errores de ESTE ticket. Un comando que no se puede limitar (una suite que necesita una base de datos activa, un navegador, un entorno desplegado) es una verificación solo de CI — dígalo bajo la estrategia de prueba y déjelo fuera de los comandos de verificación en lugar de entregar al ejecutor algo que no puede ejecutar.

7. depends_on impulsa la cascada, no solo el orden. Bajo la entrega apilada por épica (la predeterminada), un ticket raíz (con depends_on vacío) hace PR a la rama de la épica de fase; un ticket dependiente se casca — hace PR a la rama de su padre principal SIN esperar una fusión, por lo que el flujo nunca se bloquea. Declare las dependencias con precisión: una dependencia espuria serializa el flujo, una faltante entrega al ejecutor una base incompleta. El validador deriva la épica (epic/<directorio-de-fase>), el padre principal, y pr_base; múltiples padres de la misma fase (un diamante) obtienen una advertencia — linealice cuando sea práctico. Mantenga las dependencias dentro de una fase. Una dependencia entre fases no puede cascarse — no hay una rama compartida sobre la que apilar — por lo que el ticket dependiente permanece bloqueado hasta que toda la fase del padre haya aterrizado en la rama predeterminada. El validador advierte sobre cada una de ellas; vuelva a cortar en su lugar.

8. Los IDs son canónicos: T-<fase de 2 dígitos>-<plan de 2 dígitos>. Escriba T-01-02, nunca T-1-2 — el validador normaliza ambos, pero las ramas, los títulos de PR y las etiquetas de Jira se comparan como cadenas en todos los demás lugares.

9. Sin comentarios # al final de un valor. Ponga un comentario en su propia línea. files_modified: [a.ts] # nota solía plegar el comentario dentro de la última ruta; el analizador ahora lo elimina correctamente, pero la Compuerta 2 aún rechaza cualquier valor que contenga # porque casi siempre es una fuga.

10. La Compuerta 2 es mecánica: pasa solo cuando el validador de grafo sale con 0. Los problemas de Jira/GitHub, ROLLOUT.md o resúmenes en prosa nunca son un sustituto de archivos PLAN materializados.

11. Jira es una proyección, no la fuente de verdad. Por defecto (a menos que pipeline.jira.enabled: false o no haya un MCP de Jira conectado) decompose exporta el grafo validado a Jira (una Épica por fase, un issue por ticket) en inglés, después de la Compuerta 2 — nunca antes, nunca en su lugar. El proyecto se resuelve y almacena en caché automáticamente; un fallo de Jira no debe bloquear la descomposición; los archivos PLAN siguen siendo canónicos.

Para ejecutores (implementando un ticket)

1. Manténgase dentro de files_modified. Los cambios fuera del ámbito pertenecen a otro ticket — escale en lugar de expandir el ámbito en silencio.
2. Lea la implementación existente antes de escribir una nueva. Todo lo que el plan nombró bajo §5, más cualquier reuse_candidates que la cinta transportadora le haya entregado desde drift-check: lea cada uno primero y extiéndalo en lugar de agregar una capa paralela a su lado. Si un candidato realmente no encaja, diga por qué en su evidencia — ese es un resultado legítimo, ignorarlo en silencio no lo es. La reutilización nunca autoriza salirse de files_modified: si construir sobre él lo llevaría fuera del ámbito, eso es una escalada fuera de ámbito (§1), no un diff más amplio.
3. Commits atómicos con prefijo del id del ticket: feat(T-01-02): ….
4. Ejecute los comandos de verificación del plan localmente hasta que estén en verde antes de declarar terminado; nunca afirme verificación sin la salida del comando. Ejecute esos comandos — no "sea minucioso" ampliándolos a toda la suite (§6): CI posee la ejecución completa, y una suite que inició aquí bloquea su propio worktree y a todos los demás ejecutores que comparten la máquina. Si los comandos del plan están rotos o claramente no cubren el cambio, arréglelos o redúzcalos en el plan y dígalo en su evidencia; sustituir npm test en silencio no es una solución.
5. El worktree y la rama provienen de la cinta transportadora (tickets.json) — no cree ramas o worktrees ad hoc. La base de su PR también la resuelve la cinta transportadora (delivery-state.json → base: la rama de la épica para un ticket raíz, la rama del padre para un dependiente) — nunca abra un PR directamente en main/master bajo apilado de épicas.
6. Deténgase en el commit. No haga push, no abra la pull request, no toque a los revisores. El orquestador verifica el worktree mecánicamente (git log <base>..HEAD) antes de publicar cualquier cosa — esa verificación es lo que detecta "el agente reportó éxito y no cambió nada", y solo funciona si la publicación no está en manos del agente que se está verificando. Entregue su evidencia de verificación y un cuerpo de PR en su lugar.