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