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
@@ -0,0 +1,224 @@
1
+ # Tasks: cli-intuitiva-v1
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Plan**: ./plan.md
5
+ - **Status**: approved
6
+ - **Criado em**: 2026-09-07
7
+
8
+ > Decomposição executável. Cada task tem dono claro, critério de done e referência a arquivos.
9
+
10
+ Convenção de IDs: `T1`, `T2`, … Sequência = ordem padrão. Paralelizável onde indicado.
11
+
12
+ Grafo de dependência:
13
+
14
+ ```
15
+ T1 ─┬─ T2 ─┬─ T3 ── T4 ─┐
16
+ │ ├─ T6 ────────┤
17
+ │ └────────────►T10
18
+ ├─ T5 ──────────────►T10
19
+ ├─ T7 ── T8 │
20
+ └─ T9 ───────────────┤
21
+ T3,T4,T9 ─► T11 │
22
+ todas ───────────────────►T12
23
+ ```
24
+
25
+ Paralelizável após T1: **T2 · T5 · T7 · T9**.
26
+
27
+ ---
28
+
29
+ ## T1 — Campos opcionais no tipo do registry + retrocompat
30
+ - **Owner**: Worker
31
+ - **Estimativa**: P
32
+ - **Depende de**: —
33
+ - **Paths**: `lib/core/registry.ts`, `test/forja-core.test.js`
34
+ - **Escopo**: adicionar `type CommandArg = { name; required; desc }` e os campos **opcionais**
35
+ ao tipo do comando: `usage?`, `cliArgs?`, `examples?`, `next?`, `spec?`, `readonly?`, `json?`,
36
+ `tier?: 'core'|'advanced'`. Nenhum valor preenchido ainda. Sem mudança de comportamento.
37
+ - **Done quando**:
38
+ - [ ] `tsc --noEmit` verde
39
+ - [ ] teste novo: comando sem nenhum campo novo resolve e executa (retrocompat) — AC-1
40
+ - [ ] `node --test test/*.test.js` verde (473 → 474+)
41
+
42
+ ## T2 — Preencher os 14 comandos do núcleo
43
+ - **Owner**: Worker
44
+ - **Estimativa**: M
45
+ - **Depende de**: T1
46
+ - **Paths**: `lib/core/registry.ts`
47
+ - **Escopo**: nos 14 comandos do núcleo (plan §D4: `workspace:init`, `project:new`, `spec:new`,
48
+ `spec:plan`, `spec:tasks`, `spec:check`, `orchestrate`, `orchestrate:status`,
49
+ `orchestrate:advance`, `context:smart`, `query:universal`, `tools:doctor`, `project:check`,
50
+ `engineer`) definir `tier:'core'`, `usage`, `cliArgs` (quando houver posicional), ≥1 `example`
51
+ (começa com `forja `, cita comando do registry), `next`. Mover `(SPEC-0XX)` de `desc` → `spec`.
52
+ - **Done quando**:
53
+ - [ ] 14 comandos com `tier:'core'` + `usage` + ≥1 `example` — AC-1
54
+ - [ ] nenhuma `desc` do núcleo contém `(SPEC-`
55
+ - [ ] `node --test test/*.test.js` + `tsc --noEmit` verdes
56
+
57
+ ## T3 — `printHelp()` em camadas + `forja help --all`
58
+ - **Owner**: Worker
59
+ - **Estimativa**: P
60
+ - **Depende de**: T2
61
+ - **Paths**: `bin/forja.ts`
62
+ - **Escopo**: default = só `tier:'core'`, agrupado por domínio, **sem** sufixo `(SPEC-`, com
63
+ rodapé `use 'forja help --all' para os N comandos restantes`. `forja help --all` = saída atual
64
+ completa. Ajustar o teste `help: sem args lista domínios` para verificar `--all` (a lista curta
65
+ não cobre os domínios `design`/`llm`/`geracao`).
66
+ - **Done quando**:
67
+ - [ ] `forja help --all` diff vs. baseline atual = apenas remoção de `(SPEC-` nas `desc` do núcleo — AC-3
68
+ - [ ] `forja help` mostra só núcleo + rodapé com contagem correta
69
+ - [ ] testes de help verdes
70
+
71
+ ## T4 — `printCommandHelp()` + branch `help <cmd>`
72
+ - **Owner**: Worker
73
+ - **Estimativa**: M
74
+ - **Depende de**: T2, T3
75
+ - **Paths**: `bin/forja.ts`
76
+ - **Escopo**: `forja help <cmd>` imprime nome, domínio, `desc`, `usage`, tabela de `cliArgs`,
77
+ `examples`, "Próximos passos" (`next`), e `spec` (origem SPEC/ADR) quando houver. `<cmd>`
78
+ inexistente → `suggest()` + exit 1. Sem `--json` nesta spec.
79
+ - **Done quando**:
80
+ - [ ] `forja help spec:new` mostra `usage` + ≥1 exemplo + próximos passos — AC-2
81
+ - [ ] `forja help xpto` → exit 1 com sugestão
82
+ - [ ] `forja help` (sem cmd) e `forja help --all` seguem funcionando
83
+
84
+ ## T5 — `suggest()` fuzzy + mensagens de erro acionáveis
85
+ - **Owner**: Worker
86
+ - **Estimativa**: P
87
+ - **Depende de**: — (paralelo a T2–T4)
88
+ - **Paths**: `bin/forja.ts` (+ helper Levenshtein inline, ~15 linhas DP — plan §D3)
89
+ - **Escopo**: `suggest()` casa por substring **e** distância de edição ≤ 2 sobre o **nome
90
+ completo**; ordena (substring exato → menor distância); teto 5. Mensagem de comando
91
+ desconhecido termina com `forja help <melhor-palpite>`.
92
+ - **Done quando**:
93
+ - [ ] `suggest('plan')` inclui `spec:plan` — AC-4
94
+ - [ ] `forja plan` → stderr contém `forja help spec:plan`, exit 1, sem stack trace
95
+ - [ ] teste existente "comando desconhecido: exit 1 com sugestão" verde
96
+
97
+ ## T6 — Pré-validação de `cliArgs` required antes do spawn
98
+ - **Owner**: Worker
99
+ - **Estimativa**: P
100
+ - **Depende de**: T1, T2
101
+ - **Paths**: `bin/forja.ts`
102
+ - **Escopo**: antes de `spawnSync`, se `cmd.cliArgs` tem entrada `required:true` sem posicional
103
+ correspondente em `rest` (contar posicionais, ignorar `--flags` e seus valores), imprimir
104
+ `cmd.usage` em stderr, exit 1, **sem spawnar**. Auditar como hoje (`exitCode: 1`).
105
+ - **Done quando**:
106
+ - [ ] `forja spec:new` (sem slug) → imprime `usage`, exit 1, stderr sem stack trace do filho — AC-5
107
+ - [ ] `forja spec:new foo` executa normalmente
108
+ - [ ] comandos sem `cliArgs` inalterados
109
+
110
+ ## T7 — `bucket` nos checks de `lib/core/health.ts`
111
+ - **Owner**: Worker
112
+ - **Estimativa**: P
113
+ - **Depende de**: — (paralelo)
114
+ - **Paths**: `lib/core/health.ts`
115
+ - **Escopo**: cada check declara `bucket: 'blocking' | 'first-run' | 'optional'`. Classificação:
116
+ `native-abi`, `node-engines`, `runtime-deps`, `mcp-json`, `docs-commands`,
117
+ `commands-documented`, `docs-links`, `adr-refs`, `agent-topology` → **blocking**;
118
+ `memory-db` (não indexado), `memory-fresh`, `workspace` → **first-run**;
119
+ ferramentas ADR-0018 (`codegraph`, `gitleaks`, …) → **optional**. `runChecks`/`worstStatus` e
120
+ o exit-code do gate **inalterados**.
121
+ - **Done quando**:
122
+ - [ ] todo check tem `bucket` — AC-7 (base)
123
+ - [ ] `tsc --noEmit` + testes de health existentes verdes
124
+
125
+ ## T8 — Render em 3 blocos: `tools:doctor` + hook SessionStart
126
+ - **Owner**: Worker
127
+ - **Estimativa**: M
128
+ - **Depende de**: T7
129
+ - **Paths**: `scripts/tools-doctor.ts`, `scripts/hook-session-start.ts`
130
+ - **Escopo**: agrupar a saída pelos 3 rótulos fixos — **"Bloqueia o fluxo"**, **"Rotina de
131
+ primeiro uso"**, **"Opcional (ferramentas)"**. O bloco first-run cita `forja setup` como
132
+ correção. Exit code do doctor inalterado. O hook SessionStart usa a mesma classificação no
133
+ bloco `<framework-status>`.
134
+ - **Done quando**:
135
+ - [ ] `forja tools:doctor` mostra os 3 rótulos; em clone novo, `workspace`/`memory-db` sob "Rotina de primeiro uso" — AC-7
136
+ - [ ] exit 0 "com ressalvas" preservado; falha crítica ainda exit 1
137
+ - [ ] `hook-session-start` renderiza os 3 buckets
138
+
139
+ ## T9 — `forja setup`
140
+ - **Owner**: Worker
141
+ - **Estimativa**: M
142
+ - **Depende de**: T1
143
+ - **Paths**: `scripts/forja-setup.ts` (**novo**), `lib/core/registry.ts` (entrada `setup`)
144
+ - **Escopo**: allowlist **fixa e hard-coded** `['workspace:init', 'sync:universal']`, em ordem.
145
+ Sem `--yes` + TTY → confirmação `[s/N]`. Sem `--yes` + stdin não-TTY → aborta exit 1, **nada
146
+ executado**. Cada passo auditado em `forja-runs.jsonl`. Idempotente. Entrada no registry:
147
+ domínio `workspace`, `tier:'core'`, `readonly:false`, `usage`/`examples`/`next`.
148
+ - **Done quando**:
149
+ - [ ] `forja setup --yes` em `FORJA_WORKSPACE` temporário limpo → estrutura criada + índice, exit 0 — AC-6
150
+ - [ ] 2ª execução → exit 0 (idempotente)
151
+ - [ ] sem `--yes` e stdin não-TTY → exit 1, `getWorkspaceInfo().exists` inalterado
152
+ - [ ] `forja help` (core) lista `setup`
153
+
154
+ ## T10 — Testes AC-8 em `forja-core.test.js`
155
+ - **Owner**: Worker
156
+ - **Estimativa**: P
157
+ - **Depende de**: T2, T4, T5, T6
158
+ - **Paths**: `test/forja-core.test.js`
159
+ - **Escopo**: (a) todo `tier:'core'` tem `usage` não-vazio e ≥ 1 `example`; (b) todo `example`
160
+ começa com `forja ` e o 2º token existe em `COMMANDS`; (c) `suggest('plan')` inclui
161
+ `spec:plan`; ajustar o teste de domínios para `--all`.
162
+ - **Done quando**:
163
+ - [ ] `node --test test/forja-core.test.js` verde — AC-8
164
+ - [ ] falha proposital (remover um `usage` do núcleo) faz o teste (a) quebrar
165
+
166
+ ## T11 — Documentação + CHANGELOG
167
+ - **Owner**: Worker
168
+ - **Estimativa**: P
169
+ - **Depende de**: T3, T4, T9
170
+ - **Paths**: `docs/quick-reference.md`, `docs/cli-first-operacao.md`, `DOC-MAP.md`, `CHANGELOG.md`
171
+ - **Escopo**: documentar `forja help <cmd>`, `forja help --all`, `forja setup`. Entrada no
172
+ CHANGELOG (Adicionado: help em camadas, `help <cmd>`, `forja setup`; Alterado: saída de
173
+ `tools:doctor` em 3 blocos — aditivo).
174
+ - **Done quando**:
175
+ - [ ] `forja tools:doctor` → `docs-commands`, `commands-documented`, `docs-links` verdes
176
+ - [ ] CHANGELOG atualizado
177
+
178
+ ## T12 — Validação final + fecho de contrato
179
+ - **Owner**: Worker → Governance
180
+ - **Estimativa**: P
181
+ - **Depende de**: T1–T11
182
+ - **Escopo**: rodar a bateria; atualizar `spec.md` §Evidências com as 2 mudanças de contrato
183
+ (D1 `args`→`cliArgs`; D2 `tools:doctor --fix`→`forja setup`); mover status.
184
+ - **Done quando**:
185
+ - [ ] `node --test test/*.test.js`, `tsc --noEmit`, `node bin/forja.ts spec:check` verdes — AC-9
186
+ - [ ] `spec.md` §Evidências registra D1 e D2
187
+ - [ ] `spec:set-status … spec implementing` no início da execução; `done` ao fim
188
+
189
+ ---
190
+
191
+ ## Mapa AC → task
192
+
193
+ | AC | Tasks | Verificação-chave |
194
+ |---|---|---|
195
+ | AC-1 | T1, T2 | `tsc --noEmit`; teste de retrocompat |
196
+ | AC-2 | T4 | `forja help spec:new`; `forja help xpto` exit 1 |
197
+ | AC-3 | T2, T3 | diff `forja help --all` vs baseline; rodapé em `forja help` |
198
+ | AC-4 | T5 | `suggest('plan') ∋ spec:plan`; `forja plan` → `forja help spec:plan` |
199
+ | AC-5 | T6 | `forja spec:new` sem slug → usage, exit 1, sem stack |
200
+ | AC-6 | T9 | `forja setup --yes` em WS limpo; não-TTY sem `--yes` aborta |
201
+ | AC-7 | T7, T8 | `tools:doctor` com 3 rótulos; hook SessionStart idem |
202
+ | AC-8 | T10 | `node --test test/forja-core.test.js` |
203
+ | AC-9 | T12 | bateria completa verde |
204
+
205
+ ## Handoffs entre agentes
206
+
207
+ Cadeia: SDD Architect (spec+plan+tasks, feito) → **Worker** (implement, T1–T11) → **Governance**
208
+ (review, T12 + `project:check`). Registrar via core:
209
+
210
+ ```bash
211
+ node bin/forja.ts hermes:handoff implement cli-intuitiva-v1
212
+ # ao fim:
213
+ node bin/forja.ts hermes:handoff review cli-intuitiva-v1
214
+ ```
215
+
216
+ ## Evidências e estado real
217
+
218
+ - Cada task declara o comando/observação que verifica seu AC (tabela acima).
219
+ - **Hipótese, não medição**: as métricas de §8 da spec dependem de instrumentação inexistente;
220
+ baseline sobre `forja-runs.jsonl` antes de qualquer percentual.
221
+ - **Mudanças de contrato pendentes de registro na spec** (T12): D1 (`args`→`cliArgs`),
222
+ D2 (`tools:doctor --fix`→`forja setup`).
223
+ - **Fora de escopo** (herdado): bug de alocação de ID do `spec:new` (achado A9 do roadmap).
224
+ - Nada aqui foi executado ainda — todas as caixas `[ ]` abertas.
@@ -0,0 +1,162 @@
1
+ # Plan: contrato-saida-cli
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Status**: approved
5
+ - **Criado em**: 2026-09-08
6
+
7
+ > Como vamos construir o que a spec define. Sem código aqui — só estrutura e decisões.
8
+
9
+ ## 1. Abordagem técnica
10
+
11
+ **Um contrato escrito, um helper que o torna mecânico, um teste que o guarda.** ADR-0082 e
12
+ `docs/contrato-saida-cli.md` fixam a regra. `lib/cli-output.ts` (novo) dá três funções —
13
+ `emitOk`, `emitError`, `emitRejected` — que escrevem o JSON no formato certo e devolvem o exit
14
+ code certo; conformar um script é trocar `console.log(JSON.stringify(x))` + `process.exitCode` por
15
+ uma dessas. `test/cli-output-contract.test.js` roda cada comando `json: true` com `--json` e
16
+ afirma forma + exit code. `bin/forja.ts` só ganha um comentário com a tabela — o exit code do
17
+ filho já passa direto.
18
+
19
+ ## 2. Módulos afetados
20
+
21
+ | Caminho | Mudança | Risco |
22
+ |---|---|---|
23
+ | `memory/90-decisions/0082-contrato-saida-cli.md` | **criar** — o contrato (status accepted; Allan aprovou incluindo as quebras) | B |
24
+ | `docs/contrato-saida-cli.md` | **criar** — para autores e consumidores, com exemplos | B |
25
+ | `DOC-MAP.md` | editar — uma linha para o doc novo | B |
26
+ | `lib/cli-output.ts` | **criar** — `emitOk(fields)`, `emitError(message, code?)`, `emitRejected(fields)`; cada uma faz `console.log(JSON.stringify(...))` no stdout e `process.exit(0\|1\|2)` | B |
27
+ | `scripts/forja-status.ts` | editar — trocar os `console.log(JSON.stringify(...))` por `emitOk` (já é conformante na forma; passa a usar o helper) | B |
28
+ | `scripts/engineer.ts` | editar — `--json` passa por `emitOk({ ...report })`; erro de arg → `emitError` | M |
29
+ | `scripts/simulate.ts` | editar — `emitOk` no caminho normal; **recommendation `discard` → `emitRejected` (exit 2)**; erro de arg → `emitError` | M |
30
+ | `scripts/cost-economy.ts` | editar — os `console.log` de aviso vão para **stderr**; `--json` → `emitOk({ status, ...rows })` | M |
31
+ | `scripts/token-economy.ts` | editar — `--json` **deixa de emitir array cru**; passa a `emitOk({ status, rows: [...] })` | M |
32
+ | `scripts/spec-cli.ts` | editar — **adicionar** `--json` ao subcomando `check`: `emitOk({ status, features: [{slug, spec, plan, tasks}] })` | M |
33
+ | `scripts/tools-doctor.ts` | editar — **adicionar** `--json`: `emitOk`/`emitError({ status, core: [...], tools: [...] })` a partir do que `runChecks` já devolve; texto atual quando sem `--json` | M |
34
+ | `lib/core/registry.ts` | editar — `json: true` no conjunto conformado; `--json` no `usage`/`examples` de cada um | B |
35
+ | `bin/forja.ts` | editar — bloco de comentário com a tabela de exit codes junto ao dispatch; sem mudança de comportamento | B |
36
+ | `test/cli-output-contract.test.js` | **criar** — AC-6 | B |
37
+ | `CHANGELOG.md` | editar — `[Unreleased]`: Adicionado (contrato, `--json` em `spec:check`/`tools:doctor`); **Alterado/Breaking** (`token:economy --json`, `simulate` discard exit) | B |
38
+
39
+ ## 3. Diagrama de fluxo
40
+
41
+ ```
42
+ qualquer script com --json
43
+ │
44
+ ├─ sucesso → emitOk({ status:'ok', ...campos }) → stdout: 1 objeto JSON, exit 0
45
+ ├─ erro operacional → emitError('mensagem', 'CODE?') → stdout: {status:'error', error:{message,code?}}, exit 1
46
+ │ (diagnóstico verboso → stderr)
47
+ └─ validação/gate neg → emitRejected({ status:'rejected', ...payload }) → stdout: 1 objeto JSON, exit 2
48
+
49
+ binário externo obrigatório ausente → bin/forja.ts → exit 127 (já existe)
50
+
51
+ sem --json → comportamento atual, inalterado
52
+ ```
53
+
54
+ ## 4. Contratos (API/CLI/Schema)
55
+
56
+ ```ts
57
+ // lib/cli-output.ts
58
+ type Json = Record<string, unknown>;
59
+
60
+ /** stdout = {status:'ok', ...fields}; process.exit(0). */
61
+ export function emitOk(fields?: Json): never;
62
+
63
+ /** stdout = {status:'error', error:{message, code?}}; process.exit(1). `detail` opcional vai para stderr. */
64
+ export function emitError(message: string, opts?: { code?: string; detail?: string }): never;
65
+
66
+ /** stdout = {status:'rejected', ...fields}; process.exit(2). Para quando um gate/validação do próprio comando deu negativo. */
67
+ export function emitRejected(fields?: Json): never;
68
+ ```
69
+
70
+ **Tabela de exit codes (todos os modos, não só `--json`)**:
71
+
72
+ | code | significado |
73
+ |---|---|
74
+ | 0 | sucesso (`status:'ok'`) |
75
+ | 1 | erro operacional: args inválidos, arquivo ausente, subsistema fora (`status:'error'`) |
76
+ | 2 | validação/gate do comando deu negativo (`status:'rejected'`) — ex.: `llm:run`, `simulate` discard |
77
+ | 127 | binário externo obrigatório ausente (só `bin:` no registry; `bin/forja.ts` já cuida) |
78
+
79
+ **Conjunto `json: true` fechado** (AC-5, ajustado na implementação): `status`, `next` (já
80
+ conformes da SPEC-044), `engineer`, `simulate`, `cost:economy`, `token:economy`.
81
+ `spec:check` e `tools:doctor` **saíram** (ver D7). `risk:assess` fica de fora (orientado a
82
+ arquivo; `--json` lá é backlog).
83
+
84
+ ## 5. Decisões e alternativas
85
+
86
+ **D1 — `status` flat, não um envelope `{status, data, meta}`.** Os campos do comando ficam ao
87
+ lado de `status`. Alinha com `llm:run`, que já expõe `executionStatus`/`validationStatus` no
88
+ topo. Rejeitado: envelope aninhado (mais profundidade para o agente navegar, e quebraria o
89
+ formato que `llm:run`/`status`/`next` já usam).
90
+
91
+ **D2 — Helper `lib/cli-output.ts` com `process.exit`, não um objeto de retorno.** As três funções
92
+ terminam o processo. Conformar vira substituição direta. Rejeitado: devolver `{json, code}` para
93
+ o script imprimir (cada script erra de um jeito diferente — foi como chegamos aqui).
94
+
95
+ **D3 — `spec:check` e `tools:doctor` ganham `--json` nesta spec.** São os dois que um agente mais
96
+ quer estruturados e ambos já têm o dado pronto por dentro (`runChecks(): Result[]`; os triples de
97
+ status das specs). Rejeitado adiar: sem eles o contrato nasce sem os comandos mais consumidos.
98
+
99
+ **D4 — `token:economy --json`: array → `{status, rows}`. Breaking, aceito.** É o único cujo
100
+ formato JSON muda. `--json` desse comando é recente e sem consumidor externo conhecido. ADR-0082
101
+ e CHANGELOG registram. Alternativa (manter o array e pôr `status` num header): rejeitada — viola
102
+ "stdout = um objeto".
103
+
104
+ **D5 — `simulate`: recommendation `discard` passa de exit 1 para exit 2 (`rejected`).** Hoje usa
105
+ `1`, que colide com "erro operacional". `discard` é o gate do simulate dizendo "não promova" — é
106
+ `rejected`. Alternativa (deixar 1): rejeitada — apaga a distinção que o contrato existe para criar.
107
+
108
+ **D6 — ADR-0082 `accepted`, não `proposed`.** Allan aprovou a spec incluindo D4 e D5.
109
+
110
+ **D7 — `spec:check` e `tools:doctor` saem do conjunto (descoberto na implementação).** Os dois
111
+ são roteados como **capability MCP** por `bin/forja.ts` (`capabilityIdForCommand` → `apps/cli/
112
+ src/index.ts`): o `--json` é consumido pelo dispatcher, o script roda sem ele, e a saída é
113
+ embrulhada no envelope `{ status: 'succeeded'|'failed', output: { payload } }`. Fazer o script
114
+ conformar seria código morto atrás do envelope. Alinhar o **envelope da capability** ao contrato
115
+ é trabalho de W6 (cobertura MCP). Registrado no ADR-0082 e no §Evidências da spec.
116
+
117
+ ## 6. Dependências
118
+
119
+ - **Spec `cli-intuitiva-v1` (SPEC-043)** — o campo `json` do registry já existe.
120
+ - **Spec `forja-status-caminho-feliz` (SPEC-044)** — `status`/`next` são o formato de referência;
121
+ branch empilhada sobre `feat/forja-status`.
122
+ - **Pacotes npm**: nenhum.
123
+ - **Migrações**: nenhuma.
124
+
125
+ ## 7. Rollout
126
+
127
+ - [ ] Feature flag: não.
128
+ - [ ] Migração de dados: não.
129
+ - [ ] Doc/persona: `docs/contrato-saida-cli.md` novo + `DOC-MAP.md`; `docs/llm-fit-loop.md` já
130
+ descreve o contrato de `llm:run` — adicionar um "ver contrato-saida-cli.md".
131
+ - [ ] `CHANGELOG.md` `[Unreleased]`: **Adicionado** (contrato + `--json` em `spec:check` e
132
+ `tools:doctor`); **Alterado (breaking, `--json` só)**: `token:economy` array→objeto;
133
+ `simulate` discard exit 1→2.
134
+
135
+ ## 8. Sinais de fracasso (kill criteria)
136
+
137
+ - Conformar `cost:economy`/`token:economy` esbarra em lógica de negócio entrelaçada com o
138
+ `console.log` → congelar esses dois em "backlog de conformidade" e entregar o contrato + o
139
+ helper + `status`/`next`/`spec:check`/`tools:doctor`/`engineer`/`simulate`.
140
+ - `tools:doctor --json` exige refatorar `printCore`/`printTools` a ponto de arriscar o exit-code
141
+ do gate → entregar `spec:check --json` só, e deixar `tools:doctor --json` para uma spec própria.
142
+ - O teste de conformidade fica flaky por depender de estado do workspace → rodar cada comando num
143
+ `FORJA_WORKSPACE` temporário fixo, com fixtures mínimas.
144
+
145
+ ## Evidências e estado real
146
+
147
+ | AC | Task | Verificação |
148
+ |---|---|---|
149
+ | AC-1 | T1 | ADR-0082 existe, `adr-refs` do doctor verde |
150
+ | AC-2 | T2 | `docs/contrato-saida-cli.md` + `DOC-MAP.md`; `docs-links`/`commands-documented` verdes |
151
+ | AC-3 | T3 | `lib/cli-output.ts` + testes unitários das 3 funções (forma + exit) |
152
+ | AC-4 | T8 | comentário da tabela em `bin/forja.ts`; `forja-core` test verde |
153
+ | AC-5 | T4, T5, T6 | registry `json:true` no conjunto; `forja help <cmd>` cita `--json` |
154
+ | AC-6 | T7 | `node --test test/cli-output-contract.test.js` verde |
155
+ | AC-7 | T5, T6 | `token:economy --json` → objeto; `simulate` discard → exit 2; saída default inalterada (snapshot) |
156
+ | AC-8 | T4 | `usage`/`examples` dos `json:true` mencionam `--json` |
157
+ | AC-9 | T9 | bateria completa verde |
158
+
159
+ - **Mudança de contrato**: `token:economy --json` (array → `{status,rows}`), `simulate` discard
160
+ (exit 1 → 2). No ADR-0082 e no CHANGELOG.
161
+ - **Hipótese, não medição**: métricas de §8 dependem de agregação da flag `--json` do
162
+ `forja-runs.jsonl`, que ninguém faz ainda.
@@ -0,0 +1,157 @@
1
+ # Spec: contrato-saida-cli — `--json` e exit codes como contrato de máquina
2
+
3
+ - **ID**: SPEC-045
4
+ - **Status**: done
5
+ - **Owner**: apk
6
+ - **Criado em**: 2026-09-08
7
+ - **Sprint alvo**: <a definir>
8
+ - **ADRs relacionadas**: **ADR-0082** (nova — o contrato de saída).
9
+ - **Origem**: `docs/roadmap-v4.1.md`, Onda 2 (W5).
10
+ - **Depende de**: `cli-intuitiva-v1` (SPEC-043) — o campo `json` do registry já existe;
11
+ `forja-status-caminho-feliz` (SPEC-044) — `status`/`next` já nascem com o formato-alvo.
12
+ Branch empilhada sobre `feat/forja-status`.
13
+
14
+ ## 1. Problema
15
+
16
+ Um agente LLM que dirige o Forja por automação não tem um contrato estável de máquina. Hoje:
17
+
18
+ - `--json` é ad-hoc por script. `simulate` e `engineer` emitem um `report` sem chave de status;
19
+ `token:economy` emite um **array cru**; `cost:economy` emite um objeto de forma diferente.
20
+ Nenhum tem uma chave comum que diga "deu certo?".
21
+ - Exit codes variam: alguns scripts fazem `process.exitCode = 1` em erro de argumento, `simulate`
22
+ usa `1` também para "recomendação = discard", `llm:run` usa **2** para "validação reprovou"
23
+ (documentado), `bin/forja.ts` já devolve **127** para binário ausente. Não há uma tabela.
24
+ - Diagnóstico e resultado se misturam no stdout: um `console.log` de aviso no meio quebra o
25
+ `JSON.parse` de quem consome.
26
+
27
+ **Como medimos hoje**: não há instrumentação. Evidência: `grep -rl "\-\-json" scripts/` → 10
28
+ scripts, 4 formatos diferentes.
29
+
30
+ ## 2. Proposta de valor
31
+
32
+ Um contrato único, documentado e testado: **`--json` sempre emite um objeto JSON parseável com
33
+ uma chave `status`; os exit codes seguem uma tabela fixa (0 / 1 / 2 / 127)**. Comandos marcados
34
+ `json: true` no registry cumprem o contrato e um teste de conformidade os verifica. Automação
35
+ (inclusive agentes LLM) decide o próximo passo lendo `status` + exit code, sem parsear texto.
36
+
37
+ ## 3. User stories
38
+
39
+ - **Como** agente LLM em automação, **quero** que todo comando `--json` devolva `{ "status": … }`
40
+ e um exit code da tabela, **para que** eu ramifique sem interpretar prosa.
41
+ - **Como** autor de script novo no Forja, **quero** o contrato num doc + um teste que falha se eu
42
+ desviar, **para que** a conformidade não dependa de memória.
43
+ - **Como** operador, **quero** que `--json` mande diagnóstico para o stderr, **para que** o stdout
44
+ seja sempre um único valor JSON.
45
+
46
+ ## 4. Critérios de aceite (Definition of Done)
47
+
48
+ - [ ] **AC-1**: **ADR-0082** registra o contrato: chave `status`, valores, tabela de exit codes,
49
+ regra "stdout = um único JSON, diagnóstico no stderr", e que é **aditivo e incremental**
50
+ (não obriga todo comando a suportar `--json`).
51
+ - [ ] **AC-2**: `docs/contrato-saida-cli.md` descreve o contrato para quem escreve e quem consome,
52
+ com exemplos, e é citado no `DOC-MAP.md`.
53
+ - [ ] **AC-3**: o contrato:
54
+ - `--json` → stdout carrega **exatamente um** valor JSON, um **objeto**, com string `status`:
55
+ - `"ok"` — sucesso → exit **0**
56
+ - `"error"` — falha operacional (args inválidos, arquivo ausente, subsistema fora) → exit
57
+ **1**, com `error: { message, code? }`
58
+ - `"rejected"` — uma validação/gate que o comando roda deu negativo (caso `llm:run` /
59
+ `simulate`) → exit **2**, com o payload ainda presente
60
+ - `127` reservado para binário externo obrigatório ausente (já em `bin/forja.ts`)
61
+ - campos específicos do comando ficam **ao lado** de `status` (flat), não sob um `data`
62
+ - `--json` implica: sem ANSI, sem prompt interativo (falha em vez de perguntar)
63
+ - [ ] **AC-4**: `bin/forja.ts` — comentário/normalização que documenta a tabela de exit codes num
64
+ lugar; nenhuma mudança de comportamento para comandos que já saem 0/1/127.
65
+ - [ ] **AC-5**: conjunto inicial marcado `json: true` no registry e **conformado**:
66
+ `status`, `next`, `engineer`, `simulate`, `cost:economy`, `token:economy`.
67
+ `spec:check` e `tools:doctor` ficaram **fora**: já emitem JSON, mas pelo envelope da
68
+ capability (roteados como MCP em `apps/cli/src/index.ts`) — alinhar isso é W6.
69
+ `risk:assess` fica para depois (orientado a arquivo). (Ajustado do texto original no `plan`.)
70
+ - [ ] **AC-6**: `test/cli-output-contract.test.js` — para cada comando `json: true`: roda com
71
+ `--json` e argumentos mínimos válidos, e afirma (a) stdout é **um** JSON parseável,
72
+ (b) é objeto com `status` ∈ {`ok`,`error`,`rejected`}, (c) exit code casa com o `status`,
73
+ (d) com args inválidos → `status:"error"` + exit 1.
74
+ - [ ] **AC-7**: os comandos que hoje quase cumprem são adaptados sem mudar a saída **default**
75
+ (sem `--json`): `token:economy` deixa de emitir array cru (embrulha em `{status, rows}`);
76
+ `simulate`/`engineer` ganham `status`; exit code de `simulate` para "discard" passa a `2`
77
+ (`rejected`), não `1`.
78
+ - [ ] **AC-8**: `forja help` de todo comando `json: true` mostra `--json` no `usage` ou num
79
+ exemplo.
80
+ - [ ] **AC-9**: `tsc --noEmit`, `node --test test/*.test.js`, `forja spec:check`,
81
+ `forja project:check` verdes; `forja help --all` sem regressão além do esperado.
82
+
83
+ ## 5. Escopo
84
+
85
+ **Dentro**:
86
+ - ADR-0082 + `docs/contrato-saida-cli.md` + linha no `DOC-MAP.md`.
87
+ - `json: true` no registry para o conjunto do AC-5; adaptação dos scripts do AC-7.
88
+ - `test/cli-output-contract.test.js`.
89
+ - Comentário da tabela de exit codes em `bin/forja.ts`.
90
+
91
+ **Fora** (evita scope creep):
92
+ - Retrofit de `--json` em comandos que hoje não têm (é backlog incremental; o contrato só rege
93
+ quem opta por `json: true`).
94
+ - Mudar a saída **default** (sem `--json`) de qualquer comando.
95
+ - Padronizar a saída de `capabilities:*` / MCP (isso é W6).
96
+ - Um envelope `data`/`meta` aninhado — o contrato é flat de propósito.
97
+ - `--json` no `bin/forja.ts` em si (ele repassa; o formato é de cada script).
98
+
99
+ ## 6. NFRs / restrições
100
+
101
+ - **Compatibilidade**: nenhuma mudança na saída default. `token:economy --json` muda de forma
102
+ (array → objeto) — **é uma quebra do contrato JSON desse comando**, registrada no ADR e no
103
+ CHANGELOG; os outros só ganham a chave `status`.
104
+ - **Performance**: irrelevante (formatação de saída).
105
+ - **Segurança**: `--json` não pode vazar stack trace no stdout; erro vai em `error.message`
106
+ saneado + stderr.
107
+ - **Observabilidade**: exit code auditado em `forja-runs.jsonl` como hoje.
108
+
109
+ ## 7. Riscos e mitigação
110
+
111
+ | Risco | Probabilidade | Impacto | Mitigação |
112
+ |---|---|---|---|
113
+ | Mudar `token:economy --json` quebra algum consumidor | M | M | ADR + CHANGELOG explícitos; é o único cujo formato muda; `--json` desse comando é novo o suficiente para não ter consumidor externo conhecido |
114
+ | "conformar" um script vira refactor grande | M | M | Conjunto do AC-5 é pequeno e fechado no plan; adaptação é embrulhar a saída, não reescrever |
115
+ | `simulate` mudar exit 1→2 para "discard" confunde CI que trata !=0 igual | B | B | CI trata `!= 0` como falha de qualquer jeito; a distinção 1 vs 2 só importa para quem lê o código, e o ADR documenta |
116
+ | Exit code 2 colide com convenção de shell (misuse) | B | B | 2 é livre para o app; documentado; `llm:run` já usa |
117
+
118
+ ## 8. Métricas de sucesso
119
+
120
+ 30 dias, baseline antes:
121
+
122
+ - Todo comando `json: true` passa no teste de conformidade (0 exceções).
123
+ - Adoção: automação/agentes consumindo `--json` desses comandos aparece em `forja-runs.jsonl`
124
+ (flag `--json` nas linhas de auditoria).
125
+ - Zero incidentes de "quebrou meu parse" reportados após a mudança do `token:economy`.
126
+
127
+ ## Evidências e estado real
128
+
129
+ **Implementado em 2026-09-08** na branch `feat/contrato-saida-cli` (sobre `feat/forja-status`).
130
+ Bateria: `tsc --noEmit` limpo; `node --test test/*.test.js` **503/503** (+7: `test/cli-output.test.js`,
131
+ `test/cli-output-contract.test.js`); `forja spec:check` e `forja project:check` (100%) verdes.
132
+
133
+ | AC | Onde | Verificado |
134
+ |---|---|---|
135
+ | AC-1 | `memory/90-decisions/0082-contrato-saida-cli.md` | `adr-refs` do doctor verde (78 ADRs) |
136
+ | AC-2 | `docs/contrato-saida-cli.md`, `DOC-MAP.md` | `docs-links`/`docs-commands` verdes |
137
+ | AC-3 | `lib/cli-output.ts` (`emitOk`/`emitError`/`emitRejected`) | `test/cli-output.test.js` — forma + exit + `detail` no stderr |
138
+ | AC-4 | `bin/forja.ts` — comentário da tabela; arg obrigatório + `--json` → `{status:'error'}` | teste no `cli-output-contract` |
139
+ | AC-5 | `lib/core/registry.ts` `json:true` | `status`, `next`, `engineer`, `simulate`, `cost:economy`, `token:economy` |
140
+ | AC-6 | `test/cli-output-contract.test.js` | itera `json:true` do registry; forma + exit por `status` |
141
+ | AC-7 | `scripts/{token-economy,cost-economy,simulate,engineer,forja-status}.ts` | `token:economy --json`→objeto; `cost:economy --json` sem poluição; `simulate` discard→exit 2; saída default inalterada (testes existentes verdes) |
142
+ | AC-8 | `lib/core/registry.ts` | `--json` no `usage`/`examples` dos 6 |
143
+ | AC-9 | — | bateria acima verde |
144
+
145
+ - **Desvio vs. o plan (D7, descoberto na implementação)**: `spec:check` e `tools:doctor`
146
+ **saíram** do conjunto. São roteados como capability MCP por `bin/forja.ts` — o `--json` é
147
+ consumido pelo dispatcher e a saída sai no envelope `{ status: 'succeeded'|'failed', output }`.
148
+ Conformar o script seria código morto atrás do envelope; alinhar o **envelope** é W6.
149
+ - **Quebras de contrato deliberadas** (ADR-0082 + CHANGELOG): `token:economy --json` (array →
150
+ `{status, rows}`); `simulate` discard (exit 0 → 2, `status:'rejected'` no `--json`). O texto
151
+ original da spec dizia "1 → 2" — na verdade discard não sinalizava exit code algum; agora
152
+ sinaliza 2. Teste `test/simulate-cli.test.js` atualizado.
153
+ - **Também corrigido**: `cost:economy --json` escrevia avisos de texto no stdout, quebrando o
154
+ `JSON.parse`; agora vão para o stderr.
155
+ - **Hipótese, não medição**: os ganhos de §8 dependem de agregação da flag `--json` do
156
+ `forja-runs.jsonl`, que ninguém faz ainda.
157
+ - **Pendências**: revisão de Governança; handoff `review` registrado; depende do merge de #62/#61.