forjajs 4.0.0 → 4.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (94) hide show
  1. package/CHANGELOG.md +115 -0
  2. package/DOC-MAP.md +1 -0
  3. package/README.md +7 -2
  4. package/dist/apps/cli/src/index.d.ts +18 -1
  5. package/dist/apps/cli/src/index.js +161 -26
  6. package/dist/apps/cli/src/params.d.ts +44 -0
  7. package/dist/apps/cli/src/params.js +123 -0
  8. package/dist/bin/forja.js +234 -13
  9. package/dist/bin/init-project.js +11 -62
  10. package/dist/lib/cli-output.d.ts +29 -0
  11. package/dist/lib/cli-output.js +39 -0
  12. package/dist/lib/core/checks.d.ts +1 -1
  13. package/dist/lib/core/health.d.ts +9 -0
  14. package/dist/lib/core/health.js +9 -0
  15. package/dist/lib/core/project-smoke.d.ts +6 -2
  16. package/dist/lib/core/project-smoke.js +83 -7
  17. package/dist/lib/core/registry.d.ts +38 -571
  18. package/dist/lib/core/registry.js +174 -25
  19. package/dist/lib/core/release.d.ts +1 -571
  20. package/dist/lib/core/release.js +0 -3
  21. package/dist/lib/handoffs-index.d.ts +16 -0
  22. package/dist/lib/handoffs-index.js +29 -0
  23. package/dist/lib/llm/claude-output.d.ts +8 -0
  24. package/dist/lib/llm/claude-output.js +54 -0
  25. package/dist/lib/llm/context.d.ts +22 -0
  26. package/dist/lib/llm/context.js +39 -0
  27. package/dist/lib/llm/session.d.ts +6 -1
  28. package/dist/lib/llm/session.js +12 -2
  29. package/dist/lib/multi-ai-instructions.d.ts +28 -0
  30. package/dist/lib/multi-ai-instructions.js +83 -0
  31. package/dist/lib/orchestrate.d.ts +5 -0
  32. package/dist/lib/orchestrate.js +18 -0
  33. package/dist/lib/specs-index.d.ts +20 -0
  34. package/dist/lib/specs-index.js +51 -0
  35. package/dist/lib/sprint-index.d.ts +15 -0
  36. package/dist/lib/sprint-index.js +34 -0
  37. package/dist/lib/status-model.d.ts +64 -0
  38. package/dist/lib/status-model.js +180 -0
  39. package/dist/packages/evals/src/index.d.ts +2 -0
  40. package/dist/packages/evals/src/index.js +21 -0
  41. package/dist/packages/llm/src/index.d.ts +24 -3
  42. package/dist/packages/llm/src/index.js +51 -5
  43. package/dist/scripts/cost-economy.js +12 -10
  44. package/dist/scripts/drift-check.d.ts +2 -0
  45. package/dist/scripts/drift-check.js +57 -1
  46. package/dist/scripts/engineer.js +7 -4
  47. package/dist/scripts/forja-setup.d.ts +14 -0
  48. package/dist/scripts/forja-setup.js +58 -0
  49. package/dist/scripts/forja-status.d.ts +11 -0
  50. package/dist/scripts/forja-status.js +70 -0
  51. package/dist/scripts/hook-session-start.js +20 -46
  52. package/dist/scripts/llm-fit.js +113 -8
  53. package/dist/scripts/project-smoke.js +13 -3
  54. package/dist/scripts/simulate.js +18 -6
  55. package/dist/scripts/token-economy.js +34 -28
  56. package/dist/scripts/tools-doctor.js +14 -6
  57. package/docs/2x/CLI-CAPABILITIES.md +34 -10
  58. package/docs/agent-operating-contract.md +1 -1
  59. package/docs/cli-first-operacao.md +17 -0
  60. package/docs/contrato-saida-cli.md +79 -0
  61. package/docs/llm-evolution.md +2 -1
  62. package/docs/llm-fit-loop.md +74 -2
  63. package/docs/quick-reference.md +13 -0
  64. package/docs/roadmap-v4.1.md +199 -0
  65. package/memory/90-decisions/0082-contrato-saida-cli.md +95 -0
  66. package/memory/90-decisions/0083-mcp-cobertura-declarativa.md +103 -0
  67. package/memory/90-decisions/0084-drift-sentinel-fecha.md +79 -0
  68. package/memory/90-decisions/0085-adaptador-claude-paridade.md +85 -0
  69. package/package.json +4 -1
  70. package/specs/cli-intuitiva-v1/plan.md +169 -0
  71. package/specs/cli-intuitiva-v1/spec.md +163 -0
  72. package/specs/cli-intuitiva-v1/tasks.md +224 -0
  73. package/specs/contrato-saida-cli/plan.md +162 -0
  74. package/specs/contrato-saida-cli/spec.md +157 -0
  75. package/specs/contrato-saida-cli/tasks.md +153 -0
  76. package/specs/drift-sentinel/spec.md +17 -8
  77. package/specs/forja-status-caminho-feliz/plan.md +149 -0
  78. package/specs/forja-status-caminho-feliz/spec.md +158 -0
  79. package/specs/forja-status-caminho-feliz/tasks.md +175 -0
  80. package/specs/llm-adaptador-claude/plan.md +117 -0
  81. package/specs/llm-adaptador-claude/spec.md +144 -0
  82. package/specs/llm-adaptador-claude/tasks.md +100 -0
  83. package/specs/llm-benchmark-recomendacao/plan.md +121 -0
  84. package/specs/llm-benchmark-recomendacao/spec.md +141 -0
  85. package/specs/llm-benchmark-recomendacao/tasks.md +88 -0
  86. package/specs/llm-contexto-e-sessoes/plan.md +143 -0
  87. package/specs/llm-contexto-e-sessoes/spec.md +139 -0
  88. package/specs/llm-contexto-e-sessoes/tasks.md +127 -0
  89. package/specs/mcp-cobertura-nucleo/plan.md +158 -0
  90. package/specs/mcp-cobertura-nucleo/spec.md +161 -0
  91. package/specs/mcp-cobertura-nucleo/tasks.md +169 -0
  92. package/specs/projeto-gerado-confiavel/plan.md +148 -0
  93. package/specs/projeto-gerado-confiavel/spec.md +142 -0
  94. package/specs/projeto-gerado-confiavel/tasks.md +139 -0
@@ -58,6 +58,22 @@ duplicados removidos. Arquivo ausente ou diretório causa erro antes de executar
58
58
  O hash cobre tarefa e contexto completos. O Forja não salva esses conteúdos nem a resposta no banco
59
59
  ou na auditoria; salva modelo, duração, resultado, comando, referências e contagens de tokens.
60
60
 
