forjajs 4.0.1 → 4.1.1
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 +170 -7
- package/DOC-MAP.md +1 -0
- package/README.md +10 -2
- package/README.pt-BR.md +3 -0
- 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 +3 -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 +13 -16
- 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
package/docs/llm-fit-loop.md
CHANGED
|
@@ -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
|
-
|
|
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
|
package/docs/publishing.md
CHANGED
|
@@ -5,14 +5,17 @@ package.json define o conteúdo distribuído. O workspace de produtos fica fora
|
|
|
5
5
|
|
|
6
6
|
## Preparar uma versão
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
8
|
+
1. Revisar mudanças e atualizar versão em package.json e package-lock.json.
|
|
9
|
+
2. **Reconciliar o README** (`README.md` e `README.pt-BR.md`): tabelas de comandos e de pilares,
|
|
10
|
+
listas de features e exemplos que a versão mudou. Nenhuma tag sai com o README descrevendo o
|
|
11
|
+
comportamento anterior.
|
|
12
|
+
3. **Escrever a entrada da versão no `CHANGELOG.md`** começando pela subseção `### O que melhorou`
|
|
13
|
+
— o diff em linguagem de produto vs. a versão anterior (o que passa a funcionar, o que para de
|
|
14
|
+
dar errado, o que fica mais simples) — e só então as seções técnicas. Esse bloco é o texto da
|
|
15
|
+
release note do GitHub.
|
|
16
|
+
4. Executar tipos, testes e governança pelo core do Forja.
|
|
17
|
+
5. Commitar a entrega. O modo de publicação exige árvore Git limpa.
|
|
18
|
+
6. Executar doctor e o gate estrito do tarball na revisão que será publicada.
|
|
16
19
|
|
|
17
20
|
```bash
|
|
18
21
|
npm run types:check
|
|
@@ -23,13 +26,6 @@ npm run release:check -- --publish
|
|
|
23
26
|
```
|
|
24
27
|
|
|
25
28
|
O gate constrói dist, empacota, instala em diretório isolado e verifica o pacote instalado.
|
|
26
|
-
Os subprocessos npm usam um cache próprio em `.npm-cache` dentro desse diretório temporário,
|
|
27
|
-
removido pelo bloco de limpeza ao final, inclusive em caso de erro. O gate não depende das
|
|
28
|
-
permissões nem do conteúdo do cache global do npm e precisa de acesso ao registry para baixar
|
|
29
|
-
as dependências. Variáveis herdadas `npm_*`, incluindo `npm_config_cache`, são descartadas antes
|
|
30
|
-
de configurar esse cache isolado. Essa configuração vale apenas para o gate; não altera o cache
|
|
31
|
-
usado por comandos npm executados diretamente.
|
|
32
|
-
|
|
33
29
|
O parecer vale para aquele conteúdo: mudanças posteriores exigem nova verificação.
|
|
34
30
|
Ferramentas opcionais ausentes são reportadas separadamente pelo doctor.
|
|
35
31
|
|
|
@@ -48,7 +44,8 @@ Se a sessão expirou, o mantenedor renova o login com `npm login`. Se o npm exig
|
|
|
48
44
|
adicional, concluir o fluxo oficial. Não contornar o gate com ignore-scripts.
|
|
49
45
|
|
|
50
46
|
Enviar o commit para o GitHub, aguardar o CI e criar a tag/release correspondente à versão
|
|
51
|
-
publicada.
|
|
47
|
+
publicada. O corpo da release no GitHub é a subseção `### O que melhorou` daquela versão no
|
|
48
|
+
`CHANGELOG.md`. Não mover uma tag existente nem republicar uma versão imutável.
|
|
52
49
|
|
|
53
50
|
## Conteúdo e compatibilidade
|
|
54
51
|
|
package/docs/quick-reference.md
CHANGED
|
@@ -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)
|