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,175 @@
1
+ # Tasks: forja-status-caminho-feliz
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Plan**: ./plan.md
5
+ - **Status**: approved
6
+ - **Criado em**: 2026-09-07
7
+
8
+ > Decomposição executável. Cada task tem dono, critério de done e paths.
9
+
10
+ Grafo de dependência:
11
+
12
+ ```
13
+ T1 ─┐
14
+ T2 ─┤
15
+ T3 ─┼─ T5 ─┬─ T7 ─┬─ T9
16
+ T4 ─┘ └─ T6 ─┘ │
17
+ T1,T2,T7 ─────► T8 ───┤
18
+ T7,T8 ────────► T10 ──┤
19
+ todas ────────────────► T11
20
+ ```
21
+
22
+ Paralelizável no início: **T1 · T2 · T3 · T4**.
23
+
24
+ ---
25
+
26
+ ## T1 — `lib/specs-index.ts` (extrair `listSpecs`)
27
+ - **Owner**: Worker · **Est**: P · **Depende de**: —
28
+ - **Paths**: `lib/specs-index.ts` (novo), `scripts/hook-session-start.ts`
29
+ - **Escopo**: mover `listSpecs()` de `hook-session-start.ts` para `lib/specs-index.ts`
30
+ (`export function listSpecs(root: string): { slug: string; status: string }[]`); o hook passa a
31
+ importar de lá. Sem mudança de comportamento do hook.
32
+ - **Done**:
33
+ - [ ] `hook-session-start` importa de `lib/specs-index`; nenhuma lógica de parsing duplicada
34
+ - [ ] `tsc --noEmit` verde; `node --test test/*.test.js` sem regressão no hook
35
+
36
+ ## T2 — `lib/handoffs-index.ts` (extrair `openHandoffs`)
37
+ - **Owner**: Worker · **Est**: P · **Depende de**: —
38
+ - **Paths**: `lib/handoffs-index.ts` (novo), `scripts/hook-session-start.ts`
39
+ - **Escopo**: mover `openHandoffs()` (query SQLite readonly, `try/catch` → `[]`) para
40
+ `lib/handoffs-index.ts`; o hook reimporta. Assinatura:
41
+ `openHandoffs(): { id; from; to; intent; slug }[]` (normaliza `from_agent`/`to_agent`/`spec_slug`).
42
+ - **Done**:
43
+ - [ ] hook usa `lib/handoffs-index`; degrada para `[]` sem `node_modules`/sem banco
44
+ - [ ] `tsc` + testes verdes
45
+
46
+ ## T3 — `lib/sprint-index.ts` (`readSprint`)
47
+ - **Owner**: Worker · **Est**: P · **Depende de**: —
48
+ - **Paths**: `lib/sprint-index.ts` (novo)
49
+ - **Escopo**: `readSprint(root): { active: boolean; title: string | null; items: number } | null`
50
+ lendo `memory/40-delivery/current-sprint.md` (existe? primeira `# `/`## ` como título; conta
51
+ itens de checklist). Espelha o que `showStatus` de `sprint-manager.ts` lê — **não** importa
52
+ aquele script (ele só imprime).
53
+ - **Done**:
54
+ - [ ] retorna `null` quando o arquivo não existe; `{active:true,...}` quando existe
55
+ - [ ] `tsc` verde
56
+
57
+ ## T4 — `lib/orchestrate.ts` — `listRuns()`
58
+ - **Owner**: Worker · **Est**: P · **Depende de**: —
59
+ - **Paths**: `lib/orchestrate.ts`
60
+ - **Escopo**: `export function listRuns(root: string, env?: OrchestrateEnv): string[]` — glob
61
+ `<root>/.context/orchestrate-*.json`, devolve os slugs. Restrito ao `contextDir` passado (não
62
+ varre projetos gerados). `loadState` já é exportado.
63
+ - **Done**:
64
+ - [ ] `listRuns` só enxerga `.context/` do root dado; array vazio quando não há corrida
65
+ - [ ] testes existentes de `lib/orchestrate` verdes
66
+
67
+ ## T5 — `lib/status-model.ts` — `collectStatus()`
68
+ - **Owner**: Worker · **Est**: M · **Depende de**: T1, T2, T3, T4
69
+ - **Paths**: `lib/status-model.ts` (novo)
70
+ - **Escopo**: `collectStatus(root, opts?): StatusModel` (contrato no plan §4). Cada coletor em
71
+ `try/catch` → `{ available: false, reason }`. `workspace` ← `getWorkspaceInfo()`; `sprint` ←
72
+ `readSprint`; `orchestrate` ← `listRuns` + `loadState` (deriva `openStage`, `lastVerdict`,
73
+ `concluded`); `specs` ← `listSpecs`; `recentRuns` ← tail (≤5) de
74
+ `<contextDir>/forja-runs.jsonl` (`getWorkspaceContextDir()` ou `.context/` do repo); `handoffs`
75
+ ← `openHandoffs`. **Nunca lança.**
76
+ - **Done**:
77
+ - [ ] num WS temporário vazio → 6 chaves presentes, subsistemas sem fonte → `available:false` com `reason`
78
+ - [ ] num WS real → seções preenchidas
79
+ - [ ] teste unitário de `collectStatus` (sem spawn)
80
+
81
+ ## T6 — `lib/status-model.ts` — `recommendNext()` (escada AC-4)
82
+ - **Owner**: Worker · **Est**: P · **Depende de**: T5 (tipos)
83
+ - **Paths**: `lib/status-model.ts`
84
+ - **Escopo**: função **pura** `recommendNext(model): { action, command, reason }` implementando os
85
+ 7 níveis da AC-4, na ordem. Determinística.
86
+ - **Done**:
87
+ - [ ] teste cobrindo os 7 ramos (workspace ausente; memória crua; corrida gate vermelho; corrida
88
+ etapa pronta; spec approved sem plan; plan approved sem tasks; spec implementing; nada pendente)
89
+ - [ ] empates impossíveis (a ordem resolve)
90
+
91
+ ## T7 — `scripts/forja-status.ts` (render `status` + `next`)
92
+ - **Owner**: Worker · **Est**: M · **Depende de**: T5, T6
93
+ - **Paths**: `scripts/forja-status.ts` (novo)
94
+ - **Escopo**: dispatch por `args[0]` (`status` | `next`); flag `--json`. `status` texto → seções
95
+ rotuladas (seção em erro → `indisponível: <reason>`); `status --json` → `{ status:"ok", ...model }`.
96
+ `next` texto → 1 linha `→ forja <cmd> …` + `reason`; `next --json` → `{ action, command, reason }`.
97
+ Exit 0 sempre que o model montou.
98
+ - **Done**:
99
+ - [ ] `forja status` e `forja status --json` rodam num repo real, exit 0
100
+ - [ ] `forja next` imprime exatamente uma recomendação
101
+ - [ ] nenhuma saída com stack trace
102
+
103
+ ## T8 — Registry: `status`/`next` + reordenar `orchestrate`
104
+ - **Owner**: Worker · **Est**: P · **Depende de**: T1, T2, T7
105
+ - **Paths**: `lib/core/registry.ts`, `scripts/hook-session-start.ts`
106
+ - **Escopo**: entradas `status` e `next` → `node: 'scripts/forja-status.ts'`, `args: ['status']` /
107
+ `['next']`, `domain: 'gsd'`, `tier: 'core'`, `readonly: true`, `json: true`, `usage`/`examples`/
108
+ `next`, sem gate bloqueante (`workspace-warn` no máximo). Mover os 3 `orchestrate*` para o
109
+ início do bloco `gsd` no objeto `COMMANDS` (ordem = ordem no `forja help`). Confirmar que o hook
110
+ já importa de `lib/` (T1/T2).
111
+ - **Done**:
112
+ - [ ] `forja help` (núcleo) lista `status`, `next`; `orchestrate` aparece antes de `gsd:*`
113
+ - [ ] `forja help status` mostra uso + exemplo
114
+ - [ ] `test/forja-core.test.js` (integridade do registry) verde
115
+
116
+ ## T9 — Testes (AC-8) + regressão do hook
117
+ - **Owner**: Worker · **Est**: M · **Depende de**: T5, T6, T7, T8
118
+ - **Paths**: `test/forja-status.test.js` (novo), `test/` do hook se existir
119
+ - **Escopo**: `forja status --json` em WS temporário vazio → 6 chaves + `status:"ok"` + subs
120
+ `available:false`; `forja next --json` no mesmo → `action ∈ {setup, sync}`; fixture de spec
121
+ `approved` sem `plan.md` → `forja next` aponta `spec:plan <slug>`. Garantir que o
122
+ `hook-session-start` continua produzindo o mesmo `<framework-status>` após T1/T2.
123
+ - **Done**:
124
+ - [ ] `node --test test/forja-status.test.js` verde
125
+ - [ ] teste do hook (ou smoke `node scripts/hook-session-start.ts`) sem regressão
126
+
127
+ ## T10 — Documentação + CHANGELOG
128
+ - **Owner**: Worker · **Est**: P · **Depende de**: T7, T8
129
+ - **Paths**: `README.md`, `docs/cli-first-operacao.md`, `docs/quick-reference.md`, `CHANGELOG.md`
130
+ - **Escopo**: `README.md` ganha uma linha com `orchestrate` como caminho padrão + menção a
131
+ `forja next`. `docs/cli-first-operacao.md` e `quick-reference.md`: `forja status` / `forja next`
132
+ no bloco "Descoberta pela própria CLI". CHANGELOG `[Unreleased]`: Adicionado (`forja status`,
133
+ `forja next`); Alterado (`orchestrate` no topo do bloco GSD do help).
134
+ - **Done**:
135
+ - [ ] `forja tools:doctor` → `docs-commands`, `commands-documented`, `docs-links` verdes
136
+
137
+ ## T11 — Validação final + fecho
138
+ - **Owner**: Worker → Governance · **Est**: P · **Depende de**: T1–T10
139
+ - **Escopo**: bateria completa; atualizar `spec.md` §Evidências (resultado, data, desvios se
140
+ houver); mover status. Registrar handoff `review` via Hermes.
141
+ - **Done**:
142
+ - [ ] `tsc --noEmit`, `node --test test/*.test.js`, `forja spec:check`, `forja project:check` verdes — AC-9
143
+ - [ ] `forja spec:set-status forja-status-caminho-feliz spec implementing` no início; `done` ao fim
144
+ - [ ] handoff `worker → governance (review)` registrado
145
+
146
+ ---
147
+
148
+ ## Mapa AC → task
149
+
150
+ | AC | Tasks | Verificação-chave |
151
+ |---|---|---|
152
+ | AC-1 | T5, T7 | `forja status` — 6 seções rotuladas |
153
+ | AC-2 | T5, T7, T9 | `forja status --json` — 6 chaves + `status:"ok"`, subs `available:false` |
154
+ | AC-3 | T6, T7 | `forja next` — 1 linha `→ forja …`; `--json` → `{action,command,reason}` |
155
+ | AC-4 | T6, T9 | testes dos 7 ramos de `recommendNext` |
156
+ | AC-5 | T8 | registry `readonly:true`, sem gate `workspace`; `forja next` não escreve estado |
157
+ | AC-6 | T8 | `forja help` lista `status`/`next`; `orchestrate` no topo do bloco GSD |
158
+ | AC-7 | T1, T2, T4 | hook importa de `lib/specs-index`, `lib/handoffs-index`; corrida via `loadState`/`listRuns` |
159
+ | AC-8 | T9 | `node --test test/forja-status.test.js` |
160
+ | AC-9 | T11 | bateria completa verde |
161
+
162
+ ## Handoffs entre agentes
163
+
164
+ SDD Architect (spec+plan+tasks, feito) → **Worker** (T1–T10) → **Governance** (T11 + `project:check`).
165
+
166
+ ```bash
167
+ node bin/forja.ts hermes:handoff '{"from":"sdd-architect","to":"worker","intent":"implement","context":"SPEC-044 forja-status-caminho-feliz, branch feat/forja-status (empilhada sobre feat/cli-intuitiva-v1)","acceptance":"AC-1..AC-9 + bateria verde","constraints":"read-only, sem ADR, sem mudar comando existente; depende de SPEC-043","return":"diff + parecer"}'
168
+ ```
169
+
170
+ ## Evidências e estado real
171
+
172
+ - Nada executado — todas as caixas `[ ]` abertas.
173
+ - **Dependência viva**: `feat/cli-intuitiva-v1` (PR #61). Se #61 mudar `forja setup` ou os campos
174
+ do registry, revisar T5/T8.
175
+ - **Hipótese, não medição**: métricas de §8 da spec dependem de instrumentação inexistente.
@@ -0,0 +1,117 @@
1
+ # Plan: llm-adaptador-claude
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Status**: approved
5
+ - **Criado em**: 2026-09-08
6
+
7
+ ## 1. Abordagem técnica
8
+
9
+ O padrão já existe (`if (provider === 'codex') …` + `lib/llm/codex-output.ts`); W12 preenche o
10
+ ramo `claude`. `buildLlmExecution` monta `claude -p "<prompt>" --output-format json [--model]
11
+ [--resume <id>]`. `lib/llm/claude-output.ts` `normalizeClaudeResult` parseia o **objeto JSON
12
+ único** do `--output-format json` (não JSONL). `RESUME_PROVIDERS = { 'codex', 'claude' }`
13
+ (exportado de `lib/llm/session.ts`) substitui os dois `provider === 'codex'` que travam a
14
+ retomada. `run()` escolhe o normalizador por provedor e salva a sessão para os dois. `doctor()`
15
+ ganha um ramo `claude` para `features`. Sem framework de adaptadores — ADR-0085 §alt.
16
+
17
+ ## 2. Módulos afetados
18
+
19
+ | Caminho | Mudança | Risco |
20
+ |---|---|---|
21
+ | `packages/llm/src/index.ts` | editar — ramo `claude` de `buildLlmExecution` (`--output-format json`, `--resume`); guard de `resume`: `provider !== 'codex'` → `!RESUME_PROVIDERS.has(provider)`. Importa `RESUME_PROVIDERS` | M |
22
+ | `lib/llm/claude-output.ts` | **criar** — `normalizeClaudeResult(result): NormalizedLlmResult` (objeto único; `result`→stdout, `session_id`→sessionId, `usage`, `is_error`/`subtype`→`PROVIDER_FAILED`, parse ruim→`INVALID_PROVIDER_OUTPUT`) | M |
23
+ | `lib/llm/session.ts` | editar — `export const RESUME_PROVIDERS = new Set(['codex', 'claude'])`; `require()`: `profile.provider !== 'codex'` → `!RESUME_PROVIDERS.has(profile.provider)` | B |
24
+ | `scripts/llm-fit.ts` | editar — `run()`: `provider === 'claude'` → `normalizeClaudeResult`; `if (selected.provider === 'codex' && sessionId …)` → `if (RESUME_PROVIDERS.has(selected.provider) && sessionId …)`. `doctor()`: ramo `value.provider === 'claude'` → `features = { resume: help.stdout.includes('--resume'), outputSchema: false }` | M |
25
+ | `docs/llm-fit-loop.md`, `docs/llm-evolution.md` | editar — adaptador Claude + nota "schema local"; C3 fechado | B |
26
+ | `test/*` | criar/estender — `buildLlmExecution` claude, `normalizeClaudeResult`, `require` claude, `doctor` features | M |
27
+
28
+ ## 3. Diagrama de fluxo
29
+
30
+ ```
31
+ forja llm:run --profile claude [--prompt "<t>" | --engineer "<o>"] [--resume <id>] [--output-schema s]
32
+ │
33
+ ├─ buildLlmExecution(claude, prompt, { resume, outputSchema }):
34
+ │ guard: resume && !RESUME_PROVIDERS.has('claude') → erro (agora passa)
35
+ │ argv = [ -p, "<prompt>", --output-format, json, (--model m)?, (--resume <id>)? ] (shell:false)
36
+ │ outputSchema NÃO vira flag do claude — vai como instrução no prompt (caminho não-Codex)
37
+ ├─ runLlm(...) → raw stdout = { type:"result", result, session_id, usage, is_error, subtype, ... }
38
+ ├─ normalizeClaudeResult(raw):
39
+ │ ok → { stdout: result, sessionId: session_id, usage, exitCode:0 }
40
+ │ is_error → { errorCode: 'PROVIDER_FAILED', exitCode:1 }
41
+ │ parse ✗ → { errorCode: 'INVALID_PROVIDER_OUTPUT', exitCode:1 }
42
+ ├─ validateLlmResponse(prepared, stdout, …) (Ajv local — igual pra todos)
43
+ └─ RESUME_PROVIDERS.has('claude') && sessionId → LlmSessionStore.save(sessionId, profile, cwd, obsId)
44
+
45
+ forja llm:probe claude → features: { resume: true, outputSchema: false }
46
+ ```
47
+
48
+ ## 4. Contratos (API/CLI/Schema)
49
+
50
+ ```ts
51
+ // packages/llm — buildLlmExecution(provider:'claude'):
52
+ // args = [...base, ...(model!=='default'?['--model',model]:[]), '-p', prompt,
53
+ // '--output-format','json', ...(resume?['--resume',resume]:[])]
54
+
55
+ // lib/llm/session.ts
56
+ export const RESUME_PROVIDERS: ReadonlySet<string>; // { 'codex', 'claude' }
57
+
58
+ // lib/llm/claude-output.ts
59
+ export function normalizeClaudeResult(result: LlmExecutionResult): NormalizedLlmResult;
60
+ ```
61
+
62
+ Nenhuma chave nova na saída JSON do `llm:run` — Claude usa o mesmo `NormalizedLlmResult`.
63
+
64
+ ## 5. Decisões e alternativas
65
+
66
+ **D1 — `RESUME_PROVIDERS` como `Set` exportado, não um campo no perfil.** Suportar retomada é
67
+ propriedade do *adaptador* (o que a CLI oferece), não escolha do operador. Rejeitado: `resume:
68
+ boolean` no `LlmProfile` (operador não deveria poder mentir sobre a capacidade da CLI).
69
+
70
+ **D2 — `--output-format json` (objeto único), não `stream-json`.** ADR-0085 §alt. Menos parsing,
71
+ suficiente para não-interativo.
72
+
73
+ **D3 — `--output-schema` para Claude = instrução + Ajv local; `features.outputSchema: false`.**
74
+ O `claude` não tem flag de schema. O caminho não-Codex já faz isso (SPEC-028). `false` é honesto:
75
+ a garantia é local. Rejeitado: fingir `true` (o operador confiaria numa garantia que não existe).
76
+
77
+ **D4 — `doctor` probe de `claude --help` para `features.resume`.** Espelha o probe do Codex
78
+ (`codex exec resume --help`). `outputSchema` fixo em `false` para claude (não há o que probar).
79
+
80
+ ADR-0085 cobre o desenho; sem ADR adicional.
81
+
82
+ ## 6. Dependências
83
+
84
+ - De `main` (com W10 + W11). Reusa `NormalizedLlmResult` (`lib/llm/codex-output.ts` exporta o
85
+ tipo), `LlmSessionStore`, `prepareValidation`/`validateLlmResponse`.
86
+ - `claude` CLI ≥ o que tem `--print --output-format json --resume` (2.x). Testes usam fixture.
87
+ - Pacotes npm: nenhum. Migrações: nenhuma.
88
+
89
+ ## 7. Rollout
90
+
91
+ - [ ] Feature flag: não. O perfil `claude` já existe em `DEFAULT_LLM_PROFILES`; ganha capacidade.
92
+ - [ ] Doc: `docs/llm-fit-loop.md` (adaptador Claude, nota do schema local), `docs/llm-evolution.md`
93
+ (C3 → fechado).
94
+ - [ ] `CHANGELOG.md` `[Unreleased]`: Adicionado (adaptador Claude com resume + JSON + schema local).
95
+
96
+ ## 8. Sinais de fracasso (kill criteria)
97
+
98
+ - O `claude --output-format json` real diverge do formato assumido a ponto de `normalizeClaudeResult`
99
+ virar um parser frágil → congelar no formato do fixture, marcar `INVALID_PROVIDER_OUTPUT` em
100
+ tudo que não bater, e abrir issue para revisar quando um humano rodar contra o CLI real.
101
+ - Relaxar o guard de `resume` quebra um teste do Codex que assumia "só codex" → o teste vira
102
+ "só RESUME_PROVIDERS"; se for mais que 1–2 asserções, manter Codex-only e entregar só o
103
+ `--output-format json` + normalização nesta rodada, resume numa spec própria.
104
+
105
+ ## Evidências e estado real
106
+
107
+ | AC | Task | Verificação |
108
+ |---|---|---|
109
+ | AC-1/AC-2 | T1 | argv exato de `buildLlmExecution` claude com/sem resume; guard aceita claude |
110
+ | AC-3 | T2 | `normalizeClaudeResult` — sucesso / `is_error` / parse ruim |
111
+ | AC-4 | T3 | `run()` normaliza e salva sessão para claude |
112
+ | AC-5 | T3 | `--output-schema` + claude → instrução + Ajv, sem flag no claude |
113
+ | AC-6 | T3 | `doctor` `features` para claude |
114
+ | AC-7 | T4 | docs + CHANGELOG |
115
+ | AC-8/AC-9 | T5 | testes; caminho Codex intacto |
116
+
117
+ - **Sem mudança no contrato de saída.** Limitação assumida: schema local para Claude.
@@ -0,0 +1,144 @@
1
+ # Spec: llm-adaptador-claude — adaptador Claude com paridade de retomada e formato
2
+
3
+ - **ID**: SPEC-050
4
+ - **Status**: done
5
+ - **Owner**: apk
6
+ - **Criado em**: 2026-09-08
7
+ - **Sprint alvo**: <a definir>
8
+ - **ADRs relacionadas**: **ADR-0085** (o desenho do adaptador). ADR-0081 (sessões e validação).
9
+ - **Origem**: `docs/roadmap-v4.1.md`, Onda 4 (W12) — fecha C3.
10
+
11
+ ## 1. Problema
12
+
13
+ O adaptador `claude` do `llm:run` é mínimo: `buildLlmExecution` monta `claude -p "<prompt>"` e
14
+ nada mais. **Retomada** e **formato estruturado** são Codex-only por decisão do ADR-0081 —
15
+ `buildLlmExecution` lança `"resume requires codex"`, e `llm:run` só normaliza/salva sessão para
16
+ `codex`. O `claude` CLI (Claude Code) já expõe `--print --output-format json` (objeto único com
17
+ `result`, `session_id`, `usage`), `-r/--resume <session-id>` e `--session-id <uuid>` — a
18
+ assimetria não tem mais razão técnica.
19
+
20
+ ## 2. Proposta de valor
21
+
22
+ `llm:run --profile claude` passa a: emitir JSON estruturado do provedor, registrar `sessionId`
23
+ retomável, aceitar `--resume`, e validar `--output-schema` localmente. `llm:probe claude` reporta
24
+ `features.resume: true` / `features.outputSchema: false`. Dentro da mesma fronteira de privacidade
25
+ do Codex — `shell: false`, sem ler API keys.
26
+
27
+ ## 3. User stories
28
+
29
+ - **Como** operador com um perfil Claude, **quero** `llm:run --profile claude --resume <id>` para
30
+ continuar uma conversa, **para que** eu não perca contexto entre execuções.
31
+ - **Como** operador, **quero** `llm:run --profile claude --output-schema s` com validação local,
32
+ **para que** eu tenha a mesma garantia de formato do fluxo Codex (mesmo que local).
33
+ - **Como** operador, **quero** `llm:probe claude` mostrando quais recursos o adaptador suporta,
34
+ **para que** eu não descubra a limitação só na execução.
35
+
36
+ ## 4. Critérios de aceite (Definition of Done)
37
+
38
+ - [x] **AC-1**: `buildLlmExecution` para `provider: 'claude'` monta
39
+ `claude -p "<prompt>" --output-format json [--model <m>] [--resume <session-id>]`
40
+ (`shell: false`, prompt por argumento). Sem `--resume`, sem esse par.
41
+ - [x] **AC-2**: o guard de `resume` deixa de ser Codex-only — `RESUME_PROVIDERS = { 'codex',
42
+ 'claude' }` rege `buildLlmExecution` e `LlmSessionStore.require`. `validSessionId` já aceita
43
+ UUID (não muda). Um provedor fora do conjunto com `--resume` → erro claro.
44
+ - [x] **AC-3**: `lib/llm/claude-output.ts` `normalizeClaudeResult(result): NormalizedLlmResult`
45
+ parseia o objeto JSON único: `stdout` ← `result`; `sessionId` ← `session_id`; `usage` ←
46
+ `{ inputTokens: input_tokens, outputTokens: output_tokens, cachedInputTokens:
47
+ cache_read_input_tokens? }`. `is_error: true` ou `subtype !== 'success'` → `errorCode:
48
+ 'PROVIDER_FAILED'`; JSON inválido → `'INVALID_PROVIDER_OUTPUT'`; nunca devolve o objeto cru
49
+ como resposta.
50
+ - [x] **AC-4**: `llm:run` `run()` — `provider === 'claude'` → `normalizeClaudeResult(raw)`;
51
+ `sessionId` gravado em `llm_session` via `LlmSessionStore.save` para `claude` também (a
52
+ condição `provider === 'codex'` vira `RESUME_PROVIDERS.has(provider)`).
53
+ - [x] **AC-5**: `--output-schema` com um perfil Claude — o Forja instrui "responda só JSON
54
+ conforme o schema" e valida com Ajv localmente (caminho não-Codex já existente); nenhum
55
+ flag de schema é passado ao `claude`.
56
+ - [x] **AC-6**: `doctor()` (`llm:probe`/`llm:doctor`) — para `provider: 'claude'` disponível,
57
+ `features = { resume: <`claude --help` tem `--resume`>, outputSchema: false }`.
58
+ - [x] **AC-7**: `docs/llm-fit-loop.md` (seção do adaptador Claude + a nota "schema é garantia
59
+ local, não do provedor") e `docs/llm-evolution.md` (C3 fechado). Registry: `llm:run.desc`
60
+ pode citar `--profile claude` sem mudança estrutural.
61
+ - [x] **AC-8**: testes — `buildLlmExecution` claude com/sem `--resume` (argv exato);
62
+ `normalizeClaudeResult` (sucesso, `is_error`, JSON inválido); `LlmSessionStore.require`
63
+ aceita `claude`; `doctor` reporta `features` para claude (probe do binário fake).
64
+ - [x] **AC-9**: `tsc --noEmit`, `node --test test/*.test.js`, `forja spec:check`,
65
+ `forja project:check` verdes. Testes de Codex/sessão/`buildLlmExecution` existentes
66
+ inalterados (o caminho Codex não muda).
67
+
68
+ ## 5. Escopo
69
+
70
+ **Dentro**:
71
+ - `packages/llm/src/index.ts` — `buildLlmExecution` claude; guard de `resume` por `RESUME_PROVIDERS`.
72
+ - `lib/llm/claude-output.ts` (novo) — `normalizeClaudeResult`.
73
+ - `lib/llm/session.ts` — `RESUME_PROVIDERS` exportado; `require` usa o conjunto.
74
+ - `scripts/llm-fit.ts` — normalização por provedor; `save` de sessão para `claude`; `features` no `doctor`.
75
+ - `docs/llm-fit-loop.md`, `docs/llm-evolution.md`; testes.
76
+
77
+ **Fora** (evita scope creep):
78
+ - `--output-format stream-json` (streaming) — o objeto único basta para o `llm:run` não-interativo.
79
+ - Ler `total_cost_usd` do Claude como custo real — segue a estimativa por `model-pricing.json`
80
+ (ADR-0085 §5); anotar o número do provedor é ADR/spec própria.
81
+ - Adaptador Gemini/outros à paridade — cada um é sua rodada.
82
+ - `--session-id <uuid>` para *fixar* uma sessão nova — nesta rodada só se consome o `session_id`
83
+ que o provedor devolve; fixar é backlog.
84
+ - `packages/llm/adapters/` genérico — mantém o `if (provider === …)` + `*-output.ts` (ADR-0085).
85
+
86
+ ## 6. NFRs / restrições
87
+
88
+ - **Privacidade**: `shell: false`; o Forja não lê API keys — auth é da CLI do Claude, igual ao
89
+ Codex. O relatório/prompt vai ao provedor e ao hash, nunca ao banco (contrato de `llm:run`).
90
+ - **Compatibilidade**: o caminho Codex de `buildLlmExecution`/`run()` **não muda**. Só o ramo
91
+ `claude` cresce e o guard de `resume` passa a aceitar um conjunto.
92
+ - **Determinismo**: `normalizeClaudeResult` só lê campos conhecidos; formato inesperado → erro
93
+ visível, nunca resposta silenciosa.
94
+ - **Sem rede nos testes**: `claude` é um binário fixture nos testes (como o Codex já é).
95
+
96
+ ## 7. Riscos e mitigação
97
+
98
+ | Risco | Probabilidade | Impacto | Mitigação |
99
+ |---|---|---|---|
100
+ | Formato do `claude --output-format json` muda numa versão | M | M | `normalizeClaudeResult` lê só campos conhecidos e falha com `INVALID_PROVIDER_OUTPUT`; teste fixture congela o formato esperado |
101
+ | `--output-schema` para Claude dá falsa sensação de garantia do provedor | M | M | `features.outputSchema: false` explícito + nota na doc; a validação Ajv reprova formato inválido de qualquer forma |
102
+ | `RESUME_PROVIDERS` como conjunto no código vira dívida ao crescer | B | B | É uma decisão de contrato (ADR-0085); 2 provedores hoje, aditivo |
103
+ | Prompt por argumento (Claude) vs stdin (Codex) — divergência de tratamento | B | B | `buildLlmExecution` já ramifica por provedor; o `runLlm` lida com ambos (o Codex usa `stdin`, o Claude não) |
104
+
105
+ ## 8. Métricas de sucesso
106
+
107
+ - `llm:run --profile claude --output-schema s` num fixture valida a resposta localmente e
108
+ registra observação normalizada (mesmos campos do Codex).
109
+ - `llm:run --profile claude` seguido de `llm:run --profile claude --resume <id>` (fixture)
110
+ registra e reusa o `sessionId`; `llm:sessions show <id>` mostra a sessão Claude.
111
+ - `llm:probe claude` reporta `features.resume: true`, `features.outputSchema: false`.
112
+ - Zero regressão no caminho Codex.
113
+
114
+ ## Evidências e estado real
115
+
116
+ **Implementado (branch `feat/llm-adaptador-claude`, W12):**
117
+
118
+ - **AC-1/AC-2** — `packages/llm/src/index.ts`: `RESUME_PROVIDERS = new Set(['codex','claude'])`;
119
+ `buildLlmExecution` ramo `claude` → `['-p', prompt, '--output-format', 'json', …('--model' m)?,
120
+ …('--resume' id)?]`; guard `resume` rejeita provedor fora do conjunto ou id inválido
121
+ (`LlmProfileError`). `lib/llm/session.ts` re-exporta `RESUME_PROVIDERS`; `LlmSessionStore.require`
122
+ usa `RESUME_PROVIDERS.has(provider)`.
123
+ - **AC-3** — `lib/llm/claude-output.ts` `normalizeClaudeResult`: objeto JSON único → `stdout`←`result`,
124
+ `sessionId`←`session_id`, `usage`←`input_tokens`/`output_tokens`/`cache_read_input_tokens`;
125
+ `is_error`/`subtype!=='success'` → `PROVIDER_FAILED`; parse falho ou sem `result` →
126
+ `INVALID_PROVIDER_OUTPUT`.
127
+ - **AC-4** — `scripts/llm-fit.ts` `run()`: normalizador por provedor
128
+ (`codex`→`normalizeCodexResult`, `claude`→`normalizeClaudeResult`); `sessions.save` guardado por
129
+ `RESUME_PROVIDERS.has(selected.provider)`.
130
+ - **AC-5** — caminho Ajv local não-Codex reusado; nenhum flag de schema vai ao `claude`.
131
+ - **AC-6** — `doctor()` ramo `provider === 'claude'`: `features = { resume: `claude --help` tem
132
+ `--resume`, outputSchema: false }`. Verificado por `llm:probe claude` (real: `resume:true`).
133
+ - **AC-7** — `docs/llm-fit-loop.md` (seção "Adaptador Claude"), `docs/llm-evolution.md` (etapa 2b),
134
+ `docs/agent-operating-contract.md`, `CHANGELOG.md`.
135
+ - **AC-8** — `test/llm-claude-adapter.test.js` (7 casos: `RESUME_PROVIDERS`, argv com/sem resume,
136
+ `normalizeClaudeResult` × 3, `LlmSessionStore.require` claude, `llm:probe` com fixture executável).
137
+ `test/llm-resume-validation.test.js` ajustado: `claude`+resume agora **passa**; `ollama` rejeita.
138
+ - **AC-9** — `tsc --noEmit` exit 0; `node --test test/*.test.js` → 490/490; `spec:check
139
+ llm-adaptador-claude` e `project:check` verdes.
140
+
141
+ - **Sem mudança no contrato de saída do `llm:run`** — mesmos campos do Codex.
142
+ - **Limitação assumida**: `--output-schema` para Claude é garantia **local** (Ajv), não do
143
+ provedor — `features.outputSchema: false`.
144
+ - **ADR**: [0085](../../memory/90-decisions/0085-adaptador-claude-paridade.md).
@@ -0,0 +1,100 @@
1
+ # Tasks: llm-adaptador-claude
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Plan**: ./plan.md
5
+ - **Status**: approved
6
+ - **Criado em**: 2026-09-08
7
+
8
+ ```
9
+ T1 ─┐
10
+ T2 ─┼─ T3 ─ T4 ─ T5
11
+ ```
12
+
13
+ Paralelizável: **T1 · T2**.
14
+
15
+ ---
16
+
17
+ ## T1 — `buildLlmExecution` claude + `RESUME_PROVIDERS`
18
+ - **Owner**: Worker · **Est**: M · **Depende de**: —
19
+ - **Paths**: `packages/llm/src/index.ts`, `lib/llm/session.ts`
20
+ - **Escopo**: `lib/llm/session.ts`: `export const RESUME_PROVIDERS = new Set(['codex', 'claude'])`;
21
+ `require()` troca `profile.provider !== 'codex'` por `!RESUME_PROVIDERS.has(profile.provider)`.
22
+ `packages/llm/src/index.ts`: guard de `resume` usa `!RESUME_PROVIDERS.has(profile.provider)`;
23
+ ramo `claude` de `buildLlmExecution` →
24
+ `[...base, ...(model!=='default'?['--model',model]:[]), '-p', prompt, '--output-format', 'json',
25
+ ...(resume?['--resume', resume]:[])]`.
26
+ - **Done**:
27
+ - [ ] `tsc --noEmit` verde
28
+ - [ ] `buildLlmExecution(claudeProfile, 'x')` → argv com `--output-format json`, sem `--resume`
29
+ - [ ] com `{ resume: '<uuid>' }` → argv com `--resume <uuid>`; provedor fora do set + resume → erro
30
+
31
+ ## T2 — `lib/llm/claude-output.ts`
32
+ - **Owner**: Worker · **Est**: M · **Depende de**: —
33
+ - **Paths**: `lib/llm/claude-output.ts` (novo)
34
+ - **Escopo**: `normalizeClaudeResult(result): NormalizedLlmResult`. `JSON.parse(result.stdout)`
35
+ (falha → `errorCode: 'INVALID_PROVIDER_OUTPUT'`, `stdout: ''`). Objeto: `stdout` ← `result`
36
+ (string; ausente/não-string → `INVALID_PROVIDER_OUTPUT`); `sessionId` ← `session_id` se string;
37
+ `usage` ← `{ inputTokens: usage.input_tokens, outputTokens: usage.output_tokens,
38
+ cachedInputTokens: usage.cache_read_input_tokens? }` quando `usage` presente e válido;
39
+ `is_error === true` ou `subtype` presente e `!== 'success'` → `errorCode: 'PROVIDER_FAILED'`.
40
+ `exitCode` como no `normalizeCodexResult` (não-zero preservado; senão 1 se errorCode, senão 0).
41
+ - **Done**:
42
+ - [ ] teste: `{type:'result',subtype:'success',result:'ok',session_id:'u-1',usage:{input_tokens:10,output_tokens:2}}` → `{stdout:'ok', sessionId:'u-1', usage:{inputTokens:10,outputTokens:2}, exitCode:0}`
43
+ - [ ] `is_error:true` → `errorCode: 'PROVIDER_FAILED'`; `"não é json"` → `INVALID_PROVIDER_OUTPUT`
44
+
45
+ ## T3 — `run()` + `doctor()` no `llm-fit.ts`
46
+ - **Owner**: Worker · **Est**: M · **Depende de**: T1, T2
47
+ - **Paths**: `scripts/llm-fit.ts`
48
+ - **Escopo**: `run()`: `let result = selected.provider === 'codex' ? normalizeCodexResult(raw) :
49
+ selected.provider === 'claude' ? normalizeClaudeResult(raw) : raw`. A checagem de
50
+ `SESSION_MISMATCH` (que hoje roda sempre) fica; `if (selected.provider === 'codex' && sessionId
51
+ !== undefined)` para `sessions.save` → `if (RESUME_PROVIDERS.has(selected.provider) && sessionId
52
+ !== undefined)`. `--output-schema` não vira flag do claude — `buildLlmExecution` não passa
53
+ (T1), e o `fullPrompt` já ganha a instrução de schema (código atual). `doctor()`: ramo
54
+ `else if (value.provider === 'claude')` → `const help = spawnSync(value.command, ['--help'], …);
55
+ features = { resume: !help.error && help.stdout.includes('--resume'), outputSchema: false }`.
56
+ - **Done**:
57
+ - [ ] `forja llm:run --profile claude …` (fixture) registra observação normalizada + salva sessão
58
+ - [ ] `forja llm:run --profile claude --resume <id>` (fixture) reusa o id; `llm:sessions show <id>` mostra
59
+ - [ ] `forja llm:probe claude` → `features: { resume: true, outputSchema: false }`
60
+
61
+ ## T4 — Documentação + CHANGELOG
62
+ - **Owner**: Worker · **Est**: P · **Depende de**: T3
63
+ - **Paths**: `docs/llm-fit-loop.md`, `docs/llm-evolution.md`, `CHANGELOG.md`
64
+ - **Escopo**: `llm-fit-loop.md` — seção "Adaptador Claude" (resume nativo, JSON do provedor, e a
65
+ **nota**: `--output-schema` é validação **local** para Claude, não garantia do provedor).
66
+ `llm-evolution.md` — C3 fechado. CHANGELOG `[Unreleased]`.
67
+ - **Done**:
68
+ - [ ] `forja tools:doctor` → `docs-commands`, `commands-documented`, `docs-links`, `adr-refs` verdes
69
+
70
+ ## T5 — Testes + validação final + fecho
71
+ - **Owner**: Worker → Governance · **Est**: M · **Depende de**: T1–T4
72
+ - **Paths**: `test/llm-fit.test.js` / `test/llm-integration.test.js` / novo
73
+ - **Escopo**: cobrir AC-8; um fixture `claude` que ecoa um objeto JSON válido (`process.execPath -e
74
+ "..."`), como o fixture Codex já faz. Bateria; `spec.md` §Evidências; status; handoff.
75
+ - **Done**:
76
+ - [ ] `tsc --noEmit`, `node --test test/*.test.js`, `forja spec:check`, `forja project:check` verdes — AC-9
77
+ - [ ] testes de Codex/`buildLlmExecution`/sessão existentes verdes (só o que muda por desenho)
78
+ - [ ] `spec:set-status llm-adaptador-claude spec implementing` no início; handoff `review` ao fim
79
+
80
+ ---
81
+
82
+ ## Mapa AC → task
83
+
84
+ | AC | Tasks |
85
+ |---|---|
86
+ | AC-1 / AC-2 | T1 |
87
+ | AC-3 | T2 |
88
+ | AC-4 / AC-5 / AC-6 | T3 |
89
+ | AC-7 | T4 |
90
+ | AC-8 / AC-9 | T5 |
91
+
92
+ ## Handoffs
93
+
94
+ SDD Architect (spec+plan+tasks + ADR-0085) → **Worker** (T1–T4) → **Governance** (T5 + `project:check`).
95
+
96
+ ## Evidências e estado real
97
+
98
+ - Nada executado.
99
+ - **De `main`** (com W10 + W11). ADR-0085 cobre o desenho. Caminho Codex inalterado.
100
+ - **Limitação assumida**: `--output-schema` para Claude é garantia local (Ajv), não do provedor.
@@ -0,0 +1,121 @@
1
+ # Plan: llm-benchmark-recomendacao
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Status**: approved
5
+ - **Criado em**: 2026-09-08
6
+
7
+ ## 1. Abordagem técnica
8
+
9
+ Duas funções puras ganham eixos. `EvaluationEngine.metrics()` calcula 3 chaves novas
10
+ (`durationMsP50`, `durationMsP95`, `costPerAcceptedTask`) sobre as mesmas observações — nada de
11
+ novo é lido. `recommendProfile` agrega, por candidato, a mediana de `durationMs` e a média de
12
+ `cost` das amostras, aplica um ajuste **limitado** ao `score` (mais rápido/barato que a coorte →
13
+ alguns pontos) e devolve um bloco `evidence`. Tudo determinístico, sem rede. Os scripts
14
+ (`llm:eval`, `llm:recommend`) já serializam o retorno inteiro — os campos novos fluem sozinhos.
15
+
16
+ ## 2. Módulos afetados
17
+
18
+ | Caminho | Mudança | Risco |
19
+ |---|---|---|
20
+ | `packages/evals/src/index.ts` | editar — `metrics()`: `percentile(durations, 50/95)` helper; `costPerAcceptedTask = totalCost / accepted` (0 se `accepted === 0`). Existentes intactas | B |
21
+ | `packages/llm/src/index.ts` | editar — `recommendProfile`: por candidato, `median(durationMs)`, `mean(cost)` das amostras; `cohortMedianLatency`/`cohortMeanCost` das amostras totais; `latencyBonus`/`costBonus` ∈ [0, 4] cada; `score += latencyBonus + costBonus`; `reasons` ganha `latency:p50=<ms>`/`cost:$<x>/run`; item ganha `evidence: { samples, medianDurationMs, meanCostUsd, successRate }` | M |
22
+ | `packages/contracts/src/index.ts` | editar **se** `EvaluationReport.metrics`/o item de `recommendProfile` forem tipos nominais — estender aditivamente | B |
23
+ | `docs/llm-fit-loop.md`, `docs/llm-evolution.md` | editar — métricas + ponderação + ressalva do baseline de 30d | B |
24
+ | `test/llm-routing.test.js`, `test/*eval*` | editar/criar — percentis; preferência barato/rápido no empate; `evidence`; sem amostras → score de fit puro | M |
25
+
26
+ ## 3. Diagrama de fluxo
27
+
28
+ ```
29
+ llm:eval --scope model --id p:m
30
+ └─ EvaluationEngine.evaluate → metrics(selected):
31
+ (existentes) successRate, reworkRate, tokensPerTask, totalCost, …
32
+ (novas) durationMsP50, durationMsP95, costPerAcceptedTask
33
+
34
+ llm:recommend --role r --task t
35
+ └─ recommendProfile(profiles, observations, r, t):
36
+ cohortMedianLatency = median(todas as durationMs com amostra)
37
+ cohortMeanCost = mean(todos os cost definidos)
38
+ por candidato c com samples>0:
39
+ medLat = median(samples.durationMs); meanCost = mean(samples.cost ?? —)
40
+ latencyBonus = medLat < cohortMedianLatency ? min(4, round(4·(1 - medLat/cohort))) : 0
41
+ costBonus = meanCost < cohortMeanCost ? min(4, round(4·(1 - meanCost/cohort))) : 0
42
+ score = fitScore + successBonus + min(samples,10) + latencyBonus + costBonus
43
+ evidence = { samples, medianDurationMs: medLat, meanCostUsd: meanCost ?? null, successRate }
44
+ sort: score desc, name asc
45
+ ```
46
+
47
+ ## 4. Contratos (API/CLI/Schema)
48
+
49
+ ```ts
50
+ // packages/evals — metrics() acrescenta (Record<string, number>):
51
+ durationMsP50: number; // 0 quando sem observação
52
+ durationMsP95: number;
53
+ costPerAcceptedTask: number; // totalCost / accepted; 0 quando accepted === 0
54
+
55
+ // packages/llm — cada item de recommendProfile acrescenta:
56
+ evidence: {
57
+ samples: number;
58
+ medianDurationMs: number; // 0 quando samples === 0
59
+ meanCostUsd: number | null; // null quando nenhuma amostra tem cost
60
+ successRate: number;
61
+ };
62
+ // reasons ganha, quando samples>0: `latency:p50=<ms>` e (se meanCost definido) `cost:$<x>/run`
63
+ ```
64
+
65
+ Sem quebra: só chaves novas; `score` de candidatos **com amostras** muda por desenho.
66
+
67
+ ## 5. Decisões e alternativas
68
+
69
+ **D1 — Bônus limitado a `[0,4]` por eixo, aditivo ao score.** Fit declarado vale 100+50; sucesso
70
+ até 25; presença até 10. Latência+custo somam no máximo 8 — nunca invertem um fit, só desempatam
71
+ e refinam entre pares próximos. Rejeitado: multiplicar o score por um fator de custo (fácil de
72
+ inverter tudo sem querer).
73
+
74
+ **D2 — Percentil por interpolação linear** (`p·(n-1)` → índice, mistura os dois vizinhos). Padrão,
75
+ determinístico. Rejeitado: "nearest rank" (salta em amostras pequenas).
76
+
77
+ **D3 — `costPerAcceptedTask` fica em `metrics` (number, 0-fallback); `meanCostUsd` (que pode ser
78
+ `null`) fica só no `evidence`.** `metrics` é `Record<string, number>` — `null` não cabe. "Nenhuma
79
+ tarefa aceita" e "custo real zero" ambos viram 0 em `metrics`; o `evidence` do `recommend` é onde
80
+ a distinção `null` importa e cabe.
81
+
82
+ **D4 — Coorte = todas as amostras do conjunto de observações passado**, não por role/task. É a
83
+ referência "rápido/barato comparado a quê"; filtrar por role/task reduziria a amostra a quase nada.
84
+
85
+ Sem ADR — evolui `EvaluationReport`/`recommendProfile` aditivamente; ordenação e determinismo
86
+ preservados.
87
+
88
+ ## 6. Dependências
89
+
90
+ - De `main` (com W10). `Observation.cost`/`durationMs` (SPEC-028) já existem e já chegam ao
91
+ `recommendProfile`.
92
+ - Pacotes npm: nenhum. Migrações: nenhuma.
93
+
94
+ ## 7. Rollout
95
+
96
+ - [ ] Feature flag: não. Aditivo.
97
+ - [ ] Doc: `docs/llm-fit-loop.md` (§Execução e evidência / §recommend), `docs/llm-evolution.md`
98
+ (etapa 3 → "implementada"), com a ressalva do baseline.
99
+ - [ ] `CHANGELOG.md` `[Unreleased]`: Adicionado (`llm:eval` p50/p95 + custo/tarefa; `llm:recommend`
100
+ pondera custo/latência + `evidence`).
101
+
102
+ ## 8. Sinais de fracasso (kill criteria)
103
+
104
+ - O ajuste de bônus muda demais o `llm:routing.test.js` (mais que 1–2 asserções) → reduzir o teto
105
+ para `[0,2]` por eixo ou tornar o bônus só um `reasons`/`evidence`, sem tocar o `score`.
106
+ - `EvaluationReport.metrics` tipado impede as chaves novas sem uma mudança de contrato grande →
107
+ entregar só `recommendProfile` nesta rodada e `llm:eval` numa spec própria.
108
+
109
+ ## Evidências e estado real
110
+
111
+ | AC | Task | Verificação |
112
+ |---|---|---|
113
+ | AC-1 | T1 | `metrics()` com fixtures de duração → p50/p95 corretos; `costPerAcceptedTask` |
114
+ | AC-2/AC-3/AC-4 | T2 | `recommendProfile` — bônus limitado, `evidence`, ordem estável, empate → barato/rápido |
115
+ | AC-5 | T3 | saída de `llm:eval`/`llm:recommend` com os campos novos |
116
+ | AC-6 | T4 | docs + ressalva do baseline |
117
+ | AC-7 | T5 | testes |
118
+ | AC-8 | T5 | bateria; `llm-routing` ajustado ao mínimo |
119
+
120
+ - **Mudança de score, não de contrato.** As métricas existentes não mudam para os mesmos dados.
121
+ - **Nada de percentual prometido** antes do baseline de 30d.