61
+ ### Contexto pelo façade — `--engineer` (SPEC-048)
62
+
63
+ ```bash
64
+ forja llm:run --profile codex --engineer "adicionar rate limit no login" --prompt "implemente"
65
+ ```
66
+
67
+ `--engineer "<objetivo>"` roda `forja engineer "<objetivo>" --json` (contexto mínimo do domínio +
68
+ ADRs relevantes + `architecture:check` + risco + agentes recomendados + incidentes parecidos +
69
+ fluxo) e **embute o relatório no prompt**, antes do que você passar em `--prompt`/`--task` e antes
70
+ dos `--context`. Sem `--prompt`/`--task`, o próprio objetivo vira o prompt.
71
+
72
+ O hash cobre o prompt transmitido, incluindo o bloco do `engineer`. Em `contextRefs` fica só a
73
+ **referência** `engineer:<objetivo>` — o conteúdo do relatório **nunca** é persistido, igual ao
74
+ tratamento de `--context`. Se o façade sair com erro, o `llm:run` falha **antes** de chamar o
75
+ provedor com `errorCode: "ENGINEER_FAILED"`.
76
+
61
77
  Codex recebe o prompt por stdin e retorna eventos JSONL. O Forja extrai a resposta do agente,
62
78
  `sessionId` e uso, sem devolver eventos de raciocínio como resposta final. Falhas explícitas,
63
79
  JSONL inválido ou ausência de conclusão resultam em erro mesmo com exit zero do subprocesso.
@@ -99,6 +115,61 @@ Esforço e timeout podem mudar. A configuração global da CLI não é fingerpri
99
115
  explícito no perfil quando precisar fixá-lo. Não há coordenação de retomadas simultâneas da mesma
100
116
  sessão nem garantia de que o modelo nunca repetirá uma ação.
101
117
 
118
+ ### Descobrir o `SESSION_ID` — `llm:sessions` (SPEC-048)
119
+
120
+ ```bash
121
+ forja llm:sessions list # id, projeto, quando, observação — mais recente primeiro
122
+ forja llm:sessions show <id> [--json] # a sessão + a observação e a validação vinculadas
123
+ ```
124
+
125
+ Somente leitura sobre `llm_session` — não abre o provedor nem a rede. É como recuperar o `id` do
126
+ `--resume` quando a saída da execução anterior se perdeu. `list --json` emite um array; `show`
127
+ emite um objeto; `id` desconhecido sai com código 1.
128
+
129
+ ## Adaptador Claude (SPEC-050, ADR-0085)
130
+
131
+ O perfil `claude` tem paridade de retomada e formato com o Codex, dentro da mesma fronteira de
132
+ privacidade (`shell:false`, o Forja nunca lê API keys; prompt e contexto vão ao provedor, ao DB
133
+ só as refs).
134
+
135
+ ```bash
136
+ forja llm:run --profile claude --prompt "Analise o requisito pendente"
137
+ forja llm:run --profile claude --resume SESSION_ID --prompt "Continue a análise"
138
+ ```
139
+
140
+ - **Invocação**: `claude -p "<prompt>" --output-format json [--model <m>] [--resume <id>]`. A
141
+ resposta é um **objeto JSON único** (não JSONL como o Codex); o Forja lê `result`,
142
+ `session_id` e `usage` (`input_tokens`, `output_tokens`, `cache_read_input_tokens`). Formato
143
+ inesperado, `is_error: true` ou `subtype != "success"` viram erro visível — nunca resposta
144
+ silenciosa.
145
+ - **Retomada**: `RESUME_PROVIDERS = { codex, claude }`. `--resume` exige um id explícito e
146
+ válido; as mesmas travas de fingerprint do Codex se aplicam (projeto, provedor, modelo
147
+ declarado, executável, argumentos, privacidade). `llm:sessions` também lista sessões `claude`.
148
+ - **`--output-schema` com o perfil `claude`**: a validação é **local (Ajv), nunca uma garantia
149
+ do provedor**. O `claude` CLI não tem geração estruturada nativa equivalente; ele recebe a
150
+ instrução de responder JSON e a resposta é validada localmente pelo mesmo caminho do Codex.
151
+ Por isso `llm:probe claude` reporta `features.outputSchema: false` e `features.resume: true`.
152
+ - **Custo**: o `total_cost_usd` do provedor **não** substitui a estimativa local de
153
+ `model-pricing.json` — a evidência de custo continua vindo do preço declarado no Forja.
154
+
155
+ ## Métricas e recomendação por custo/latência (SPEC-049)
156
+
157
+ `llm:eval` acrescenta às métricas do relatório:
158
+
159
+ - `durationMsP50` / `durationMsP95` — percentis da latência das observações do escopo.
160
+ - `costPerAcceptedTask` — `totalCost` dividido pelas observações com `validationStatus: "accepted"`
161
+ (`0` quando nenhuma foi aceita, não `null` nem infinito).
162
+
163
+ `llm:recommend` passa a ponderar **latência** e **custo** além do fit declarado (`role`/`taskType`)
164
+ e da taxa de sucesso local. O bônus de latência/custo é limitado (soma no máximo 8 pontos): ele
165
+ desempata e refina entre pares próximos, **nunca inverte um fit declarado** (que vale 100+50).
166
+ Cada candidato ganha `evidence: { samples, medianDurationMs, meanCostUsd, successRate }` e o
167
+ `reasons` mostra `latency:p50=<ms>` e `cost:$<x>/run` — a recomendação deixa de ser um número opaco.
168
+
169
+ Sem amostras para um perfil, o score é o de fit puro (comportamento anterior). **Nenhum
170
+ percentual de melhoria é afirmado**: os eixos precisam de um baseline de observações reais de 30
171
+ dias antes de qualquer comparação numérica (ver [llm-evolution.md](llm-evolution.md)).
172
+
102
173
  ## Formato e validação independente
103
174
 
104
175
  O operador escolhe o schema da resposta e os checks antes de executar o modelo:
@@ -158,8 +229,9 @@ aprova somente os checks configurados; não equivale a merge ou aprovação gera
158
229
 
159
230
  - O adapter padrão do Codex é `read-only`; mudanças de arquivos continuam no runtime/sandbox
160
231
  supervisionado do Forja.
161
- - `llm:probe` executa `--version` e, para Codex, os helps de `exec` e `exec resume`;
162
- informa também `features.resume` e `features.outputSchema`, sem consumir tokens ou enviar contexto.
232
+ - `llm:probe` executa `--version` e, para Codex, os helps de `exec` e `exec resume`; para Claude,
233
+ o `--help` (procura `--resume`). Informa `features.resume` e `features.outputSchema` (sempre
234
+ `false` para Claude — validação de schema é local), sem consumir tokens ou enviar contexto.
163
235
  - Recomendações são ordenadas por compatibilidade declarada e observações locais. O operador escolhe
164
236
  o perfil; não existe failover automático nem chamada direta a APIs nesta versão.
