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.
Files changed (96) hide show
  1. package/CHANGELOG.md +170 -7
  2. package/DOC-MAP.md +1 -0
  3. package/README.md +10 -2
  4. package/README.pt-BR.md +3 -0
  5. package/dist/apps/cli/src/index.d.ts +18 -1
  6. package/dist/apps/cli/src/index.js +161 -26
  7. package/dist/apps/cli/src/params.d.ts +44 -0
  8. package/dist/apps/cli/src/params.js +123 -0
  9. package/dist/bin/forja.js +234 -13
  10. package/dist/bin/init-project.js +11 -62
  11. package/dist/lib/cli-output.d.ts +29 -0
  12. package/dist/lib/cli-output.js +39 -0
  13. package/dist/lib/core/checks.d.ts +1 -1
  14. package/dist/lib/core/health.d.ts +9 -0
  15. package/dist/lib/core/health.js +9 -0
  16. package/dist/lib/core/project-smoke.d.ts +6 -2
  17. package/dist/lib/core/project-smoke.js +83 -7
  18. package/dist/lib/core/registry.d.ts +38 -571
  19. package/dist/lib/core/registry.js +174 -25
  20. package/dist/lib/core/release.d.ts +1 -571
  21. package/dist/lib/core/release.js +0 -3
  22. package/dist/lib/handoffs-index.d.ts +16 -0
  23. package/dist/lib/handoffs-index.js +29 -0
  24. package/dist/lib/llm/claude-output.d.ts +8 -0
  25. package/dist/lib/llm/claude-output.js +54 -0
  26. package/dist/lib/llm/context.d.ts +22 -0
  27. package/dist/lib/llm/context.js +39 -0
  28. package/dist/lib/llm/session.d.ts +6 -1
  29. package/dist/lib/llm/session.js +12 -2
  30. package/dist/lib/multi-ai-instructions.d.ts +28 -0
  31. package/dist/lib/multi-ai-instructions.js +83 -0
  32. package/dist/lib/orchestrate.d.ts +5 -0
  33. package/dist/lib/orchestrate.js +18 -0
  34. package/dist/lib/specs-index.d.ts +20 -0
  35. package/dist/lib/specs-index.js +51 -0
  36. package/dist/lib/sprint-index.d.ts +15 -0
  37. package/dist/lib/sprint-index.js +34 -0
  38. package/dist/lib/status-model.d.ts +64 -0
  39. package/dist/lib/status-model.js +180 -0
  40. package/dist/packages/evals/src/index.d.ts +2 -0
  41. package/dist/packages/evals/src/index.js +21 -0
  42. package/dist/packages/llm/src/index.d.ts +24 -3
  43. package/dist/packages/llm/src/index.js +51 -5
  44. package/dist/scripts/cost-economy.js +12 -10
  45. package/dist/scripts/drift-check.d.ts +2 -0
  46. package/dist/scripts/drift-check.js +57 -1
  47. package/dist/scripts/engineer.js +7 -4
  48. package/dist/scripts/forja-setup.d.ts +14 -0
  49. package/dist/scripts/forja-setup.js +58 -0
  50. package/dist/scripts/forja-status.d.ts +11 -0
  51. package/dist/scripts/forja-status.js +70 -0
  52. package/dist/scripts/hook-session-start.js +20 -46
  53. package/dist/scripts/llm-fit.js +113 -8
  54. package/dist/scripts/project-smoke.js +13 -3
  55. package/dist/scripts/simulate.js +18 -6
  56. package/dist/scripts/token-economy.js +34 -28
  57. package/dist/scripts/tools-doctor.js +14 -6
  58. package/docs/2x/CLI-CAPABILITIES.md +34 -10
  59. package/docs/agent-operating-contract.md +3 -1
  60. package/docs/cli-first-operacao.md +17 -0
  61. package/docs/contrato-saida-cli.md +79 -0
  62. package/docs/llm-evolution.md +2 -1
  63. package/docs/llm-fit-loop.md +74 -2
  64. package/docs/publishing.md +13 -16
  65. package/docs/quick-reference.md +13 -0
  66. package/docs/roadmap-v4.1.md +199 -0
  67. package/memory/90-decisions/0082-contrato-saida-cli.md +95 -0
  68. package/memory/90-decisions/0083-mcp-cobertura-declarativa.md +103 -0
  69. package/memory/90-decisions/0084-drift-sentinel-fecha.md +79 -0
  70. package/memory/90-decisions/0085-adaptador-claude-paridade.md +85 -0
  71. package/package.json +4 -1
  72. package/specs/cli-intuitiva-v1/plan.md +169 -0
  73. package/specs/cli-intuitiva-v1/spec.md +163 -0
  74. package/specs/cli-intuitiva-v1/tasks.md +224 -0
  75. package/specs/contrato-saida-cli/plan.md +162 -0
  76. package/specs/contrato-saida-cli/spec.md +157 -0
  77. package/specs/contrato-saida-cli/tasks.md +153 -0
  78. package/specs/drift-sentinel/spec.md +17 -8
  79. package/specs/forja-status-caminho-feliz/plan.md +149 -0
  80. package/specs/forja-status-caminho-feliz/spec.md +158 -0
  81. package/specs/forja-status-caminho-feliz/tasks.md +175 -0
  82. package/specs/llm-adaptador-claude/plan.md +117 -0
  83. package/specs/llm-adaptador-claude/spec.md +144 -0
  84. package/specs/llm-adaptador-claude/tasks.md +100 -0
  85. package/specs/llm-benchmark-recomendacao/plan.md +121 -0
  86. package/specs/llm-benchmark-recomendacao/spec.md +141 -0
  87. package/specs/llm-benchmark-recomendacao/tasks.md +88 -0
  88. package/specs/llm-contexto-e-sessoes/plan.md +143 -0
  89. package/specs/llm-contexto-e-sessoes/spec.md +139 -0
  90. package/specs/llm-contexto-e-sessoes/tasks.md +127 -0
  91. package/specs/mcp-cobertura-nucleo/plan.md +158 -0
  92. package/specs/mcp-cobertura-nucleo/spec.md +161 -0
  93. package/specs/mcp-cobertura-nucleo/tasks.md +169 -0
  94. package/specs/projeto-gerado-confiavel/plan.md +148 -0
  95. package/specs/projeto-gerado-confiavel/spec.md +142 -0
  96. package/specs/projeto-gerado-confiavel/tasks.md +139 -0
