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,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).