serhii-nochevnyi/shipyard

Regras da esteira de entrega

Este projeto executa uma esteira de entrega por ticket sobre o GSD (veja docs/gsd_multilevel_delivery_pipeline.md). Os planos funcionam como tickets; estas regras os mantêm consumíveis pela camada determinística da esteira.

Idioma. Todos os artefatos — planos, frontmatter, commits, código, corpos de PR — são escritos em inglês. Ao se dirigir diretamente ao usuário, responda no idioma do usuário; o inglês é para os artefatos, o idioma do usuário é para conversa.

Para planejadores (escrevendo PLAN.md)

1. Frontmatter completo, sempre: phase, plan, title, type, wave, depends_on: [], files_modified: [], requirements: []. requirements vazio é um BLOQUEADOR — tanto o verificador de planos do GSD quanto o Portão 2 (validate-graph) o rejeitam; referencie IDs de requisitos do ROADMAP, ou o ID do rastreador externo quando o plano foi importado. wave é documentação para o leitor humano: o grafo é autoritativo e o validador recalcula a profundidade real de dependência, avisando quando seu valor discorda. Mantenha-o verdadeiro em vez de decorativo.

2. Bloco de entrega (aditivo, nunca substitui campos do GSD):

   delivery:
     ticket: T-<phase>-<plan>
     risk: low|medium|high        # high REQUER human_checkpoint: true
     human_checkpoint: false
     repo: owner/name             # SOMENTE quando o trabalho vive em outro repositório
   

   repo é obrigatório para qualquer ticket que não modifique este repositório. Omita-o e a esteira rastreará o ticket contra o repositório errado: seu PR pode ficar verde e ser mesclado ao lado enquanto o quadro mostra pending para sempre, e cada dependente permanece bloqueado atrás de um ticket que nunca se moverá. Caminhos em files_modified são então relativos AQUELE repositório — nunca ../other-repo/x.ts, que nenhum worktree pode alcançar (Portão 2 avisa, state-sync estaciona o ticket). Dependências entre repositórios não se cascateiam: o pai deve MESCLAR primeiro, então fatie o lado do contrato (tipos/nomes de ferramentas) em seu próprio ticket em vez de fazer o consumidor esperar por uma funcionalidade completa.

3. Não invente nomes de branch. O branch canônico é ticket/<ID>-<slug> onde o slug é o título do ticket sanitizado (minúsculo, transliterado, não alfanuméricos colapsados para um único hífen, ≤40 caracteres). Omita delivery.branch — o validador do grafo o gera; um valor explícito é validado pela mesma regra.

4. files_modified é um contrato, não um palpite — liste cada caminho que o plano toca. Um files_modified VAZIO falha no Portão 2 (é o que torna verificável "tickets sem ordenação de dependência nunca colidem", e é o escopo do executor). Planos sem ordenação de dependência com caminhos sobrepostos também falham no Portão 2; resolva com uma dependência ou um novo fatiamento, nunca alargando globs (um glob qualquer que corresponda a tudo é sinalizado).

5. Nomeie o que já faz isso, antes de planejar escrever. Toda leitura de Contexto do plano deve apontar para a implementação existente que o ticket estende (path:line — o transformador, ordenador, middleware, helper, endpoint no qual ele se baseia), ou registrar a verificação que não encontrou nenhuma: qual comportamento você pesquisou e os dois ou três locais plausíveis em que olhou. Pesquise por COMPORTAMENTO, não pelo nome que você pretende dar ao novo código — um duplicado quase sempre já é chamado de outra coisa, que é exatamente o motivo pelo qual sobrevive à revisão. "Eu não vi nenhum" não é a mesma afirmação que "Eu olhei"; apenas a segunda é um plano em que um leitor pode confiar. Este é o portão mais barato na esteira: um duplicado despercebido é encontrado pelo integrador uma fase inteira depois, depois que outros tickets já construíram sobre ele, e aí removê-lo é seu próprio ticket. Diferente do §4, isso não pode ser verificado por máquina a partir do frontmatter — o Portão 2 nunca vê isso, o drift-check apenas suporta os tickets que reavalia, então escrever isso é o controle.

6. Comandos de verificação são limitados ao ticket, não ao projeto. Escreva os comandos mais estreitos que realmente cobrem files_modified — os arquivos de teste ou filtros específicos, o typecheck e lint sobre os caminhos tocados. Um npm test / make test / toda a suíte e2e NÃO é um comando de verificação aqui: ele pertence ao CI, que o executa uma vez por push em hardware projetado para isso. O executor executa estes em CADA tentativa e as funções de correção os reexecutam em cada rodada, então um comando sem escopo não é lento uma vez — é a taxa de tick de toda a esteira, multiplicada por cada ticket executando em paralelo em seu próprio worktree. Duas propriedades tornam um comando utilizável: ele deve ser executado em um worktree limpo sem serviços externos, e deve falhar pelos erros DESTE ticket. Um comando que não pode ser limitado (uma suíte que precisa de um banco de dados ativo, um navegador, um ambiente implantado) é uma verificação apenas de CI — diga isso sob a Estratégia de teste e deixe-o de fora dos comandos de Verificação em vez de entregar ao executor algo que ele não pode executar.