package/CHANGELOG.md CHANGED
@@ -2,18 +2,181 @@
2
2
 
3
3
  Histórico consolidado das mudanças estruturais do framework. Para decisões arquiteturais com rationale, ver `memory/90-decisions/`.
4
4
 
5
+ ### Como escrever uma entrada de versão
6
+
7
+ Toda versão nova (ao tagear / publicar) abre com uma subseção **`### O que melhorou`** em
8
+ linguagem de produto: o diff observável em relação à versão anterior — o que o usuário passa a
9
+ conseguir fazer, o que para de dar errado, o que fica mais simples. Só depois vêm as seções
10
+ técnicas (`Adicionado`, `Alterado`, `Mudança de contrato`, `Notas…`). A nota de release do
11
+ GitHub reusa esse bloco. O README também é reconciliado na mesma entrega — ver
12
+ [`docs/publishing.md`](docs/publishing.md).
13
+
5
14
  ---
6
15
 
7
- ## [4.0.1] — 2026-09-05 — Cache isolado no gate de release
16
+ ## [Unreleased]
8
17
 
9
- ### Corrigido
18
+ ### O que melhorou
10
19
 
11
- - `release:check` usa cache npm temporário próprio na instalação isolada, sem depender do
12
- estado ou das permissões do cache global; o cache é removido ao final do gate.
13
- - Guia de publicação documenta o cache isolado, o acesso ao registry e a instalação das
14
- dependências do checkout antes dos gates.
20
+ _(preencher a cada release: diff de produto vs. a versão anterior, antes das seções técnicas)_
15
21
 
