forjajs 4.0.0 → 4.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (94) hide show
  1. package/CHANGELOG.md +115 -0
  2. package/DOC-MAP.md +1 -0
  3. package/README.md +7 -2
  4. package/dist/apps/cli/src/index.d.ts +18 -1
  5. package/dist/apps/cli/src/index.js +161 -26
  6. package/dist/apps/cli/src/params.d.ts +44 -0
  7. package/dist/apps/cli/src/params.js +123 -0
  8. package/dist/bin/forja.js +234 -13
  9. package/dist/bin/init-project.js +11 -62
  10. package/dist/lib/cli-output.d.ts +29 -0
  11. package/dist/lib/cli-output.js +39 -0
  12. package/dist/lib/core/checks.d.ts +1 -1
  13. package/dist/lib/core/health.d.ts +9 -0
  14. package/dist/lib/core/health.js +9 -0
  15. package/dist/lib/core/project-smoke.d.ts +6 -2
  16. package/dist/lib/core/project-smoke.js +83 -7
  17. package/dist/lib/core/registry.d.ts +38 -571
  18. package/dist/lib/core/registry.js +174 -25
  19. package/dist/lib/core/release.d.ts +1 -571
  20. package/dist/lib/core/release.js +0 -3
  21. package/dist/lib/handoffs-index.d.ts +16 -0
  22. package/dist/lib/handoffs-index.js +29 -0
  23. package/dist/lib/llm/claude-output.d.ts +8 -0
  24. package/dist/lib/llm/claude-output.js +54 -0
  25. package/dist/lib/llm/context.d.ts +22 -0
  26. package/dist/lib/llm/context.js +39 -0
  27. package/dist/lib/llm/session.d.ts +6 -1
  28. package/dist/lib/llm/session.js +12 -2
  29. package/dist/lib/multi-ai-instructions.d.ts +28 -0
  30. package/dist/lib/multi-ai-instructions.js +83 -0
  31. package/dist/lib/orchestrate.d.ts +5 -0
  32. package/dist/lib/orchestrate.js +18 -0
  33. package/dist/lib/specs-index.d.ts +20 -0
  34. package/dist/lib/specs-index.js +51 -0
  35. package/dist/lib/sprint-index.d.ts +15 -0
  36. package/dist/lib/sprint-index.js +34 -0
  37. package/dist/lib/status-model.d.ts +64 -0
  38. package/dist/lib/status-model.js +180 -0
  39. package/dist/packages/evals/src/index.d.ts +2 -0
  40. package/dist/packages/evals/src/index.js +21 -0
  41. package/dist/packages/llm/src/index.d.ts +24 -3
  42. package/dist/packages/llm/src/index.js +51 -5
  43. package/dist/scripts/cost-economy.js +12 -10
  44. package/dist/scripts/drift-check.d.ts +2 -0
  45. package/dist/scripts/drift-check.js +57 -1
  46. package/dist/scripts/engineer.js +7 -4
  47. package/dist/scripts/forja-setup.d.ts +14 -0
  48. package/dist/scripts/forja-setup.js +58 -0
  49. package/dist/scripts/forja-status.d.ts +11 -0
  50. package/dist/scripts/forja-status.js +70 -0
  51. package/dist/scripts/hook-session-start.js +20 -46
  52. package/dist/scripts/llm-fit.js +113 -8
  53. package/dist/scripts/project-smoke.js +13 -3
  54. package/dist/scripts/simulate.js +18 -6
  55. package/dist/scripts/token-economy.js +34 -28
  56. package/dist/scripts/tools-doctor.js +14 -6
  57. package/docs/2x/CLI-CAPABILITIES.md +34 -10
  58. package/docs/agent-operating-contract.md +1 -1
  59. package/docs/cli-first-operacao.md +17 -0
  60. package/docs/contrato-saida-cli.md +79 -0
  61. package/docs/llm-evolution.md +2 -1
  62. package/docs/llm-fit-loop.md +74 -2
  63. package/docs/quick-reference.md +13 -0
  64. package/docs/roadmap-v4.1.md +199 -0
  65. package/memory/90-decisions/0082-contrato-saida-cli.md +95 -0
  66. package/memory/90-decisions/0083-mcp-cobertura-declarativa.md +103 -0
  67. package/memory/90-decisions/0084-drift-sentinel-fecha.md +79 -0
  68. package/memory/90-decisions/0085-adaptador-claude-paridade.md +85 -0
  69. package/package.json +4 -1
  70. package/specs/cli-intuitiva-v1/plan.md +169 -0
  71. package/specs/cli-intuitiva-v1/spec.md +163 -0
  72. package/specs/cli-intuitiva-v1/tasks.md +224 -0
  73. package/specs/contrato-saida-cli/plan.md +162 -0
  74. package/specs/contrato-saida-cli/spec.md +157 -0
  75. package/specs/contrato-saida-cli/tasks.md +153 -0
  76. package/specs/drift-sentinel/spec.md +17 -8
  77. package/specs/forja-status-caminho-feliz/plan.md +149 -0
  78. package/specs/forja-status-caminho-feliz/spec.md +158 -0
  79. package/specs/forja-status-caminho-feliz/tasks.md +175 -0
  80. package/specs/llm-adaptador-claude/plan.md +117 -0
  81. package/specs/llm-adaptador-claude/spec.md +144 -0
  82. package/specs/llm-adaptador-claude/tasks.md +100 -0
  83. package/specs/llm-benchmark-recomendacao/plan.md +121 -0
  84. package/specs/llm-benchmark-recomendacao/spec.md +141 -0
  85. package/specs/llm-benchmark-recomendacao/tasks.md +88 -0
  86. package/specs/llm-contexto-e-sessoes/plan.md +143 -0
  87. package/specs/llm-contexto-e-sessoes/spec.md +139 -0
  88. package/specs/llm-contexto-e-sessoes/tasks.md +127 -0
  89. package/specs/mcp-cobertura-nucleo/plan.md +158 -0
  90. package/specs/mcp-cobertura-nucleo/spec.md +161 -0
  91. package/specs/mcp-cobertura-nucleo/tasks.md +169 -0
  92. package/specs/projeto-gerado-confiavel/plan.md +148 -0
  93. package/specs/projeto-gerado-confiavel/spec.md +142 -0
  94. package/specs/projeto-gerado-confiavel/tasks.md +139 -0
