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,141 @@
|
|
|
1
|
+
# Spec: llm-benchmark-recomendacao — `llm:eval` com latência/custo e `llm:recommend` multi-eixo
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-049
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **Criado em**: 2026-09-08
|
|
7
|
+
- **Sprint alvo**: <a definir>
|
|
8
|
+
- **ADRs relacionadas**: nenhuma — evolui os contratos de `EvaluationReport` (SPEC-028) e
|
|
9
|
+
`recommendProfile` (SPEC-028) de forma **aditiva**; sem decisão estrutural.
|
|
10
|
+
- **Origem**: `docs/roadmap-v4.1.md`, Onda 4 (W11) — etapa 3 do `docs/llm-evolution.md`. Fecha C4.
|
|
11
|
+
|
|
12
|
+
## 1. Problema
|
|
13
|
+
|
|
14
|
+
**C4 — `llm:recommend` não pondera custo nem latência.** O score de `recommendProfile` hoje é
|
|
15
|
+
`role*100 + taskType*50 + successRate*25 + min(samples,10)`. Ele **recebe** `cost` e `durationMs`
|
|
16
|
+
nas observações e **não usa nenhum dos dois**. Um perfil caro e lento com o mesmo fit declarado
|
|
17
|
+
que um barato e rápido recebe a mesma recomendação. `cost:economy` mede o custo acumulado, mas
|
|
18
|
+
isolado do roteamento.
|
|
19
|
+
|
|
20
|
+
**`llm:eval` não expõe latência por percentil nem custo por tarefa aprovada.** `EvaluationReport`
|
|
21
|
+
já tem `successRate`, `reworkRate`, `tokensPerTask`, `totalCost` — mas não `p50`/`p95` de duração
|
|
22
|
+
nem `totalCost / tarefas aceitas`, que são o que decide "vale a pena este modelo?".
|
|
23
|
+
|
|
24
|
+
**Como medimos hoje**: `recommendProfile` não referencia `cost`/`durationMs`; `metrics()` de
|
|
25
|
+
`EvaluationEngine` não tem chave de percentil.
|
|
26
|
+
|
|
27
|
+
## 2. Proposta de valor
|
|
28
|
+
|
|
29
|
+
`llm:eval` passa a reportar `durationMsP50`/`durationMsP95` e `costPerAcceptedTask`. `llm:recommend`
|
|
30
|
+
pondera **custo e latência** além do fit declarado e da taxa de sucesso, e devolve a **evidência
|
|
31
|
+
por candidato** (amostras, mediana de duração, custo médio, taxa de sucesso) — a recomendação
|
|
32
|
+
deixa de ser opaca. Nenhum percentual de ganho é prometido antes de um baseline de 30 dias.
|
|
33
|
+
|
|
34
|
+
## 3. User stories
|
|
35
|
+
|
|
36
|
+
- **Como** operador escolhendo um perfil, **quero** que `llm:recommend` prefira o mais barato e
|
|
37
|
+
rápido quando o fit e o sucesso empatam, **para que** o roteamento não me custe mais do que
|
|
38
|
+
precisa.
|
|
39
|
+
- **Como** operador, **quero** ver *por que* um perfil foi recomendado (não só o score), **para
|
|
40
|
+
que** eu confie ou conteste a escolha.
|
|
41
|
+
- **Como** quem avalia um modelo, **quero** `llm:eval` com p50/p95 de latência e custo por tarefa
|
|
42
|
+
aprovada, **para que** eu compare modelos pelo que importa, não só pela taxa de sucesso.
|
|
43
|
+
|
|
44
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
45
|
+
|
|
46
|
+
- [ ] **AC-1**: `EvaluationEngine.metrics()` ganha `durationMsP50`, `durationMsP95` (percentis da
|
|
47
|
+
`durationMs` das observações do escopo; 0 quando não há observação) e `costPerAcceptedTask`
|
|
48
|
+
(`totalCost / nº de observações com validationStatus 'accepted'`; 0 quando nenhuma aceita).
|
|
49
|
+
As métricas existentes são **inalteradas**.
|
|
50
|
+
- [ ] **AC-2**: `recommendProfile` passa a incluir no `score`, para cada candidato com amostras,
|
|
51
|
+
um ajuste por **latência** (mais rápido que a mediana da coorte → bônus) e por **custo**
|
|
52
|
+
(mais barato que a média da coorte → bônus), **limitado** para que fit declarado
|
|
53
|
+
(`role`/`taskType`) continue dominando. Sem amostras → sem ajuste (score de fit puro).
|
|
54
|
+
- [ ] **AC-3**: cada item de `recommendProfile` ganha `evidence: { samples, medianDurationMs,
|
|
55
|
+
meanCostUsd, successRate }` (números; `meanCostUsd` é `null` quando nenhuma amostra tem
|
|
56
|
+
custo). O `reasons` ganha `latency:p50=<ms>` e `cost:$<x>/run` quando há evidência.
|
|
57
|
+
- [ ] **AC-4**: a ordenação de `recommendProfile` continua `score desc, name asc` — determinística.
|
|
58
|
+
Dois perfis de fit idêntico e amostras: o de menor mediana de latência (ou menor custo, se a
|
|
59
|
+
latência empata) vem antes.
|
|
60
|
+
- [ ] **AC-5**: `forja llm:eval` e `forja llm:recommend` emitem os campos novos na saída JSON sem
|
|
61
|
+
quebrar as chaves existentes (consumidores antigos ignoram o que não conhecem).
|
|
62
|
+
- [ ] **AC-6**: `docs/llm-fit-loop.md` e `docs/llm-evolution.md` documentam as métricas novas e a
|
|
63
|
+
ponderação, **com a ressalva explícita**: nenhum percentual de melhoria é afirmado antes de
|
|
64
|
+
coletar um baseline de 30 dias (o roadmap e o `llm-evolution.md` já exigem isso).
|
|
65
|
+
- [ ] **AC-7**: testes — percentis de `metrics()` (com fixtures de duração conhecida);
|
|
66
|
+
`recommendProfile` prefere o candidato barato/rápido quando fit e sucesso empatam; `evidence`
|
|
67
|
+
presente e correta; sem amostras → score de fit puro (comportamento atual preservado).
|
|
68
|
+
- [ ] **AC-8**: `tsc --noEmit`, `node --test test/*.test.js`, `forja spec:check`,
|
|
69
|
+
`forja project:check` verdes. `test/llm-routing.test.js` e os testes de `EvaluationEngine`
|
|
70
|
+
passam com ajuste **mínimo** (só onde o score muda por desenho).
|
|
71
|
+
|
|
72
|
+
## 5. Escopo
|
|
73
|
+
|
|
74
|
+
**Dentro**:
|
|
75
|
+
- `packages/evals/src/index.ts` — `durationMsP50`/`P95`, `costPerAcceptedTask` em `metrics()`.
|
|
76
|
+
- `packages/llm/src/index.ts` — ponderação custo/latência + `evidence` em `recommendProfile`.
|
|
77
|
+
- `packages/contracts/src/index.ts` — se `EvaluationReport.metrics`/o retorno de `recommendProfile`
|
|
78
|
+
forem tipados nominalmente, estender o tipo (aditivo).
|
|
79
|
+
- `docs/llm-fit-loop.md`, `docs/llm-evolution.md`; testes.
|
|
80
|
+
|
|
81
|
+
**Fora** (evita scope creep):
|
|
82
|
+
- Eixo de **qualidade** por avaliador LLM ("LLM-as-judge") — fica com `validationSuccessRate`
|
|
83
|
+
(checks independentes) como proxy de qualidade nesta rodada.
|
|
84
|
+
- Eixo de **risco** por perfil — `risk:assess` é sobre um diff, não sobre um modelo; ligar os dois
|
|
85
|
+
é outra spec.
|
|
86
|
+
- Failover automático ou escolha implícita — `llm:recommend` continua informando, o operador
|
|
87
|
+
escolhe (ADR-0081).
|
|
88
|
+
- Reponderação configurável (pesos por `.forjarc`) — pesos fixos e documentados nesta rodada.
|
|
89
|
+
- Alimentar `cost:economy` de volta no `recommend` como fonte separada — as observações já
|
|
90
|
+
carregam `cost`; usa isso.
|
|
91
|
+
|
|
92
|
+
## 6. NFRs / restrições
|
|
93
|
+
|
|
94
|
+
- **Compatibilidade**: saída JSON de `llm:eval`/`llm:recommend` só **ganha** chaves. Score muda
|
|
95
|
+
por desenho (é o ponto); `test/llm-routing.test.js` ajusta o mínimo.
|
|
96
|
+
- **Determinismo**: percentis por interpolação linear fixa; ordenação estável.
|
|
97
|
+
- **Sem rede, sem modelo**: tudo é agregação sobre observações locais.
|
|
98
|
+
- **Honestidade de métrica**: `costPerAcceptedTask` = 0 quando não há aceita (não `null` nem
|
|
99
|
+
`Infinity`); `meanCostUsd` = `null` quando nenhuma amostra tem custo (distinto de "custo zero").
|
|
100
|
+
|
|
101
|
+
## 7. Riscos e mitigação
|
|
102
|
+
|
|
103
|
+
| Risco | Probabilidade | Impacto | Mitigação |
|
|
104
|
+
|---|---|---|---|
|
|
105
|
+
| Bônus de custo/latência grande demais e inverte um fit declarado | M | A | Ajuste **limitado** (AC-2) — no máximo alguns pontos, nunca mais que `min(samples,10)`; teste garante que fit ganha |
|
|
106
|
+
| Poucas amostras → mediana/custo enganosos | M | M | Ajuste só com `samples > 0`; `evidence.samples` sempre exposto para o operador ponderar |
|
|
107
|
+
| Consumidor do JSON quebra com chave nova | B | B | Só adição; documentado; consumidores conhecidos são internos |
|
|
108
|
+
| `EvaluationReport.metrics` é `Record<string, number>` e `null` não cabe | M | M | `costPerAcceptedTask` fica em `metrics` (number, 0-fallback); `meanCostUsd` (que pode ser null) fica só no `evidence` de `recommendProfile`, que é objeto livre |
|
|
109
|
+
|
|
110
|
+
## 8. Métricas de sucesso
|
|
111
|
+
|
|
112
|
+
**Baseline primeiro** — o `llm-evolution.md` já exige coletar 30 dias antes de prometer números.
|
|
113
|
+
|
|
114
|
+
- Em 30 dias, com observações reais: `llm:recommend` para um par (role, task) com histórico
|
|
115
|
+
recomenda o perfil de menor `costPerAcceptedTask` quando o fit e o `validationSuccessRate` empatam.
|
|
116
|
+
- `llm:eval --scope model` mostra `durationMsP50`/`P95` e `costPerAcceptedTask` para cada modelo com
|
|
117
|
+
observações.
|
|
118
|
+
- Zero regressão nas métricas existentes (mesmos valores para os mesmos dados).
|
|
119
|
+
|
|
120
|
+
## Evidências e estado real
|
|
121
|
+
|
|
122
|
+
**Implementado em 2026-09-08** na branch `feat/llm-benchmark-recomendacao` (de `main`, já com W10).
|
|
123
|
+
`tsc --noEmit` limpo; `node --test test/*.test.js` **483/483** (+4: 2 em `test/evals.test.js`, 2 em
|
|
124
|
+
`test/llm-fit.test.js`); `forja spec:check` e `forja project:check` (100%) verdes.
|
|
125
|
+
|
|
126
|
+
| AC | Onde | Verificado |
|
|
127
|
+
|---|---|---|
|
|
128
|
+
| AC-1 | `packages/evals/src/index.ts` `metrics()` + `percentile()` | `[100,200,300,400]` → p50 250, p95 ≈385; 0 aceita → `costPerAcceptedTask` 0 |
|
|
129
|
+
| AC-2 | `packages/llm/src/index.ts` `recommendProfile` (`latencyBonus`/`costBonus` ∈ [0,4]) | teste: fit+sucesso idênticos, amostras mais rápidas/baratas → score maior; bônus máx. 8 < fit (150) |
|
|
130
|
+
| AC-3 | idem — `evidence: { samples, medianDurationMs, meanCostUsd, successRate }` + `reasons` | teste: `latency:p50=…` e `cost:$…/run` presentes; `meanCostUsd` `null` sem custo |
|
|
131
|
+
| AC-4 | idem — `sort(score desc, name asc)` | ordem determinística; empate de latência → menor custo |
|
|
132
|
+
| AC-5 | `scripts/llm-fit.ts` (já serializa o retorno inteiro — sem alteração) | `llm:eval`/`llm:recommend` carregam os campos novos |
|
|
133
|
+
| AC-6 | `docs/llm-fit-loop.md`, `docs/llm-evolution.md`, CHANGELOG | métricas + ponderação + **ressalva do baseline de 30d** |
|
|
134
|
+
| AC-7/AC-8 | `test/evals.test.js`, `test/llm-fit.test.js` | 4 testes novos; `recommendation uses declared role/task fit…` **inalterado** (sem regressão) |
|
|
135
|
+
|
|
136
|
+
- **Sem desvio do plan.** `scripts/llm-fit.ts` não precisou de mudança — os scripts já serializam
|
|
137
|
+
o retorno completo.
|
|
138
|
+
- **Mudança de score, não de contrato**: `score` de candidatos com amostras muda por desenho; as
|
|
139
|
+
chaves de saída só crescem. Nenhum teste de `recommendProfile` existente quebrou.
|
|
140
|
+
- **Nada de percentual prometido** antes do baseline de 30 dias.
|
|
141
|
+
- **Pendências**: revisão de Governança; handoff `review` registrado.
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
# Tasks: llm-benchmark-recomendacao
|
|
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 — `metrics()`: p50/p95 + custo por tarefa aprovada
|
|
18
|
+
- **Owner**: Worker · **Est**: P · **Depende de**: —
|
|
19
|
+
- **Paths**: `packages/evals/src/index.ts` (+ `packages/contracts/src/index.ts` se tipado)
|
|
20
|
+
- **Escopo**: helper `percentile(sorted: number[], p: number): number` (interpolação linear, `[]`→0).
|
|
21
|
+
Em `metrics()`: `durationMsP50 = percentile(durações, 50)`, `durationMsP95 = percentile(…, 95)`;
|
|
22
|
+
`costPerAcceptedTask = accepted === 0 ? 0 : totalCost / accepted`. As chaves existentes ficam
|
|
23
|
+
**idênticas** para os mesmos dados.
|
|
24
|
+
- **Done**:
|
|
25
|
+
- [ ] `tsc --noEmit` verde
|
|
26
|
+
- [ ] teste: fixtures `[100,200,300,400]` → p50 ≈ 250, p95 ≈ 385; 0 aceita → `costPerAcceptedTask` 0
|
|
27
|
+
|
|
28
|
+
## T2 — `recommendProfile`: ponderação custo/latência + `evidence`
|
|
29
|
+
- **Owner**: Worker · **Est**: M · **Depende de**: —
|
|
30
|
+
- **Paths**: `packages/llm/src/index.ts`
|
|
31
|
+
- **Escopo**: helpers `median`/`mean`. `cohortMedianLatency` = mediana das `durationMs` de todas as
|
|
32
|
+
amostras; `cohortMeanCost` = média dos `cost` definidos. Por candidato com `samples > 0`:
|
|
33
|
+
`latencyBonus`/`costBonus` ∈ `[0, 4]` conforme plan §3; `score += latencyBonus + costBonus`;
|
|
34
|
+
`reasons` ganha `latency:p50=<ms>` e (se custo definido) `cost:$<x>/run`; item ganha
|
|
35
|
+
`evidence: { samples, medianDurationMs, meanCostUsd, successRate }` (`meanCostUsd` `null` sem custo).
|
|
36
|
+
`samples === 0` → sem bônus, `evidence` com zeros/`null`. Ordenação `score desc, name asc` intacta.
|
|
37
|
+
- **Done**:
|
|
38
|
+
- [ ] `tsc --noEmit` verde
|
|
39
|
+
- [ ] teste: 2 perfis fit+sucesso idênticos, um com amostras mais rápidas → esse vem 1º; sem amostras → score de fit puro
|
|
40
|
+
|
|
41
|
+
## T3 — Fios: `llm:eval` / `llm:recommend`
|
|
42
|
+
- **Owner**: Worker · **Est**: P · **Depende de**: T1, T2
|
|
43
|
+
- **Paths**: `scripts/llm-fit.ts` (só se precisar passar algo novo — provavelmente não)
|
|
44
|
+
- **Escopo**: confirmar que a saída JSON de `forja llm:eval` e `forja llm:recommend` carrega os
|
|
45
|
+
campos novos (os scripts já serializam o retorno inteiro). Ajustar só se houver projeção que
|
|
46
|
+
descarta chaves.
|
|
47
|
+
- **Done**:
|
|
48
|
+
- [ ] `forja llm:eval --scope model --id <x>` mostra `durationMsP50`/`P95`/`costPerAcceptedTask`
|
|
49
|
+
- [ ] `forja llm:recommend --role <r> --task <t>` mostra `evidence` por item
|
|
50
|
+
|
|
51
|
+
## T4 — Documentação + CHANGELOG
|
|
52
|
+
- **Owner**: Worker · **Est**: P · **Depende de**: T3
|
|
53
|
+
- **Paths**: `docs/llm-fit-loop.md`, `docs/llm-evolution.md`, `CHANGELOG.md`
|
|
54
|
+
- **Escopo**: métricas novas + ponderação; **ressalva explícita**: nenhum percentual antes de um
|
|
55
|
+
baseline de 30 dias. `llm-evolution.md` etapa 3 → "implementada, sem promessa numérica".
|
|
56
|
+
CHANGELOG `[Unreleased]`.
|
|
57
|
+
- **Done**:
|
|
58
|
+
- [ ] `forja tools:doctor` → `docs-commands`, `commands-documented`, `docs-links` verdes
|
|
59
|
+
|
|
60
|
+
## T5 — Testes + validação final + fecho
|
|
61
|
+
- **Owner**: Worker → Governance · **Est**: M · **Depende de**: T1–T4
|
|
62
|
+
- **Paths**: `test/llm-routing.test.js`, `test/*eval*`, novos se necessário
|
|
63
|
+
- **Escopo**: cobrir AC-7; ajustar `test/llm-routing.test.js` **só** nas asserções de score que
|
|
64
|
+
mudam por desenho (documentar cada ajuste). Bateria; `spec.md` §Evidências; status; handoff.
|
|
65
|
+
- **Done**:
|
|
66
|
+
- [ ] `tsc --noEmit`, `node --test test/*.test.js`, `forja spec:check`, `forja project:check` verdes — AC-8
|
|
67
|
+
- [ ] `spec:set-status llm-benchmark-recomendacao spec implementing` no início; handoff `review` ao fim
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## Mapa AC → task
|
|
72
|
+
|
|
73
|
+
| AC | Tasks |
|
|
74
|
+
|---|---|
|
|
75
|
+
| AC-1 | T1 |
|
|
76
|
+
| AC-2 / AC-3 / AC-4 | T2 |
|
|
77
|
+
| AC-5 | T3 |
|
|
78
|
+
| AC-6 | T4 |
|
|
79
|
+
| AC-7 / AC-8 | T5 |
|
|
80
|
+
|
|
81
|
+
## Handoffs
|
|
82
|
+
|
|
83
|
+
SDD Architect (spec+plan+tasks) → **Worker** (T1–T4) → **Governance** (T5 + `project:check`).
|
|
84
|
+
|
|
85
|
+
## Evidências e estado real
|
|
86
|
+
|
|
87
|
+
- Nada executado.
|
|
88
|
+
- **De `main`** (com W10). Sem ADR. Mudança de score por desenho; chaves de saída só crescem.
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
# Plan: llm-contexto-e-sessoes
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Status**: approved
|
|
5
|
+
- **Criado em**: 2026-09-08
|
|
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
|
+
Dois acréscimos ao `scripts/llm-fit.ts`, sem tocar o motor. **`--engineer "<objetivo>"`**: no
|
|
12
|
+
`run()`, antes de montar o prompt, roda `forja engineer "<obj>" --json` num subprocesso, faz
|
|
13
|
+
`JSON.parse` do relatório e o **prepende ao prompt** como um bloco rotulado — daí em diante o
|
|
14
|
+
fluxo é idêntico (hash cobre o prompt final, `contextRefs` ganha `engineer:<obj>`). **`sessions`**:
|
|
15
|
+
subcomando novo (`list` | `show <id>`) que lê `llm_session` por `SqliteJsonRepository.list/get`,
|
|
16
|
+
via dois métodos de leitura pura em `LlmSessionStore`. Read-only, sem provedor.
|
|
17
|
+
|
|
18
|
+
## 2. Módulos afetados
|
|
19
|
+
|
|
20
|
+
| Caminho | Mudança | Risco |
|
|
21
|
+
|---|---|---|
|
|
22
|
+
| `scripts/llm-fit.ts` | editar — `run()`: aceitar `--engineer` na allowlist de flags; se presente, `buildEngineerBlock(obj)` e prepender ao prompt; `refs` ganha `engineer:<obj>`; `errorCode: 'ENGINEER_FAILED'` se o façade falhar (antes de `runLlm`). Novo `cmdSessions()` + branch `command === 'sessions'` no `main()` | M |
|
|
23
|
+
| `lib/llm/context.ts` | editar — `buildEngineerBlock(objective, { cwd, run? }): { text: string; ref: string }` — spawna `forja engineer "<obj>" --json`, parseia, formata o bloco; `run` injetável para teste | M |
|
|
24
|
+
| `lib/llm/session.ts` | editar — `LlmSessionStore.all(): LlmSession[]` (desc por `updatedAt`) e `find(id): LlmSession \| undefined` (sem `assertBinding`) | B |
|
|
25
|
+
| `lib/core/registry.ts` | editar — `llm:run.desc` cita `--engineer`; entrada `llm:sessions` (`domain: 'llm'`, `node: 'scripts/llm-fit.ts'`, `args: ['sessions']`, `gates: ['workspace']`, `readonly: true`, `json: true`, `usage`, `examples`) | B |
|
|
26
|
+
| `docs/llm-fit-loop.md` | editar — seções de `--engineer` e `llm:sessions` | B |
|
|
27
|
+
| `test/llm-fit.test.js` (ou novo `test/llm-sessions.test.js`) | criar/estender — `buildEngineerBlock` com `run` fake; `LlmSessionStore.all/find`; `sessions list|show` via CLI num workspace com `llm_session` semeado | M |
|
|
28
|
+
|
|
29
|
+
## 3. Diagrama de fluxo
|
|
30
|
+
|
|
31
|
+
```
|
|
32
|
+
forja llm:run --profile p --engineer "<obj>" [--prompt "<t>"] [--context f] [--output-schema s]
|
|
33
|
+
│
|
|
34
|
+
├─ engineerBlock = buildEngineerBlock("<obj>")
|
|
35
|
+
│ spawn: forja engineer "<obj>" --json
|
|
36
|
+
│ exit ≠ 0 → imprime { errorCode:'ENGINEER_FAILED', stderr:<1ª linha> } · process.exit(1) ← antes do provedor
|
|
37
|
+
│ exit 0 → { text: "=== Contexto do engineer ===\n<JSON>", ref: "engineer:<obj>" }
|
|
38
|
+
├─ prompt' = engineerBlock.text + "\n\n" + (prompt | task)
|
|
39
|
+
├─ context = buildContextPrompt(prompt', --context files) (mecanismo atual, inalterado)
|
|
40
|
+
├─ fullPrompt = context.prompt [+ instrução de schema]
|
|
41
|
+
├─ inputHash = sha256(fullPrompt) (cobre o bloco engineer — AC-2)
|
|
42
|
+
├─ refs = [...context.refs, "engineer:<obj>", schemaPath?, manifestPath?] (referência, nunca conteúdo)
|
|
43
|
+
└─ runLlm(...) → observação + validação + (Codex) llm_session (tudo como hoje)
|
|
44
|
+
|
|
45
|
+
forja llm:sessions list [--json] → LlmSessionStore.all() → tabela / array
|
|
46
|
+
forja llm:sessions show <id> [--json] → find(id) + observação vinculada + llm_validation → objeto
|
|
47
|
+
id desconhecido → stderr + exit 1
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## 4. Contratos (API/CLI/Schema)
|
|
51
|
+
|
|
52
|
+
```ts
|
|
53
|
+
// lib/llm/context.ts
|
|
54
|
+
export function buildEngineerBlock(
|
|
55
|
+
objective: string,
|
|
56
|
+
opts?: { cwd?: string; run?: (argv: string[]) => { code: number; stdout: string; stderr: string } },
|
|
57
|
+
): { text: string; ref: string }; // lança/propaga o exit≠0 via um erro com .code === 'ENGINEER_FAILED'
|
|
58
|
+
|
|
59
|
+
// lib/llm/session.ts (métodos novos em LlmSessionStore)
|
|
60
|
+
all(): readonly LlmSession[]; // desc por updatedAt
|
|
61
|
+
find(id: string): LlmSession | undefined; // leitura pura, sem assertBinding
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
**CLI**:
|
|
65
|
+
- `llm:run --engineer "<objetivo>"` — combina com `--prompt`/`--task` e `--context`. Sem
|
|
66
|
+
`--prompt`/`--task`, o `<objetivo>` também vira o prompt.
|
|
67
|
+
- `llm:sessions list [--json]` — `[{ id, cwd, updatedAt, observationId }]`.
|
|
68
|
+
- `llm:sessions show <id> [--json]` — `{ session, observation?: { model, outcome, validationStatus,
|
|
69
|
+
durationMs }, validation?: { status, checks: string[] } }`.
|
|
70
|
+
|
|
71
|
+
**Saída do `llm:run`**: inalterada, exceto o ramo de erro novo
|
|
72
|
+
`{ profile, errorCode: 'ENGINEER_FAILED', stderr }` com exit 1.
|
|
73
|
+
|
|
74
|
+
## 5. Decisões e alternativas
|
|
75
|
+
|
|
76
|
+
**D1 — `--engineer` por subprocesso (`forja engineer --json`), não in-process.** `scripts/engineer.ts`
|
|
77
|
+
carrega grafo + sqlite + vários pacotes; importar `buildReport` exige mover todo esse setup para
|
|
78
|
+
`lib/`. Rejeitado nesta rodada — o subprocesso reusa o façade como está, ao custo de ~1–2 s de
|
|
79
|
+
bootstrap, desprezível vs. a chamada ao modelo. (Extrair para `lib/` fica como backlog se
|
|
80
|
+
`--engineer` virar caminho quente.)
|
|
81
|
+
|
|
82
|
+
**D2 — Prepender o bloco ao prompt, sem tocar `buildContextPrompt`.** `prompt' = block + prompt`,
|
|
83
|
+
depois `buildContextPrompt(prompt', files)` como hoje. Ordem final: engineer → prompt → contextos
|
|
84
|
+
→ schema. Rejeitado: adicionar um parâmetro a `buildContextPrompt` (mais superfície, o mesmo
|
|
85
|
+
efeito).
|
|
86
|
+
|
|
87
|
+
**D3 — `contextRefs` ganha `engineer:<objetivo>`, o conteúdo nunca é persistido.** Igual ao
|
|
88
|
+
tratamento de `--context` (path, não conteúdo). O relatório vai só para o prompt transmitido e o
|
|
89
|
+
hash — a fronteira de privacidade do `docs/llm-fit-loop.md` é preservada.
|
|
90
|
+
|
|
91
|
+
**D4 — `ENGINEER_FAILED` falha antes do provedor.** Pedir `--engineer` e mandar um prompt sem o
|
|
92
|
+
contexto seria pior que falhar. Aditivo ao `errorCode` (que já distingue timeout/protocolo/etc.).
|
|
93
|
+
|
|
94
|
+
**D5 — `sessions` não usa `flags()`.** `flags()` é estrito com `--`; `list`/`show`/`<id>` são
|
|
95
|
+
posicionais. `cmdSessions()` parseia `argv` próprio, aceitando `--json` em qualquer posição.
|
|
96
|
+
|
|
97
|
+
**D6 — `show` lê a observação por `store.list().find(id)` e a `llm_validation` por
|
|
98
|
+
`repository.get('llm_validation', observationId)`, com fallback "indisponível".** Não acopla a
|
|
99
|
+
schema interno além do que a saída do `llm:run` já expõe.
|
|
100
|
+
|
|
101
|
+
Sem ADR — nenhuma decisão estrutural; a fronteira de privacidade e o read-only default (ADR-0081)
|
|
102
|
+
seguem intactos.
|
|
103
|
+
|
|
104
|
+
## 6. Dependências
|
|
105
|
+
|
|
106
|
+
- `forja engineer` (SPEC-035) e `llm_session` (ADR-0081) — ambos em `main`.
|
|
107
|
+
- **Pacotes npm**: nenhum.
|
|
108
|
+
- **Migrações**: nenhuma (`llm_session` já existe na tabela genérica `forja_records`).
|
|
109
|
+
|
|
110
|
+
## 7. Rollout
|
|
111
|
+
|
|
112
|
+
- [ ] Feature flag: não. `--engineer` e `llm:sessions` são aditivos.
|
|
113
|
+
- [ ] Migração de dados: não.
|
|
114
|
+
- [ ] Doc/persona: `docs/llm-fit-loop.md` (`--engineer`, `llm:sessions`); `docs/llm-evolution.md`
|
|
115
|
+
pode citar que C2/C5 fecharam.
|
|
116
|
+
- [ ] `CHANGELOG.md` `[Unreleased]`: Adicionado (`llm:run --engineer`, `llm:sessions`).
|
|
117
|
+
|
|
118
|
+
## 8. Sinais de fracasso (kill criteria)
|
|
119
|
+
|
|
120
|
+
- O bloco do `engineer` é grande e sem `--ref` fica genérico demais para valer — então `--engineer`
|
|
121
|
+
passa a aceitar `--engineer-ref`/`--engineer-role` (sai do "fora de escopo") ou vira só um
|
|
122
|
+
atalho documentado para `--context <(forja engineer --json)`.
|
|
123
|
+
- `sessions show` depende de campos internos que mudam a cada release — reduzir `show` a só a
|
|
124
|
+
`LlmSession` + um ponteiro para `forja llm:eval`/`evidence:show`.
|
|
125
|
+
- `flags()`/`main()` do `llm-fit.ts` resistem ao subcomando novo sem refator — nesse caso
|
|
126
|
+
`llm:sessions` vira um script próprio (`scripts/llm-sessions.ts`) reusando `lib/llm/session.ts`.
|
|
127
|
+
|
|
128
|
+
## Evidências e estado real
|
|
129
|
+
|
|
130
|
+
| AC | Task | Verificação |
|
|
131
|
+
|---|---|---|
|
|
132
|
+
| AC-1 | T2, T3 | `llm:run --engineer` embute o bloco; combina com `--prompt`/`--context` |
|
|
133
|
+
| AC-2 | T3 | `inputHash` cobre o bloco; `contextRefs` tem `engineer:<obj>`, sem conteúdo |
|
|
134
|
+
| AC-3 | T3 | `engineer` exit≠0 → `ENGINEER_FAILED`, exit 1, sem `runLlm` |
|
|
135
|
+
| AC-4 | T4, T5 | `llm:sessions list` (texto + `--json`) |
|
|
136
|
+
| AC-5 | T4, T5 | `llm:sessions show <id>`; id desconhecido → exit 1 |
|
|
137
|
+
| AC-6 | T4 | registry `readonly:true`; nenhuma escrita |
|
|
138
|
+
| AC-7 | T6 | registry + `docs/llm-fit-loop.md` |
|
|
139
|
+
| AC-8 | T1, T2 | `LlmSessionStore.all/find`; `buildEngineerBlock` testável |
|
|
140
|
+
| AC-9 | T7 | bateria completa; testes de `llm:run`/sessão intactos |
|
|
141
|
+
|
|
142
|
+
- **Sem mudança de contrato** na saída do `llm:run` (só um `errorCode` novo, aditivo).
|
|
143
|
+
- **Hipótese, não medição**: adoção depende de uso real; a flag `--engineer` já é auditada.
|
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
# Spec: llm-contexto-e-sessoes — `llm:run --engineer` e `llm:sessions`
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-048
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **Criado em**: 2026-09-08
|
|
7
|
+
- **Sprint alvo**: <a definir>
|
|
8
|
+
- **ADRs relacionadas**: nenhuma — extensão dos contratos de SPEC-028/029/ADR-0081; nenhuma
|
|
9
|
+
decisão estrutural. Read-only default preservado.
|
|
10
|
+
- **Origem**: `docs/roadmap-v4.1.md`, Onda 4 (W10). Fecha os pontos C2 e C5 do diagnóstico.
|
|
11
|
+
|
|
12
|
+
## 1. Problema
|
|
13
|
+
|
|
14
|
+
**C2 — montar contexto para o `llm:run` é manual.** Hoje o operador escolhe arquivos à mão
|
|
15
|
+
(`--context a.md --context b.md`). O façade `engineer` já compõe o pacote certo — contexto
|
|
16
|
+
mínimo do domínio + ADRs relevantes + `architecture:check` + risco + agentes recomendados +
|
|
17
|
+
incidentes parecidos + fluxo — mas **não alimenta o `llm:run`**. Quem quer o melhor contexto
|
|
18
|
+
roda `engineer` num terminal, copia, e cola no `--task`.
|
|
19
|
+
|
|
20
|
+
**C5 — não há como listar sessões.** `llm:run --resume SESSION_ID` retoma uma sessão Codex, mas
|
|
21
|
+
o `SESSION_ID` só aparece na saída JSON da execução anterior. `llm_session` guarda os metadados
|
|
22
|
+
(id, cwd, fingerprint do perfil, observação vinculada), e **nada os expõe**. Quem perdeu o
|
|
23
|
+
terminal anterior não retoma.
|
|
24
|
+
|
|
25
|
+
**Como medimos hoje**: `grep -rn "llm:sessions" .` → nada. `llm:run` só aceita `--context`.
|
|
26
|
+
|
|
27
|
+
## 2. Proposta de valor
|
|
28
|
+
|
|
29
|
+
`llm:run --engineer "<objetivo>"` monta o contexto pelo façade e o envia — hash cobrindo o
|
|
30
|
+
prompt transmitido, **sem persistir o conteúdo** (só a referência). `llm:sessions list|show`
|
|
31
|
+
torna as sessões retomáveis descobríveis. O agente para de reconstruir contexto na mão e não
|
|
32
|
+
perde mais uma sessão por fechar um terminal.
|
|
33
|
+
|
|
34
|
+
## 3. User stories
|
|
35
|
+
|
|
36
|
+
- **Como** operador do `llm:run`, **quero** `--engineer "<objetivo>"` no lugar de escolher
|
|
37
|
+
arquivos, **para que** o modelo receba o pacote que o `engineer` já sabe montar.
|
|
38
|
+
- **Como** operador que fechou o terminal, **quero** `forja llm:sessions` listando as sessões
|
|
39
|
+
Codex retomáveis (id, projeto, quando), **para que** eu recupere o `SESSION_ID` do `--resume`.
|
|
40
|
+
- **Como** auditor, **quero** `llm:sessions show <id>` ligando a sessão à observação e à
|
|
41
|
+
validação registradas, **para que** eu veja o histórico sem abrir o SQLite.
|
|
42
|
+
|
|
43
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
44
|
+
|
|
45
|
+
- [ ] **AC-1**: `forja llm:run --profile <p> --engineer "<objetivo>"` roda `forja engineer
|
|
46
|
+
"<objetivo>" --json` num subprocesso, embute o relatório no prompt (mesmo mecanismo de
|
|
47
|
+
`buildContextPrompt`: bloco rotulado + JSON), e envia. `--engineer` e `--prompt`/`--task`
|
|
48
|
+
combinam (o objetivo pode ser o próprio prompt); `--engineer` e `--context` também combinam.
|
|
49
|
+
- [ ] **AC-2**: o `inputHash` (`sha256`) cobre o **prompt final transmitido**, incluindo o bloco
|
|
50
|
+
do `engineer`. `contextRefs` da observação ganha uma entrada `engineer:<objetivo>` — a
|
|
51
|
+
**referência**, nunca o conteúdo do relatório. `llm_validation`/`Observation` continuam sem
|
|
52
|
+
texto.
|
|
53
|
+
- [ ] **AC-3**: se `forja engineer --json` falhar (exit ≠ 0), `llm:run --engineer` **falha antes
|
|
54
|
+
de chamar o provedor** com `errorCode: 'ENGINEER_FAILED'` e a primeira linha do stderr do
|
|
55
|
+
façade — nunca envia um prompt sem o contexto que foi pedido.
|
|
56
|
+
- [ ] **AC-4**: `forja llm:sessions list` — lista as sessões de `llm_session` (id, cwd/projeto,
|
|
57
|
+
`updatedAt`, `observationId`), mais recentes primeiro. `--json` emite um array.
|
|
58
|
+
- [ ] **AC-5**: `forja llm:sessions show <id>` — a sessão + resumo da observação vinculada
|
|
59
|
+
(`model`, `outcome`, `validationStatus`, `durationMs`) e da `llm_validation` (`status`,
|
|
60
|
+
nomes dos checks). `id` desconhecido → exit 1 com mensagem clara. `--json` emite um objeto.
|
|
61
|
+
- [ ] **AC-6**: `llm:sessions` é **somente leitura** — nenhuma escrita em `llm_session` nem no
|
|
62
|
+
recorder; `gates: ['workspace']` (precisa do banco), sem gate de rede.
|
|
63
|
+
- [ ] **AC-7**: registry — `llm:run.desc` menciona `--engineer`; entrada `llm:sessions` nova
|
|
64
|
+
(`tier` não; `domain: 'llm'`; `readonly: true`; `json: true`). `docs/llm-fit-loop.md`
|
|
65
|
+
documenta os dois.
|
|
66
|
+
- [ ] **AC-8**: `lib/llm/session.ts` `LlmSessionStore` ganha `all()` e `find(id)` (leitura pura,
|
|
67
|
+
sem `assertBinding`); `lib/llm/context.ts` ganha o builder do bloco `engineer` (ou fica em
|
|
68
|
+
`llm-fit.ts` se menor) — testável sem provedor.
|
|
69
|
+
- [ ] **AC-9**: `tsc --noEmit`, `node --test test/*.test.js`, `forja spec:check`,
|
|
70
|
+
`forja project:check` verdes. Testes de `llm:run`/sessão existentes inalterados.
|
|
71
|
+
|
|
72
|
+
## 5. Escopo
|
|
73
|
+
|
|
74
|
+
**Dentro**:
|
|
75
|
+
- `scripts/llm-fit.ts` — flag `--engineer` no `run()`; subcomando `sessions` (list/show).
|
|
76
|
+
- `lib/llm/session.ts` — `all()` / `find(id)`.
|
|
77
|
+
- `lib/llm/context.ts` — builder do bloco `engineer` a partir do JSON do façade (subprocesso).
|
|
78
|
+
- `lib/core/registry.ts` — `llm:sessions`; desc de `llm:run`.
|
|
79
|
+
- `docs/llm-fit-loop.md`; testes.
|
|
80
|
+
|
|
81
|
+
**Fora** (evita scope creep):
|
|
82
|
+
- Importar a lógica do `engineer` in-process — fica subprocesso (`forja engineer --json`), sem
|
|
83
|
+
refatorar `scripts/engineer.ts`.
|
|
84
|
+
- Passar `--ref`/`--role` do `engineer` por dentro do `--engineer` — usa os defaults do façade
|
|
85
|
+
nesta rodada; flags dedicadas são backlog.
|
|
86
|
+
- `llm:sessions delete`/`prune` — leitura só; limpeza é outra spec.
|
|
87
|
+
- Retomada automática ("continuar a última sessão") — o `--resume` continua exigindo o ID
|
|
88
|
+
explícito (ADR-0081).
|
|
89
|
+
- Adaptador não-Codex de sessão — `llm_session` segue Codex-only (ADR-0081).
|
|
90
|
+
|
|
91
|
+
## 6. NFRs / restrições
|
|
92
|
+
|
|
93
|
+
- **Privacidade**: o relatório do `engineer` pode conter dados do projeto — entra no prompt
|
|
94
|
+
transmitido e no hash, **nunca** no banco. Igual ao `--context` de hoje (`docs/llm-fit-loop.md`).
|
|
95
|
+
- **Compatibilidade**: `llm:run` sem `--engineer` inalterado; `--resume`, schema, checks intactos.
|
|
96
|
+
- **Performance**: `--engineer` adiciona um `forja engineer` (~1–2 s de bootstrap de grafo/sqlite)
|
|
97
|
+
antes da chamada ao provedor — desprezível vs. a latência do modelo.
|
|
98
|
+
- **Segurança**: `llm:sessions` não abre o provedor nem a rede; só lê o SQLite do workspace.
|
|
99
|
+
|
|
100
|
+
## 7. Riscos e mitigação
|
|
101
|
+
|
|
102
|
+
| Risco | Probabilidade | Impacto | Mitigação |
|
|
103
|
+
|---|---|---|---|
|
|
104
|
+
| Relatório do `engineer` estoura o contexto do modelo | M | M | AC-3 não trunca silenciosamente; o operador vê o tamanho no `stdout`; truncar/resumir é backlog |
|
|
105
|
+
| `forja engineer --json` sai 0 mas com relatório degradado (grafo vazio) | M | B | AC-1 embute o que vier; o relatório já sinaliza suas próprias lacunas |
|
|
106
|
+
| `llm:sessions show` acopla ao schema interno de `Observation`/`llm_validation` | B | M | `show` lê pelos campos públicos já expostos na saída do `llm:run`, com fallback "indisponível" |
|
|
107
|
+
| `--engineer` + `--context` + schema → prompt gigante e ordem confusa | B | B | Ordem fixa: prompt → bloco engineer → contextos → instrução de schema; documentada |
|
|
108
|
+
|
|
109
|
+
## 8. Métricas de sucesso
|
|
110
|
+
|
|
111
|
+
30 dias, baseline sobre `forja-runs.jsonl` (a flag `--engineer` já é auditada):
|
|
112
|
+
|
|
113
|
+
- Adoção: `llm:run --engineer` aparece como fração das execuções de `llm:run`.
|
|
114
|
+
- `llm:sessions` aparece em `forja-runs.jsonl` — alguém usou para recuperar um `SESSION_ID`.
|
|
115
|
+
- Zero regressão nos testes de `llm:run`/sessão.
|
|
116
|
+
|
|
117
|
+
## Evidências e estado real
|
|
118
|
+
|
|
119
|
+
**Implementado em 2026-09-08** na branch `feat/llm-engineer-sessions` (de `main`).
|
|
120
|
+
Bateria: `tsc --noEmit` limpo; `node --test test/*.test.js` **479/479** (+6: `test/llm-sessions.test.js`
|
|
121
|
+
e 1 em `test/llm-fit.test.js`); `forja spec:check` e `forja project:check` (100%) verdes.
|
|
122
|
+
|
|
123
|
+
| AC | Onde | Verificado |
|
|
124
|
+
|---|---|---|
|
|
125
|
+
| AC-1 | `lib/llm/context.ts` `buildEngineerBlock` + `scripts/llm-fit.ts run()` | `llm:run --engineer` embute `=== Contexto do engineer (objetivo: …) ===` + JSON antes do prompt; combina com `--prompt` |
|
|
126
|
+
| AC-2 | `scripts/llm-fit.ts` (`promptWithEngineer` → `buildContextPrompt` → `inputHash`) | teste: o `stdout` transmitido contém o bloco; `forja-runs.jsonl` **não** contém "Contexto do engineer"; `contextRefs` ganha `engineer:<obj>` |
|
|
127
|
+
| AC-3 | `buildEngineerBlock` (throw `.code='ENGINEER_FAILED'`) + `run()` try/catch antes de `runLlm` | teste unitário: `run` fake exit 1 → `Error.code === 'ENGINEER_FAILED'`, `.detail` = 1ª linha do stderr |
|
|
128
|
+
| AC-4 | `LlmSessionStore.all()` + `cmdSessions` `list` | `forja llm:sessions list [--json]` — array/tabela, mais recente primeiro |
|
|
129
|
+
| AC-5 | `LlmSessionStore.find()` + `cmdSessions` `show` | `show <id>` → `{ session, observation?, validation? }`; `show <id-ruim>` → exit 1, "não encontrada" |
|
|
130
|
+
| AC-6 | `lib/core/registry.ts` (`llm:sessions` `readonly: true`) + `cmdSessions` | teste: `llm_session` inalterado após `list`/`show` |
|
|
131
|
+
| AC-7 | `lib/core/registry.ts`, `docs/llm-fit-loop.md` | `llm:run.desc` cita `--engineer`; `llm:sessions` nova; `commands-documented`/`docs-*` verdes |
|
|
132
|
+
| AC-8 | `lib/llm/session.ts` `all`/`find`, `lib/llm/context.ts` `buildEngineerBlock` (com `run` injetável) | testes unitários verdes |
|
|
133
|
+
| AC-9 | — | bateria acima; `test/llm-fit.test.js`/`llm-resume-validation.test.js` intactos |
|
|
134
|
+
|
|
135
|
+
- **Sem desvio do plan.** `docs/llm-evolution.md` não foi tocado (sem âncora natural para C2/C5;
|
|
136
|
+
o registro do fecho fica no roadmap e neste spec).
|
|
137
|
+
- **Sem mudança de contrato** na saída do `llm:run` — só o `errorCode: 'ENGINEER_FAILED'`, aditivo.
|
|
138
|
+
- **Hipótese, não medição**: adoção depende de uso real; a flag `--engineer` já é auditada.
|
|
139
|
+
- **Pendências**: revisão de Governança; handoff `review` registrado.
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
# Tasks: llm-contexto-e-sessoes
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Plan**: ./plan.md
|
|
5
|
+
- **Status**: approved
|
|
6
|
+
- **Criado em**: 2026-09-08
|
|
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 ─┼─ T3 ─┐
|
|
15
|
+
T1 ─── T4 ─┼─ T5 ─┐
|
|
16
|
+
│ ├─ T6 ─ T7
|
|
17
|
+
T3,T5 ─────┘ │
|
|
18
|
+
todas ───────────────► T7
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Paralelizável no início: **T1 · T2**.
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## T1 — `LlmSessionStore.all()` + `find(id)`
|
|
26
|
+
- **Owner**: Worker · **Est**: P · **Depende de**: —
|
|
27
|
+
- **Paths**: `lib/llm/session.ts`
|
|
28
|
+
- **Escopo**: `all(): readonly LlmSession[]` = `repository.list<LlmSession>('llm_session')` ordenado
|
|
29
|
+
por `updatedAt` desc. `find(id): LlmSession | undefined` = `repository.get<LlmSession>('llm_session', id)`,
|
|
30
|
+
**sem** `assertBinding` (leitura pura). `require`/`save` inalterados.
|
|
31
|
+
- **Done**:
|
|
32
|
+
- [ ] `tsc --noEmit` verde
|
|
33
|
+
- [ ] teste unitário: `all()` devolve semeados em ordem desc; `find` acha e devolve `undefined` p/ id ausente
|
|
34
|
+
|
|
35
|
+
## T2 — `buildEngineerBlock(objective, opts?)`
|
|
36
|
+
- **Owner**: Worker · **Est**: M · **Depende de**: —
|
|
37
|
+
- **Paths**: `lib/llm/context.ts`
|
|
38
|
+
- **Escopo**: `buildEngineerBlock(objective, { cwd?, run? })` — `run` default = spawna
|
|
39
|
+
`node <forjaBin> engineer "<objective>" --json` (cwd), captura `{ code, stdout, stderr }`. `code
|
|
40
|
+
≠ 0` → `throw` de um `Error` com `.code = 'ENGINEER_FAILED'` e `.detail` = 1ª linha do stderr.
|
|
41
|
+
`code 0` → `JSON.parse(stdout)` e devolve `{ text, ref }` onde `text` é um bloco rotulado
|
|
42
|
+
(`=== Contexto do engineer (objetivo: <obj>) ===\n<JSON compacto>`) e `ref = "engineer:<obj>"`.
|
|
43
|
+
`run` injetável para teste.
|
|
44
|
+
- **Done**:
|
|
45
|
+
- [ ] teste: `run` fake code 0 → `{ text, ref }` com o JSON embutido
|
|
46
|
+
- [ ] teste: `run` fake code 1 → lança `Error` com `.code === 'ENGINEER_FAILED'`
|
|
47
|
+
|
|
48
|
+
## T3 — `llm:run --engineer`
|
|
49
|
+
- **Owner**: Worker · **Est**: M · **Depende de**: T2
|
|
50
|
+
- **Paths**: `scripts/llm-fit.ts`
|
|
51
|
+
- **Escopo**: `run()`: `--engineer` entra na allowlist de flags e não pode repetir. Se presente:
|
|
52
|
+
`const eng = buildEngineerBlock(obj)` dentro de try/catch — no catch com `.code ===
|
|
53
|
+
'ENGINEER_FAILED'` imprime `JSON.stringify({ profile: name, errorCode: 'ENGINEER_FAILED',
|
|
54
|
+
stderr: err.detail })` e `process.exit(1)` **antes** de `runLlm`. Sucesso: `prompt = eng.text +
|
|
55
|
+
'\n\n' + prompt`; `refs` (linha do `recorder.record`) ganha `eng.ref`. Se `--engineer` sem
|
|
56
|
+
`--prompt`/`--task`, o `<obj>` é o prompt.
|
|
57
|
+
- **Done**:
|
|
58
|
+
- [ ] `llm:run --engineer` (com adapter fixture) → observação com `contextRefs` contendo `engineer:<obj>`; `inputHash` muda vs. sem `--engineer`
|
|
59
|
+
- [ ] `engineer` fixture que sai 1 → `ENGINEER_FAILED`, exit 1, adapter LLM **não** chamado
|
|
60
|
+
- [ ] `llm:run` sem `--engineer` → saída byte-idêntica à de antes (snapshot)
|
|
61
|
+
|
|
62
|
+
## T4 — `cmdSessions()` (list | show)
|
|
63
|
+
- **Owner**: Worker · **Est**: M · **Depende de**: T1
|
|
64
|
+
- **Paths**: `scripts/llm-fit.ts`
|
|
65
|
+
- **Escopo**: `main()` ganha `else if (command === 'sessions') cmdSessions()`. `cmdSessions` parseia
|
|
66
|
+
`argv[3]` (`list`|`show`), `argv[4]` (id p/ show), `--json` em qualquer posição — **não** usa
|
|
67
|
+
`flags()`. `list`: `store.all()` → tabela (`id projeto(basename cwd) updatedAt obs`) ou array
|
|
68
|
+
`--json`. `show <id>`: `store.find(id)` (ausente → stderr + `process.exit(1)`); + observação por
|
|
69
|
+
`observationStore.list().find(o => o.id === session.observationId)`; + `repository.get('llm_validation',
|
|
70
|
+
session.observationId)`; monta `{ session, observation?, validation? }` com fallback `null`.
|
|
71
|
+
- **Done**:
|
|
72
|
+
- [ ] `forja llm:sessions list` e `--json` num workspace com sessões semeadas
|
|
73
|
+
- [ ] `forja llm:sessions show <id>` mostra sessão + observação; `show <id-ruim>` → exit 1
|
|
74
|
+
- [ ] nenhuma escrita (verificar: `forja_records` de `llm_session` inalterado após os comandos)
|
|
75
|
+
|
|
76
|
+
## T5 — Registry
|
|
77
|
+
- **Owner**: Worker · **Est**: P · **Depende de**: T3, T4
|
|
78
|
+
- **Paths**: `lib/core/registry.ts`
|
|
79
|
+
- **Escopo**: `llm:run.desc` cita `--engineer`. Entrada `llm:sessions`: `domain: 'llm'`,
|
|
80
|
+
`node: 'scripts/llm-fit.ts'`, `args: ['sessions']`, `gates: ['workspace']`, `readonly: true`,
|
|
81
|
+
`json: true`, `usage: 'forja llm:sessions <list|show> [id] [--json]'`, `examples`.
|
|
82
|
+
- **Done**:
|
|
83
|
+
- [ ] `forja llm:sessions` roteia; `test/forja-core.test.js` (integridade do registry) verde
|
|
84
|
+
|
|
85
|
+
## T6 — Documentação + CHANGELOG
|
|
86
|
+
- **Owner**: Worker · **Est**: P · **Depende de**: T3, T4, T5
|
|
87
|
+
- **Paths**: `docs/llm-fit-loop.md`, `docs/llm-evolution.md`, `CHANGELOG.md`
|
|
88
|
+
- **Escopo**: `llm-fit-loop.md` — subseções `--engineer` (com a nota de privacidade: relatório vai
|
|
89
|
+
ao prompt e ao hash, não ao banco) e `llm:sessions`. `llm-evolution.md` — C2/C5 fecharam.
|
|
90
|
+
CHANGELOG `[Unreleased]` — Adicionado.
|
|
91
|
+
- **Done**:
|
|
92
|
+
- [ ] `forja tools:doctor` → `docs-commands`, `commands-documented`, `docs-links` verdes
|
|
93
|
+
|
|
94
|
+
## T7 — Validação final + fecho
|
|
95
|
+
- **Owner**: Worker → Governance · **Est**: P · **Depende de**: T1–T6
|
|
96
|
+
- **Paths**: `specs/llm-contexto-e-sessoes/spec.md`
|
|
97
|
+
- **Escopo**: bateria; `spec.md` §Evidências; mover status; handoff `review`.
|
|
98
|
+
- **Done**:
|
|
99
|
+
- [ ] `tsc --noEmit`, `node --test test/*.test.js`, `forja spec:check`, `forja project:check` verdes — AC-9
|
|
100
|
+
- [ ] testes de `llm:run`/sessão existentes verdes sem alteração
|
|
101
|
+
- [ ] `spec:set-status llm-contexto-e-sessoes spec implementing` no início; handoff `review` ao fim
|
|
102
|
+
|
|
103
|
+
---
|
|
104
|
+
|
|
105
|
+
## Mapa AC → task
|
|
106
|
+
|
|
107
|
+
| AC | Tasks | Verificação-chave |
|
|
108
|
+
|---|---|---|
|
|
109
|
+
| AC-1 | T2, T3 | `llm:run --engineer` embute o bloco |
|
|
110
|
+
| AC-2 | T3 | `inputHash` cobre o bloco; `contextRefs` = `engineer:<obj>` |
|
|
111
|
+
| AC-3 | T2, T3 | `ENGINEER_FAILED` antes do provedor |
|
|
112
|
+
| AC-4 | T1, T4 | `llm:sessions list` |
|
|
113
|
+
| AC-5 | T1, T4 | `llm:sessions show <id>` |
|
|
114
|
+
| AC-6 | T4, T5 | read-only; `readonly:true` |
|
|
115
|
+
| AC-7 | T5, T6 | registry + `llm-fit-loop.md` |
|
|
116
|
+
| AC-8 | T1, T2 | `all/find`; `buildEngineerBlock` testável |
|
|
117
|
+
| AC-9 | T7 | bateria; testes existentes intactos |
|
|
118
|
+
|
|
119
|
+
## Handoffs entre agentes
|
|
120
|
+
|
|
121
|
+
SDD Architect (spec+plan+tasks) → **Worker** (T1–T6) → **Governance** (T7 + `project:check`).
|
|
122
|
+
|
|
123
|
+
## Evidências e estado real
|
|
124
|
+
|
|
125
|
+
- Nada executado — caixas `[ ]` abertas.
|
|
126
|
+
- **Sem dependência de branch** — de `main`; usa `forja engineer` (SPEC-035) e `llm_session` (ADR-0081).
|
|
127
|
+
- **Sem mudança de contrato** na saída do `llm:run` (só `errorCode: 'ENGINEER_FAILED'`, aditivo).
|