16
- ---
22
+ ## [4.1.1] — 2026-09-08 — Disciplina de release: README + "O que melhorou" acompanham toda versão
23
+
24
+ ### O que melhorou
25
+
26
+ - **Toda versão nova passa a dizer, em linguagem de produto, o que melhorou.** Cada entrada do
27
+ `CHANGELOG.md` abre por uma subseção `### O que melhorou` — o diff observável vs. a versão
28
+ anterior — antes das seções técnicas. É esse bloco que vira a nota de release no GitHub.
29
+ - **O README não fica mais para trás.** Reconciliar `README.md` e `README.pt-BR.md` com o
30
+ comportamento da versão virou passo obrigatório do runbook de release, não um "se lembrar".
31
+
32
+ ### Alterado
33
+
34
+ - `CHANGELOG.md` ganha a seção **"Como escrever uma entrada de versão"** e um esqueleto em
35
+ `[Unreleased]`; a entrada da 4.1.0 foi retroalimentada com sua subseção `### O que melhorou`.
36
+ - `docs/publishing.md` — "Preparar uma versão" reescrito como checklist de 6 passos: reconciliar
37
+ README (passo 2) e escrever o `### O que melhorou` (passo 3) são explícitos; a etapa de tag no
38
+ GitHub aponta para esse bloco como corpo da release.
39
+ - `docs/agent-operating-contract.md` (§Entrega) e `CLAUDE.md` (§Convenções → Releases) registram
40
+ a regra: README reconciliado + subseção `### O que melhorou` são parte da entrega de qualquer
41
+ bump de versão / tag / publicação.
42
+ - `README.md` / `README.pt-BR.md` — nova convenção **Releases** / **Releases**.
43
+
44
+ ### Notas
45
+
46
+ - Sem mudança de código nem de contrato de CLI. Nenhum comando, flag ou saída `--json` muda.
47
+
48
+ ## [4.1.0] — 2026-09-08 — Roadmap v4.1: menos erros, mais intuitivo, mais funcional com LLMs
49
+
50
+ ### O que melhorou
51
+
52
+ - **Menos erros na CLI.** `--json` agora sempre devolve um único objeto com chave `status`
53
+ (`ok`/`error`/`rejected`) e exit codes previsíveis (0/1/2/127); comando com argumento
54
+ obrigatório faltando imprime o `Uso:` e falha limpo, sem stack trace; `simulate` com
55
+ recomendação `discard` passa a sinalizar rejeição (exit 2) em vez de fingir sucesso.
56
+ - **Operação mais intuitiva.** `forja help <comando>` (e `--help`) explica uso, exemplos e
57
+ próximos passos; `forja setup` cobre o primeiro uso num comando; `forja status` dá o retrato
58
+ único do estado e `forja next` diz a próxima ação e o comando exato; erro de digitação
59
+ (`forja plan`) sugere o comando certo (`spec:plan`); o `help` sem argumento mostra só o núcleo,
60
+ agrupado por domínio.
61
+ - **Mais funcional com LLMs.** Adaptador **Claude** com retomada de sessão (`llm:run --resume`,
62
+ `llm:sessions`), paridade com o Codex; `llm:run --engineer` injeta o contexto de engenharia no
63
+ prompt; `llm:recommend` passa a pesar latência e custo com evidência por candidato; `llm:eval`
64
+ reporta p50/p95 e custo por tarefa aceita; o fluxo SDD roda por MCP (cobertura 6 → 18 comandos).
65
+ - **Gerador de projeto mais confiável.** `project:smoke --ai <lista>` exercita o caminho real
66
+ multi-IA (memória + instruções nativas por IA) e o CI roda isso em matriz a cada PR.
67
+ - **Drift sentinel utilizável.** `forja drift:check --all` roda o sentinela uma vez por projeto
68
+ do workspace — o modo lote para retomar projetos parados há meses (SPEC-030 fecha em `done`).
69
+
70
+ **Roadmap v4.1 concluído** ([`docs/roadmap-v4.1.md`](docs/roadmap-v4.1.md)): as 12 workstreams
71
+ (W1–W12) — menos erros, operação mais intuitiva, mais funcional com LLMs — foram implementadas
72
+ pelo pipeline SDD do próprio Forja e merjadas em `main` (PRs #61–#69). Specs SPEC-043 a SPEC-050
73
+ em `done`; `drift-sentinel` (SPEC-030) segue `implementing` por desenho (ADR-0084, janela de
74
+ observação até 2026-10-08). ADRs estruturais: 0082 (contrato de saída CLI), 0083 (cobertura MCP
75
+ declarativa), 0084 (fecho do drift-sentinel), 0085 (adaptador Claude). Detalhe de cada frente
76
+ nas entradas abaixo.
77
+
78
+ ### Adicionado
79
+
80
+ - `forja llm:run --engineer "<objetivo>"` — monta o contexto pelo façade `engineer` (ADRs, risco,
81
+ fluxo, …) e o embute no prompt. O hash cobre o prompt transmitido; em `contextRefs` fica só a
82
+ referência `engineer:<objetivo>`, nunca o conteúdo. Falha do façade → `errorCode:
83
+ "ENGINEER_FAILED"` antes de chamar o provedor. (SPEC-048)
84
+ - `forja llm:sessions list|show` — leitura das sessões LLM registradas (`llm_session`) para
85
+ recuperar o `SESSION_ID` que `llm:run --resume` exige. Somente leitura. (SPEC-048)
86
+ - `forja llm:eval` reporta `durationMsP50`/`durationMsP95` e `costPerAcceptedTask`
87
+ (`totalCost / tarefas aceitas`; 0 quando nenhuma). As métricas anteriores não mudam. (SPEC-049)
88
+ - `forja llm:recommend` pondera **latência e custo** além do fit declarado e do sucesso local
89
+ (bônus limitado — nunca inverte um fit) e devolve `evidence` por candidato
90
+ (`samples`, `medianDurationMs`, `meanCostUsd`, `successRate`) + `reasons` com `latency:p50=…` /
91
+ `cost:$…/run`. Nenhum percentual de ganho é afirmado antes de um baseline de 30 dias. (SPEC-049)
92
+ - Adaptador **Claude** com paridade de retomada e formato: `llm:run --profile claude` invoca
93
+ `claude -p "<prompt>" --output-format json [--resume <id>]` (`shell:false`, sem ler API keys),
94
+ normaliza o objeto JSON único do provedor (`result`/`session_id`/`usage`) e trata
95
+ `is_error`/`subtype` como erro visível. `RESUME_PROVIDERS = { codex, claude }` — `--resume` e
96
+ `llm:sessions` passam a valer para Claude. `--output-schema` com o perfil `claude` é validação
97
+ **local (Ajv)**, não geração garantida pelo provedor; `llm:probe claude` reporta
98
+ `features.resume: true` / `features.outputSchema: false`. (SPEC-050, ADR-0085)
99
+ - `forja help <comando>` — uso, argumentos posicionais, exemplos e próximos passos de cada
100
+ comando, a partir de campos novos e opcionais do registry (`usage`, `cliArgs`, `examples`,
101
+ `next`, `spec`, `tier`). `forja <comando> --help` faz o mesmo inline. (SPEC-043)
102
+ - `forja setup` — rotina de primeiro uso (`workspace:init` + `sync:universal`) atrás de
103
+ confirmação; `--yes` para uso não-interativo; aborta sem efeito quando não há TTY. (SPEC-043)
104
+ - `forja status` — retrato único do estado: workspace, sprint, corrida orchestrate aberta,
105
+ specs por status, últimos runs, handoffs em aberto. `--json` estável; cada seção degrada com
106
+ `indisponível: <motivo>`. (SPEC-044)
107
+ - `forja next` — a próxima ação recomendada e o comando exato, por prioridade determinística
108
+ (workspace ausente → `setup`; memória crua → `sync:universal`; corrida travada → parecer +
109
+ `orchestrate:advance`; spec `approved` sem plan → `spec:plan`; …). `--json` →
110
+ `{ action, command, reason }`. (SPEC-044)
111
+ - `suggest()` passou a casar por substring **e** distância de edição sobre o nome completo:
112
+ `forja plan` sugere `spec:plan`. Toda mensagem de comando desconhecido termina com
113
+ `forja help <palpite>`. (SPEC-043)
114
+ - Argumento posicional obrigatório em falta falha **antes** de invocar o script-filho, imprimindo
115
+ o `Uso:` do comando — sem stack trace. (SPEC-043)
116
+ - **Contrato de saída da CLI** ([ADR-0082](memory/90-decisions/0082-contrato-saida-cli.md),
117
+ [`docs/contrato-saida-cli.md`](docs/contrato-saida-cli.md)): `--json` emite um único objeto com
118
+ chave `status` (`ok`|`error`|`rejected`); exit codes 0/1/2/127. `lib/cli-output.ts`
119
+ (`emitOk`/`emitError`/`emitRejected`) impõe o formato; `test/cli-output-contract.test.js` itera
120
+ o registry e reprova qualquer `json: true` que desvie. Conjunto conformado: `status`, `next`,
121
+ `engineer`, `simulate`, `cost:economy`, `token:economy`. (SPEC-045)
122
+ - **Cobertura MCP de 6 → 18 comandos** ([ADR-0083](memory/90-decisions/0083-mcp-cobertura-declarativa.md)):
123
+ `spec:new`, `spec:plan`, `spec:tasks`, `query:universal`, `engineer`, `risk:assess`,
124
+ `orchestrate:status`, `orchestrate:advance`, `drift:check`, `code:context`, `status`, `next`
125
+ viram capabilities tipadas — `forja mcp:start` → `tools/list` passa a expô-las e o fluxo SDD
126
+ roda por `tools/call`. Mapeamento argv↔payload declarativo (`apps/cli/src/params.ts`,
127
+ `parseArgv`/`argvFor` inversos com round-trip test); o `if/else` por comando some. `spec:check`
128
+ e `tools:doctor` fecham o débito D7 de SPEC-045 (agora `json: true`). (SPEC-046)
129
+ - `forja project:smoke --ai <lista>` — o gate do projeto gerado passa a exercitar o caminho real
130
+ do `--ai` (memória + instruções nativas por IA), gerado só-memória e sem rede. (SPEC-047)
131
+ - Check `ai-instructions` no `project:smoke`: quando `--ai` é pedido, prova que cada
132
+ `.ia-instructions/<ai>.md` deriva da mesma fonte (corpo byte-idêntico entre IAs, só o cabeçalho
133
+ muda) e que `models.json` bate com a lista. É o análogo do `agent-topology`, na saída do gerador. (SPEC-047)
134
+ - `.github/workflows/ci.yml` — job `project-smoke-ai` em matriz (`claude` · `copilot` ·
135
+ `claude,copilot,gemini,codex`), tier barato, a cada PR e push. (SPEC-047)
136
+ - `lib/multi-ai-instructions.ts` — a escrita das instruções nativas por IA vira função `lib/`
137
+ testada, compartilhada por `bin/init-project.ts` e pelo smoke. (SPEC-047)
138
+ - `forja drift:check --all` — roda o sentinela de drift uma vez por projeto do workspace, cada um
139
+ num grafo isolado e persistente (`<projeto>/.context/drift-graph.db`). É o modo lote que a
140
+ SPEC-030 §3 previa: rodar antes de retomar um projeto parado há meses. (SPEC-030, ADR-0084)
141
+
142
+ ### Alterado
143
+
144
+ - **SPEC-030 (Drift Sentinel) fecha** ([ADR-0084](memory/90-decisions/0084-drift-sentinel-fecha.md)):
145
+ a métrica de sucesso do §8 (drift real encontrado no mundo) era infalsificável como bloqueio de
146
+ `done` — foi reformulada para um aceite verificável agora (determinismo, zero falso positivo no
147
+ monorepo, `--all` completa), e "drift real no mundo" virou janela de observação até 2026-10-08.
148
+ `drift:check` segue como gate opt-in (`check:all --with-drift`), inalterado. Status → `done`.
149
+ - **`--json` de comando-capability** (`spec:check`, `tools:doctor`, `code:impact`, `spec:new`, …)
150
+ deixa de emitir o `ExecutionResult` cru e passa a seguir o contrato de saída (`{ status, … }`)
151
+ via o adaptador `toContract` em `bin/forja.ts`. O consumo por MCP (`tools/call`) não muda.
152
+ (SPEC-046, ADR-0083)
153
+ - **`token:economy --json`** deixa de emitir um array cru — passa a `{ "status": "ok",
154
+ "rows": [...] }`. Quebra do JSON desse comando (ADR-0082). (SPEC-045)
155
+ - **`simulate`** com recomendação `discard`: exit code passa de `0` para **`2`** e, com `--json`,
156
+ `status: "rejected"` — é um gate negativo, não sucesso (ADR-0082). (SPEC-045)
157
+ - **`cost:economy --json`** deixava de ser parseável (avisos de texto iam no stdout); agora o
158
+ stdout é só o objeto, avisos vão para o stderr. (SPEC-045)
159
+
160
+ - `forja help` (sem argumentos) lista só os comandos do núcleo (`tier: 'core'`), agrupados por
161
+ domínio, com rodapé para `forja help --all`. `forja help --all` preserva a saída completa
162
+ anterior; os sufixos `(SPEC-0XX)` saíram das descrições do núcleo para o detalhe de `help <cmd>`. (SPEC-043)
163
+ - `orchestrate` e os comandos de estado (`status`, `next`) abrem o bloco GSD no `forja help` —
164
+ o caminho feliz em primeiro lugar. (SPEC-044)
165
+ - `tools:doctor` e o bloco `<framework-status>` do SessionStart agrupam os checks em três blocos
166
+ rotulados — **Bloqueia o fluxo**, **Rotina de primeiro uso**, **Opcional (ferramentas)**. O
167
+ exit code do gate é inalterado. Mudança aditiva. (SPEC-043)
168
+ - `listSpecs` e `openHandoffs` saíram de `scripts/hook-session-start.ts` para
169
+ `lib/specs-index.ts` / `lib/handoffs-index.ts`, compartilhados com `forja status`. `listRuns`
170
+ novo em `lib/orchestrate.ts`. (SPEC-044)
171
+
172
+ ### Notas de contrato
173
+
174
+ - Decidido no plan (`specs/cli-intuitiva-v1/`): o `--fix` da spec original virou o comando
175
+ dedicado `forja setup` — `tools:doctor` continua só diagnóstico, por desenho. O campo de args
176
+ posicionais no registry chama-se `cliArgs` (não `args`, que é o prefixo fixo do spawn).
177
+ - `spec:check` e `tools:doctor` entraram no contrato de saída via SPEC-046: o envelope da
178
+ capability MCP é convertido pelo adaptador `toContract` em `bin/forja.ts` (fecha o débito D7
179
+ de SPEC-045).
17
180
 
18
181
  ## [4.0.0] — 2026-09-05 — Integrações LLM, sessões e validação
19
182
 
package/DOC-MAP.md CHANGED
@@ -55,6 +55,7 @@ Ponto de entrada por papel. Para histórico de fases ver `CHANGELOG.md`; para de
55
55
  | Manual operacional CLI-first | `docs/manual-operacional-cli-sdd-gsd.md` |
56
56
  | Modos embedded e studio | `docs/modos-de-operacao.md` |
57
57
  | Guia curto CLI-first | `docs/cli-first-operacao.md` |
58
+ | Contrato de saída da CLI (`--json` + exit codes) | `docs/contrato-saida-cli.md` |
58
59
  | Mudanças recentes | `CHANGELOG.md` |
59
60
  | Decisões arquiteturais | `memory/90-decisions/` |
60
61
  | Glossário | `docs/glossary.md` |
package/README.md CHANGED
@@ -220,6 +220,11 @@ scripts are thin aliases that route through the core.
220
220
  ## Essential commands
221
221
 
222
222
  ```bash
223
+ # Orientation — the happy path
224
+ forja status # where am I: workspace, sprint, run, specs, runs, handoffs
225
+ forja next # what now: one line — the next action + the exact command
226
+ forja help [<command>|--all] # the core, or one command's usage/args/examples/next steps
227
+
223
228
  # Workspace & projects
224
229
  forja workspace:init # create ~/forja-workspace
225
230
  forja project:new <name> --ai claude,copilot # create a project in the workspace
@@ -234,7 +239,7 @@ forja sprint:start # also: sprint:status · sprint:compl
234
239
  forja gsd:plan <slug> # GSD runbook in .context/
235
240
  forja gsd:handoff <intent> <slug> # role-to-role handoff (ADR-0005)
236
241
  forja gsd:check <slug> # baseline runbook gates
237
- forja orchestrate "<goal>" --slug <s> # open a run: the SDD/GSD chain as a gated state machine (SPEC-021)
242
+ forja orchestrate "<goal>" --slug <s> # the default path: the whole SDD/GSD chain as a gated state machine (SPEC-021)
238
243
  forja orchestrate:status <slug> # the machine state: stages, gates, verdicts
239
244
  forja orchestrate:advance <slug> # run the stage gate; green → next; red → blocked
240
245
 
@@ -290,7 +295,7 @@ forja cost:economy # real $ cost per model, from the obs
290
295
  forja project:check # framework standards (pre-commit)
291
296
  forja tools:doctor # core X-ray; tells permission/lock from corruption; exit 1 if broken
292
297
  forja release:check --publish # tarball gate before publishing
293
- forja project:smoke # generated-project gate; --full installs and builds the backend
298
+ forja project:smoke # generated-project gate; --full installs+builds; --ai <list> checks native instructions
294
299
  forja project:dashboard # static status report
295
300
 
296
301
  # Governance & audit
@@ -360,6 +365,9 @@ output, code, and ADRs are readable regardless of language.
360
365
  - **CLI-first** — sprints, SDD, GSD, handoffs, and governance by command; the UI is never a gate.
361
366
  - **ADRs** — every structural decision becomes `memory/90-decisions/NNNN-title.md`.
362
367
  - **Handoffs** — 7 required fields (ADR-0005), stored in SQLite (ADR-0008).
368
+ - **Releases** — every new version reconciles the README with its behavior and opens its
369
+ `CHANGELOG.md` entry with a `### O que melhorou` section (product-language diff vs. the previous
370
+ version, reused as the GitHub release note). Runbook: [`docs/publishing.md`](docs/publishing.md).
363
371
  - **pt-BR** — communication and documentation in Portuguese.