@@ -0,0 +1,85 @@
1
+ # ADR-0085: Adaptador Claude com paridade de retomada e formato
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-09-08
5
+ - **Autor(es)**: Allan Pablo / Claude
6
+ - **Tags**: llm, adapters, sessions, privacy
7
+
8
+ ## Contexto
9
+
10
+ O `llm:run` já tem um adaptador `claude` mínimo — `buildLlmExecution` monta `claude -p "<prompt>"`
11
+ e mais nada. Retomada (`--resume`) e formato estruturado (`--output-schema`) são **exclusivos do
12
+ Codex** por decisão explícita do ADR-0081: `buildLlmExecution` lança "resume requires codex", e
13
+ `llm:run` só chama `normalizeCodexResult` / `LlmSessionStore` para o provedor `codex`.
14
+
15
+ O `claude` CLI (Claude Code) oferece nativamente o que falta: `--print --output-format json` (um
16
+ objeto único com `result`, `session_id`, `usage`, `total_cost_usd`), `-r/--resume <session-id>` e
17
+ `--session-id <uuid>`. Um adaptador de primeira classe fecha a assimetria do C3 do roadmap v4.1.
18
+
19
+ ## Decisão
20
+
21
+ **Elevar o adaptador `claude` à paridade, dentro da mesma fronteira de privacidade do Codex.**
22
+
23
+ 1. **`buildLlmExecution` (`provider: 'claude'`)** passa a montar
24
+ `claude -p "<prompt>" --output-format json [--model <m>] [--resume <session-id>]`. `shell:
25
+ false` (argv, nunca string de shell); o Forja **não lê API keys** — a autenticação é da CLI
26
+ do provedor, como no Codex. O prompt vai por argumento (o `claude -p` recebe assim), não por
27
+ stdin como o Codex.
28
+
29
+ 2. **`lib/llm/claude-output.ts` `normalizeClaudeResult`** parseia o objeto JSON único do
30
+ `--output-format json`: `stdout` ← `result` (string); `sessionId` ← `session_id`; `usage` ←
31
+ `{ input_tokens, output_tokens, cache_read_input_tokens? }`. `is_error: true` ou
32
+ `subtype !== 'success'` → `errorCode: 'PROVIDER_FAILED'`; JSON inválido →
33
+ `'INVALID_PROVIDER_OUTPUT'`. Mesmo contrato de `NormalizedLlmResult` do Codex — nenhum evento
34
+ de raciocínio vira resposta final.
35
+
36
+ 3. **Retomada** deixa de ser Codex-only. Um conjunto explícito `RESUME_PROVIDERS = { codex,
37
+ claude }` rege o guard de `buildLlmExecution` e o `LlmSessionStore.require`. A fingerprint do
38
+ perfil (`profileFingerprint`) e o binding a `cwd` + projeto continuam iguais — a sessão
39
+ pertence a um projeto e a uma configuração de perfil, seja Codex ou Claude.
40
+
41
+ 4. **`--output-schema` para Claude é validação LOCAL, não garantia do provedor.** O `claude` CLI
42
+ não tem flag de schema. O caminho que já existe para adaptadores não-Codex vale: o Forja
43
+ instrui "responda só JSON conforme este schema" e valida com Ajv localmente (SPEC-028). O
44
+ `llm:probe`/`llm:doctor` reporta `features.outputSchema: false` para Claude — o operador sabe
45
+ que a garantia é local. `features.resume: true`.
46
+
47
+ 5. **Custo**: o `total_cost_usd` do `claude --output-format json` **não** substitui a tabela
48
+ local de preço; o Forja continua estimando por `model-pricing.json` e marcando `costSource`.
49
+ O número do provedor pode ser anotado no futuro, com ADR próprio (não nesta rodada).
50
+
51
+ ## Alternativas consideradas
52
+
53
+ - **Manter Codex-only.** Rejeitado: a assimetria não tem razão técnica agora que o `claude` CLI
54
+ expõe resume + JSON; C3 do roadmap fica aberto sem motivo.
55
+ - **`--output-format stream-json` (como o JSONL do Codex).** Rejeitado nesta rodada: o objeto
56
+ único de `--output-format json` é mais simples e suficiente para um `llm:run` não-interativo;
57
+ streaming é para uma UI, não para este comando.
58
+ - **Ler o `total_cost_usd` do provedor como custo real.** Rejeitado: mistura estimativa local
59
+ com fatura parcial do provedor sem modelar descontos/assinatura — mesma cautela do ADR-0081.
60
+ - **Um `packages/llm/adapters/` genérico.** Rejeitado como over-engineering para 2 provedores com
61
+ resume; o `if (provider === …)` de `buildLlmExecution` + um `*-output.ts` por provedor é o
62
+ padrão vigente e continua legível.
63
+
64
+ ## Consequências
65
+
66
+ **Positivas**:
67
+ - `llm:run --profile claude --resume <id>` e `llm:sessions show <id>` funcionam para Claude.
68
+ - `llm:run --profile claude --output-schema s` valida a resposta localmente.
69
+ - Um segundo provedor de primeira classe reduz o lock-in de fato no Codex.
70
+
71
+ **Negativas / Trade-offs**:
72
+ - `features.outputSchema: false` para Claude — a garantia de formato é local (Ajv), não do
73
+ provedor. Documentado; o `llm:run` já reprova formato inválido de qualquer jeito.
74
+ - Mais um caminho de normalização para manter quando o formato do `claude --output-format json`
75
+ mudar. Mitigado por `normalizeClaudeResult` só ler campos conhecidos e falhar visível.
76
+ - `RESUME_PROVIDERS` é um conjunto no código, não configurável — adicionar um 3º provedor com
77
+ resume exige tocar aqui (aceitável: é uma decisão de contrato).
78
+
79
+ ## Rastreamento
80
+
81
+ - Implementação: `packages/llm/src/index.ts` (`buildLlmExecution` claude, guard de resume),
82
+ `lib/llm/claude-output.ts` (novo), `lib/llm/session.ts` (`RESUME_PROVIDERS`),
83
+ `scripts/llm-fit.ts` (normalização + probe/doctor)
84
+ - [Spec](../../specs/llm-adaptador-claude/spec.md) · ADR-0081 (sessões e validação), SPEC-028
85
+ - Docs: `docs/llm-fit-loop.md`, `docs/llm-evolution.md`
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "forjajs",
3
- "version": "4.0.0",
3
+ "version": "4.1.0",
4
4
  "description": "ForjaJS é uma plataforma local-first para memória, contexto, governança e execução supervisionada de agentes de desenvolvimento",