7. depends_on direciona a cascata, não apenas a ordenação. Sob entrega empilhada por épico (o padrão), um ticket raiz (depends_on vazio) faz PR para o branch do épico da fase; um ticket dependente se cascateia — ele faz PR para o branch de seu pai primário SEM esperar por uma mesclagem, então o fluxo nunca bloqueia. Declare dependências com precisão: uma dependência espúria serializa o fluxo, uma ausente entrega ao executor uma base incompleta. O validador deriva o épico (epic/<phase-dir>), o pai primário e pr_base; múltiplos pais na mesma fase (um diamante) recebem um aviso — linearize quando prático. Mantenha as dependências dentro de uma fase. Uma dependência entre fases não pode se cascatear — não há branch compartilhado para empilhar — então o ticket dependente permanece bloqueado até que toda a fase do pai tenha aterrissado no branch padrão. O validador avisa sobre cada uma delas; refatie em vez disso.

8. Os IDs são canônicos: T-<2 dígitos da fase>-<2 dígitos do plano>. Escreva T-01-02, nunca T-1-2 — o validador normaliza ambos, mas branches, títulos de PR e rótulos do Jira são comparados por string em todos os outros lugares.

9. Sem comentários # ao final de um valor. Coloque um comentário em sua própria linha. files_modified: [a.ts] # nota costumava dobrar o comentário no último caminho; o analisador agora o remove corretamente, mas o Portão 2 ainda rejeita qualquer valor que contenha # porque isso é quase sempre um vazamento.

10. O Portão 2 é mecânico: ele passa somente quando o validador do grafo sai com 0. Problemas do Jira/GitHub, ROLLOUT.md ou resumos em prosa nunca são um substituto para arquivos PLAN materializados.

11. Jira é uma projeção, não a fonte da verdade. Por padrão (a menos que pipeline.jira.enabled: false ou nenhum MCP do Jira esteja conectado) a decomposição exporta o grafo validado para o Jira (um Épico por fase, um problema por ticket) em inglês, após o Portão 2 — nunca antes, nunca em vez. O projeto é resolvido e armazenado em cache automaticamente; uma falha do Jira não deve bloquear a decomposição; os arquivos PLAN permanecem canônicos.

Para executores (implementando um ticket)

1. Fique dentro de files_modified. Alterações fora do escopo pertencem a outro ticket — escale em vez de expandir o escopo silenciosamente.
2. Leia a implementação existente antes de escrever uma nova. O que quer que o plano tenha nomeado sob o §5, mais quaisquer reuse_candidates que a esteira tenha passado a você do drift-check: leia cada um primeiro e estenda-o em vez de adicionar uma camada paralela ao lado dele. Se um candidato genuinamente não se encaixa, diga o porquê em sua evidência — esse é um resultado legítimo; ignorá-lo silenciosamente não é. Reuso nunca autoriza a deixar files_modified: se construir sobre ele o levaria para fora do escopo, isso é uma escalada fora do escopo (§1), não um diff maior.
3. Commits atômicos prefixados com o id do ticket: feat(T-01-02): ….
4. Execute os comandos de Verificação do plano localmente até ficarem verdes antes de declarar concluído; nunca reivindique verificação sem saída de comando. Execute esses comandos — não "seja minucioso" alargando-os para toda a suíte (§6): o CI é dono da execução completa, e uma suíte que você iniciou aqui bloqueia seu próprio worktree e todos os outros executores que compartilham a máquina. Se os comandos do plano estão quebrados ou claramente não cobrem a alteração, corrija ou restrinja-os no plano e diga isso em sua evidência; substituir silenciosamente por npm test não é uma correção.
5. Worktree e branch vêm da esteira (tickets.json) — não crie branches ou worktrees ad hoc. Sua base de PR também é resolvida por a esteira (delivery-state.json → base: o branch do épico para um ticket raiz, o branch do pai para um ticket dependente) — nunca abra um PR direto para main/master sob entrega empilhada por épico.
6. Pare no commit. Não faça push, não abra o pull request, não mexa nos revisores. O orquestrador verifica o worktree mecanicamente (git log <base>..HEAD) antes de publicar qualquer coisa — essa verificação é o que pega "o agente reportou sucesso e não mudou nada", e só funciona se a publicação não estiver nas mãos do agente que está sendo verificado. Devolva sua evidência de verificação e um corpo de PR.