364
372
 
365
373
  ## Roadmap
package/README.pt-BR.md CHANGED
@@ -293,6 +293,9 @@ projects/ LEGADO — não usar; projetos vivem no workspace externo
293
293
  - **CLI-first** — sprints, SDD, GSD, handoffs e governança por comando; o front nunca é gate.
294
294
  - **ADRs** — toda decisão estrutural vira `memory/90-decisions/NNNN-titulo.md`.
295
295
  - **Handoffs** — 7 campos obrigatórios (ADR-0005), gravados no SQLite (ADR-0008).
296
+ - **Releases** — toda versão nova reconcilia o README com o seu comportamento e abre a entrada do
297
+ `CHANGELOG.md` por uma seção `### O que melhorou` (diff em linguagem de produto vs. a versão
298
+ anterior, reusada como nota de release no GitHub). Runbook: [`docs/publishing.md`](docs/publishing.md).
296
299
  - **pt-BR** — comunicação e documentação em português.
297
300
 
298
301
  ## Roadmap
@@ -1,7 +1,8 @@
1
1
  import { type AgentIdentity, type CapabilityId, type ExecutionResult } from '../../../packages/contracts/src/index.ts';
2
2
  import { CapabilityRegistry } from '../../../packages/core/src/index.ts';
3
- import { PolicyEngine } from '../../../packages/policy/src/index.ts';
3
+ import { PolicyEngine, type PolicyCategory } from '../../../packages/policy/src/index.ts';
4
4
  import { GraphLoop, type GraphDocumentSource } from '../../../packages/graph/src/index.ts';