5
5
  "type": "module",
6
6
  "main": "index.js",
@@ -45,6 +45,8 @@
45
45
  "sprint:start": "node bin/forja.ts sprint:start",
46
46
  "sprint:status": "node bin/forja.ts sprint:status",
47
47
  "sprint:complete": "node bin/forja.ts sprint:complete",
48
+ "status": "node bin/forja.ts status",
49
+ "next": "node bin/forja.ts next",
48
50
  "context:smart": "node bin/forja.ts context:smart",
49
51
  "memory:compress": "node bin/forja.ts memory:compress",
50
52
  "memory:vacuum": "node bin/forja.ts memory:vacuum",
@@ -64,6 +66,7 @@
64
66
  "spec:check": "node bin/forja.ts spec:check",
65
67
  "agent:route": "node bin/forja.ts agent:route",
66
68
  "workspace:init": "node bin/forja.ts workspace:init",
69
+ "setup": "node bin/forja.ts setup",
67
70
  "project:new": "node bin/forja.ts project:new",
68
71
  "project:list": "node bin/forja.ts project:list",
69
72
  "workspace:project:check": "node bin/forja.ts workspace:project:check",
@@ -0,0 +1,169 @@
1
+ # Plan: cli-intuitiva-v1
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Status**: approved
5
+ - **Criado em**: 2026-09-07
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
+ **Extend, não rewrite.** O registry (`lib/core/registry.ts`) é a fonte única declarativa; todos
12
+ os campos novos são **opcionais e aditivos** — nenhum comando existente muda. `bin/forja.ts`
13
+ ganha (a) um branch `help <cmd>` / `help --all` antes do dispatch, (b) `printHelp()` filtrando
14
+ por `tier`, (c) `suggest()` reescrita, (d) pré-validação de `args required` antes do `spawnSync`.
15
+ A classificação em 3 blocos vai para `lib/core/health.ts` (módulo já compartilhado por
16
+ `tools:doctor` e pelo hook SessionStart). O `--fix` **sai do doctor** para um comando novo
17
+ `forja setup` (D2), preservando o contrato "diagnostica e prescreve; não conserta" que o
18
+ cabeçalho de `scripts/tools-doctor.ts` declara explicitamente. Sem estado novo, sem migração,
19
+ sem dependência externa.
20
+
21
+ ## 2. Módulos afetados
22
+
23
+ | Caminho | Mudança | Risco |
24
+ |---|---|---|
25
+ | `lib/core/registry.ts` | editar — tipo do comando ganha campos opcionais (`usage`, `args`, `examples`, `next`, `readonly`, `json`, `tier`, `spec`); preencher nos ~14 comandos do núcleo; mover `(SPEC-0XX)` de `desc` para `spec` | B |
26
+ | `bin/forja.ts` | editar — `printHelp()` filtra `tier:'core'` + rodapé; novo `printCommandHelp(name)`; branch `help <cmd>` e `help --all`; `suggest()` (substring + Levenshtein ≤2 no nome completo); pré-validação de `args required` → imprime `usage`, exit 1, sem spawn; toda msg de erro termina com `forja help <palpite>` | M |
27
+ | `lib/core/health.ts` | editar — cada check declara `bucket: 'blocking' \| 'first-run' \| 'optional'`; `runChecks`/helpers preservam; expor para os dois renderizadores | B |
28
+ | `scripts/tools-doctor.ts` | editar — `printCore`/`printTools` passam a agrupar por `bucket` com os 3 rótulos fixos; nenhuma flag `--fix` aqui | B |
29
+ | `scripts/hook-session-start.ts` | editar — reusar os mesmos 3 buckets no bloco `<framework-status>` (hoje concatena avisos crus) | B |
30
+ | `scripts/forja-setup.ts` | **criar** — executa a allowlist fixa (`workspace:init`, `sync:universal`) em ordem; sem `--yes` pede confirmação; stdin não-TTY sem `--yes` → aborta sem efeito; audita cada passo | B |
31
+ | `lib/core/registry.ts` | + entrada `setup` (domínio `workspace`, `tier:'core'`, `readonly:false`) | B |
32
+ | `test/forja-core.test.js` | editar — AC-8 (a/b/c) + retrocompat (comando sem campos novos continua resolvendo) | B |
33
+ | `docs/quick-reference.md` + `docs/cli-first-operacao.md` | editar — `help <cmd>`, `help --all`, `forja setup`; manter `docs-commands`/`commands-documented` verdes | B |
34
+
35
+ ## 3. Diagrama de fluxo
36
+
37
+ ```
38
+ forja <argv>
39
+ ├─ argv[0] ∈ {help,--help,-h}
40
+ │ ├─ + <cmd> → printCommandHelp(cmd) [AC-2] (cmd inválido → suggest, exit 1)
41
+ │ ├─ + --all → printHelp(all=true) [AC-3] (saída atual)
42
+ │ └─ (só) → printHelp(all=false) [AC-3] só tier:core + rodapé "--all para N"
43
+ ├─ COMMANDS[argv[0]] ausente
44
+ │ └─ suggest(argv[0]) → "Comando desconhecido… Você quis dizer X? forja help X" [AC-4]
45
+ └─ COMMANDS[argv[0]] presente
46
+ ├─ runGates() (inalterado)
47
+ ├─ validateRequiredArgs(cmd, rest) [AC-5]
48
+ │ falta arg required → stderr = cmd.usage; exit 1; NÃO spawna
49
+ └─ spawnSync(...) (inalterado)
50
+
51
+ forja setup [--yes] [AC-6]
52
+ └─ para step in [workspace:init, sync:universal]: (allowlist fixa, hard-coded)
53
+ --yes ausente & TTY → pergunta [s/N]
54
+ --yes ausente & não-TTY → aborta, exit 1, nada executado
55
+ → executa step, audita, segue
56
+
57
+ tools:doctor [AC-7]
58
+ └─ runChecks() → group by bucket → render:
59
+ "Bloqueia o fluxo" (blocking; falha → exit 1, como hoje)
60
+ "Rotina de primeiro uso" (first-run; ex.: workspace, memory-db — dica: forja setup)
61
+ "Opcional (ferramentas)" (optional; ADR-0018, nunca trava)
62
+ ```
63
+
64
+ ## 4. Contratos (API/CLI/Schema)
65
+
66
+ **Registry — campos opcionais adicionados ao tipo do comando** (todos `?`):
67
+
68
+ ```ts
69
+ type CommandArg = { name: string; required: boolean; desc: string };
70
+ interface Command {
71
+ domain: string; desc: string; // inalterados
72
+ node?: string; bin?: string; capability?: string; args?: string[]; gates?: string[]; // inalterados
73
+ usage?: string; // ex.: "forja spec:new <slug>"
74
+ cliArgs?: CommandArg[]; // args POSICIONAIS documentados (nome distinto de `args`, que é prefixo fixo do spawn)
75
+ examples?: string[]; // cada um começa com "forja "
76
+ next?: string[]; // comandos que costumam vir depois (nomes do registry)
77
+ spec?: string; // "SPEC-021" — antes embutido em `desc`
78
+ readonly?: boolean;
79
+ json?: boolean; // reservado p/ W5; nesta spec só declarado, não validado
80
+ tier?: 'core' | 'advanced'; // ausente ⇒ 'advanced'
81
+ }
82
+ ```
83
+
84
+ > Nota: o campo de args posicionais chama-se **`cliArgs`** para não colidir com `args` (hoje =
85
+ > prefixo fixo repassado ao script, ex.: `['new']`). AC-1/AC-5 da spec falam em `args` — registrar
86
+ > essa renomeação na spec (§Evidências).
87
+
88
+ **`forja help <cmd>`** — texto legível, exit 0; `<cmd>` inexistente → mesma saída de "comando
89
+ desconhecido", exit 1. Sem `--json` nesta spec.
90
+
91
+ **`forja setup [--yes]`** — exit 0 se todos os steps ok; 1 se abortado ou um step falhou. Ordem
92
+ fixa, allowlist fixa no código (não configurável).
93
+
94
+ **`suggest(input: string): string[]`** — até 5 nomes, ordenados por (substring exato > distância
95
+ de edição). Determinística.
96
+
97
+ ## 5. Decisões e alternativas
98
+
99
+ **D1 — Campos no registry declarativo, não um arquivo de help à parte.**
100
+ Rejeitado: `docs/commands/*.md` por comando (duplica a fonte, drift garantido); gerar help de
101
+ JSDoc dos scripts (frágil, cada script é um processo separado). O registry já é a fonte única e
102
+ já tem teste de integridade (`forja-core.test.js`).
103
+
104
+ **D2 — `--fix` vira `forja setup`, o doctor continua só diagnóstico.**
105
+ `scripts/tools-doctor.ts` declara no cabeçalho que **não conserta** por desenho ("rodar coisas
106
+ sem consentimento é a classe de risco oposta à que este comando existe para fechar"). Em vez de
107
+ violar isso, um comando dedicado `forja setup` roda a rotina de primeiro uso, e o bloco "Rotina
108
+ de primeiro uso" do doctor **aponta** para ele. Alternativa rejeitada: `tools:doctor --fix` com
109
+ confirmação — funcionaria, mas ergue a exceção "às vezes o doctor executa" que o cabeçalho pede
110
+ para nunca existir. **Impacto na spec**: AC-6 muda de `tools:doctor --fix` para `forja setup`;
111
+ AC-7 (blocos rotulados) fica; registrar em §Evidências da spec.
112
+
113
+ **D3 — Levenshtein pequeno inline, sem dependência.**
114
+ ~15 linhas de DP. Rejeitado: pacote `fastest-levenshtein` (dependência nova p/ 15 linhas);
115
+ `didyoumean2`. Limite de distância ≤ 2 e teto de 5 sugestões evitam ruído (risco da spec §7).
116
+
117
+ **D4 — "Núcleo" = 14 comandos (proposta da spec §5), fechada aqui.**
118
+ Mantidos os 14. Revisão: incluir `orchestrate:advance` (fluxo) — sim; `project:new` fica
119
+ (entrada de quem gera projeto); `engineer` fica (façade recomendada). `tier` é 1 linha por
120
+ comando — ajustável a qualquer momento, sem migração.
121
+
122
+ Nenhuma decisão é estrutural/irreversível → **sem ADR** (consistente com a spec).
123
+
124
+ ## 6. Dependências
125
+
126
+ - **Outras specs**: nenhuma bloqueia. `W5` (contrato `--json`) e `W6` (cobertura MCP) vão
127
+ **reusar** `cliArgs`/`usage`/`json` — este plan os deixa prontos, não os consome.
128
+ - **Pacotes npm**: nenhum novo.
129
+ - **Migrações de dado/memory**: nenhuma.
130
+
131
+ ## 7. Rollout
132
+
133
+ - [ ] Feature flag: não. Mudanças aditivas; `forja help --all` preserva a saída atual.
134
+ - [ ] Migração de dados: não.
135
+ - [ ] Doc/persona impactada: `docs/quick-reference.md`, `docs/cli-first-operacao.md`,
136
+ `DOC-MAP.md` (linha para `forja setup`). Personas developer/executive só ganham atalho.
137
+ - [ ] `CHANGELOG.md`: entrada em "Adicionado" (`forja help <cmd>`, `forja setup`, help em camadas)
138
+ e "Alterado" (saída de `tools:doctor` em 3 blocos — aditivo).
139
+
140
+ ## 8. Sinais de fracasso (kill criteria)
141
+
142
+ - Manter `usage`/`examples` dos 14 do núcleo já gera drift entre texto e comportamento real na
143
+ primeira semana (AC-8b não segura) → repensar: gerar `usage` a partir de `cliArgs` em vez de
144
+ string livre.
145
+ - `suggest()` fuzzy produz sugestão pior que o prefixo atual em casos reais de typo → reverter só
146
+ o algoritmo, manter o resto.
147
+ - Reclassificar os checks em 3 buckets exige tocar a lógica de `runChecks`/exit-code e arrisca o
148
+ gate de `tools:doctor` (que é `exit 1` real) → congelar AC-7, entregar AC-1..AC-6 e AC-8.
149
+
150
+ ## Evidências e estado real
151
+
152
+ | AC | Task (a decompor em `spec:tasks`) | Verificação |
153
+ |---|---|---|
154
+ | AC-1 | Campos opcionais no tipo + retrocompat | `tsc --noEmit`; teste "comando sem campos novos resolve" |
155
+ | AC-2 | `printCommandHelp` + branch `help <cmd>` | `forja help spec:new` mostra usage+exemplo; `forja help xpto` → exit 1 |
156
+ | AC-3 | `printHelp(all?)` + `tier` nos 14 | `forja help` só núcleo + rodapé; `forja help --all` == saída atual (snapshot) |
157
+ | AC-4 | `suggest()` + mensagens de erro | teste `suggest('plan')` ∋ `spec:plan`; `forja plan` → stderr com `forja help spec:plan` |
158
+ | AC-5 | `validateRequiredArgs` antes do spawn | `forja spec:new` (sem slug) → usage, exit 1, sem stack trace |
159
+ | AC-6 | `scripts/forja-setup.ts` + entrada no registry | `forja setup --yes` em clone limpo cria workspace + indexa; sem TTY e sem `--yes` → aborta |
160
+ | AC-7 | `bucket` em `health.ts` + render nos 2 consumidores | `tools:doctor` mostra os 3 rótulos; `hook-session-start` idem |
161
+ | AC-8 | Testes em `forja-core.test.js` | `node --test test/forja-core.test.js` verde |
162
+ | AC-9 | — | `node --test test/*.test.js`, `tsc --noEmit`, `forja spec:check` verdes |
163
+
164
+ - **Mudança de contrato vs. spec** (registrar na spec ao passar para `implementing`): (1) AC-6
165
+ `tools:doctor --fix` → `forja setup` (D2); (2) o campo de args posicionais chama-se `cliArgs`,
166
+ não `args` (D1/§4).
167
+ - **Hipótese, não medição**: os ganhos de §8 da spec dependem de instrumentação inexistente;
168
+ baseline sobre `forja-runs.jsonl` antes de qualquer número.
169
+ - **Bug lateral** (herdado da spec, não resolvido aqui): alocação de ID do `spec:new` — fora de escopo.
@@ -0,0 +1,163 @@
1
+ # Spec: cli-intuitiva-v1 — CLI descobrível pela própria CLI
2
+
3
+ - **ID**: SPEC-043
4
+ - **Status**: done
5
+ - **Owner**: apk
6
+ - **Criado em**: 2026-09-07
7
+ - **Sprint alvo**: <a definir>
8
+ - **ADRs relacionadas**: nenhuma — mudança aditiva ao registry declarativo (ADR-0020); nenhum
9
+ comando existente muda de assinatura, saída default ou exit code.
10
+ - **Origem**: `docs/roadmap-v4.1.md`, Onda 1 (W1 + W2 + W3).
11
+
12
+ ## 1. Problema
13
+
14
+ Agentes LLM e humanos erram ao operar o Forja porque a CLI não se explica:
15
+
16
+ - `forja help` despeja ~75 comandos numa parede única, com sufixos `(SPEC-0XX)` nas descrições
17
+ (ruído para quem opera, sinal só para auditoria) e sem uma camada "os comandos do núcleo".
18
+ - **Não existe `forja help <comando>`**. O uso, os argumentos posicionais, exemplos e próximos
19
+ passos não são descobríveis sem **executar o comando errado e interpretar o stack trace** do
20
+ script-filho.
21
+ - `suggest()` só casa prefixo do segmento antes de `:` (`bin/forja.ts`): `forja plan` **não**
22
+ sugere `spec:plan`. Mensagem de comando desconhecido não aponta para `help`.
23
+ - `tools:doctor` diagnostica mas não corrige. Em clone novo, os 3 avisos misturam "rotina de
24
+ primeiro uso" (`workspace:init`, `sync:universal`) com problema real, sem rótulo.
25
+
26
+ **Como medimos hoje**: não há instrumentação de erros de CLI. Evidência qualitativa: as seções
27
+ "Corrigido" dos changelogs v3/v4 e a leitura de `bin/forja.ts` + `lib/core/registry.ts`.
28
+
29
+ ## 2. Proposta de valor
30
+
31
+ Operar o Forja fica descobrível pela própria CLI: todo comando do núcleo tem `forja help <cmd>`
32
+ com uso, exemplo e próximo passo; erros de digitação sugerem o comando certo; `tools:doctor
33
+ --fix` resolve o setup de primeiro uso. Meta observável: um agente sem contexto prévio completa
34
+ `spec:new → spec:check` usando só `forja help`, sem doc externa.
35
+
36
+ ## 3. User stories
37
+
38
+ - **Como** agente LLM operando o Forja pela primeira vez, **quero** `forja help <cmd>` com uso e
39
+ exemplo, **para que** eu não execute o comando errado só para ler o stack trace.
40
+ - **Como** dev, **quero** `forja help` mostrando só o núcleo (~12 comandos), **para que** eu ache
41
+ o que preciso sem rolar 75 linhas.
42
+ - **Como** agente, **quero** que `forja plan` (ou um typo) sugira `spec:plan`, **para que** eu me
43
+ recupere sem consultar documentação externa.
44
+ - **Como** dev num clone novo, **quero** `forja tools:doctor --fix`, **para que** eu não
45
+ copie/cole dois comandos de setup a cada clone.
46
+
47
+ ## 4. Critérios de aceite (Definition of Done)
48
+
49
+ - [ ] **AC-1**: `lib/core/registry.ts` aceita campos **opcionais** por comando: `usage: string`,
50
+ `args: {name, required, desc}[]`, `examples: string[]`, `next: string[]`,
51
+ `readonly: boolean`, `json: boolean`, `tier: 'core' | 'advanced'`. Comandos sem esses
52
+ campos continuam funcionando (teste de retrocompatibilidade).
53
+ - [ ] **AC-2**: `forja help <comando>` imprime nome, domínio, descrição, `usage`, tabela de
54
+ `args`, `examples`, "Próximos passos" (`next`) e a ADR/SPEC de origem quando houver.
55
+ Comando inexistente → sugestão do AC-4 e exit 1.
56
+ - [ ] **AC-3**: `forja help` (sem args) lista **apenas** comandos `tier: 'core'`, agrupados por
57
+ domínio, **sem** o sufixo `(SPEC-0XX)` na linha, com rodapé
58
+ `use 'forja help --all' para os N comandos restantes`. `forja help --all` mantém a saída
59
+ completa atual.
60
+ - [ ] **AC-4**: `suggest()` casa por substring **e** distância de edição (≤ 2) sobre o nome
61
+ completo; `forja plan` inclui `spec:plan` nas sugestões; toda mensagem de comando
62
+ desconhecido termina com `forja help <melhor-palpite>`.
63
+ - [ ] **AC-5**: quando um comando declara `args` com `required: true` e o argumento falta,
64
+ `bin/forja.ts` valida **antes de spawnar** o script-filho, imprime o `usage` do comando e
65
+ sai com exit 1 — sem stack trace do filho.
66
+ - [ ] **AC-6**: `forja tools:doctor --fix [--yes]` executa **apenas** correções idempotentes e
67
+ seguras de uma allowlist fixa (`workspace:init`, `sync:universal`); sem `--yes` pede
68
+ confirmação; em stdin não-TTY sem `--yes`, aborta sem alterar nada. Sem `--fix`, o
69
+ comportamento atual é inalterado.
70
+ - [ ] **AC-7**: a saída de `tools:doctor` é agrupada em três blocos rotulados fixos —
71
+ **"Bloqueia o fluxo"**, **"Rotina de primeiro uso"**, **"Opcional (ferramentas)"**. O
72
+ gerador do bloco `<framework-status>` do SessionStart usa a mesma classificação.
73
+ - [ ] **AC-8**: `test/forja-core.test.js` estendido: (a) todo comando `tier: 'core'` tem `usage`
74
+ não-vazio e ≥ 1 `example`; (b) todo `example` começa com `forja ` e cita um comando que
75
+ existe no registry; (c) `suggest('plan')` inclui `spec:plan`.
76
+ - [ ] **AC-9**: `node --test test/*.test.js`, `tsc --noEmit` e `node bin/forja.ts spec:check`
77
+ continuam verdes.
78
+
79
+ ## 5. Escopo
80
+
81
+ **Dentro**:
82
+ - Campos novos no registry, preenchidos para o conjunto `tier: 'core'` (proposta inicial, a
83
+ fechar no `plan`): `workspace:init`, `project:new`, `spec:new`, `spec:plan`, `spec:tasks`,
84
+ `spec:check`, `orchestrate`, `orchestrate:status`, `orchestrate:advance`, `context:smart`,
85
+ `query:universal`, `tools:doctor`, `project:check`, `engineer`.
86
+ - `forja help <cmd>`, `forja help --all`, help curto por default.
87
+ - `suggest()` fuzzy; pré-validação de argumentos `required` em `bin/forja.ts`.
88
+ - `tools:doctor --fix` + reclassificação da saída em três blocos + alinhamento do SessionStart.
89
+ - Testes (AC-8) e ajuste da doc de comandos afetada.
90
+
91
+ **Fora** (evita scope creep):
92
+ - Preencher `usage`/`examples` dos ~75 comandos — só o núcleo agora; o resto é backlog incremental.
93
+ - `forja status` / `forja next` — Onda 2 (W4), spec própria.
94
+ - Contrato `--json` + exit codes global — Onda 2 (W5), spec própria.
95
+ - TUI / onboarding interativo.
96
+ - Corrigir a alocação de ID do `spec:new` (ver §Evidências) — task/bug separado.
97
+ - Qualquer mudança na semântica ou na saída default de comando existente.
98
+
99
+ ## 6. NFRs / restrições
100
+
101
+ - **Compatibilidade**: nenhum comando existente muda de assinatura, saída default ou exit code.
102
+ Exceção aditiva: `tools:doctor` ganha os blocos rotulados e a flag `--fix`. Checkout `.ts` e
103
+ pacote publicado (`dist/*.js`) idênticos — `resolveScript` já cobre.
104
+ - **Performance**: `forja help` e `forja help <cmd>` são leitura do registry em memória, < 50 ms.
105
+ - **Segurança**: `tools:doctor --fix` nunca executa nada fora da allowlist fixa de dois comandos
106
+ idempotentes; sem `--yes` exige confirmação; sem TTY e sem `--yes`, aborta.
107
+ - **Observabilidade**: cada execução de `--fix` é auditada em `forja-runs.jsonl` como hoje.
108
+
109
+ ## 7. Riscos e mitigação
110
+
111
+ | Risco | Probabilidade | Impacto | Mitigação |
112
+ |---|---|---|---|
113
+ | Definir "núcleo" errado (comando importante fora, ou núcleo inchado) | M | M | Lista revisada no `plan`; `forja help --all` sempre disponível; ajuste é 1 linha no registry |
114
+ | `suggest()` fuzzy devolve sugestão ruim e confunde o agente | B | B | Distância ≤ 2 e no máximo 5 sugestões; teste com casos reais de typo |
115
+ | `--fix` dispara `sync:universal` pesado sem o usuário querer | B | M | Confirmação obrigatória sem `--yes`; escopo restrito a 2 comandos idempotentes |
116
+ | `usage`/`example` no registry divergem do que o comando aceita | M | M | AC-8(b) valida que todo `example` cita comando existente; W6 (MCP) passará a reusar os mesmos campos, aumentando a pressão de manter em dia |
117
+
118
+ ## 8. Métricas de sucesso
119
+
120
+ Avaliar 30 dias após o release, com **baseline coletado antes** sobre `forja-runs.jsonl`:
121
+
122
+ - Queda na taxa de "errei e corrigi": execução com exit ≠ 0 seguida, em < 2 min, de re-execução
123
+ bem-sucedida do mesmo comando-base (proxy).
124
+ - Adoção: `help <cmd>` aparece em `forja-runs.jsonl` como comando efetivamente usado por agentes.
125
+ - Zero regressões abertas atribuídas a esta mudança.
126
+ - Qualitativo: numa sessão de agente sem contexto prévio, o agente completa `spec:new →
127
+ spec:check` usando só `forja help`, sem doc externa.
128
+
129
+ ## Evidências e estado real
130
+
131
+ **Implementado em 2026-09-07** (branch de trabalho, não commitado). Bateria: `tsc --noEmit`,
132
+ `node --test test/*.test.js` (479/479, +6 testes novos em `test/forja-core.test.js`),
133
+ `forja spec:check cli-intuitiva-v1`, `forja project:check` (100%), `forja tools:doctor` (exit 0,
134
+ 3 blocos rotulados) — todos verdes.
135
+
136
+ | AC | Onde | Verificado |
137
+ |---|---|---|
138
+ | AC-1 | `lib/core/registry.ts` — `interface CommandSpec` + `CommandArg`, todos os campos `?` | `tsc` verde; comandos sem campos novos seguem resolvendo |
139
+ | AC-2 | `bin/forja.ts` `printCommandHelp()` + branch `help <cmd>` / `<cmd> --help` | `forja help spec:new` mostra uso+exemplo+próximos passos; `forja help xpto` → exit 1 |
140
+ | AC-3 | `bin/forja.ts` `printHelp(all?)` + `tier` em ~20 comandos | `forja help` só núcleo + rodapé `--all`; `diff` de `forja help --all` vs baseline = só `setup` novo + `(SPEC-` removido de 4 descs |
141
+ | AC-4 | `bin/forja.ts` `suggest()` + `levenshtein()` | `suggest('plan') ∋ spec:plan`; `forja plan` → stderr com `forja help spec:plan`; teste em `forja-core.test.js` |
142
+ | AC-5 | `bin/forja.ts` `missingRequiredArg()` antes do `spawnSync` | `forja spec:new` (sem slug) → `Uso:`, exit 1, sem stack; teste dedicado |
143
+ | AC-6 | `scripts/forja-setup.ts` + entrada `setup` no registry + `package.json` | `forja setup --yes` em WS temporário limpo cria estrutura + índice (exit 0); 2ª execução exit 0; sem TTY e sem `--yes` → exit 1, nada criado |
144
+ | AC-7 | `lib/core/health.ts` `bucketFor()`/`BUCKET_LABEL`; render em `scripts/tools-doctor.ts` e `scripts/hook-session-start.ts` | `forja tools:doctor` imprime os 3 rótulos; `runChecks`/exit-code intactos |
145
+ | AC-8 | `test/forja-core.test.js` — testes (a)(b)(c) | `node --test test/forja-core.test.js` verde (11 testes) |
146
+ | AC-9 | — | bateria acima verde |
147
+
148
+ - **Hipótese**, não medição: os ganhos de §8 dependem de instrumentação que ainda não existe;
149
+ o baseline precede qualquer percentual prometido.
150
+ - **Mudanças de contrato vs. o texto original desta spec** (decididas no `plan.md`):
151
+ 1. **AC-6**: `tools:doctor --fix` → **`forja setup`** (comando dedicado). O cabeçalho de
152
+ `scripts/tools-doctor.ts` declara que o doctor *não conserta* por desenho; um `--fix` ergueria
153
+ a exceção que ele existe para impedir. O bloco "Rotina de primeiro uso" do doctor aponta para
154
+ `forja setup`.
155
+ 2. **AC-1/AC-5**: o campo de args posicionais no registry chama-se **`cliArgs`**, não `args`
156
+ (`args` já é o prefixo fixo repassado ao script no spawn).
157
+ 3. Núcleo ficou com ~20 comandos (não os 14 exatos do §5): `sync:universal` entrou por ser
158
+ alvo de `setup` e de `workspace:init.next`. `tier` é 1 linha por comando, ajustável sem migração.
159
+ - **Bug lateral, ainda aberto** (achado A9 do roadmap): `spec:new` alocou `SPEC-040` (colisão);
160
+ corrigido à mão para **SPEC-043**. Fora do escopo desta spec — candidato a bug fix próprio.
161
+ - **Pendências**: handoff `implement`/`review` não registrado via Hermes (o `hermes:handoff` exige
162
+ payload JSON ADR-0005 completo + tabela `handoffs` no workspace); revisão de Governança sobre o
163
+ diff ainda não feita; nada commitado.