forjajs 4.0.1 → 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.
- package/CHANGELOG.md +111 -7
- package/DOC-MAP.md +1 -0
- package/README.md +7 -2
- package/dist/apps/cli/src/index.d.ts +18 -1
- package/dist/apps/cli/src/index.js +161 -26
- package/dist/apps/cli/src/params.d.ts +44 -0
- package/dist/apps/cli/src/params.js +123 -0
- package/dist/bin/forja.js +234 -13
- package/dist/bin/init-project.js +11 -62
- package/dist/lib/cli-output.d.ts +29 -0
- package/dist/lib/cli-output.js +39 -0
- package/dist/lib/core/checks.d.ts +1 -1
- package/dist/lib/core/health.d.ts +9 -0
- package/dist/lib/core/health.js +9 -0
- package/dist/lib/core/project-smoke.d.ts +6 -2
- package/dist/lib/core/project-smoke.js +83 -7
- package/dist/lib/core/registry.d.ts +38 -571
- package/dist/lib/core/registry.js +174 -25
- package/dist/lib/core/release.d.ts +1 -571
- package/dist/lib/core/release.js +0 -3
- package/dist/lib/handoffs-index.d.ts +16 -0
- package/dist/lib/handoffs-index.js +29 -0
- package/dist/lib/llm/claude-output.d.ts +8 -0
- package/dist/lib/llm/claude-output.js +54 -0
- package/dist/lib/llm/context.d.ts +22 -0
- package/dist/lib/llm/context.js +39 -0
- package/dist/lib/llm/session.d.ts +6 -1
- package/dist/lib/llm/session.js +12 -2
- package/dist/lib/multi-ai-instructions.d.ts +28 -0
- package/dist/lib/multi-ai-instructions.js +83 -0
- package/dist/lib/orchestrate.d.ts +5 -0
- package/dist/lib/orchestrate.js +18 -0
- package/dist/lib/specs-index.d.ts +20 -0
- package/dist/lib/specs-index.js +51 -0
- package/dist/lib/sprint-index.d.ts +15 -0
- package/dist/lib/sprint-index.js +34 -0
- package/dist/lib/status-model.d.ts +64 -0
- package/dist/lib/status-model.js +180 -0
- package/dist/packages/evals/src/index.d.ts +2 -0
- package/dist/packages/evals/src/index.js +21 -0
- package/dist/packages/llm/src/index.d.ts +24 -3
- package/dist/packages/llm/src/index.js +51 -5
- package/dist/scripts/cost-economy.js +12 -10
- package/dist/scripts/drift-check.d.ts +2 -0
- package/dist/scripts/drift-check.js +57 -1
- package/dist/scripts/engineer.js +7 -4
- package/dist/scripts/forja-setup.d.ts +14 -0
- package/dist/scripts/forja-setup.js +58 -0
- package/dist/scripts/forja-status.d.ts +11 -0
- package/dist/scripts/forja-status.js +70 -0
- package/dist/scripts/hook-session-start.js +20 -46
- package/dist/scripts/llm-fit.js +113 -8
- package/dist/scripts/project-smoke.js +13 -3
- package/dist/scripts/simulate.js +18 -6
- package/dist/scripts/token-economy.js +34 -28
- package/dist/scripts/tools-doctor.js +14 -6
- package/docs/2x/CLI-CAPABILITIES.md +34 -10
- package/docs/agent-operating-contract.md +1 -1
- package/docs/cli-first-operacao.md +17 -0
- package/docs/contrato-saida-cli.md +79 -0
- package/docs/llm-evolution.md +2 -1
- package/docs/llm-fit-loop.md +74 -2
- package/docs/publishing.md +0 -11
- package/docs/quick-reference.md +13 -0
- package/docs/roadmap-v4.1.md +199 -0
- package/memory/90-decisions/0082-contrato-saida-cli.md +95 -0
- package/memory/90-decisions/0083-mcp-cobertura-declarativa.md +103 -0
- package/memory/90-decisions/0084-drift-sentinel-fecha.md +79 -0
- package/memory/90-decisions/0085-adaptador-claude-paridade.md +85 -0
- package/package.json +4 -1
- package/specs/cli-intuitiva-v1/plan.md +169 -0
- package/specs/cli-intuitiva-v1/spec.md +163 -0
- package/specs/cli-intuitiva-v1/tasks.md +224 -0
- package/specs/contrato-saida-cli/plan.md +162 -0
- package/specs/contrato-saida-cli/spec.md +157 -0
- package/specs/contrato-saida-cli/tasks.md +153 -0
- package/specs/drift-sentinel/spec.md +17 -8
- package/specs/forja-status-caminho-feliz/plan.md +149 -0
- package/specs/forja-status-caminho-feliz/spec.md +158 -0
- package/specs/forja-status-caminho-feliz/tasks.md +175 -0
- package/specs/llm-adaptador-claude/plan.md +117 -0
- package/specs/llm-adaptador-claude/spec.md +144 -0
- package/specs/llm-adaptador-claude/tasks.md +100 -0
- package/specs/llm-benchmark-recomendacao/plan.md +121 -0
- package/specs/llm-benchmark-recomendacao/spec.md +141 -0
- package/specs/llm-benchmark-recomendacao/tasks.md +88 -0
- package/specs/llm-contexto-e-sessoes/plan.md +143 -0
- package/specs/llm-contexto-e-sessoes/spec.md +139 -0
- package/specs/llm-contexto-e-sessoes/tasks.md +127 -0
- package/specs/mcp-cobertura-nucleo/plan.md +158 -0
- package/specs/mcp-cobertura-nucleo/spec.md +161 -0
- package/specs/mcp-cobertura-nucleo/tasks.md +169 -0
- package/specs/projeto-gerado-confiavel/plan.md +148 -0
- package/specs/projeto-gerado-confiavel/spec.md +142 -0
- 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.
|