5
+ import { type CapabilityParam } from './params.ts';
5
6
  export interface LegacyCliResult {
6
7
  readonly exitCode: number;
7
8
  readonly stdout: string;
@@ -28,6 +29,22 @@ export declare function createLegacyCliRunner(root: string, cwd?: string): Legac
28
29
  interface InputRecord {
29
30
  readonly [key: string]: unknown;
30
31
  }
32
+ interface CliCapabilitySpec<Input extends InputRecord> {
33
+ readonly id: CapabilityId;
34
+ readonly command: string;
35
+ readonly description: string;
36
+ readonly categories: readonly PolicyCategory[];
37
+ readonly permissions: readonly string[];
38
+ readonly risk: 'low' | 'medium' | 'high' | 'critical';
39
+ readonly sideEffects: readonly string[];
40
+ /** argv↔payload declarativo (SPEC-046). `toArgs` e o parse de argv derivam daqui. */
41
+ readonly params: readonly CapabilityParam[];
42
+ /** Opcional: só quando há checagem além de "required + tipo" (range, enum). Default: `makeValidator(params)`. */
43
+ readonly validateInput?: (value: unknown) => Input;
44
+ /** Opcional: `timeoutMs` do registry quando o default de 30s é curto. */
45
+ readonly timeoutMs?: number;
46
+ }
47
+ export declare const CLI_CAPABILITY_SPECS: readonly CliCapabilitySpec<InputRecord>[];
31
48
  export declare const CLI_COMMAND_TO_CAPABILITY: Readonly<Record<string, CapabilityId>>;
32
49
  /** Interface commands for discovering/executing capabilities; handlers remain in the registry. */
33
50
  export declare const CLI_INTERFACE_COMMANDS: readonly ["capabilities:list", "capabilities:describe", "capability:execute", "mcp:start"];
@@ -5,6 +5,7 @@ import { CapabilityRegistry, } from "../../../packages/core/src/index.js";
5
5
  import { PolicyEngine } from "../../../packages/policy/src/index.js";
6
6
  import { COMMANDS, resolveScript } from "../../../lib/core/registry.js";
7
7
  import { GraphIndexer } from "../../../packages/graph/src/index.js";
8
+ import { parseArgv, argvFor, makeValidator } from "./params.js";
8
9
  export function createLegacyCliRunner(root, cwd = process.cwd()) {
9
10
  return (command, args) => {
10
11
  const definition = COMMANDS[command];
@@ -17,7 +18,8 @@ export function createLegacyCliRunner(root, cwd = process.cwd()) {
17
18
  return { exitCode: result.status ?? 1, stdout: result.stdout ?? '', stderr: [result.stderr ?? '', result.error?.message ?? ''].filter(Boolean).join('\n') };
18
19
  };
19
20
  }
20
- const CLI_CAPABILITY_SPECS = [
21
+ export const CLI_CAPABILITY_SPECS = [
22
+ // --- Os 6 originais: mesma assinatura, `params` no lugar do `toArgs` manual (SPEC-046) ---
21
23
  {
22
24
  id: 'system.doctor',
23
25
  command: 'tools:doctor',
@@ -26,8 +28,8 @@ const CLI_CAPABILITY_SPECS = [
26
28
  permissions: ['read'],
27
29
  risk: 'low',
28
30
  sideEffects: [],
31
+ params: [],
29
32
  validateInput: emptyInput,
30
- toArgs: () => [],
31
33
  },
32
34
  {
33
35
  id: 'code.impact',
@@ -37,8 +39,11 @@ const CLI_CAPABILITY_SPECS = [
37
39
  permissions: ['read'],
38
40
  risk: 'low',
39
41
  sideEffects: [],
42
+ params: [
43
+ { name: 'symbol', kind: 'positional', required: true },
44
+ { name: 'depth', kind: 'positional', parse: 'int' },
45
+ ],
40
46
  validateInput: validateCodeImpactInput,
41
- toArgs: (input) => input.depth === undefined ? [input.symbol] : [input.symbol, String(input.depth)],
42
47
  },
43
48
  {
44
49
  id: 'context.budget',
@@ -48,8 +53,11 @@ const CLI_CAPABILITY_SPECS = [
48
53
  permissions: ['read'],
49
54
  risk: 'low',
50
55
  sideEffects: ['context_run_record'],
56
+ params: [
57
+ { name: 'target', kind: 'positional', required: true },
58
+ { name: 'limitTokens', kind: 'positional', parse: 'int' },
59
+ ],
51
60
  validateInput: validateContextBudgetInput,
52
- toArgs: (input) => input.limitTokens === undefined ? [input.target] : [input.target, String(input.limitTokens)],
53
61
  },
54
62
  {
55
63
  id: 'spec.validate',
@@ -59,8 +67,8 @@ const CLI_CAPABILITY_SPECS = [
59
67
  permissions: ['read'],
60
68
  risk: 'low',
61
69
  sideEffects: [],
70
+ params: [{ name: 'feature', kind: 'positional' }],
62
71
  validateInput: validateSpecCheckInput,
63
- toArgs: (input) => input.feature === undefined ? [] : [input.feature],
64
72
  },
65
73
  {
66
74
  id: 'sprint.status',
@@ -70,8 +78,8 @@ const CLI_CAPABILITY_SPECS = [
70
78
  permissions: ['read'],
71
79
  risk: 'low',
72
80
  sideEffects: [],
81
+ params: [{ name: 'project', kind: 'positional' }],
73
82
  validateInput: validateSprintStatusInput,
74
- toArgs: (input) => input.project === undefined ? [] : [input.project],
75
83
  },
76
84
  {
77
85
  id: 'handoff.create',
@@ -81,8 +89,146 @@ const CLI_CAPABILITY_SPECS = [
81
89
  permissions: ['write'],
82
90
  risk: 'low',
83
91
  sideEffects: ['handoff_record'],
92
+ params: [
93
+ { name: 'phase', kind: 'positional', required: true },
94
+ { name: 'slug', kind: 'positional', required: true },
95
+ { name: 'context', kind: 'rest' },
96
+ ],
84
97
  validateInput: validateHandoffInput,
85
- toArgs: (input) => [input.phase, input.slug, ...(input.context === undefined ? [] : [input.context])],
98
+ },
99
+ // --- SPEC-046 / ADR-0083: o núcleo do fluxo operável por MCP ---
100
+ {
101
+ id: 'spec.create',
102
+ command: 'spec:new',
103
+ description: 'Cria specs/<slug>/spec.md a partir do template.',
104
+ categories: ['write'],
105
+ permissions: ['write'],
106
+ risk: 'low',
107
+ sideEffects: ['spec_file'],
108
+ params: [{ name: 'slug', kind: 'positional', required: true }],
109
+ },
110
+ {
111
+ id: 'spec.plan',
112
+ command: 'spec:plan',
113
+ description: 'Deriva plan.md de uma spec aprovada.',
114
+ categories: ['write'],
115
+ permissions: ['write'],
116
+ risk: 'low',
117
+ sideEffects: ['spec_file'],
118
+ params: [{ name: 'slug', kind: 'positional', required: true }],
119
+ },
120
+ {
121
+ id: 'spec.tasks',
122
+ command: 'spec:tasks',
123
+ description: 'Decompõe plan.md em tasks.md.',
124
+ categories: ['write'],
125
+ permissions: ['write'],
126
+ risk: 'low',
127
+ sideEffects: ['spec_file'],
128
+ params: [{ name: 'slug', kind: 'positional', required: true }],
129
+ },
130
+ {
131
+ id: 'code.context',
132
+ command: 'code:context',
133
+ description: 'Pacote de contexto mínimo de um domínio (o mapa; + código com --code).',
134
+ categories: ['read'],
135
+ permissions: ['read'],
136
+ risk: 'low',
137
+ sideEffects: [],
138
+ params: [
139
+ { name: 'domain', kind: 'positional' },
140
+ { name: 'code', kind: 'flag' },
141
+ ],
142
+ },
143
+ {
144
+ id: 'memory.query',
145
+ command: 'query:universal',
146
+ description: 'Busca FTS5 na memória universal.',
147
+ categories: ['read', 'database'],
148
+ permissions: ['read'],
149
+ risk: 'low',
150
+ sideEffects: [],
151
+ params: [{ name: 'query', kind: 'positional', required: true }],
152
+ },
153
+ {
154
+ id: 'engineering.facade',
155
+ command: 'engineer',
156
+ description: 'Façade: contexto + ADRs relevantes + architecture:check + risco + fluxo recomendado.',
157
+ categories: ['read', 'database', 'execution'],
158
+ permissions: ['read'],
159
+ risk: 'medium',
160
+ sideEffects: [],
161
+ params: [
162
+ { name: 'objective', kind: 'positional', required: true },
163
+ { name: 'ref', kind: 'flag-value', flag: '--ref' },
164
+ { name: 'role', kind: 'flag-value', flag: '--role' },
165
+ ],
166
+ timeoutMs: 120_000,
167
+ },
168
+ {
169
+ id: 'risk.assess',
170
+ command: 'risk:assess',
171
+ description: 'Score de risco 0-100 (7 fatores) sobre o diff de um ref.',
172
+ categories: ['read', 'database'],
173
+ permissions: ['read'],
174
+ risk: 'low',
175
+ sideEffects: ['risk_assessment'],
176
+ params: [{ name: 'ref', kind: 'positional' }],
177
+ },
178
+ {
179
+ id: 'orchestrate.status',
180
+ command: 'orchestrate:status',
181
+ description: 'O estado de uma corrida orchestrate: etapas, gates, vereditos.',
182
+ categories: ['read'],
183
+ permissions: ['read'],
184
+ risk: 'low',
185
+ sideEffects: [],
186
+ params: [{ name: 'slug', kind: 'positional', required: true }],
187
+ },
188
+ {
189
+ id: 'orchestrate.advance',
190
+ command: 'orchestrate:advance',
191
+ description: 'Roda o gate da etapa aberta; verde abre a próxima, vermelho trava com o parecer.',
192
+ categories: ['write', 'execution', 'database'],
193
+ permissions: ['write'],
194
+ risk: 'medium',
195
+ sideEffects: ['orchestrate_state'],
196
+ params: [{ name: 'slug', kind: 'positional', required: true }],
197
+ timeoutMs: 300_000,
198
+ },
199
+ {
200
+ id: 'drift.check',
201
+ command: 'drift:check',
202
+ description: 'Reindexa e sinaliza relações verified que a extração atual não reproduz mais.',
203
+ categories: ['read', 'database', 'execution'],
204
+ permissions: ['read'],
205
+ risk: 'medium',
206
+ sideEffects: ['graph_write'],
207
+ params: [
208
+ { name: 'domain', kind: 'flag-value', flag: '--domain' },
209
+ { name: 'all', kind: 'flag' }, // SPEC-030 §3 / ADR-0084: modo lote por projeto do workspace
210
+ ],
211
+ timeoutMs: 120_000,
212
+ },
213
+ {
214
+ id: 'forja.status',
215
+ command: 'status',
216
+ description: 'Retrato único do estado: workspace, sprint, corrida, specs, runs, handoffs.',
217
+ categories: ['read'],
218
+ permissions: ['read'],
219
+ risk: 'low',
220
+ sideEffects: [],
221
+ params: [],
222
+ },
223
+ {
224
+ id: 'forja.next',
225
+ command: 'next',
226
+ description: 'A próxima ação recomendada e o comando exato para executá-la.',
227
+ categories: ['read'],
228
+ permissions: ['read'],
229
+ risk: 'low',
230
+ sideEffects: [],
231
+ params: [],
86
232
  },
87
233
  ];
88
234
  export const CLI_COMMAND_TO_CAPABILITY = Object.freeze(Object.fromEntries(CLI_CAPABILITY_SPECS.map((spec) => [spec.command, spec.id])));
@@ -138,27 +284,16 @@ export function capabilityIdForCommand(command) {
138
284
  return command === 'graph:sync' ? 'graph.sync' : CLI_COMMAND_TO_CAPABILITY[command];
139
285
  }
140
286
  export function parseLegacyCommandInput(command, args) {
287
+ // `graph:sync` é o único sem comando CLI / sem params — os demais derivam de `spec.params` (SPEC-046).
141
288
  if (command === 'graph:sync')
142
289
  return { capabilityId: 'graph.sync', payload: {} };
143
290
  const capabilityId = capabilityIdForCommand(command);
144
291
  if (capabilityId === undefined)
145
292
  throw new Error(`Command is not migrated to a capability: ${command}`);
146
- if (command === 'tools:doctor')
147
- return { capabilityId, payload: {} };
148
- if (command === 'code:impact') {
149
- const [symbol, depth] = args;
150
- return { capabilityId, payload: { symbol, ...(depth === undefined ? {} : { depth: Number(depth) }) } };
151
- }
152
- if (command === 'context:budget') {
153
- const [target, limitTokens] = args;
154
- return { capabilityId, payload: { target, ...(limitTokens === undefined ? {} : { limitTokens: Number(limitTokens) }) } };
155
- }
156
- if (command === 'spec:check')
157
- return { capabilityId, payload: args[0] === undefined ? {} : { feature: args[0] } };
158
- if (command === 'sprint:status')
159
- return { capabilityId, payload: args[0] === undefined ? {} : { project: args[0] } };
160
- const [phase, slug, ...contextParts] = args;
161
- return { capabilityId, payload: { phase, slug, ...(contextParts.length === 0 ? {} : { context: contextParts.join(' ') }) } };
293
+ const spec = CLI_CAPABILITY_SPECS.find((s) => s.command === command);
294
+ if (spec === undefined)
295
+ throw new Error(`No capability spec for command: ${command}`);
296
+ return { capabilityId, payload: parseArgv(spec.params, args) };
162
297
  }
163
298
  export async function executeCliCapability(runtime, capabilityId, payload, correlationId) {
164
299
  const definition = runtime.registry.describe(capabilityId);
@@ -206,16 +341,16 @@ function registerCliCapability(registry, runner, spec) {
206
341
  requirements: [],
207
342
  supportsAutonomy: true,
208
343
  idempotent: true,
209
- timeoutMs: 30_000,
344
+ timeoutMs: spec.timeoutMs ?? 30_000,
210
345
  retry: { maxAttempts: 1, backoffMs: 0 },
211
346
  aliases: [spec.command],
212
347
  };
213
348
  const registration = {
214
349
  definition,
215
- validateInput: spec.validateInput,
350
+ validateInput: spec.validateInput ?? makeValidator(spec.params),
216
351
  validateOutput: validateCliPayload,
217
352
  handler: async (input) => {
218
- const args = spec.toArgs(input);
353
+ const args = argvFor(spec.params, input);
219
354
  const result = await runner(spec.command, args);
220
355
  const capturedAt = new Date().toISOString();
221
356
  const evidence = {
@@ -0,0 +1,44 @@
1
+ /**
2
+ * apps/cli/src/params.ts — mapeamento declarativo argv↔payload de um comando-capability
3
+ * (SPEC-046, ADR-0083).
4
+ *
5
+ * `parseArgv` e `argvFor` são inversas. Um teste de round-trip
6
+ * (`argvFor(params, parseArgv(params, argv)) === argv`) para todo spec é o contrato que impede
7
+ * as duas de divergirem — o `if/else` por comando que existia antes não tinha esse contrato.
8
+ *
9
+ * Convenção de ordem em `argvFor`: os params são emitidos na ordem em que aparecem em `params`.
10
+ * Um `positional` opcional só é seguro antes de outro `positional` se o anterior estiver sempre
11
+ * presente — na prática, opcionais ficam por último.
12
+ */
13
+ export interface InputRecord {
14
+ readonly [key: string]: unknown;
15
+ }
16
+ export type CapabilityParam = {
17
+ readonly name: string;
18
+ readonly kind: 'positional';
19
+ readonly required?: boolean;
20
+ readonly parse?: 'string' | 'int';
21
+ } | {
22
+ readonly name: string;
23
+ readonly kind: 'flag';
24
+ } | {
25
+ readonly name: string;
26
+ readonly kind: 'flag-value';
27
+ readonly flag: string;
28
+ readonly required?: boolean;
29
+ readonly parse?: 'string' | 'int';
30
+ } | {
31
+ readonly name: string;
32
+ readonly kind: 'rest';
33
+ readonly required?: boolean;
34
+ };
35
+ /** argv → `{ [param.name]: value }`. Flags desconhecidas são ignoradas. */
36
+ export declare function parseArgv(params: readonly CapabilityParam[], argv: readonly string[]): InputRecord;
37
+ /** `{ [param.name]: value }` → argv, na ordem de `params`. */
38
+ export declare function argvFor(params: readonly CapabilityParam[], input: InputRecord): string[];
39
+ /**
40
+ * Validador base a partir de `params`: exige os `required` presentes e o tipo certo
41
+ * (`int` → número finito; resto → string). Specs com limite adicional (range, enum) embrulham
42
+ * esta função.
43
+ */
44
+ export declare function makeValidator(params: readonly CapabilityParam[]): (value: unknown) => InputRecord;