165
237
  - O dashboard pode editar e exibir perfis, mas não executa modelos. A antiga rota de execução retorna
@@ -4,6 +4,19 @@
4
4
 
5
5
  ---
6
6
 
7
+ ## Descoberta pela propria CLI
8
+
9
+ ```bash
10
+ forja status # onde estou (workspace, sprint, corrida, specs, runs, handoffs)
11
+ forja next # o que faco agora (proxima acao + comando)
12
+ forja help # so o nucleo, agrupado por dominio
13
+ forja help --all # tudo
14
+ forja help spec:new # uso + argumentos + exemplos + proximos passos
15
+ npm run setup # primeiro uso: workspace:init + sync:universal (forja setup)
16
+ ```
17
+
18
+ ---
19
+
7
20
  ## Operacao CLI-First
8
21
 
9
22
  ```bash
@@ -0,0 +1,199 @@
1
+ # Roadmap ForjaJS v4.1 — menos erros, mais intuitivo, mais funcional com LLMs
2
+
3
+ - **Data**: 2026-09-07
4
+ - **Direção**: Allan Pablo — evoluir o ForjaJS usando o próprio ForjaJS, reduzindo erros,
5
+ tornando a operação mais intuitiva e mais funcional com LLMs (ver `docs/llm-evolution.md`).
6
+ - **Estado de partida**: v4.0.0. Core em `bin/forja.ts` + `lib/core/registry.ts` (ADR-0020),
7
+ 473 testes verdes, 77 ADRs, pipeline SDD, Engineering Control Plane (v3), integração LLM
8
+ read-only via Codex (v4).
9
+ - **Formato**: diagnóstico + 12 workstreams em 4 ondas. Cada frente aprovada vira
10
+ `specs/<slug>/spec.md` pelo pipeline do Forja, com ADR nas decisões estruturais.
11
+ - **Primeira spec derivada**: [`specs/cli-intuitiva-v1/spec.md`](../specs/cli-intuitiva-v1/spec.md)
12
+ (SPEC-043 — Onda 1, W1+W2+W3).
13
+
14
+ > **Estado (2026-09-08): concluído.** As 12 workstreams (W1–W12) foram implementadas pelo
15
+ > pipeline SDD do próprio Forja e merjadas em `main` (PRs #61–#69). Todas as specs derivadas
16
+ > estão `done` (`spec:check` exit 0); `drift-sentinel` segue `implementing` **por desenho** —
17
+ > ADR-0084 mantém aberta a janela de observação de "drift real no mundo" até 2026-10-08.
18
+ > ADRs estruturais: 0082 (contrato de saída), 0083 (cobertura MCP declarativa), 0084 (fecho do
19
+ > drift-sentinel), 0085 (adaptador Claude).
20
+
21
+ ## Método
22
+
23
+ Levantado por leitura direta (codegraph ausente na máquina de trabalho — `tools:doctor` reporta
24
+ 0/5 ferramentas opcionais; busca feita com `rg`/leitura):
25
+
26
+ - `bin/forja.ts` (362 L), `lib/core/registry.ts` (642 L), `apps/cli/src/index.ts`
27
+ - `node bin/forja.ts` — ~75 comandos em 10 domínios
28
+ - `node --test test/*.test.js` — 473/473 verdes (~10,8 s)
29
+ - `node bin/forja.ts tools:doctor` — núcleo OK com ressalvas; clone novo sem workspace/índice
30
+ - `.github/workflows/ci.yml` — roda `npm test`, `spec:check forja-core`, `release:check`
31
+ - `CHANGELOG.md` (v3/v4), `docs/llm-fit-loop.md`, `docs/llm-evolution.md`, `specs/drift-sentinel/spec.md`
32
+
33
+ ## Diagnóstico
34
+
35
+ ### Eixo A — Diminuir erros
36
+
37
+ | # | Achado | Evidência |
38
+ |---|---|---|
39
+ | A1 | `suggest()` só faz prefix-match do segmento antes de `:` — `forja plan` **não** sugere `spec:plan` | `bin/forja.ts` `suggest()` |
40
+ | A2 | Registry declara só `domain/desc/node/args/gates`. Sem `usage`, `args`, `examples`. O agente descobre o uso **executando e lendo o stack trace** do script-filho | `lib/core/registry.ts` |
41
+ | A3 | Não existe `forja help <comando>` | `printHelp()` só imprime a lista |
42
+ | A4 | Padrão recorrente de bugs: divergência **dev-checkout × pacote publicado × worktree isolado** (HOME não passado ao sandbox; `cwd` errado no pacote; `resolveScript`; memory-db falso "corrompido") | seções "Corrigido" dos changelogs 3.0/4.0 |
43
+ | A5 | Projeto gerado **não tem smoke no CI**: `lib/core/project-smoke.ts` existe mas `ci.yml` não o roda; nenhuma combinação de `--ai` é validada com `install && test && project:check` | `.github/workflows/ci.yml` |
44
+ | A6 | `init:project` escreve 4 conjuntos de instruções (CLAUDE/Copilot/Gemini/Codex). O check `agent-topology` que garante coerência **só existe para este repo**, não para o gerado — os 4 divergem com o tempo | `tools:doctor`; `lib/generators/` |
45
+ | A7 | `drift:check` (SPEC-030) está `implementing`: AC-5 com escopo reduzido, métrica do §8 (drift real achado em projeto real) **nunca observada** — só dogfooding local sem achados | `specs/drift-sentinel/spec.md` |
46
+ | A8 | `--json` e exit codes **inconsistentes**. `llm:run`/`simulate` têm padrão bom (`executionStatus`/`validationStatus`, exit 2 = validação reprovada); o resto varia | `docs/llm-fit-loop.md` §validação |
47
+ | A9 | `spec:new` aloca ID por contagem de diretórios em `specs/`, não pelo maior `SPEC-NNN` — já há colisões (SPEC-037/038/039/040 aparecem 2× cada). `cli-intuitiva-v1` recebeu SPEC-040, corrigido à mão para SPEC-043 | observado em 2026-09-07 ao criar a spec |
48
+
49
+ ### Eixo B — Mais intuitivo
50
+
51
+ | # | Achado | Evidência |
52
+ |---|---|---|
53
+ | B1 | `forja help` = parede de ~75 linhas, sem camada "os 10–12 que você usa 90% do tempo" | saída de `node bin/forja.ts` |
54
+ | B2 | Sufixos `(SPEC-0XX)` na descrição de ~30 comandos são ruído para quem opera | descrições no help |
55
+ | B3 | `orchestrate` (a cadeia SDD/GSD como máquina de estados guardada por gates, SPEC-021) é **o caminho feliz** mas fica no meio da lista; não há `forja next`/`forja status` que diga a próxima ação | help; `scripts/orchestrate.ts` |
56
+ | B4 | 3 formas de invocar (`npm run x`, `node bin/forja.ts x`, `forja x`) + aliases não documentados (`ops:*` = `gsd:*`) | `package.json`, registry |
57
+ | B5 | `tools:doctor` lista correções mas **não as aplica**; SessionStart mistura "normal em clone novo" com acionável | saída `tools:doctor`; hook `<framework-status>` |
58
+
59
+ ### Eixo C — Mais funcional com LLMs
60
+
61
+ | # | Achado | Evidência |
62
+ |---|---|---|
63
+ | C1 | **Só 6 comandos** viram capability MCP (`tools:doctor`, `code:impact`, `context:budget`, `spec:check`, `sprint:status`, `gsd:handoff`) + `graph.sync`. De ~75. Agente em `mcp:start` **não consegue** rodar spec:new/plan/tasks, `engineer`, `risk:assess`, `context:smart`, `query:universal`, `orchestrate*` | `apps/cli/src/index.ts` `CLI_CAPABILITY_SPECS` |
64
+ | C2 | `llm:run --context` é **manual**; o façade `engineer` já compõe contexto+ADR+risco+fluxo mas não alimenta `llm:run` | `docs/llm-fit-loop.md`; help `engineer` |
65
+ | C3 | `resume` e `output-schema` são **exclusivos do adaptador Codex**; Claude/Gemini não herdam (contrato explícito) | `docs/agent-operating-contract.md` §LLMs |
66
+ | C4 | `llm:recommend` ordena por compat declarada + observação local; **sem eixo custo/latência/qualidade**. `cost:economy` existe isolado. Etapas 3–5 do `llm-evolution.md` seguem "planejadas" | `docs/llm-evolution.md` |
67
+ | C5 | `llm_session` guarda metadados de sessão, mas não há `llm:sessions` (list/show) para descobrir o `sessionId` de retomada | `docs/llm-fit-loop.md` §retomar |
68
+
69
+ ## Roadmap priorizado
70
+
71
+ RICE aproximado (Reach = execuções/agentes afetados; Impact 1–3; Confidence 0–1; Effort S/M/L).
72
+ Ordenado por onda. Cada frente vira uma spec após aprovação.
73
+
74
+ ### Onda 1 — Fundação de intuitividade e menos atrito (habilita o resto) — ✅ concluída
75
+
76
+ **W1 — Registry enriquecido + `forja help <comando>`** · eixos A2/A3/B1/B2 · Effort M · ✅ feito
77
+ Campos opcionais em `COMMANDS` (`usage`, `args[]`, `examples[]`, `next[]`, `readonly`, `json`,
78
+ `tier`); `forja help <cmd>` renderiza tudo; `forja help` lista só `tier:'core'` + rodapé `--all`.
79
+ Arquivos: `lib/core/registry.ts`, `bin/forja.ts`, `test/forja-core.test.js`.
80
+
81
+ **W2 — `suggest()` fuzzy + erros acionáveis** · eixos A1/A2/B5 · Effort S · ✅ feito
82
+ Match por substring + distância de edição sobre o nome completo; pré-validação de args `required`
83
+ em `bin/forja.ts` (sem stack trace do filho); toda mensagem de erro termina com o comando de correção.
84
+ Arquivos: `bin/forja.ts`, util de distância.
85
+
86
+ **W3 — rotina de primeiro uso + SessionStart classificado** · eixos A4/B5 · Effort S–M · ✅ feito
87
+ No plan o `tools:doctor --fix` virou o comando dedicado **`forja setup`** (`workspace:init` +
88
+ `sync:universal` atrás de confirmação; `--yes` para não-interativo) — `tools:doctor` segue só
89
+ diagnóstico. Saída de `tools:doctor` e do `<framework-status>` em 3 blocos fixos (Bloqueia /
90
+ Rotina de primeiro uso / Opcional).
91
+ Arquivos: `scripts/forja-setup.ts`, `scripts/tools-doctor.ts`, `scripts/hook-session-start.ts`.
92
+
93
+ > **Entregue como** [`specs/cli-intuitiva-v1/spec.md`](../specs/cli-intuitiva-v1/spec.md)
94
+ > (SPEC-043, `done`) — PR #61.
95
+
96
+ ### Onda 2 — Caminho feliz + contrato de máquina — ✅ concluída
97
+
98
+ **W4 — `forja status` + `forja next`** · eixos B3/C · Effort M · ✅ feito
99
+ `status` agrega workspace, sprint, run `orchestrate` aberto (+ etapa/gate), specs por status,
100
+ últimos runs. `next` = só a próxima ação + comando exato. `orchestrate` promovido no help/README.
101
+ Arquivos: `lib/status-model.ts` (novo), `scripts/forja-status.ts` (novo), `lib/orchestrate.ts`,
102
+ `lib/specs-index.ts` / `lib/handoffs-index.ts`, registry, `bin/forja.ts`.
103
+ > **Entregue como** [`specs/forja-status-caminho-feliz/spec.md`](../specs/forja-status-caminho-feliz/spec.md)
104
+ > (SPEC-044, `done`) — PR #62.
105
+
106
+ **W5 — Contrato de saída CLI: `--json` + exit codes** · eixo A8 · Effort M (incremental) · **ADR-0082** · ✅ feito
107
+ `docs/contrato-saida-cli.md`: `--json` emite um objeto único com chave `status`
108
+ (`ok`|`error`|`rejected`); exit 0/1/2/127. `lib/cli-output.ts` (`emitOk`/`emitError`/`emitRejected`)
109
+ impõe o formato; `test/cli-output-contract.test.js` itera o registry `json:true`. `llm:sessions`
110
+ (SPEC-048) fica como exceção conhecida (forma própria, anterior ao ADR).
111
+ Arquivos: `docs/contrato-saida-cli.md` (novo), `lib/cli-output.ts` (novo), `lib/core/registry.ts`, testes.
112
+ > **Entregue como** [`specs/contrato-saida-cli/spec.md`](../specs/contrato-saida-cli/spec.md)
113
+ > (SPEC-045, `done`) — PR #63.
114
+
115
+ **W6 — Cobertura MCP: de 6 para 18 comandos** · eixo C1 · Effort M–L · **ADR-0083** · ✅ feito
116
+ `CLI_CAPABILITY_SPECS` cobre o núcleo do fluxo (`spec:new/plan/tasks`, `query:universal`,
117
+ `engineer`, `risk:assess`, `orchestrate:status/advance`, `drift:check`, `code:context`, `status`,
118
+ `next`). Mapeamento argv↔payload declarativo (`apps/cli/src/params.ts`, `parseArgv`/`argvFor`
119
+ inversos com round-trip test) — o `if/else` por comando some. `spec:check` e `tools:doctor`
120
+ conformam via o adaptador `toContract` em `bin/forja.ts` (fecha o débito D7 de W5).
121
+ Arquivos: `apps/cli/src/index.ts`, `apps/cli/src/params.ts` (novo), `bin/forja.ts`, testes.
122
+ > **Entregue como** [`specs/mcp-cobertura-nucleo/spec.md`](../specs/mcp-cobertura-nucleo/spec.md)
123
+ > (SPEC-046, `done`) — PR #64.
124
+
125
+ ### Onda 3 — Qualidade que previne regressão — ✅ concluída
126
+
127
+ **W7 — Smoke do projeto gerado no CI (matrix por `--ai`)** · eixo A5 · Effort S–M · ✅ feito
128
+ Job de CI `project-smoke-ai` em matriz (`claude` · `copilot` · `claude,copilot,gemini,codex`),
129
+ tier barato, a cada PR e push. `project:smoke --ai <lista>` exercita o caminho real (memória +
130
+ instruções nativas por IA), gerado só-memória e sem rede.
131
+ Arquivos: `.github/workflows/ci.yml`, `lib/core/project-smoke.ts`.
132
+
133
+ **W8 — Coerência das instruções multi-IA no projeto gerado** · eixo A6 · Effort M · ✅ feito
134
+ `lib/multi-ai-instructions.ts` (novo) — fonte única para CLAUDE/Copilot/Gemini/Codex; check
135
+ `ai-instructions` no `project:smoke` prova corpo byte-idêntico entre IAs (só o cabeçalho muda) e
136
+ `models.json` coerente. É o análogo do `agent-topology`, na saída do gerador.
137
+ Arquivos: `lib/multi-ai-instructions.ts` (novo), `bin/init-project.ts`, `lib/core/project-smoke.ts`.
138
+ > W7+W8 **entregues como** [`specs/projeto-gerado-confiavel/spec.md`](../specs/projeto-gerado-confiavel/spec.md)
139
+ > (SPEC-047, `done`) — PR #65.
140
+
141
+ **W9 — Fechar SPEC-030 (`drift:check`) com métrica real** · eixo A7 · Effort S + observação · **ADR-0084** · ✅ feito
142
+ `drift:check --all` roda o sentinela uma vez por projeto do workspace, cada um num grafo isolado
143
+ e persistente. A métrica "drift real no mundo" do §8 (infalsificável como bloqueio de `done`)
144
+ virou aceite verificável agora + janela de observação até **2026-10-08**; `drift:check` segue
145
+ gate opt-in. Spec fica `implementing` **por desenho** até a janela fechar.
146
+ Arquivos: `scripts/drift-check.ts`, `apps/cli/src/index.ts` (param `--all` na capability),
147
+ `memory/90-decisions/0084-*`, `specs/drift-sentinel/spec.md`.
148
+ > **Entregue como** atualização de [`specs/drift-sentinel/spec.md`](../specs/drift-sentinel/spec.md)
149
+ > (SPEC-030) — PR #66.
150
+
151
+ ### Onda 4 — LLM de próxima geração (etapas 3–5 do `llm-evolution.md`) — ✅ concluída
152
+
153
+ **W10 — `llm:run --engineer` + `llm:sessions`** · eixos C2/C5 · Effort M · ✅ feito
154
+ `llm:run --engineer "<objetivo>"` monta o contexto pelo façade `engineer` e o embute no prompt
155
+ (hash cobre o prompt transmitido; `contextRefs` guarda só `engineer:<objetivo>`, nunca o
156
+ conteúdo). `llm:sessions list|show` sobre `llm_session`, read-only.
157
+ Arquivos: `lib/llm/context.ts`, `lib/llm/session.ts`, `scripts/llm-fit.ts`, registry, `docs/llm-fit-loop.md`.
158
+ > **Entregue como** [`specs/llm-contexto-e-sessoes/spec.md`](../specs/llm-contexto-e-sessoes/spec.md)
159
+ > (SPEC-048, `done`) — PR #67.
160
+
161
+ **W11 — Benchmark real + recomendação por custo/latência (etapa 3)** · eixo C4 · Effort M–L · ✅ feito
162
+ `llm:eval` ganha `durationMsP50`/`durationMsP95` e `costPerAcceptedTask`; `llm:recommend`
163
+ pondera latência e custo (bônus limitado, nunca inverte um fit) e devolve `evidence` por
164
+ candidato + `reasons` com `latency:p50=…` / `cost:$…/run`. Baseline de 30 d antes de qualquer percentual.
165
+ Arquivos: `packages/evals/src/index.ts`, `packages/llm/src/index.ts`, `scripts/llm-fit.ts`, `docs/llm-evolution.md`.
166
+ > **Entregue como** [`specs/llm-benchmark-recomendacao/spec.md`](../specs/llm-benchmark-recomendacao/spec.md)
167
+ > (SPEC-049, `done`) — PR #68.
168
+
169
+ **W12 — Adaptador Claude com paridade (`resume`/`output-schema`)** · eixo C3 · Effort L · **ADR-0085** · ✅ feito
170
+ `llm:run --profile claude` → `claude -p "<prompt>" --output-format json [--model m] [--resume id]`
171
+ (`shell:false`, sem ler API keys). `lib/llm/claude-output.ts` normaliza o objeto JSON único do
172
+ provedor; `RESUME_PROVIDERS = { codex, claude }` rege o guard de retomada; `--output-schema` para
173
+ Claude é validação **local (Ajv)**, não garantia do provedor (`features.outputSchema: false`).
174
+ Mantido o `if (provider === …)` + `*-output.ts` — sem `lib/llm/adapters/` genérico (ADR-0085).
175
+ Arquivos: `packages/llm/src/index.ts`, `lib/llm/claude-output.ts` (novo), `lib/llm/session.ts`,
176
+ `scripts/llm-fit.ts`, `memory/90-decisions/0085-*`, `specs/llm-adaptador-claude/`.
177
+ > **Entregue como** [`specs/llm-adaptador-claude/spec.md`](../specs/llm-adaptador-claude/spec.md)
178
+ > (SPEC-050, `done`) — PR #69.
179
+
180
+ ## Agrupamento em specs — ✅ todas entregues
181
+
182
+ | Spec | Frentes | ID | ADR | Estado | PR |
183
+ |---|---|---|---|---|---|
184
+ | `cli-intuitiva-v1` | W1 + W2 + W3 | SPEC-043 | não | `done` | #61 |
185
+ | `forja-status-caminho-feliz` | W4 | SPEC-044 | não | `done` | #62 |
186
+ | `contrato-saida-cli` | W5 | SPEC-045 | ADR-0082 | `done` | #63 |
187
+ | `mcp-cobertura-nucleo` | W6 | SPEC-046 | ADR-0083 | `done` | #64 |
188
+ | `projeto-gerado-confiavel` | W7 + W8 | SPEC-047 | — | `done` | #65 |
189
+ | `drift-sentinel` (existente) | W9 | SPEC-030 | ADR-0084 | `implementing` (janela de observação até 2026-10-08) | #66 |
190
+ | `llm-contexto-e-sessoes` | W10 | SPEC-048 | não | `done` | #67 |
191
+ | `llm-benchmark-recomendacao` | W11 | SPEC-049 | não | `done` | #68 |
192
+ | `llm-adaptador-claude` | W12 | SPEC-050 | ADR-0085 | `done` | #69 |
193
+
194
+ ## Fora de escopo desta rodada
195
+
196
+ - Reescrita do help/onboarding como TUI interativa (só camadas de texto agora).
197
+ - Failover automático entre modelos ou chamada direta a APIs sem ADR (contrato proíbe no MVP).
198
+ - Habilitar manutenção autônoma (ADR-0079 mantém como prontidão arquitetural, não habilitação).
199
+ - Editar `projects/` (off-limits) ou os relatórios de `docs/archive/`.
@@ -0,0 +1,95 @@
1
+ # ADR-0082: Contrato de saída da CLI — `--json` e exit codes
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-09-08
5
+ - **Autor(es)**: Allan Pablo / Claude
6
+ - **Tags**: cli, contract, llm, automation
7
+
8
+ ## Contexto
9
+
10
+ Um agente LLM (ou qualquer automação) que dirige o Forja precisa decidir o próximo passo lendo
11
+ a saída de um comando. Hoje não há contrato: `grep -rl "\-\-json" scripts/` encontra 10 scripts
12
+ em ~4 formatos. `simulate` e `engineer` emitem um `report` sem nenhuma chave de estado;
13
+ `token:economy --json` emite um **array cru**; `cost:economy --json` emite um objeto de forma
14
+ diferente e ainda escreve avisos no stdout, quebrando o `JSON.parse`. Os exit codes também
15
+ variam: `process.exitCode = 1` para erro de argumento, `1` também para `simulate` recomendar
16
+ `discard`, `2` para `llm:run` reprovar validação (documentado em `llm-fit-loop.md`), `127` para
17
+ binário externo ausente (em `bin/forja.ts`). Não existe tabela.
18
+
19
+ A SPEC-043 já adicionou o campo opcional `json` ao registry; a SPEC-044 já fez `forja status` e
20
+ `forja next` nascerem no formato-alvo. Falta fixar a regra e conformar os demais.
21
+
22
+ ## Decisão
23
+
24
+ **Definir um contrato de saída, aditivo e incremental.** Ele rege apenas os comandos que optam
25
+ por `json: true` no registry — não obriga todo comando a suportar `--json`.
26
+
27
+ Com `--json`, o stdout carrega **exatamente um** valor JSON, um **objeto**, com uma string
28
+ `status`:
29
+
30
+ - `"ok"` — sucesso → exit **0**
31
+ - `"error"` — falha operacional (argumentos inválidos, arquivo ausente, subsistema fora) → exit
32
+ **1**, com `error: { message, code? }`
33
+ - `"rejected"` — uma validação ou gate que o próprio comando roda deu negativo → exit **2**, com
34
+ o payload ainda presente. É o caso de `llm:run` (validação reprovou) e de `simulate` quando a
35
+ recomendação é `discard`.
36
+
37
+ Exit codes, em qualquer modo (não só `--json`):
38
+
39
+ | code | significado |
40
+ |---|---|
41
+ | 0 | sucesso |
42
+ | 1 | erro operacional |
43
+ | 2 | validação/gate do comando deu negativo |
44
+ | 127 | binário externo obrigatório ausente (só alvos `bin:` do registry; `bin/forja.ts` já cuida) |
45
+
46
+ Regras adicionais de `--json`: os campos específicos do comando ficam **ao lado** de `status`
47
+ (flat, não sob um `data`); diagnóstico verboso vai para o **stderr**; sem ANSI; sem prompt
48
+ interativo (falha em vez de perguntar).
49
+
50
+ Um helper compartilhado `lib/cli-output.ts` (`emitOk`, `emitError`, `emitRejected`) implementa o
51
+ formato e o exit code. Um teste de conformidade (`test/cli-output-contract.test.js`) itera o
52
+ registry e verifica todo comando `json: true`.
53
+
54
+ Conjunto conformado nesta rodada: `status`, `next`, `engineer`, `simulate`, `cost:economy`,
55
+ `token:economy`. `spec:check` e `tools:doctor` **já** emitem JSON, mas pelo **envelope da
56
+ capability** (`apps/cli/src/index.ts` os roteia como MCP), cujo `status` é `succeeded`/`failed` —
57
+ alinhar esse envelope ao contrato é trabalho da cobertura MCP (W6), não desta spec. `risk:assess`
58
+ fica para depois (orientado a arquivo).
59
+
60
+ ## Alternativas consideradas
61
+
62
+ - **Envelope aninhado `{ status, data, meta }`** — rejeitado: mais profundidade para o agente
63
+ navegar e quebraria o formato flat que `llm:run` (`executionStatus`/`validationStatus`) e
64
+ `status`/`next` já usam.
65
+ - **Manter o array cru de `token:economy` e pôr o estado num campo lateral** — impossível sem
66
+ violar "stdout = um objeto".
67
+ - **Helper que devolve `{ json, code }` para o script imprimir** — rejeitado: cada script erra
68
+ de um jeito diferente na hora de imprimir e sair; foi assim que os 4 formatos surgiram. O
69
+ helper termina o processo.
70
+ - **Deixar `simulate` discard em exit 1** — rejeitado: apaga a distinção entre "não promova"
71
+ (decisão do gate) e "o comando falhou" (erro operacional), que é o motivo do contrato existir.
72
+
73
+ ## Consequências
74
+
75
+ **Positivas**:
76
+ - Automação e agentes LLM ramificam por `status` + exit code, sem parsear prosa.
77
+ - Autor de script novo tem um doc e um teste que falha no desvio — a conformidade não depende de
78
+ memória.
79
+ - `cost:economy --json` deixa de ser inutilizável (avisos saíam no stdout).
80
+
81
+ **Negativas / Trade-offs**:
82
+ - **Quebra de contrato JSON** em dois comandos, registrada aqui e no CHANGELOG:
83
+ - `token:economy --json` passa de array `[...]` para `{ "status": "ok", "rows": [...] }`.
84
+ - `simulate` com recomendação `discard` passa de exit `1` para exit `2`.
85
+ Ambos os `--json` são recentes e sem consumidor externo conhecido; CI que trata `!= 0` como
86
+ falha não muda de comportamento.
87
+ - O contrato é incremental: comandos sem `json: true` continuam sem garantia — a cobertura
88
+ cresce spec a spec.
89
+
90
+ ## Rastreamento
91
+
92
+ - Implementação: `lib/cli-output.ts`, `scripts/{forja-status,engineer,simulate,cost-economy,token-economy}.ts`, `lib/core/registry.ts`, `bin/forja.ts`
93
+ - Testes: `test/cli-output.test.js`, `test/cli-output-contract.test.js`
94
+ - [Spec](../../specs/contrato-saida-cli/spec.md) · [Doc](../../docs/contrato-saida-cli.md)
95
+ - ADRs relacionadas: ADR-0020 (core/registry), SPEC-043 (campo `json`), SPEC-044 (`status`/`next`)
@@ -0,0 +1,103 @@
1
+ # ADR-0083: Cobertura MCP — arg mapping declarativo e envelope alinhado ao contrato de saída
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-09-08
5
+ - **Autor(es)**: Allan Pablo / Claude
6
+ - **Tags**: mcp, cli, capabilities, contract
7
+
8
+ ## Contexto
9
+
10
+ Um agente que fala com o Forja por MCP (`forja mcp:start`) enxerga 6 comandos de ~75:
11
+ `tools:doctor`, `code:impact`, `context:budget`, `spec:check`, `sprint:status`, `gsd:handoff`
12
+ (+ `graph.sync`). Não consegue rodar o fluxo SDD nem os comandos de contexto/engenharia. Dois
13
+ obstáculos estruturais impediam ampliar:
14
+
15
+ 1. **`apps/cli/src/index.ts`** traduz argv↔payload num `if/else` por comando dentro de
16
+ `parseLegacyCommandInput`, e cada `CliCapabilitySpec` tem um `toArgs` que é o inverso manual.
17
+ Adicionar um comando exige mexer nos dois em sincronia, sem contrato que force a coerência.
18
+ 2. O `--json` de um comando-capability despeja o `ExecutionResult` cru
19
+ (`{ status: "succeeded" | "failed", output: { payload: { command, args, exitCode, stdout,
20
+ stderr } } }`) — não segue o contrato de saída (ADR-0082). É o débito **D7** da SPEC-045:
21
+ `spec:check` e `tools:doctor` ficaram fora do contrato por causa disso.
22
+
23
+ ## Decisão
24
+
25
+ **1 — Mapeamento argv↔payload declarativo.** `CliCapabilitySpec` ganha
26
+ `params: CapabilityParam[]`, onde cada param é `positional` | `flag` (booleana) | `flag-value`
27
+ (`--x <v>`) | `rest` (resto → string). Duas funções puras e **inversas** em
28
+ `apps/cli/src/params.ts` — `parseArgv(params, argv)` e `argvFor(params, input)` — substituem o
29
+ `toArgs` manual e o `if/else`. Um teste de round-trip
30
+ (`argvFor(params, parseArgv(params, argv)) === argv`) para todo spec é o contrato que impede
31
+ divergência. `validateInput` continua explícito: `makeValidator(params)` cobre "required
32
+ presente + tipo", e specs com limite real (`code:impact` depth 1..10) o embrulham. `graph.sync`
33
+ permanece o único caso sem `command`/`params` (não tem CLI equivalente).
34
+
35
+ **2 — Critério do que vira capability nesta rodada.** Somente leitura e escrita SDD de baixo
36
+ risco. Entram (13): `spec.create` (`spec:new`), `spec.plan`, `spec.tasks`, `context.smart`,
37
+ `code.context`, `memory.query` (`query:universal`), `engineering.facade` (`engineer`),
38
+ `risk.assess`, `orchestrate.status`, `orchestrate.advance`, `drift.check`, `forja.status`,
39
+ `forja.next`. **Ficam de fora**, e por quê:
40
+
41
+ - `orchestrate` (start) — abre uma corrida inteira; efeito grande demais para uma tool.
42
+ - `llm:*` — contrato de privacidade próprio (ADR-0081); rodada separada.
43
+ - `project:new`, `sprint:start`/`sprint:complete`, `workspace:init`, `setup` — mutação fora do
44
+ fluxo SDD.
45
+ - `memory:*` de escrita (`sync:universal`, `memory:compress`, …) e `architecture:approve` —
46
+ manutenção/governança, não fluxo de feature.
47
+
48
+ Capabilities de escrita declaram `permissions: ['write']` e `categories` com `write`/`database`;
49
+ o `PolicyEngine` do CLI já permite `roles: ['cli']` em todas as categorias — a decisão **não
50
+ amplia autonomia**, só torna o comando invocável.
51
+
52
+ **3 — Envelope → contrato de saída.** Só no modo `--json` da CLI, `bin/forja.ts` traduz o
53
+ `ExecutionResult` de um comando-capability para o objeto do contrato de saída (ADR-0082), via
54
+ uma única função `toContract`:
55
+
56
+ | `ExecutionResult` | contrato |
57
+ |---|---|
58
+ | `status: "succeeded"` e `payload.exitCode === 0` (ou sem `exitCode`, ex.: `graph.sync`) | `{ status: "ok", ...merge(stdout) }` — exit 0 |
59
+ | `status: "succeeded"` e `payload.exitCode === 2` | `{ status: "rejected", ...merge(stdout) }` — exit 2 |
60
+ | `status: "failed"`, ou `exitCode === 1` | `{ status: "error", error: { message, code }, ...merge(stdout) }` — exit 1 |
61
+
62
+ `merge(stdout)`: se o `stdout` do comando-filho é um objeto JSON, suas chaves são espalhadas no
63
+ resultado (quando o filho já é `json: true`, o `status` dele coincide com o do contrato);
64
+ colisão real de `status` → o `stdout` inteiro vai para `raw` e o `status` do contrato prevalece.
65
+ `stdout` que não é JSON → `raw: "<texto>"`. `stderr` não vazio → stderr.
66
+
67
+ O **consumo MCP** (`tools/call`) **não** passa por `toContract` — o MCP tem o próprio contrato
68
+ de protocolo e continua recebendo o `ExecutionResult`.
69
+
70
+ Com isso, `spec:check` e `tools:doctor` passam a `json: true` no registry — fecha D7.
71
+
72
+ ## Alternativas consideradas
73
+
74
+ - **Gerar só um sentido do mapeamento e inferir o outro** — frágil para flags e `rest`; o
75
+ round-trip explícito é mais barato de garantir.
76
+ - **`toContract` em `apps/cli` / mudar `normalizeCliResult`** — quebraria o consumo MCP, que
77
+ depende do `ExecutionResult`.
78
+ - **Aninhar sempre em `output`** em vez de `merge` flat — contraria o ADR-0082 ("campos ao lado
79
+ de `status`") e piora a ergonomia para o agente.
80
+ - **Cobrir também `orchestrate` start e `llm:*`** — efeito/contrato grandes demais para esta
81
+ rodada; ficam para specs próprias.
82
+
83
+ ## Consequências
84
+
85
+ **Positivas**:
86
+ - `tools/list` do MCP passa de 6 para ~18; o fluxo SDD roda por `tools/call`.
87
+ - Adicionar um comando à cobertura vira uma entrada declarativa + uma fixture de round-trip.
88
+ - `--json` de qualquer comando-capability segue um contrato único.
89
+
90
+ **Negativas / Trade-offs**:
91
+ - **Mudança de forma**: o `--json` de comando-capability deixa de emitir o `ExecutionResult` cru
92
+ e passa a emitir o objeto do contrato. Sem consumidor externo conhecido (o MCP usa
93
+ `tools/call`, não `--json`). Registrado no CHANGELOG.
94
+ - Mais capabilities carregadas em todo `mcp:start`; o custo por capability é só o registro (o
95
+ handler continua spawnando `node bin/forja.ts <cmd>` sob demanda).
96
+ - A lista de 18 é um ponto de pressão ("só mais esse"); o critério acima é o que decide, e o que
97
+ estiver fora dele exige nova spec.
98
+
99
+ ## Rastreamento
100
+
101
+ - Implementação: `apps/cli/src/params.ts`, `apps/cli/src/index.ts`, `bin/forja.ts`, `lib/core/registry.ts`
102
+ - Testes: `test/cli-params.test.js`, `test/mcp-coverage.test.js`, `test/cli-output-contract.test.js`
103
+ - [Spec](../../specs/mcp-cobertura-nucleo/spec.md) · [Contrato de saída](../../docs/contrato-saida-cli.md) · ADR-0082 (contrato de saída), ADR-0020 (core/registry)
@@ -0,0 +1,79 @@
1
+ # ADR-0084: Drift Sentinel (SPEC-030) fecha — gate opt-in permanente, métrica reformulada
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-09-08
5
+ - **Autor(es)**: Allan Pablo / Claude
6
+ - **Tags**: drift, graph, governance, sdd
7
+
8
+ ## Contexto
9
+
10
+ SPEC-030 entregou `drift:check` — reindexação determinística do workspace que sinaliza quando uma
11
+ relação `verified` do Engineering Graph deixou de ser reproduzível a partir do conteúdo atual do
12
+ documento que a originou. AC-1 a AC-5 estão implementados (`lib/drift-sentinel.ts`,
13
+ `scripts/drift-check.ts`, `lib/core/drift-gate.ts` ligando ao `check:all --with-drift` opt-in),
14
+ com testes em `test/drift-sentinel.test.js`.
15
+
16
+ A spec está `implementing` desde 2026-08-31 por um único motivo: a **métrica de sucesso do §8** —
17
+ "30 dias após o release, rodar `drift:check` num projeto real e ativo resulta em ao menos um
18
+ drift genuíno confirmado por um humano". Essa métrica é **infalsificável como bloqueio de
19
+ `done`**: ela depende de drift *acontecer* no mundo, o que ninguém controla nem força. O
20
+ dogfooding local contra o próprio monorepo nunca achou drift — que é o **estado saudável**, não
21
+ uma falha do sentinela. A spec apodrece num limbo enquanto se espera algo que talvez nunca venha
22
+ num intervalo dado.
23
+
24
+ ## Decisão
25
+
26
+ **1 — `drift:check` permanece como gate opt-in (`check:all --with-drift`), nunca default.** O
27
+ custo (reindex completo do workspace) justifica o opt-in; o valor (pegar uma aresta `verified`
28
+ que morreu em silêncio) justifica manter o comando disponível e ligado ao `check:all` sob flag.
29
+ Nenhuma mudança no wiring atual.
30
+
31
+ **2 — `forja drift:check --all` é adicionado.** Roda `drift:check` uma vez por projeto do
32
+ workspace (`listProjects()`), cada um contra o próprio dir (`FORJA_GRAPH_ROOT`) e um grafo
33
+ **isolado e persistente** em `<projeto>/.context/drift-graph.db`. A primeira rodada de um projeto
34
+ semeia o grafo; da segunda em diante, compara. É o uso em lote que a user story 3 da SPEC-030
35
+ pede — "rodar antes de retomar um projeto que não toco há meses". Subprocess por projeto (mesmo
36
+ padrão de `drift-gate.ts`), sem misturar grafos.
37
+
38
+ **3 — O §8 da SPEC-030 é reformulado para um aceite observável agora:**
39
+ - `drift:check` é determinístico (mesmo input → mesmo resultado em duas rodadas);
40
+ - roda contra o monorepo reportando **zero** drift (nenhum falso positivo);
41
+ - `drift:check --all` completa sobre o workspace (0 projetos → saída limpa; N projetos → semeia).
42
+
43
+ **4 — "Drift real encontrado no mundo" vira janela de observação, não bloqueio.** Até
44
+ **2026-10-08** (30 dias): se **nenhum** drift real for confirmado **E** um falso positivo **for**
45
+ reportado, revisitar — rebaixar `drift:check` a ferramenta manual (tirar do `check:all`). Na
46
+ ausência dessa combinação, o comando fica como está.
47
+
48
+ **5 — SPEC-030 vai para `done`.**
49
+
50
+ ## Alternativas consideradas
51
+
52
+ - **Continuar esperando a métrica original.** Rejeitado: infalsificável como gate de `done`; a
53
+ spec fica em `implementing` indefinidamente e o processo perde credibilidade.
54
+ - **Rebaixar agora** (tirar `drift:check` do `check:all`). Rejeitado: não há evidência de que o
55
+ sinal seja ruidoso — zero falso positivo no dogfooding. Rebaixar sem dado é tão arbitrário
56
+ quanto esperar sem prazo.
57
+ - **`--all` reindexando tudo num grafo só.** Rejeitado: misturaria nós de N projetos; o subprocess
58
+ por projeto com grafo isolado é limpo e reusa o mecanismo existente.
59
+
60
+ ## Consequências
61
+
62
+ **Positivas**:
63
+ - A spec sai do limbo com um aceite que se pode verificar hoje.
64
+ - Consultores com muitos projetos gerados ganham o modo lote que a spec previa.
65
+ - A pergunta "o sinal vale o custo?" tem um prazo e um critério de revisão, não um "algum dia".
66
+
67
+ **Negativas / Trade-offs**:
68
+ - O valor de campo do `drift:check` (pegar um drift real antes de um humano tropeçar) continua
69
+ **não comprovado** — só a corretude e o não-ruído estão. A janela de observação assume isso
70
+ explicitamente.
71
+ - `--all` persiste um `.context/drift-graph.db` por projeto; é gitignorado no gerado, mas ocupa
72
+ disco e cresce com o histórico.
73
+
74
+ ## Rastreamento
75
+
76
+ - Implementação: `scripts/drift-check.ts` (`--all`), `lib/drift-sentinel.ts` (motor, inalterado)
77
+ - [Spec](../../specs/drift-sentinel/spec.md) (SPEC-030) · ADRs relacionadas: ADR-0078 (Engineering
78
+ Control Plane), a auditoria de 2026-08-31 que originou a SPEC-030
79
+ - Revisão da janela de observação: 2026-10-08