Criar o esqueleto da CLI orq com store SQLite orq #3

[cedric-lamalle]

Story: https://agile.basis.com.br/project/orq/us/3

O que entra

• CLI orq (Go, cobra) com o estado da Central de US num SQLite (modernc.org/sqlite, sem cgo, WAL, busy_timeout de 15 s, escrita sempre em BEGIN IMMEDIATE). Banco em $ORQ_STATE_DIR/central.db, padrão $XDG_STATE_HOME/orq/ ou ~/.local/state/orq/. Migrations embutidas, versionadas por PRAGMA user_version.
• Modelo: coordenador, onda, us (chave projeto/ref), dependencia, mr (com estado nulo, previsto para a US Criar o orq tui, o workspace Central e o plugin do Herdr orq #5 #4), pendencia (P1, P2… por US, nunca reaproveitado) e evento (toda escrita grava o seu na mesma transação).
• Comandos: coord registrar|list, onda criar|ver|list|proxima|encerrar, us status, mr add|rm, pend add|resolver|list, diario, snapshot (JSON versionado, contrato em docs/snapshot.md) e version.
• Erro JSON {"error":{"code","cause","recovery"}}, --output json|text (JSON fora de terminal), como na taiga-cli.
• AGENTS.md, README.md com instalação e o contrato dos comandos, CI com gofmt -l, go vet e go test -race.

Decisões a conferir

• done numa US quer dizer "chegou ao limite da autorização da onda" (plano aprovado, MR pronta ou mesclada). Dependência e ordem estrita só liberam a próxima com a anterior em done; onda proxima devolve a autorização e o texto do limite para quem despacha.
• --ordem padrão livre e --ate padrão mr-pronta. Em ordem estrita, uma US só pode depender de outra anterior.
• TG-312 sem projeto: vale a única US com essa ref; havendo várias, a da onda aberta do coordenador corrente e, depois, a do projeto padrão dele. O resto é ref_ambigua.
• A US só existe dentro de uma onda; uma US numa onda aberta não entra em outra, e numa onda encerrada muda de onda guardando o status.
• O diário de eventos ganhou o comando orq diario (o nome orq evento fica livre para o hook do Herdr da US #5).

Testes

• Tabela da máquina de status, de onda proxima (ordem estrita, livre, dependência, autorização, onda encerrada/concluída), dos ids de pendência e da resolução de ref ambígua.
• Concorrência: dois processos (o binário de teste reexecutado) escrevendo 40 pendências cada, mais um terceiro mudando status, no mesmo banco; nenhum número repetido e um evento por escrita. Sem o BEGIN IMMEDIATE o teste falha com SQLITE_BUSY.
• Contrato do snapshot: as chaves de cada objeto são conferidas contra docs/snapshot.md.

Fora do escopo: chamadas a herdr/glab/taiga, daemon, TUI e plugin (US #4 e #5).

[cedric-lamalle]

Revisão qa-adversarial r1 da US orq #3 sobre 070370d95af43a1d4b94f11f301be1a001c7158a: com achados — 2 Sérios e 1 Menor.

CI do SHA conferido: run 38146201232, unit passou. Build, vet, test -race e gofmt também passaram localmente.

1. Sério — primeira abertura concorrente falha: internal/central/store.go:70. Dois coord registrar distintos em um diretório de estado novo: um pode retornar banco_ocupado em 5–6 ms. Confirmado em 9 de 100 bancos novos; isolamento com o mesmo driver localizou a corrida no PRAGMA journal_mode(WAL) antes da migration (15 falhas em 100 pares), apesar do busy_timeout de 15 s. Ocorre no cenário exigido de dois coordenadores iniciando juntos na cedagente. O teste atual prepara o banco antes de lançar os processos.
2. Sério — conclusão herdada entre limites: internal/central/onda.go:149. Criar onda --ate plano --us 3, marcar a US done, encerrar e criar onda --ate mr-pronta --us 3: mantém done e onda proxima anuncia “onda concluída até mr-pronta”, com a US sem MR. O ciclo planejamento → implementação pode pular a execução. A composição das decisões 1 e 4 precisa tratar o limite anteriormente atingido.
3. Menor — divergência documental: snapshot --json, citado na story/desenho, dá uso exit 2. snapshot funciona e corresponde ao pacote de implementação/README; alinhar a documentação ou aceitar o alias.

O que tentei e não quebrou: 240 snapshots simultâneos em bancos novos; duas escritas com 300 snapshots preservaram 80 números/eventos e snapshots coerentes; disputa de onda reverteu a perdedora; snapshot durante escrita leu o último commit sem bloquear; refs ambíguas, Pn, --forcar, no-ops, normalização de MRs/IaC e rejeição de versão futura funcionaram.

A dependência que exige done não trava mr-pronta quando done significa revisão independente aprovada. Empilhar antes dessa aprovação exige a decisão humana prevista no pacote; não registrei isso como defeito.

Relatório completo entregue ao coordenador em /home/cedric/tmp/orquestrador/orq/TG-3/revisao/r1/relatorio.md, com reproduções, ocorrência, limites e avaliação das 11 decisões. Nenhum código, status de story, aprovação ou merge alterado.

[cedric-lamalle]

Revisão qa-adversarial r2 da US orq #3 sobre 92fc6b8947068a6126d28251d8c818ec1a9282bc: aprovada. Os 2 Sérios e o Menor da r1 estão confirmados como corrigidos; nenhum achado novo no delta.

• Primeira abertura: reprodução com 100 bancos novos e dois coordenadores simultâneos deu 0 falhas, com dois registros e dois eventos em cada banco.
• Mudança de limite: plano → mr-pronta e mr-pronta → merge reiniciam a US em wait, tornam-na elegível e registram a mudança no diário. Sete variantes conferidas, inclusive mesmo limite, status exec/rev e wait. MRs e pendências preservadas; conflito posterior reverte toda a transferência.
• snapshot --json aceito, com JSON versão 1; documentação alinhada.

O que tentei e não quebrou: espera curta e timeout real do flock (15 s), liberação após morte do detentor, rollback da onda/status/eventos e snapshot durante escrita lendo apenas o último commit sem bloqueio.

CI do SHA conferido: success, unit executou gofmt, vet e test -race. Build, vet, test -race -count=1 e gofmt também passaram localmente.

Relatório completo: /home/cedric/tmp/orquestrador/orq/TG-3/revisao/r2/relatorio.md. Revisão restrita à confirmação e ao delta. Nenhum código, aprovação formal no GitHub, merge ou status de story alterado.