forjajs 5.1.0 → 5.3.1
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 +108 -0
- package/README.md +52 -4
- package/README.pt-BR.md +54 -4
- package/dist/apps/cli/src/index.d.ts +0 -1
- package/dist/apps/cli/src/index.js +43 -32
- package/dist/apps/dashboard/app/api/forja/[...path]/route.js +34 -1
- package/dist/apps/dashboard/app/api/forja/capabilities.d.ts +26 -0
- package/dist/apps/dashboard/app/api/forja/capabilities.js +39 -0
- package/dist/apps/dashboard/app/dashboard-client.jsx +607 -42
- package/dist/apps/server/src/forja-nest.module.d.ts +6 -0
- package/dist/apps/server/src/forja-nest.module.js +55 -0
- package/dist/apps/server/src/main.d.ts +21 -4
- package/dist/apps/server/src/main.js +79 -57
- package/dist/apps/server/src/task-planning-service.d.ts +29 -0
- package/dist/apps/server/src/task-planning-service.js +195 -0
- package/dist/apps/server/src/task-runtime-coordinator.d.ts +57 -0
- package/dist/apps/server/src/task-runtime-coordinator.js +229 -0
- package/dist/bin/forja.js +3 -2
- package/dist/lib/agent-evals.d.ts +138 -0
- package/dist/lib/agent-evals.js +365 -0
- package/dist/lib/cli-output.js +14 -2
- package/dist/lib/code-context.d.ts +33 -5
- package/dist/lib/code-context.js +70 -5
- package/dist/lib/context-builder.d.ts +49 -4
- package/dist/lib/context-builder.js +114 -47
- package/dist/lib/core/coverage-gate.d.ts +59 -0
- package/dist/lib/core/coverage-gate.js +58 -0
- package/dist/lib/core/doc-graph.d.ts +38 -0
- package/dist/lib/core/doc-graph.js +83 -0
- package/dist/lib/core/health.js +286 -5
- package/dist/lib/core/journey.js +26 -0
- package/dist/lib/core/registry.js +81 -6
- package/dist/lib/docs-reference.d.ts +35 -0
- package/dist/lib/docs-reference.js +57 -0
- package/dist/lib/exec.d.ts +55 -0
- package/dist/lib/exec.js +141 -0
- package/dist/lib/project-wiring.js +6 -2
- package/dist/lib/session-memory.d.ts +38 -0
- package/dist/lib/session-memory.js +206 -0
- package/dist/lib/spec-trace.d.ts +46 -0
- package/dist/lib/spec-trace.js +184 -0
- package/dist/packages/adapter-git/src/index.js +13 -4
- package/dist/packages/adapter-nest/src/index.d.ts +2 -1
- package/dist/packages/adapter-nest/src/index.js +59 -1
- package/dist/packages/adapter-sqlite/src/index.d.ts +15 -1
- package/dist/packages/adapter-sqlite/src/index.js +61 -1
- package/dist/packages/context/src/index.d.ts +2 -0
- package/dist/packages/context/src/index.js +36 -15
- package/dist/packages/contracts/src/index.d.ts +64 -0
- package/dist/packages/core/src/index.d.ts +9 -1
- package/dist/packages/core/src/index.js +28 -3
- package/dist/packages/graph/src/index.js +14 -5
- package/dist/packages/llm/src/index.js +7 -24
- package/dist/packages/mcp/src/index.d.ts +8 -0
- package/dist/packages/mcp/src/index.js +12 -1
- package/dist/packages/observability/src/index.d.ts +11 -0
- package/dist/packages/observability/src/index.js +3 -0
- package/dist/packages/orchestration/src/index.d.ts +15 -1
- package/dist/packages/orchestration/src/index.js +127 -21
- package/dist/packages/planner/src/index.d.ts +7 -1
- package/dist/packages/planner/src/index.js +67 -10
- package/dist/packages/planner/src/proposal-store.d.ts +30 -0
- package/dist/packages/planner/src/proposal-store.js +109 -0
- package/dist/packages/policy/src/index.d.ts +9 -16
- package/dist/packages/policy/src/index.js +114 -31
- package/dist/packages/runtime/src/index.d.ts +16 -2
- package/dist/packages/runtime/src/index.js +176 -61
- package/dist/scripts/build-smart-context.d.ts +2 -0
- package/dist/scripts/build-smart-context.js +12 -3
- package/dist/scripts/code-context.d.ts +3 -1
- package/dist/scripts/code-context.js +13 -3
- package/dist/scripts/coverage-gate.d.ts +2 -0
- package/dist/scripts/coverage-gate.js +101 -0
- package/dist/scripts/eval-agents.d.ts +11 -0
- package/dist/scripts/eval-agents.js +96 -0
- package/dist/scripts/gen-commands-doc.d.ts +2 -0
- package/dist/scripts/gen-commands-doc.js +18 -0
- package/dist/scripts/hook-session-memory.d.ts +9 -0
- package/dist/scripts/hook-session-memory.js +20 -0
- package/dist/scripts/hook-session-start.js +34 -0
- package/dist/scripts/llm-fit.js +15 -6
- package/dist/scripts/simulate.js +16 -4
- package/dist/scripts/spec-trace.d.ts +10 -0
- package/dist/scripts/spec-trace.js +73 -0
- package/dist/scripts/sync-universal-memory.js +69 -4
- package/dist/scripts/token-benchmark.d.ts +33 -1
- package/dist/scripts/token-benchmark.js +179 -5
- package/dist/scripts/token-economy.js +3 -1
- package/dist/scripts/tools-doctor.d.ts +16 -1
- package/dist/scripts/tools-doctor.js +58 -17
- package/docs/commands.md +155 -0
- package/docs/fluxo.md +11 -7
- package/docs/init-project.md +3 -1
- package/docs/llm-fit-loop.md +20 -0
- package/docs/manual-operacional-cli-sdd-gsd.md +3 -2
- package/docs/produto/factsheet-marketing.md +7 -5
- package/docs/produto/roteiro-demo.md +14 -5
- package/docs/quick-reference.md +3 -3
- package/docs/token-optimization.md +10 -6
- package/memory/90-decisions/0091-memoria-de-sessao-por-hooks.md +40 -0
- package/memory/90-decisions/0092-criterios-de-aceite-ligados-a-testes.md +37 -0
- package/memory/90-decisions/0093-avaliacoes-com-agentes-reais.md +40 -0
- package/package.json +4 -2
- package/specs/avaliacoes-de-agentes/spec.md +52 -0
- package/specs/criterios-ligados-a-testes/spec.md +42 -0
- package/specs/memoria-de-sessao/spec.md +48 -0
- package/specs/v6-agent-runtime-portable/spec.md +83 -0
- package/specs/v6-core-consolidation/spec.md +70 -0
- package/specs/v6-docs-drift/spec.md +85 -0
- package/specs/v6-quality-gates/spec.md +104 -0
- package/specs/v6-token-economy/spec.md +84 -0
- package/templates/evals/agents/adr.json +25 -0
- package/templates/evals/agents/memoria.json +32 -0
- package/templates/evals/agents/proxima-acao.json +29 -0
- package/templates/evals/agents/spec-nova.json +26 -0
- package/templates/evals/agents/teste-do-criterio.json +29 -0
- package/templates/project/AGENTS.md +7 -0
- package/templates/project/CLAUDE.md +3 -2
- package/templates/project/skills/testing/SKILL.md +1 -1
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# Spec: criterios-ligados-a-testes
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-053
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **Criado em**: 2026-10-21
|
|
7
|
+
- **Sprint alvo**: 5.2
|
|
8
|
+
- **ADRs relacionadas**: [ADR-0007](../../memory/90-decisions/0007-sdd-pipeline.md) (SDD), ADR-0092 (esta feature)
|
|
9
|
+
|
|
10
|
+
## 1. Problema
|
|
11
|
+
Uma spec diz o que é "pronto" nos critérios de aceite (`AC-N`), mas nada liga um critério ao teste
|
|
12
|
+
que o prova. Uma spec vira `done` com critérios sem teste, e um critério renumerado deixa testes
|
|
13
|
+
apontando para o critério errado, sem ninguém notar. A convenção existe por costume (`SPEC-029 AC-5`
|
|
14
|
+
no nome do teste), mas ninguém a confere. Medição hoje: não sabemos quantos ACs têm teste.
|
|
15
|
+
|
|
16
|
+
## 2. Proposta de valor
|
|
17
|
+
`forja spec:trace` mostra, para cada critério de cada spec, os testes que o citam, e aponta os
|
|
18
|
+
critérios sem teste e as citações órfãs. Com `--strict`, vira gate para specs aprovadas ou prontas.
|
|
19
|
+
|
|
20
|
+
## 3. User stories
|
|
21
|
+
- **Como** governance, **quero** ver quais critérios de uma spec `done` não têm teste, **para que** "pronto" signifique provado.
|
|
22
|
+
- **Como** dev, **quero** saber que citar `SPEC-053 AC-2` no nome do teste basta, **para que** a ligação não custe nada.
|
|
23
|
+
- **Como** dev que editou a spec, **quero** ser avisado de testes citando um critério que não existe mais, **para que** a rastreabilidade não minta.
|
|
24
|
+
|
|
25
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
26
|
+
- [ ] AC-1: `forja spec:trace [slug]` lista cada `AC-N` da spec e os testes que o citam (arquivo:linha), e resume `N/M critérios com teste`.
|
|
27
|
+
- [ ] AC-2: um teste cita um critério escrevendo `SPEC-NNN AC-N`, `<slug> AC-N` ou listas (`SPEC-029 AC-5/AC-6`, `AC-1, AC-2`); `AC-N` sozinho vale para a spec quando o arquivo de teste cita uma única spec (pelo ID, pelo slug, por `specs/<slug>/` ou pelo nome do arquivo, `<slug>.test.js`) e o critério existe nela; senão, é listado como ambíguo.
|
|
28
|
+
- [ ] AC-3: citação qualificada de critério inexistente (`SPEC-053 AC-9` sem AC-9) aparece como órfã.
|
|
29
|
+
- [ ] AC-4: arquivos de teste são achados em qualquer stack (`*.test.*`, `*.spec.*`, `test_*.py`, `*_test.go`, pastas `test/`, `tests/`, `__tests__/`), ignorando `node_modules`, `dist`, `.git` e `coverage`.
|
|
30
|
+
- [ ] AC-5: `--strict` sai com 2 (`rejected`) quando uma spec `approved`, `implementing` ou `done` tem critério sem teste ou citação órfã; sem `--strict` o comando só informa (exit 0). `--json` segue o contrato (ADR-0082).
|
|
31
|
+
- [ ] AC-6: o `AGENTS.md` do projeto gerado e a skill `testing` ensinam a convenção.
|
|
32
|
+
|
|
33
|
+
## 5. Requisitos não-funcionais
|
|
34
|
+
- **Performance**: repo do Forja (~90 arquivos de teste, ~50 specs) em < 2 s.
|
|
35
|
+
- **Segurança**: somente leitura.
|
|
36
|
+
|
|
37
|
+
## 6. Fora de escopo
|
|
38
|
+
- Rodar os testes e marcar o critério como verde/vermelho (fica para o executor de testes de cada stack).
|
|
39
|
+
- Editar specs ou testes automaticamente.
|
|
40
|
+
|
|
41
|
+
## 7. Riscos e dependências
|
|
42
|
+
- `AC-N` sozinho num arquivo que cita várias specs é ambíguo: não conta para nenhuma (o relatório diz por quê).
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Spec: memoria-de-sessao
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-052
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **Criado em**: 2026-10-21
|
|
7
|
+
- **Sprint alvo**: 5.2
|
|
8
|
+
- **ADRs relacionadas**: [ADR-0086](../../memory/90-decisions/0086-projeto-conectado-e-jornada-como-gate.md) (projeto conectado), ADR-0091 (esta feature)
|
|
9
|
+
|
|
10
|
+
## 1. Problema
|
|
11
|
+
O que acontece numa sessão de IA só fica no transcript, que o Forja não lê. Quando o contexto é
|
|
12
|
+
compactado, a IA perde o fio (quais arquivos mexeu, qual spec estava seguindo, o que já commitou), e a
|
|
13
|
+
sessão seguinte começa do zero: o briefing do SessionStart mostra specs e handoffs, mas nada sobre o
|
|
14
|
+
que foi feito por último. Medição hoje: 0 registros de sessão em `memory/` de qualquer projeto.
|
|
15
|
+
|
|
16
|
+
## 2. Proposta de valor
|
|
17
|
+
Toda sessão do Claude Code que muda alguma coisa deixa um checkpoint determinístico na memória do
|
|
18
|
+
projeto, atualizado ao fim de cada turno e antes de cada compactação. Depois de compactar, a IA recebe
|
|
19
|
+
o checkpoint de volta; numa sessão nova, vê onde a anterior parou. Sem chamar LLM, sem custo.
|
|
20
|
+
|
|
21
|
+
## 3. User stories
|
|
22
|
+
- **Como** dev numa sessão longa, **quero** que a IA, depois da compactação, saiba quais arquivos já
|
|
23
|
+
editou e qual spec estava seguindo, **para que** ela não refaça nem contradiga o trabalho.
|
|
24
|
+
- **Como** dev abrindo uma sessão nova, **quero** ver onde a última parou, **para que** eu retome sem reler o histórico.
|
|
25
|
+
- **Como** dono do projeto, **quero** que nenhum texto de prompt ou comando inteiro vá para a memória
|
|
26
|
+
commitada, **para que** um segredo colado no chat não acabe no git.
|
|
27
|
+
|
|
28
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
29
|
+
- [x] AC-1: `forja hook:session-memory` lê o JSON do hook (stdin: `session_id`, `transcript_path`, `cwd`, `hook_event_name`) e grava `memory/60-runs/sessions/<AAAA-MM-DD>-<id8>.md` com: título da sessão (`ai-title`), branch, arquivos editados (Edit/Write/MultiEdit/NotebookEdit, relativos ao projeto), comandos `forja <cmd>` (só o nome), specs tocadas (citadas em caminhos editados ou em comandos `forja spec:*`) e assuntos de `git commit -m`.
|
|
30
|
+
- [x] AC-2: sessão sem edição, sem comando forja e sem commit não grava nada; o mesmo `session_id` reescreve o mesmo arquivo (idempotente); o arquivo não contém texto de prompt.
|
|
31
|
+
- [x] AC-3: o hook nunca derruba a sessão: transcript ausente, JSON inválido ou projeto sem `memory/` saem com 0 e sem saída.
|
|
32
|
+
- [x] AC-4: `project:wire` registra o hook nos eventos `Stop` e `PreCompact` do `.claude/settings.json`, e `project:wire --check` (check `claude-hooks`) falha se faltar algum dos quatro eventos.
|
|
33
|
+
- [x] AC-5: `hook:session-start` lê o `source` do stdin: em `compact` injeta o checkpoint da própria sessão; em `startup`/`resume` injeta uma linha com a última sessão registrada (data, título, nº de arquivos, specs).
|
|
34
|
+
- [x] AC-6: a jornada (`lib/core/journey.ts`) cobre o caminho: transcript sintético → checkpoint gravado → SessionStart `compact` o devolve.
|
|
35
|
+
|
|
36
|
+
## 5. Requisitos não-funcionais
|
|
37
|
+
- **Performance**: transcript de 10 MB processado em < 1 s (linhas sem `tool_use`/`ai-title` são descartadas antes do `JSON.parse`); timeout do hook 10 s.
|
|
38
|
+
- **Segurança/LGPD**: sem texto de prompt, sem argumentos de comando além do nome do subcomando `forja`, sem saída de ferramenta.
|
|
39
|
+
- **Observabilidade**: não audita (hooks já são excluídos da trilha, `bin/forja.ts`).
|
|
40
|
+
|
|
41
|
+
## 6. Fora de escopo
|
|
42
|
+
- Resumo por LLM da sessão (custo; pode vir depois, alimentado por este checkpoint).
|
|
43
|
+
- Gate de "pronto" no Stop (bloquear o fim do turno com testes vermelhos).
|
|
44
|
+
- Codex/Gemini/Copilot: não têm eventos equivalentes de fim de turno e compactação com transcript em disco.
|
|
45
|
+
|
|
46
|
+
## 7. Riscos e dependências
|
|
47
|
+
- Formato do transcript do Claude Code não é contrato público: o parser ignora o que não reconhece e degrada para "nada a gravar".
|
|
48
|
+
- Checkpoints entram no git do projeto como o resto de `memory/`; quem não quiser ignora `memory/60-runs/sessions/`.
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# Spec: v6-agent-runtime-portable
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-059
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: allanpablo
|
|
6
|
+
- **Criado em**: 2026-11-08
|
|
7
|
+
- **Sprint alvo**: v6.0 Wave 2
|
|
8
|
+
- **ADRs relacionadas**: a criar em memory/90-decisions/
|
|
9
|
+
|
|
10
|
+
## 1. Problema
|
|
11
|
+
O forja fala com agentes de IA por subprocesso, e essa fronteira foi escrita para unix. Estado validado em 2026-11-08 (`packages/llm/src/index.ts`, `scripts/llm-fit.ts`, `lib/agent-evals.ts`, log da rodada 4 da célula `windows-latest` no PR #83, v5.2.0):
|
|
12
|
+
|
|
13
|
+
- **`llm:run` não spawnar o provedor** — `runLlm()` faz `spawn(executable, args, { shell: false, detached: true })` (`packages/llm/src/index.ts:123`). No Windows o que `npm i -g` instala é `claude.cmd`/`codex.cmd`, e o Node recusa spawnar `.bat`/`.cmd` sem `shell: true` desde o endurecimento da CVE-2024-27980 (18.20.2 / 20.12.2 / 21.7.3), com `EINVAL`. Toda execução termina em `errorCode: 'SPAWN_FAILED'`, exit 127, antes de falar com o provedor. **Não existe versão de Node suportada em que isso funcione**: a matriz do CI roda 22 e 24, ambas do lado endurecido.
|
|
14
|
+
- **`llm:doctor`/`llm:probe` mentem sobre o que está instalado** — as seis sondagens de binário usam `shell: false` explícito (`scripts/llm-fit.ts:76,84,86,91,104,108`). O mesmo `EINVAL` vira `available: false`, e o comando reporta "provedor indisponível" para uma CLI instalada e funcionando, saindo com código 1 se o perfil estiver habilitado. O `detail` traz o errno cru, não o diagnóstico.
|
|
15
|
+
- **`eval:agents` tem duas frentes unix** — `timed()`/`cliVersion()` spawnam o binário direto (`lib/agent-evals.ts:177,183`, mesma restrição do probe), e o check `type: 'command'` roda via `spawnSync('sh', ['-c', …])` (`lib/agent-evals.ts:254`). Sem `sh`, checks declarativos como `"run": "node --test"` (`templates/evals/agents/teste-do-criterio.json:21`) são inaplicáveis — ainda que o comando em si seja perfeitamente portável.
|
|
16
|
+
- **Timeout não derruba a árvore** — `killGroup()` mata com `process.kill(-pid, 'SIGTERM')` (`packages/llm/src/index.ts:132-140`). Grupo de processo por pid negativo é POSIX; no Windows lança e cai no `child.kill(signal)`, que (a) não alcança os netos — o CLI real que o shim `.cmd` spawnou sobrevive — e (b) não tem o grace de `SIGTERM_GRACE_MS`, porque sinal em Windows é emulação: `kill('SIGTERM')` termina incondicionalmente. O orçamento de custo do forja pressupõe que um agente estourando o timeout para de queimar token.
|
|
17
|
+
|
|
18
|
+
Quem sente: usuário Windows (`llm:run`/`llm:doctor`/`eval:agents` não funcionam, e um agente em timeout continua rodando e cobrando), agente de IA consumindo o doctor (relatório falso de disponibilidade), maintainer (esta família é 6 dos 10 casos que seguram o `continue-on-error` da célula Windows, SPEC-056 AC-4).
|
|
19
|
+
|
|
20
|
+
**Honestidade sobre os 6 casos do CI**: eles falham porque os testes modelam o CLI do agente como script com shebang + `chmod 0o755` (`test/agent-evals.test.js` AC-4/AC-5/AC-6, `test/llm-resume-validation.test.js:142` → `spawn EFTYPE`, `test/llm-claude-adapter.test.js:99`, `test/llm-integration.test.js:111`). O fixture é unix-cêntrico, mas o que ele expõe é o caminho real do produto: em Windows um binário de agente **é** um `.cmd`, e o produto não resolve `.cmd`. Consertar só o fixture — um stub em Node, por exemplo — deixaria a suíte verde com `llm:run` quebrado em produção. Por isso o AC-3 obriga o stub falso a passar pelo `.cmd`, em vez de desviar dele.
|
|
21
|
+
|
|
22
|
+
## 2. Proposta de valor
|
|
23
|
+
Um único módulo de execução de subprocesso (`lib/exec.ts`) que resolve o binário do agente (`where`/`PATHEXT`), escapa argumentos para `cmd.exe` quando o SO exige, derruba a árvore do processo no timeout e oferece um launcher de shell portável para checks declarativos. `llm:run`, `llm:doctor`, `llm:probe` e `eval:agents` passam a funcionar nos três SOs, e o primeiro item do inventário da SPEC-056 AC-4 — o único que quebra o produto do usuário em produção, e não o CI — zera.
|
|
24
|
+
|
|
25
|
+
Sem dependência nova, de propósito: o que falta são ~40 linhas de quoting que conseguimos testar exaustivamente, inclusive contra injeção. Importar `cross-spawn` para isso colocaria na cadeia de suprimento de uma CLI publicada um pacote que já teve o seu próprio CVE (ReDoS, CVE-2024-21538) — é o mesmo defeito que a SPEC-058 ataca, importar uma segunda máquina para o que a primeira já faz. A decisão fica registrada em ADR, com a alternativa documentada em vez de esquecida (R-1).
|
|
26
|
+
|
|
27
|
+
## 3. User stories
|
|
28
|
+
- **Como** usuário Windows, **quero** que `forja llm:run` encontre o `claude`/`codex` que o npm instalou, **para que** eu use o framework sem depender de WSL.
|
|
29
|
+
- **Como** operador, **quero** que o `llm:doctor` distinga "não instalado" de "instalado mas o forja não conseguiu executar", **para que** o relatório não me mande reinstalar o que já está lá.
|
|
30
|
+
- **Como** maintainer rodando `eval:agents` com orçamento, **quero** que o timeout derrube a árvore inteira do agente, **para que** um caso estourado não continue queimando token depois do resultado sair.
|
|
31
|
+
- **Como** contribuidor, **quero** escrever checks `type: 'command'` com comandos portáveis e vê-los rodar em qualquer SO, **para que** a suíte de evals não seja um ativo só de unix.
|
|
32
|
+
|
|
33
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
34
|
+
- [x] AC-1: os quatro call sites de fronteira de agente passam por `lib/exec.ts` (`resolveCommand`, `spawnAgent`, `runShell`, `killTree`): `packages/llm/src/index.ts:123`, `scripts/llm-fit.ts:76,84,86,91,104,108`, `lib/agent-evals.ts:177,183` e `lib/agent-evals.ts:254`. Spawn de `git`, `node` e `process.execPath` continua como está — não é a fronteira em questão e mexer nele seria escopo emprestado.
|
|
35
|
+
- [x] AC-2 (segurança): o quoting de argumentos para `cmd.exe` é provado por teste com argumentos hostis — `"`, `&`, `|`, `>`, `<`, `%VAR%`, `^`, espaço, caminho com `\` — chegando ao processo-filho byte a byte como foi passado, e nenhum deles executando um segundo comando. O prompt do usuário e o comando do perfil são argumentos: sem este AC, o AC-1 trocava `EINVAL` por injeção. `shell: true` do Node nunca é usado (ele não escapa argumentos).
|
|
36
|
+
- [x] AC-3 (fixture não desvia do produto): o stub de agente dos testes é um `.cmd` no Windows e continua script com shebang em unix, executado pelo mesmo resolver do produto. Os 6 casos do inventário ficam verdes na célula Windows **sem skip**.
|
|
37
|
+
- [x] AC-4 (a árvore morre junto): em timeout, `runLlm` derruba filho e netos nos três SOs — no Windows por `taskkill /pid <pid> /T /F` ou equivalente, em POSIX pelo pid negativo como hoje. Teste: agente falso de dois níveis cujo neto escreve a cada 100ms para de escrever depois do grace, nos dois SOs. `exitCode: 124` / `errorCode: 'TIMEOUT'` não mudam.
|
|
38
|
+
- [x] AC-5 (diagnóstico honesto): binário não encontrável → `available: false` com `detail` dizendo o que foi procurado (caminho resolvido, `PATHEXT`); binário encontrável que falha ao executar → outro detail. O contrato `--json` (ADR-0082) e os campos existentes não mudam, só o conteúdo de `detail`.
|
|
39
|
+
- [x] AC-6 (checks `command`): `type: 'command'` roda por `runShell`, que usa `sh -c` em POSIX e `%ComSpec% /d /s /c` no Windows; as suítes de `templates/evals/agents/*.json` rodam inteiras nos três SOs. `CheckResult` não ganha estado novo nesta spec.
|
|
40
|
+
|
|
41
|
+
## 5. Escopo
|
|
42
|
+
**Dentro**:
|
|
43
|
+
- `lib/exec.ts` (novo) + `test/exec.test.js` (novo): resolver, quoting, `killTree`, `runShell`.
|
|
44
|
+
- `packages/llm/src/index.ts`: `runLlm` aceita launcher injetável — o pacote hoje importa só `node:child_process` e continua assim; quem injeta é o `scripts/llm-fit.ts`.
|
|
45
|
+
- `scripts/llm-fit.ts`: as seis sondagens do doctor e a chamada de `runLlm`.
|
|
46
|
+
- `lib/agent-evals.ts`: `timed()`, `cliVersion()` e o check `command`.
|
|
47
|
+
- Fixtures dos quatro arquivos de teste do inventário: stub portável.
|
|
48
|
+
|
|
49
|
+
**Fora**:
|
|
50
|
+
- `cross-spawn`/`execa`/qualquer dependência nova (§2, R-1).
|
|
51
|
+
- Estado `skipped` em `CheckResult` — muda o JSON que o dashboard de evals consome; decisão separada.
|
|
52
|
+
- Os outros dois itens do inventário Windows (`git worktree` em `test/simulate-cli.test.js`, `spec:trace 0/0` na jornada) e a linha `continue-on-error` do `ci.yml`, que só sai quando o inventário inteiro zerar.
|
|
53
|
+
- WSL como caminho suportado: é contorno, não solução, e o framework já é usado fora dele.
|
|
54
|
+
- Reescrever checks `command` de usuários em Node: o launcher portável resolve sem exigir migração.
|
|
55
|
+
|
|
56
|
+
## 6. NFRs / restrições
|
|
57
|
+
- Segurança: fronteira de subprocesso com argumento vindo de usuário (prompt) e de configuração (comando do perfil). Quoting é requisito, não otimização.
|
|
58
|
+
- Compatibilidade: em POSIX/macOS nenhum comportamento muda — o caminho direto continua vencendo quando existe, como no `inside()` da SPEC-056. Zero regressão nos 666 testes das células ubuntu/macos.
|
|
59
|
+
- Superfície: um módulo, quatro funções. `hasBinary()` (`lib/project-wiring.ts:98`) já resolve binário por plataforma com `where`/`which` — o módulo segue essa convenção em vez de inventar outra, e ela passa a ser caso particular de `resolveCommand`.
|
|
60
|
+
- Custo: zero minuto novo de CI (os testes rodam na matriz que já existe).
|
|
61
|
+
|
|
62
|
+
## 7. Riscos e mitigação
|
|
63
|
+
| Risco | Probabilidade | Impacto | Mitigação |
|
|
64
|
+
|---|---|---|---|
|
|
65
|
+
| Quoting de `cmd.exe` escrito à mão deixar passar injeção | M | A | AC-2 com casos hostis explícitos; ADR registra o que foi testado; alternativa (dependência) documentada em vez de esquecida |
|
|
66
|
+
| `taskkill /T` não alcançar neto de shim `.cmd` encadeado | M | M | AC-4 mede com agente falso de dois níveis; se não alcançar, o detail do timeout reporta quantos processos restaram |
|
|
67
|
+
| Consertar o fixture e não o produto (suíte verde, `llm:run` quebrado) | M | A | AC-3 obriga o stub a ser `.cmd` no Windows e a passar pelo resolver do produto |
|
|
68
|
+
| Launcher injetável em `runLlm` quebrar o contrato dos adapters | B | M | Injeção com default = comportamento atual; testes existentes de resume/timeout continuam provando o mesmo contrato |
|
|
69
|
+
| `resolveCommand` escolher binário errado (PATH com duplicados) | B | M | `where` lista todos; o módulo usa o primeiro e o AC-5 expõe o caminho resolvido no `detail` |
|
|
70
|
+
| `runShell` executar comando de check com semântica diferente por SO | M | M | AC-6 roda as suítes template nos três SOs; comando que não é portável falha com o launcher no detail, não silenciosamente |
|
|
71
|
+
|
|
72
|
+
## 8. Métricas de sucesso
|
|
73
|
+
30 dias após: `llm:run`, `llm:doctor` e `eval:agents` verdes na célula Windows do CI; inventário da SPEC-056 AC-4 de 3 causas/10 casos para 2 causas/4 casos; zero relato de "provedor indisponível" em máquina com o provedor instalado; nenhum caso novo nos testes de injeção de argumento.
|
|
74
|
+
|
|
75
|
+
## Evidências e estado real
|
|
76
|
+
Levantamento de 2026-11-08, branch `feat/v6-wave1` (PR #83), por leitura de código e log da rodada 4 — sem patch adivinhado:
|
|
77
|
+
|
|
78
|
+
- **Call sites lidos, um a um**: `packages/llm/src/index.ts:123` (`spawn` com `shell: false, detached: true`), `:132-140` (`killGroup` com `process.kill(-pid)` e fallback `child.kill`), `scripts/llm-fit.ts:76,84,86,91,104,108` (seis sondagens com `shell: false`), `lib/agent-evals.ts:177,183` (spawn direto do binário do agente), `:254` (`spawnSync('sh', ['-c', check.run])`).
|
|
79
|
+
- **Os 6 casos da célula Windows**: `test/llm-resume-validation.test.js:142` (`spawn EFTYPE`), `test/agent-evals.test.js` AC-4/AC-5/AC-6 (`agent.args` nunca escrito), `test/llm-claude-adapter.test.js:99`, `test/llm-integration.test.js:111`. Os 2 casos do AC-1 da SPEC-054, que eram desta família, ficaram verdes na rodada 2 — o que confirma que a causa deles era o CRLF das skills, não o stub, e é o motivo de esta spec não reivindicá-los.
|
|
80
|
+
- **Restrição do Node**: spawn de `.bat`/`.cmd` sem `shell: true` lança `EINVAL` desde 18.20.2 / 20.12.2 / 21.7.3 (endurecimento da CVE-2024-27980). A matriz do CI roda Node 22 e 24: as duas células estão do lado endurecido, então não há versão suportada em que o código atual funcione no Windows.
|
|
81
|
+
- **Comando do check template é portável, o launcher não**: `"run": "node --test"` em `templates/evals/agents/teste-do-criterio.json:21` roda igual em `cmd.exe`; o que impede é o `sh` fixo na linha 254.
|
|
82
|
+
- **Convenção que já existe no repo**: `lib/project-wiring.ts:98` usa `where` no Windows e `which` no resto. Também por isso o caminho é um módulo só — não quatro remendos de plataforma espalhados pelos call sites.
|
|
83
|
+
- **Estado**: implementado em 2026-11-16 (PR #86, branch `fix/windows-inventory`). `lib/exec.ts` + `test/exec.test.js` (14 testes). CI Windows verde (run 43804567909). SPEC-056 AC-4 fechado.
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# Spec: v6-core-consolidation
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-058
|
|
4
|
+
- **Status**: draft
|
|
5
|
+
- **Owner**: allanpablo
|
|
6
|
+
- **Criado em**: 2026-11-05
|
|
7
|
+
- **Sprint alvo**: v6.0 Wave 2
|
|
8
|
+
- **ADRs relacionadas**: a criar em memory/90-decisions/
|
|
9
|
+
|
|
10
|
+
## 1. Problema
|
|
11
|
+
O núcleo do forja cresceu por acréscimo e hoje há múltiplas implementações para a mesma responsabilidade. Estado validado em 2026-11-05 (v5.2.0):
|
|
12
|
+
|
|
13
|
+
- **6 leitores independentes** do audit trail `.context/forja-runs.jsonl` (`lib/governance-report.ts`, `lib/status-model.ts`, `lib/audit.ts`, `scripts/memory-schema.ts`, `scripts/risk.ts`, `scripts/audit-sync.ts`) — cada um com seu parsing; um bug de formato precisa ser corrigido 6×.
|
|
14
|
+
- **`process.exit(1)` em 32 arquivos** e `cli-output.ts` adotado em apenas **8 de 54 scripts** — saída e códigos de erro inconsistentes entre comandos.
|
|
15
|
+
- **`audit()` silencia sem workspace**: `bin/forja.ts` tem `if (!info.exists) return;` — comandos rodados fora de projeto forja não geram trilha (por design atual, mas sem alternativa de log mínimo).
|
|
16
|
+
- **`any` em 360 pontos** do código do repo (341 `: any` + 19 `as any`; 0 em `packages/` e `apps/`) — fronteiras internas sem contrato de tipo.
|
|
17
|
+
- Dispatch de comandos via processos `node:` separados (99 dos 104 comandos do registry) — overhead de spawn por comando e estado não compartilhado.
|
|
18
|
+
- Gates declarados em apenas **39 dos 104 comandos**, sem middleware uniforme de execução.
|
|
19
|
+
- `apps/worker` dormente desde 2026-08-01; `specs/clean-arch-boilerplate` ainda "approved" sem implementação — ativos ambíguos no repo.
|
|
20
|
+
|
|
21
|
+
Quem sente: maintainer (cada mudança toca N pontos), agentes de IA (saída inconsistente), contribuidores (sem contrato claro).
|
|
22
|
+
|
|
23
|
+
## 2. Proposta de valor
|
|
24
|
+
Uma única implementação por responsabilidade no núcleo: módulo de auditoria único, camada de saída/erros uniforme, gates como middleware e dispatch in-process — mudanças de comportamento passam de "editar N arquivos" para "editar 1 módulo", com tipos contratuais nas fronteiras.
|
|
25
|
+
|
|
26
|
+
## 3. User stories
|
|
27
|
+
- **Como** maintainer, **quero** um único módulo `audit` que lê/grava o JSONL, **para que** formato e migrações mudem em um só lugar.
|
|
28
|
+
- **Como** agente de IA consumindo saída do forja, **quero** formato e códigos de saída uniformes em todos os comandos, **para que** eu possa parsear sem casos especiais por comando.
|
|
29
|
+
- **Como** contribuidor, **quero** gates executados por um middleware do registry, **para que** adicionar gate a um comando seja declarativo, não código novo.
|
|
30
|
+
- **Como** usuário, **quero** dispatch in-process dos comandos `node:`, **para que** cada comando tenha menos latência de spawn.
|
|
31
|
+
|
|
32
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
33
|
+
- [ ] AC-1: Módulo único de auditoria (`lib/audit-core.ts` ou equivalente) é a **única** implementação de leitura/escrita do JSONL; os 6 consumidores atuais o utilizam (grep confirma zero parsing direto remanescente).
|
|
34
|
+
- [ ] AC-2: Camada uniforme de saída/erros: `cli-output` (ou sucessor) adotado nos 54 scripts; `process.exit(1)` direto eliminado ou restrito ao entrypoint `bin/forja.ts`.
|
|
35
|
+
- [ ] AC-3: Gates executados por middleware do dispatch: comando declara gate no registry e o runner aplica (pré/pós), sem código de gate por script; os 39 gates atuais preservados com mesmo comportamento (testes).
|
|
36
|
+
- [ ] AC-4: Dispatch in-process para comandos `node:` com fallback a spawn quando o módulo exigir (documentado); latência média por comando medida antes/depois nas evidências.
|
|
37
|
+
- [ ] AC-5: Fronteiras dos módulos públicos tipadas: `any` reduzido em ≥ 50% da baseline (360 → ≤ 180), com teto do lint (SPEC-056) acompanhando a redução.
|
|
38
|
+
- [ ] AC-6: Destino de `apps/worker` e `specs/clean-arch-boilerplate` decidido e executado (arquivar com status explícito ou reativar) — zero ativos "aprovados/dormentes" sem decisão.
|
|
39
|
+
|
|
40
|
+
## 5. Escopo
|
|
41
|
+
**Dentro**:
|
|
42
|
+
- Consolidação de auditoria, saída/erros, gates middleware, dispatch.
|
|
43
|
+
- Tipagem das fronteiras (redução de `any`).
|
|
44
|
+
- Decisão sobre worker/specs stale.
|
|
45
|
+
|
|
46
|
+
**Fora**:
|
|
47
|
+
- Mudança do formato do JSONL de auditoria (compatibilidade com trilhas existentes é obrigatória; migração só se inevitável, com ADR).
|
|
48
|
+
- Consolidação de `packages/` do monorepo além do necessário para o dispatch (pode virar ADR própria).
|
|
49
|
+
- Reescrita de comandos `bin:` (4) — continuam via shell.
|
|
50
|
+
- Redução de `any` em código gerado por templates de projeto.
|
|
51
|
+
|
|
52
|
+
## 6. NFRs / restrições
|
|
53
|
+
- Compatibilidade: trilhas JSONL antigas continuam legíveis; `forja-runs.jsonl` sem breaking change de schema.
|
|
54
|
+
- Performance: dispatch in-process não pode aumentar p95 de comando simples; AC-4 mede.
|
|
55
|
+
- Segurança: auditoria continua imutável (append-only); nenhum caminho novo permite edição de trilha.
|
|
56
|
+
- Observabilidade: erros uniformes incluem código estável de erro por classe de falha.
|
|
57
|
+
|
|
58
|
+
## 7. Riscos e mitigação
|
|
59
|
+
| Risco | Probabilidade | Impacto | Mitigação |
|
|
60
|
+
|---|---|---|---|
|
|
61
|
+
| Refatorar 6 leitores + 54 scripts em um PR gigante | A | A | Fatiar: AC-1 primeiro (audit-core), depois AC-2, cada um com testes e merge próprio |
|
|
62
|
+
| Dispatch in-process vazar estado entre comandos | M | A | Isolamento por contexto explícito; fallback spawn; testes de concorrência |
|
|
63
|
+
| Redução de `any` introduzir regressões de runtime | M | M | Teto decrescente (SPEC-056) + suíte completa multi-OS antes de cada merge |
|
|
64
|
+
| Mudar gates quebrar `release:check`/`project:smoke` | B | A | Gates atuais com snapshot de comportamento antes da migração |
|
|
65
|
+
|
|
66
|
+
## 8. Métricas de sucesso
|
|
67
|
+
30 dias após: 1 implementação de auditoria (grep = 0 duplicatas); 100% dos scripts na camada de saída uniforme; `any` ≤ 180; latência média de comando ≤ valor pré-refatoração; zero issues de trilha de auditoria ilegível.
|
|
68
|
+
|
|
69
|
+
## Evidências e estado real
|
|
70
|
+
- Diagnóstico validado em 2026-11-05 contra v5.2.0: 6 leitores JSONL confirmados por grep; `process.exit(1)` em 32 arquivos; `cli-output` em 8/54 scripts; `any`=360 (0 em packages/apps); registry 104 comandos (99 node:, 4 bin:, 1 outro; 39 com gates); `audit()` skip sem workspace em `bin/forja.ts`; worker último commit 2026-08-01; spec clean-arch "approved".
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# Spec: v6-docs-drift
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-055
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: allanpablo
|
|
6
|
+
- **Criado em**: 2026-11-05
|
|
7
|
+
- **Sprint alvo**: v6.0 Wave 1
|
|
8
|
+
- **ADRs relacionadas**: a criar em memory/90-decisions/
|
|
9
|
+
|
|
10
|
+
## 1. Problema
|
|
11
|
+
A documentação (README.md, README.pt-BR.md, docs/) deriva do código e ninguém detecta a deriva até um usuário tropeçar nela. Estado validado em 2026-11-05 no repo (v5.2.0):
|
|
12
|
+
|
|
13
|
+
- `forja setup` não era mencionado em nenhum dos dois READMEs (0 ocorrências) — o onboarding não estava documentado.
|
|
14
|
+
- O registry tem 104 comandos; o README EN documentava **72** únicos e o pt-BR **42** — 32 comandos não apareciam em lugar nenhum (não havia referência completa).
|
|
15
|
+
- **12 comandos** não declaravam `usage` no registry, embora os READMEs documentassem suas flags (`agent:route --open/--mine`, `llm:run --profile`, `audit:query --failed` etc.) — a fonte única estava incompleta, e não o README errado.
|
|
16
|
+
- Drift de sintaxe de flags: registry declara `[-- --ai ...]` em `project:new`, `README.md:139` documenta `--ai` direto (as duas formas funcionam — o `--` é repassado e ignorado pelo gerador; o check passa a validar **existência** da flag, não o estilo do separador).
|
|
17
|
+
- `README.pt-BR.md` **não estava em `DOC_SURFACES`**: o scanner de "doc como dado" lia README.md/README.en.md e era cego para a superfície em português.
|
|
18
|
+
- Contagem de skills nos READMEs ("34") **estava correta**: `templates/project/skills/` tem 34 pastas + 1 README.md (35 entradas). A regra de contagem existe para impedir drift futuro, não para corrigir o atual.
|
|
19
|
+
|
|
20
|
+
Quem sente: novos usuários (onboarding quebrado), agentes de IA que leem o README como fonte de verdade, e o maintainer (correção manual tardia).
|
|
21
|
+
|
|
22
|
+
## 2. Proposta de valor
|
|
23
|
+
As regras de coerência doc × código vivem **no catálogo do doctor** (`lib/core/health.ts`), que já é gate no CI e na bateria `check:all` — deriva de documentação vira falha `critical` no PR, sem criar uma segunda máquina de ler markdown (princípio do repo: duas máquinas iguais divergem com o tempo; é exatamente o defeito que a SPEC-058 ataca). A referência completa de comandos (`docs/commands.md`) passa a ser **gerada** do registry por `forja docs:gen`, e o check `commands-ref` garante que ninguém a edita à mão.
|
|
24
|
+
|
|
25
|
+
## 3. User stories
|
|
26
|
+
- **Como** maintainer, **quero** que o doctor compare registry ↔ doc, **para que** nenhum comando novo seja publicado sem documentação.
|
|
27
|
+
- **Como** novo usuário, **quero** que o README documente o fluxo real de instalação e `forja setup`, **para que** eu consiga começar sem ler o código.
|
|
28
|
+
- **Como** agente de IA consumindo o README, **quero** números gerados do código (skills, comandos), **para que** o contexto injetado não contenha fato falso.
|
|
29
|
+
|
|
30
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
31
|
+
- [x] AC-1: `forja docs:gen` regenera `docs/commands.md` a partir do registry (idempotente) e `forja tools:doctor` sai 0 no estado corrigido do repo.
|
|
32
|
+
- [x] AC-2: O doctor detecta (a) comando `tier: 'core'` ausente de **qualquer um dos dois** READMEs (`core-in-readme`, critical), (b) comando documentado que não existe no registry (`docs-commands`, já existia), (c) flag documentada que o comando não declara em `usage`/`examples` (`docs-flags`, critical), (d) contagem de skills divergente de `templates/project/skills/` (`docs-skills-count`, warn), (e) `docs/commands.md` fora de sincronia com o registry (`commands-ref`, critical).
|
|
33
|
+
- [x] AC-3: README.md e README.pt-BR.md documentam instalação + `forja setup` + fluxo mínimo (workspace:init → project:new → spec:new → …).
|
|
34
|
+
- [x] AC-4: Drifts reais corrigidos — `forja setup` nos dois READMEs, `forja next`/orientação no pt-BR, `usage` declarado nas 15 entradas que não tinham, `demo:workspace --path`, `project:new --skip-backend` e `llm:run --context/--output-schema/--validation` declarados, `--verbose` (flag que nunca existiu) removido do quick-reference, e referência completa dos 105 comandos em `docs/commands.md` ligada na seção Documentação dos dois READMEs.
|
|
35
|
+
- [x] AC-5: Os checks rodam no CI (job `test`, passo "Doctor do núcleo", todas as células da matriz) **e** na bateria `check:all` pelo grupo de saúde do núcleo — `critical` que falha bloqueia (exit 1).
|
|
36
|
+
- [x] AC-6: `docs-flags` não produz falso positivo nas classes medidas no repo real: citação de comando sem prefixo `forja`/`npm run` (prosa), flag de binário de terceiro na mesma linha (`llm:run` → `claude -p`), clítico do português ("consultá-lo" ≠ `-lo`) e comando inexistente de superfície planejada (`docs/2x/*`).
|
|
37
|
+
|
|
38
|
+
## 5. Escopo
|
|
39
|
+
**Dentro**:
|
|
40
|
+
- `lib/core/doc-graph.ts`: `README.pt-BR.md` em `DOC_SURFACES`; `scanFlags`, `scanSkillCounts`, `flagTokens` (tokenizer único de flags).
|
|
41
|
+
- `lib/docs-reference.ts` (novo): o lado código da comparação — `declaredFlags`, `skillsCount`, `renderCommandsDoc`.
|
|
42
|
+
- `scripts/gen-commands-doc.ts` (novo) + entrada `docs:gen` no registry + script npm.
|
|
43
|
+
- 4 checks novos em `lib/core/health.ts` (`docs-flags`, `core-in-readme`, `docs-skills-count`, `commands-ref`), todos `scope: 'repo'`.
|
|
44
|
+
- `docs/commands.md` gerado do registry (referência completa, 105 comandos).
|
|
45
|
+
- `usage`/`examples` declarados nos comandos que não tinham (fonte única completa).
|
|
46
|
+
- Correção factual dos READMEs (setup, orientação, link da referência) e do `docs/quick-reference.md`.
|
|
47
|
+
- Testes em `test/health.test.js` (18 novos).
|
|
48
|
+
|
|
49
|
+
**Fora**:
|
|
50
|
+
- Gate paralelo próprio (`docs:check`, `lib/docs-check.ts`, `lib/core/docs-gate.ts`): construído na primeira passada e **removido** — dobrado no doctor.
|
|
51
|
+
- Reescrever prosa/marketing dos READMEs.
|
|
52
|
+
- Estilo do separador `--` (as duas formas funcionam; o check valida existência de flag).
|
|
53
|
+
- CHANGELOG (registro histórico — e nem está em `DOC_SURFACES`).
|
|
54
|
+
- `docs/2x/*`, `specs/`, `memory/` (superfície planejada e registro histórico).
|
|
55
|
+
- Documentação de projetos gerados (têm a sua).
|
|
56
|
+
|
|
57
|
+
## 6. NFRs / restrições
|
|
58
|
+
- Orçamento do hook SessionStart intacto: os 4 checks são `scope: 'repo'`, logo não rodam no `scope: 'runtime'` (5s, nenhuma tolerância a travar a sessão).
|
|
59
|
+
- Determinismo: `renderCommandsDoc` segue a ordem do registry (domínios por primeira aparição), sem depender de ordem de `readdir`; `skillsCount` recebe o diretório pronto, sem impor separador de caminho (portável entre SOs).
|
|
60
|
+
- Compatibilidade: não muda a saída de nenhum comando existente; `docs:gen` é aditivo.
|
|
61
|
+
|
|
62
|
+
## 7. Riscos e mitigação
|
|
63
|
+
| Risco | Probabilidade | Impacto | Mitigação |
|
|
64
|
+
|---|---|---|---|
|
|
65
|
+
| Check estrito bloqueia PR legítimo (comando experimental) | M | M | Comando que o registry não conhece é ignorado por `docs-flags`; flag citada em nome de outro comando da mesma linha absolve |
|
|
66
|
+
| Falsos positivos em parsing de markdown | M | M | Dono de flag é só invocação prefixada; as 4 classes medidas viraram teste (AC-6) |
|
|
67
|
+
| Duplicar a máquina de ler doc | M | A | Sem scanner próprio: leitura em `doc-graph.ts`, juízo em `health.ts`, tokenizer de flags um só (`flagTokens`) |
|
|
68
|
+
| Correção dos READMEs conflitar com PRs em andamento | B | B | Branch dedicada, merge rápido na Wave 1 |
|
|
69
|
+
|
|
70
|
+
## 8. Métricas de sucesso
|
|
71
|
+
30 dias após o release: zero issues de "comando não documentado"; `tools:doctor` verde em todos os PRs; README pt-BR com paridade de comandos documentados ≥ 95% do EN.
|
|
72
|
+
|
|
73
|
+
## Evidências e estado real
|
|
74
|
+
Medições de 2026-11-05, branch `feat/v6-wave1`:
|
|
75
|
+
|
|
76
|
+
- **Primeira passada no repo real: 35 divergências** — 3 de comando core fora do README (`setup` nos dois, `next` no pt-BR) e 32 de flag. A contagem de skills não disparou: os "34 skills" dos READMEs conferem com as 34 pastas reais (o 35 que circulava na análise contava o `README.md` do diretório).
|
|
77
|
+
- Investigação das 32 flags: **todas existem nos scripts** (`--mine/--open` em agent-router.ts, `--role` em agent.ts, `--title` em incident.ts, `--code` em code-context.ts, `--task` em build-smart-context.ts, `--profile/--scope/--id` em llm-fit.ts, `--publish` em release-check.ts, `--full` em gates.ts, `--failed/--cmd/--since` em audit-query.ts). O drift estava no **registry sem `usage`**, não na prosa → 15 entradas ganharam `usage`/`examples` (`agent:route`, `agent:register`, `agent:recommend`, `agent:score`, `agent:monitor`, `incident:record`, `code:context`, `context:smart` (estendido), `llm:recommend`, `llm:run`, `llm:eval`, `drift:check`, `release:check`, `check:all`, `audit:query`).
|
|
78
|
+
- **Drift real achado na segunda passada** (com a regra já dobrada no doctor): `demo:workspace --path` (`scripts/demo-workspace.ts:27`) e `project:new --skip-backend` (`scripts/agent-harness.ts:468`) existiam e não estavam no registry — corrigidos; `llm:run --context/--output-schema/--validation` existem em `scripts/llm-fit.ts:126` e não no `usage` — corrigido; `npm run project:new -- --verbose` em `docs/quick-reference.md:57` documentava flag que **não existe** em lugar nenhum — linha removida.
|
|
79
|
+
- **Falsos positivos eliminados** (todos viraram teste): (1) citação sem prefixo — "`llm:probe` executa `--version`" e "`llm:run --profile claude` → `claude -p …`" atribuíam flags de terceiros ao Forja → dono de flag passou a exigir `forja`/`npm run`; (2) flag de outro comando citado na linha — "(project:new --template)" dentro da célula de `project:templates` → o check absolve quando qualquer comando citado na linha declara a flag; (3) clítico português — "consultá-lo" casava como `-lo` → traço simples só casa com uma letra; (4) comando inexistente (`capabilities:list` de `docs/2x/*`) → ignorado, quem julga citação é `docs-commands`.
|
|
80
|
+
- **Estado final: `forja tools:doctor` com os 4 checks OK** (`docs-flags`, `core-in-readme`, `docs-skills-count` = 34 skills, `commands-ref` = 105 comandos).
|
|
81
|
+
- `docs/commands.md` gerado: **105 comandos** em 9 domínios, 34 skills, `|` escapado nas células, cabeçalho "Gerado por `forja docs:gen` … não edite à mão".
|
|
82
|
+
- Testes: `test/health.test.js` **72/72 verdes** (18 novos: 6 de `docs-flags`, 2 de `core-in-readme`, 2 de `docs-skills-count`, 3 de `commands-ref`, 1 de não-aplicação fora do repo do framework, 3 de `lib/docs-reference.ts`). Suíte completa: **615/615 verdes** (`npm test`, ~18s). O fs de fixture (`repoStub`) passou a honrar `readdirSync(p, { withFileTypes: true })`, como o `node:fs` real.
|
|
83
|
+
- `npm run types:check` (tsc --noEmit): **0 erros**.
|
|
84
|
+
- Wiring: `package.json` (`docs:gen`), registry (`docs:gen`, domínio governanca, `next: ['tools:doctor']`); CI inalterado — o passo "Doctor do núcleo" já existente no job `test` (matriz 22.x/24.x) é o que bloqueia.
|
|
85
|
+
- Limitação registrada: os checks leem a doc do **framework**; projetos gerados têm a sua própria documentação e não são cobertos aqui.
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
# Spec: v6-quality-gates
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-056
|
|
4
|
+
- **Status**: implementing
|
|
5
|
+
- **Owner**: allanpablo
|
|
6
|
+
- **Criado em**: 2026-11-05
|
|
7
|
+
- **Sprint alvo**: v6.0 Wave 1
|
|
8
|
+
- **ADRs relacionadas**: a criar em memory/90-decisions/
|
|
9
|
+
|
|
10
|
+
## 1. Problema
|
|
11
|
+
O forja vende gates de qualidade para os projetos que adota, mas não aplica todos a si mesmo. Estado validado em 2026-11-05 (`.github/workflows/ci.yml`, v5.2.0):
|
|
12
|
+
|
|
13
|
+
- CI roda **100% em ubuntu-latest** — o framework é usado em macOS e Windows (paths, `bin:` shells, cópia de skills), e regressões de plataforma só aparecem na máquina do usuário. O próprio `lib/paths.ts` documenta histórico de bug de raiz dupla (v1.6.1, v4.x, 18 scripts).
|
|
14
|
+
- **Sem lint do próprio repo e sem coverage** — `any` explícito aparece **359×** no código-fonte (medição da máquina desta spec, não grep de linha), `process.exit(1)` em 32 arquivos, e `cli-output.ts` é usado em apenas 8 de 54 scripts sem que nada sinalize a tendência.
|
|
15
|
+
- A suíte nunca foi rodada sob instrumentação de cobertura, e é justamente aí que um defeito real do contrato `--json` estava escondido (ver Evidências: stdout truncado em 64KB com exit 0).
|
|
16
|
+
|
|
17
|
+
Quem sente: mantenedor (regressões descobertas tarde), usuários Windows/macOS (bugs de plataforma), agentes de IA (saída inconsistente — e às vezes cortada — entre scripts).
|
|
18
|
+
|
|
19
|
+
## 2. Proposta de valor
|
|
20
|
+
CI que roda a suíte em matriz multi-OS e cobra, a cada push, dois ratchets versionados em `lib/core/quality-budget.json`: teto de `any` explícito (check `type-debt` no doctor) e piso de cobertura de linhas (`forja quality:coverage`, com a cobertura nativa do Node). Sem ESLint e sem c8 de propósito: adotar toolchain nova para medir o que uma regex e o `--experimental-test-coverage` já medem é importar uma segunda máquina — o defeito que a SPEC-058 ataca. Qualidade do próprio forja passa a ser medida a cada push, como ele exige dos projetos que adota.
|
|
21
|
+
|
|
22
|
+
## 3. User stories
|
|
23
|
+
- **Como** usuário Windows/macOS, **quero** que o CI rode nos três SOs, **para que** bugs de caminho/shell sejam pegos antes do release.
|
|
24
|
+
- **Como** maintainer, **quero** um teto de `any` e piso de coverage versionados, **para que** a dívida de tipos não cresça silenciosamente.
|
|
25
|
+
- **Como** contribuidor, **quero** feedback de lint no PR, **para que** eu corrija antes do review humano.
|
|
26
|
+
|
|
27
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
28
|
+
- [x] AC-1: Job `test` roda em matriz multi-OS (`ubuntu-latest` × Node 22/24, `macos-latest` e `windows-latest` × Node 24) com `fail-fast: false`; falha em qualquer célula bloqueia.
|
|
29
|
+
- [x] AC-2: Check `type-debt` no catálogo do doctor conta `any` explícito (`: any`, `as any`, `<any>`, `any[]`) em `bin/lib/scripts/apps` (`.ts`/`.tsx`, fora `.d.ts`, com template literals descartados) e compara com `anyCeiling` versionado em `lib/core/quality-budget.json`: acima do teto → `critical` fail; abaixo → `warn` mandando descer o teto. Sem ESLint.
|
|
30
|
+
- [x] AC-3: `forja quality:coverage` roda **a mesma suíte** com `--experimental-test-coverage`, lê a linha `all files` da tabela e cobra `coverageLineFloor` (exit 2 abaixo do piso, exit 1 se a suíte falhar, `--json` no contrato do ADR-0082). O CI usa esse passo na célula ubuntu **no lugar** de `npm test` — custo adicional zero.
|
|
31
|
+
- [x] AC-4: Testes que dependem de comportamento unix (permissões, `bin:` shells) têm skip condicional explícito e justificado, não falha silenciosa — a levantar pela primeira rodada verde/vermelha das células macOS/Windows. **Fechado (2026-11-16, PR #86)**: Windows 665/665 verdes (1 skip justificado: SIGTERM). `continue-on-error` removido do ci.yml — toda célula bloqueia o merge. Ver Evidências.
|
|
32
|
+
- [x] AC-5: Tempo total do CI não cresce por causa das réguas: a cobertura substitui o passo de teste no ubuntu (não soma), e as células novas rodam em paralelo.
|
|
33
|
+
- [x] AC-6: O stdout do contrato `--json` nunca sai truncado — `lib/cli-output.ts` escreve com `fs.writeSync` em laço antes do `process.exit()`, com teste de regressão de payload de 400KB (6× o buffer do pipe).
|
|
34
|
+
|
|
35
|
+
## 5. Escopo
|
|
36
|
+
**Dentro**:
|
|
37
|
+
- `.github/workflows/ci.yml`: matriz OS/Node do job `test`, passo de cobertura no ubuntu.
|
|
38
|
+
- `lib/core/quality-budget.json` (novo): `anyCeiling` + `coverageLineFloor` versionados.
|
|
39
|
+
- Check `type-debt` em `lib/core/health.ts` (`scope: 'repo'`, `critical`).
|
|
40
|
+
- `scripts/coverage-gate.ts` (novo) + entrada `quality:coverage` no registry + script npm `test:coverage`; a leitura da tabela e a decisão de código de saída em `lib/core/coverage-gate.ts`, para que o critério tenha teste sem rodar a suíte dentro da suíte.
|
|
41
|
+
- Correção do truncamento de stdout em `lib/cli-output.ts` (+ fixture e teste).
|
|
42
|
+
- Testes em `test/health.test.js` (6), `test/cli-output.test.js` (1), `test/coverage-gate.test.js` (10) e `test/ci-workflow.test.js` (7).
|
|
43
|
+
|
|
44
|
+
**Fora**:
|
|
45
|
+
- ESLint/`typescript-eslint` e c8/istanbul: nada de toolchain nova para medir o que o `tsc` e o runner nativo já medem.
|
|
46
|
+
- Refatorar os 359 `any` existentes (Wave 2/3 — aqui só o teto; SPEC-058).
|
|
47
|
+
- Substituir `process.exit(1)`/consolidar `cli-output` nos 54 scripts (SPEC-058).
|
|
48
|
+
- Codecov/serviço externo — a tabela do Node já vai para o log do CI.
|
|
49
|
+
- `release-gate`, `project-smoke-ai`, `project-smoke-full`: continuam ubuntu (o custo deles é compilar better-sqlite3, e replicar isso em três SOs não prova mais).
|
|
50
|
+
|
|
51
|
+
## 6. NFRs / restrições
|
|
52
|
+
- Performance: matriz em paralelo com cache de npm por SO; `quality:coverage` custa o mesmo que `npm test` (é a mesma suíte).
|
|
53
|
+
- Custo: minutos de Actions dentro do free tier para repo público (4 células no job `test`, antes 2).
|
|
54
|
+
- Compatibilidade: não muda `release:check`, `tools:doctor`, `project:smoke` existentes; `type-debt` é `scope: 'repo'`, logo não toca o orçamento de 5s do hook SessionStart.
|
|
55
|
+
- Portabilidade: o contador de `any` emite caminho relativo com `/` (independente do SO), e a suíte já depende só do runner do Node — `npm test` funciona no Windows porque o Node expande o glob `test/*.test.js` sem shell (verificado localmente).
|
|
56
|
+
|
|
57
|
+
## 7. Riscos e mitigação
|
|
58
|
+
| Risco | Probabilidade | Impacto | Mitigação |
|
|
59
|
+
|---|---|---|---|
|
|
60
|
+
| Testes falharem só em Windows/macOS por paths/shell | M | A | **Realizado na primeira rodada**: macOS limpo, 23 falhas no Windows — 3 causas de produto consertadas (paths POSIX, CRLF, limpeza de temp) e o resto em inventário não-bloqueante. Ver Evidências. |
|
|
61
|
+
| Ratchet de `any` bloquear PR legítimo | M | B | Teto = contagem atual (359); só impede crescimento, e subir o teto exige commit próprio justificado |
|
|
62
|
+
| Piso de cobertura oscilar entre SOs e dar falso vermelho | M | B | A régua roda só no ubuntu; piso 87 contra 87,45 medido dá folga, e branch/function não bloqueiam. **Realizado, mas por outro caminho**: a oscilação veio do próprio Node (blocos de processos-filho no agregado) — ver Evidências; piso re-ancorado em medição determinística. |
|
|
63
|
+
| CI mais lento desestimular contribuição | B | B | Células em paralelo + cache; AC-5 mede |
|
|
64
|
+
|
|
65
|
+
## 8. Métricas de sucesso
|
|
66
|
+
30 dias após: zero releases com regressão exclusiva de Windows/macOS; `any` ≤ 357 e caindo; cobertura de linhas ≥ 90% em todo PR, com o número se repetindo igual entre execuções; nenhum `--json` truncado.
|
|
67
|
+
|
|
68
|
+
## Evidências e estado real
|
|
69
|
+
Medições de 2026-11-05, branch `feat/v6-wave1`:
|
|
70
|
+
|
|
71
|
+
- **Diagnóstico**: leitura direta de `ci.yml` (5 jobs, todos `ubuntu-latest`) e contagem medida pela própria máquina nova — **359 `any` explícitos** (o grep ingênuo de linhas dava 301 e o de ocorrências 388; a diferença são template literals de geradores de boilerplate, `.d.ts` e `node_modules`, que o check descarta). Maiores arquivos listados no detail do check.
|
|
72
|
+
- **Cobertura baseline**: `node --test --experimental-test-coverage` → `all files | 86.40 | 74.18 | 77.85` na primeira medição (com 1 teste falho) e **87.45% de linhas** após o reparo abaixo → piso fixado em **87**.
|
|
73
|
+
- **A régua media ruído (achado da Wave 1, 2026-11-05)**: a suíte inteira, dois commits depois, dava `85,71 / 86,09 / 86,50 / 86,96 / 87,33` em execuções *idênticas*, e o gate ficava vermelho ou verde conforme a sorte. Causa raiz, isolada por pares de execução: com `--experimental-test-coverage` o runner expõe `NODE_V8_COVERAGE` e **todo CLI filho herda** — dezenas de processos escrevem blocos parciais dos mesmos arquivos no diretório de agregação, e o agregador do Node não faz união. Reprodução mínima: `packages/adapter-nest/src/index.ts` apareceu **100,00%** numa execução e **51,09%** na seguinte, com branches (70,30) e funções (63,16) idênticos, e o conjunto de arquivos da tabela mudando entre execuções. Um número que muda sem que nada mude não é uma régua: `test/isolate-workspace.mjs` passou a retirar `NODE_V8_COVERAGE` do ambiente (o processo de teste continua medindo a si mesmo; os filhos param de contaminar a agregação), a medição ficou **bit a bit reproduzível** (`91,80 | 79,8x | 87,99` em duas execuções seguidas, exit 0 nas duas) e o piso subiu de 87 para **90** — folga de 1,8pp para a variação entre SOs/Node que só a CI vai medir. `--test-concurrency=1` não muda nada: a instabilidade não é de agendamento.
|
|
74
|
+
- **Bug real achado pela instrumentação** (e não pela suíte normal): `contrato: spec:trace --json` falhava **só sob cobertura** com `SyntaxError: Unterminated string in JSON at position 64695`. Causa raiz reproduzida fora do teste — `process.stdout.write(json)` seguido de `process.exit()` trunca no buffer do pipe: payload de 400KB saía com **65536 bytes e exit 0**. Ou seja: qualquer comando `json:true` com resposta grande devolvia JSON cortado para o agente que o consumia, sem sinal de erro. Reparo: escrita síncrona no fd 1 em laço (`lib/cli-output.ts`), regressão coberta por `test/cli-output.test.js` + fixture `big`. Sob cobertura, a suíte voltou a 100%.
|
|
75
|
+
- **Estado final**: `forja quality:coverage` → `OK cobertura de linhas 87.45% (piso 87%) · branches 74.28% · funções 77.92%`, exit 0. `forja tools:doctor` → `OK type-debt 359 any explícitos, no teto (359)`. `npm run types:check` → 0 erros. `test/health.test.js` + `test/cli-output.test.js` → **82/82 verdes**.
|
|
76
|
+
- **AC-4 levantado pela primeira rodada das células (2026-11-06, PR #83)**: `macos-latest` passou **665/665** — a aposta de que o macOS era a plataforma de risco não se sustentou; quem trouxe defeito foi o `windows-latest`, com **23 falhas em 665**. Era exatamente o que a célula existia para caçar: nenhuma delas aparecia em ubuntu.
|
|
77
|
+
- **Consertado na hora (causa no produto, não no teste)**:
|
|
78
|
+
1. *Separador de caminho no pack* — `lib/code-context.ts` e `lib/context-builder.ts` emitiam `path.relative()` cru, então o mesmo domínio produzía `backend\src\...` no Windows e `backend/src/...` no resto. O pacote é texto colado no contexto de um agente: agora é POSIX nos dois (`relFrom()`; `**Path**` do `context:smart` normalizado na renderização). Derrubava `code-context.test.js:123`, `:232` e o contrato do `modo task`.
|
|
79
|
+
2. *CRLF no frontmatter das skills* — `skillProblem()` exigia `\n` literal (`lib/project-wiring.ts:59`); no checkout Windows toda a validação de skills virava ruído ("frontmatter sem name/description" em 34/34), e o que isso puxava era o `project:new`/`project:wire` falhando — ou seja, a jornada inteira do usuário gerava projeto quebrado só por causa do separador de linha. Aceita `\r?\n`, com regressão que força o CRLF.
|
|
80
|
+
3. *`rmSync` do diretório temp* — EPERM transitório no Windows com SQLite recém-fechado; a limpeza do `test/memory-index.test.js` ganhou retry.
|
|
81
|
+
- **Rodada 2 (23 → 14), rodada 3 (14 → 11, com 1 skip justificado) e rodada 4 (11 → 10)**. As causas 1-3 caíram como previsto; a 4 não caiu na primeira tentativa e caiu na segunda; e a célula passou a medir 666 com 1 skipped. As restantes se agruparam em quatro causas — três delas defeito de produto, não de teste:
|
|
82
|
+
4. *Forma do caminho do nó* — em Windows o mesmo arquivo era indexado com outra identidade: `memory/00-global/mission.md` em vez de `projects/demo/memory/00-global/mission.md`. Dois atalhos unix-cêntricos no sync, isolados por inferência e confirmados pela forma do sintoma: `path.relative()` entre **unidades diferentes** devolve caminho absoluto (e o teste de "está fora" era `startsWith('..')`, que deixa o absoluto passar), e o `os.tmpdir()` do runner chega como nome **8.3** (`RUNNER~1`) enquanto o walk devolve a forma longa. A chave do nó alimenta busca, dedupe e o classificador de tipo — não era detalhe de exibição. Primeira tentativa (só `realpathSync` dos dois lados) não bastou; o que fecha é seleção por **contenção** (`inside()` com `path.isAbsolute`), com a forma canônica como segundo passo. Em unix o caminho direto vence, então nada mudou localmente — e a rodada 4 é o que prova: o contrato do `modo task` e o `sync:universal` passaram, e o `code:context` já tinha passado na rodada 2. **Regra que ficou do jeito errado da tentativa**: `startsWith('..')` não é teste de contenção; o repo já fazia certo em `lib/workspace.ts:263`, `lib/session-memory.ts:43` e `scripts/build-smart-context.ts:52` (`!rel || startsWith('..') || isAbsolute`). O sync era o único lugar com a versão incompleta — o `inside()` novo segue a convenção que já existia, não uma regra inventada aqui.
|
|
83
|
+
5. *CRLF na régua de derivação de doc* — `commands-ref` comparava `docs/commands.md` byte a byte com o renderizado; em checkout CRLF isso é "diverge" falso, e o `tools:doctor` do repo ficava vermelho sem nada estar velho. A comparação normaliza `\r\n`. **Regra geral que ficou**: o framework valida texto de *projeto do usuário*, que chega em CRLF seja lá o que a gente fizer no nosso repo — tolerar é o certo, `.gitattributes` não resolve o mundo.
|
|
84
|
+
6. *Handle vazado no próprio teste* — o `antes` do teste de sync incremental abria uma conexão `readonly` e nunca fechava. Em unix é inocente; em Windows tranca o `.db` até o processo do runner acabar, e o `rmSync` do temp volta EPERM **para sempre** (a retry de 10×100ms da rodada 1 só provou que não era transitório). Fecha na leitura.
|
|
85
|
+
7. *Sinal POSIX* — `test/server-shutdown.test.js` manda SIGTERM num filho: o sinal não existe em Windows e o probe usa `--import tsx`, opção de runtime que a célula não resolve. Este é o **skip explícito e justificado** que o AC-4 pedia, não um conserto; o contrato continua provado nas células unix. Está marcado como skipped na rodada 3, não como aprovado.
|
|
86
|
+
- **Inventário fechado (2026-11-16, PR #86, branch `fix/windows-inventory`)** — 3 causas, 10 casos → 0:
|
|
87
|
+
- *Runtime de agentes é unix por construção* (6 casos na rodada 4: `test/llm-resume-validation.test.js:142` com `spawn EFTYPE`; `test/agent-evals.test.js:85` e os AC-4/AC-5/AC-6 com `agent.args` nunca escrito; `test/llm-claude-adapter.test.js:99`; `test/llm-integration.test.js:111` — e os 2 casos do AC-1, que eram desta mesma família e ficaram verdes na rodada 2, o que confirma que a causa deles era o CRLF das skills e não o stub). Os testes modelam o CLI do agente como script com shebang, e é assim que ele falha — mas a causa é do produto, em três lugares lidos no código, não chutados do log:
|
|
88
|
+
- `scripts/llm-fit.ts:76,84,91,104,108` sondam o binário com **`shell: false`** explícito. Em Windows o shim que `npm i -g` instala é `codex.cmd`/`claude.cmd`, e Node recusa spawnar `.cmd` sem `shell: true` (endurecimento da CVE-2024-27980). O `llm:probe` não tem como reportar features de um agente instalado nesse SO.
|
|
89
|
+
- `lib/agent-evals.ts:254` executa o check `type: 'command'` com **`spawnSync('sh', ['-c', …])`** — sem `sh`, o check inteiro é inaplicável.
|
|
90
|
+
- `lib/agent-evals.ts:177,183` spawnam o binário direto, mesma restrição do probe.
|
|
91
|
+
Não é para pular: é portabilidade do `llm:run`/`llm:probe`/`eval:agents`, e merece spec própria — redigida em 2026-11-08 como **SPEC-059 (`specs/v6-agent-runtime-portable`, Wave 2)**: caminho resolvido por `where`/`PATHEXT`, `sh -c` trocado por launcher de shell portável, e o kill do timeout derrubando a árvore.
|
|
92
|
+
- *`git worktree`*: os 3 de `test/simulate-cli.test.js` (o `worktree list` antes/depois não fecha igual).
|
|
93
|
+
- *`spec:trace` sem critérios no projeto gerado*: único resto da `jornada` nas quatro rodadas, que já ficou verde em `project:new`, `project:wire`, `context:smart` e `tools:doctor` — as causas 1/2/5 eram a jornada. O que a rodada 4 permite **eliminar**: não é a família do separador de caminho (`loadSpecs` lê o slug por `readdirSync`, e `listFiles` usa `git ls-files`, que fala POSIX por protocolo), não é CRLF na leitura do checklist (`AC_LINE` termina em `(.+)$`, que engole o `\r`), e não é a contagem de *tokens por critério* (AC-7 da SPEC-053) — `0/0` vem de `trace.totals`, antes de qualquer preço. O que fica de hipótese, sem prova: `specs/` vazio ou `readdirSync` lançando no `root` resolvido pela CLI em Windows (a função devolve `[]` nesse caso, e `0/0` é exatamente o que isso produz). Precisa de uma célula com diagnostico impresso, não de mais um patch adivinhado.
|
|
94
|
+
- **Regra de saída cumprida (2026-11-16)**: `continue-on-error` removido do `ci.yml`. Toda célula bloqueia o merge. O gate de que o inventário zerou está fechado.
|
|
95
|
+
- **Rastreabilidade fechada (2026-11-09)**: `spec:trace v6-quality-gates` marcava **1/6** critérios com teste, embora AC-1/2/3/5/6 estivessem implementados e dois deles já tivessem teste real. Duas causas diferentes, tratadas de forma diferente:
|
|
96
|
+
- *Faltava a citação, não o teste* (AC-2, AC-6): os 6 testes do ratchet `type-debt` em `test/health.test.js` e o payload de 400KB em `test/cli-output.test.js` já provavam o critério — só não escreviam `SPEC-056 AC-n`, que é o que o trace lê. Marcados. Nenhum teste novo: inventar um segundo teste para o mesmo comportamento inflaria a métrica sem aumentar a garantia.
|
|
97
|
+
- *Faltava teste mesmo* (AC-3): a régua vivia inteira dentro de `scripts/coverage-gate.ts`, cujo caminho de execução é spawnar a suíte — testá-lo de ponta a ponta seria rodar a suíte dentro da suíte. A leitura da linha `all files`, a leitura do piso e a tabela de decisão saíram para `lib/core/coverage-gate.ts`, e o script virou coleta + emissão. `test/coverage-gate.test.js` (10) prova o que o script não podia provar: **suíte verde com tabela ausente é exit 1, nunca OK** (o formato do Node já mudou uma vez), processo morto por sinal não sai 0, e no piso exato passa — é ratchet, não folga.
|
|
98
|
+
- *Propriedade de arquivo que nenhuma suíte executa* (AC-1, AC-5): `test/ci-workflow.test.js` (7) lê o `ci.yml` como texto — sem parser YAML, pela mesma razão do §2: não importar uma segunda máquina para medir o que já se mede. Prova as 4 células efetivas (ubuntu×22/24, macos×24, windows×24), o `fail-fast: false`, e que `continue-on-error` aparece **uma vez**, condicionado a `windows-latest`, com a regra de saída ao lado. Do lado do AC-5, prova que os dois passos de teste têm `if:` complementares e que cada um aparece uma única vez — nenhuma célula roda a suíte duas vezes.
|
|
99
|
+
- **Medido depois**: `spec:trace v6-quality-gates` → **6/6**. AC-4 já era rastreado (o skip justificado do SIGTERM e o CRLF das skills) e continua com o checkbox aberto porque o inventário acima não zerou — teste não fecha inventário de produto. `npm test` → **683/683**, 0 skipped (666 + 17 novos). `forja quality:coverage` → `OK cobertura de linhas 91.84% (piso 90%) · branches 79.91% · funções 88.03%`, exit 0 — 0,04pp acima do estado anterior, com a régua agora coberta pelos próprios testes. `forja tools:doctor` → `OK type-debt 357 any explícitos, no teto (357)`: nenhum `any` novo. `npm run types:check` → 0 erros.
|
|
100
|
+
- **AC-4 fechado (2026-11-16, PR #86)**: as 3 causas restantes do inventário zeraram em 6 commits na branch `fix/windows-inventory`:
|
|
101
|
+
- *Runtime de agentes* (6 casos): `lib/exec.ts` novo (SPEC-059) — `resolveCommand` com `where`/PATHEXT preferindo `.cmd/.exe`, `spawnAgent` com quoting cmd.exe `/d /s /c` + aspas externas, `killTree` com `taskkill /T /F`, `runShell` portável. Fixtures Windows usam `command: process.execPath, commandArgs: [script.mjs]` (node direto, sem stdin via cmd.exe). Doctor prepende `commandArgs`. `buildLlmExecution` põe `commandArgs` antes do subcomando `exec`.
|
|
102
|
+
- *git worktree* (3 casos): `resolveCommand` prefere extensão executável (npm.cmd sobre script sh sem extensão); `sandboxEnvironment` ganha APPDATA/LOCALAPPDATA/COMSPEC/PATHEXT; `realpathSync` nos mkdtemp; cleanup com retry.
|
|
103
|
+
- *spec:trace 0/0* (1 caso): CRLF no `parseCriteria` (`split(/\r?\n/)`).
|
|
104
|
+
- **CI run 43804567909**: `test (windows-latest, 24.x)` → **success**. `continue-on-error` removido. `npm test` local → **1006/1006**, 1 skipped (SIGTERM). `npm run types:check` → 0 erros.
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
# Spec: v6-token-economy
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-057
|
|
4
|
+
- **Status**: implementing — Wave 1 entregue e medida (AC-1..AC-5); Wave 3 (tokenizer real, memória híbrida, skills lazy) segue aberta
|
|
5
|
+
- **Owner**: allanpablo
|
|
6
|
+
- **Criado em**: 2026-11-05
|
|
7
|
+
- **Sprint alvo**: v6.0 Wave 1 (snippets + sync incremental); Wave 3 (tokenizer real, memória híbrida)
|
|
8
|
+
- **ADRs relacionadas**: a criar em memory/90-decisions/
|
|
9
|
+
|
|
10
|
+
## 1. Problema
|
|
11
|
+
O forja injeta mais contexto do que o necessário em cada comando, e o custo é pago pelo usuário em tokens. Estado validado em 2026-11-05 (v5.2.0):
|
|
12
|
+
|
|
13
|
+
- `lib/context-builder.ts:199` injeta `node.content` **inteiro** para cada nó de memória relevante, apesar de o SQLite ser FTS5 (que tem `snippet()` nativo para retornar apenas o trecho casado).
|
|
14
|
+
- `lib/code-context.ts:100-120`: `--code` lê **todos os arquivos do módulo por completo**, sem filtro por relevância nem cache.
|
|
15
|
+
- Skills são copiadas fisicamente em **2 destinos por projeto** (`.claude/skills` + `.agents/skills`, `lib/project-wiring.ts:41-47` e loop :235-249): 34 pastas / 276KB duplicados por agente suportado.
|
|
16
|
+
- Estimativa de tokens = `bytes/4` em `context-builder.ts:223` e `scripts/token-economy.ts:18/:127/:143` — sem tokenizer real, o relatório de economia mede aproximado.
|
|
17
|
+
- Sync de memória reprocessa conteúdo sem `content_hash` incremental (re-trabalho a cada sync).
|
|
18
|
+
|
|
19
|
+
Quem sente: todo usuário que roda `forja` com agentes de IA — contexto inflado = custo maior e janela útil menor.
|
|
20
|
+
|
|
21
|
+
## 2. Proposta de valor
|
|
22
|
+
Reduzir os tokens injetados por comando sem perder sinal: snippet FTS5 no lugar de conteúdo integral, sync incremental por hash, e medição honesta com tokenizer real — meta Wave 1: ≥ 50% de redução no payload de memória injetado nos comandos `context`/`code:context`, medida por um cenário de referência determinístico (`forja token:benchmark`), não pelo `token-economy` (que mede outro eixo).
|
|
23
|
+
|
|
24
|
+
## 3. User stories
|
|
25
|
+
- **Como** usuário pagando tokens, **quero** que só o trecho relevante da memória seja injetado, **para que** cada comando custe menos e caiba mais contexto útil na janela.
|
|
26
|
+
- **Como** agente de IA, **quero** que `--code` traga só arquivos/trechos pertinentes à tarefa, **para que** eu não desperdice janela com módulo inteiro.
|
|
27
|
+
- **Como** maintainer, **quero** sync incremental por `content_hash`, **para que** re-sync de projeto grande não reprocessa tudo.
|
|
28
|
+
- **Como** maintainer, **quero** que `token-economy` use tokenizer real, **para que** a métrica de economia seja confiável.
|
|
29
|
+
|
|
30
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
31
|
+
- [x] AC-1: `context-builder.ts` usa `snippet(fts, col, marker, marker, radius)` para nós de memória; conteúdo integral só quando o nó for curto (< limite configurável, default ~400 tokens) ou marcado como sempre-integral.
|
|
32
|
+
- [x] AC-2: Redução ≥ 50% no total de tokens injetados em cenário de referência (projeto com ≥ 50 nós de memória), medido por máquina de evidência própria, registrada nas evidências.
|
|
33
|
+
- [x] AC-3: Sync de memória grava `content_hash` por nó e pula reprocessamento quando inalterado; re-sync de projeto inalterado custa ~0 reprocessamentos (log mostra skipped).
|
|
34
|
+
- [x] AC-4: `code-context` limita leitura por relevância (ordem FTS/grep interno) com flag `--full` como opt-in para comportamento atual.
|
|
35
|
+
- [x] AC-5: Nenhum teste existente quebra; saída dos comandos continua parseável pelos consumidores atuais (contrato de formato preservado).
|
|
36
|
+
|
|
37
|
+
## 5. Escopo
|
|
38
|
+
**Dentro**:
|
|
39
|
+
- `lib/context-builder.ts` (snippet FTS5 + política de integral).
|
|
40
|
+
- `lib/code-context.ts` (seleção por relevância + `--full`).
|
|
41
|
+
- Sync de memória (`scripts/memory-*`): `content_hash` incremental.
|
|
42
|
+
- `scripts/token-economy.ts`: medição antes/depois para evidência.
|
|
43
|
+
- `scripts/token-benchmark.ts`: cenário de referência determinístico (fixture própria, 60 nós) — é dele que sai o número do AC-2, porque medir "economia" num projeto inexistente produz número sem medição.
|
|
44
|
+
|
|
45
|
+
**Fora**:
|
|
46
|
+
- Tokenizer real (tiktoken) — Wave 3; bytes/4 continua, documentado como limitação.
|
|
47
|
+
- Embeddings/memória híbrida (sqlite-vec) — Wave 3.
|
|
48
|
+
- Skills lazy por trigger — Wave 3 (SPEC de skills, se houver).
|
|
49
|
+
- Mudança do schema FTS5 além do necessário para snippet.
|
|
50
|
+
|
|
51
|
+
## 6. NFRs / restrições
|
|
52
|
+
- Performance: `context` não pode ficar mais lento que hoje (snippet é mais barato que SELECT content inteiro).
|
|
53
|
+
- Compatibilidade: projetos com memória antiga continuam funcionando (migração de `content_hash` lazy no primeiro sync).
|
|
54
|
+
- Determinismo: snippets estáveis para o mesmo par query/nó (sem ordem aleatória).
|
|
55
|
+
|
|
56
|
+
## 7. Riscos e mitigação
|
|
57
|
+
| Risco | Probabilidade | Impacto | Mitigação |
|
|
58
|
+
|---|---|---|---|
|
|
59
|
+
| Snippet cortar informação essencial do nó | M | A | Política de integral para nós curtos/críticos + flag `--full-context`; AC-2 mede só payload, testes cobrem qualidade |
|
|
60
|
+
| `content_hash` invalidar cache errado (falso skip) | B | A | Hash do conteúdo normalizado + teste de mutação (muda 1 char → reprocessa) |
|
|
61
|
+
| `--code` por relevância omitir arquivo necessário | M | M | `--full` opt-in documentado; ranking por path+módulo antes de cortar |
|
|
62
|
+
|
|
63
|
+
## 8. Métricas de sucesso
|
|
64
|
+
30 dias após: redução ≥ 50% nos tokens de memória por comando `context` em projetos reais; tempo de re-sync de projeto inalterado < 10% do sync cheio; zero issues de "contexto cortou informação".
|
|
65
|
+
|
|
66
|
+
## Evidências e estado real
|
|
67
|
+
Medições de 2026-11-05, branch `feat/v6-wave1`, sobre v5.2.0.
|
|
68
|
+
|
|
69
|
+
- **Diagnóstico validado**: leitura direta de `context-builder.ts` (conteúdo integral por nó), `code-context.ts` (fatia inteira, sem relevância), `project-wiring.ts:41-47/:235-249` (skills em 2 destinos), `token-economy.ts` (bytes/4), e a contagem de skills (34 pastas = 276KB).
|
|
70
|
+
- **AC-1 (trecho, não inteiro)**: `snippet(search_idx, 2, '**', '**', ' … ', 24)` no caminho FTS e janela calculada (`excerptAround`) no caminho `LIKE`, com política de integral abaixo de `FULL_CONTENT_MAX_CHARS` (1600 chars ≈ 400 tokens, configurável por `FORJA_CONTEXT_FULL_MAX_CHARS`) e `mission.md`/`standards.md` sempre inteiros — o corte da constituição do pack orienta pior que o silêncio. Todo corte é visível: rodapé `- **Excerpts**: N/M nodes` e a linha `⋯ X chars omitidos — leia o arquivo acima ou rode com --full-context`.
|
|
71
|
+
- **AC-2 (meta ≥ 50%)**: a evidência não vem do `token-economy` (que mede outro eixo) mas de uma máquina própria e determinística, `referenceScenario()` em `scripts/token-benchmark.ts`, com 60 nós de texto fixo num workspace descartável. Medido: **−80%** no termo que casa pelo FTS (`pagamentos`), **−81%** no termo que só o `LIKE` casa (`pagament`), **−29%** no termo composto em que os globais sempre-integral dominam o pacote, **0%** no termo sem casamento (controle: sem casamento não há o que cortar, e a máquina diz isso em vez de inventar). Veredito impresso: `Meta AC-2 (≥ 50% no termo que casa): −80% → ✅`.
|
|
72
|
+
- **Defeito achado ao medir (o pior tipo)**: `forja token:benchmark` media um projeto chamado `benchmark-project`, que não existe em lugar nenhum — `domain`/`task` voltavam só com os globais e o relatório anunciava **~99,6% de economia** de um pacote vazio, com ar de número. Agora o projeto de referência sai do banco (o que tem mais nós), o termo sai dos caminhos indexados (`30-domains/<x>/`, senão slug de spec), cada modo imprime `Nodes:`, e se `domain`/`task` não trouxerem um nó a mais que `global` o relatório cospe `⚠️ nenhum nó do projeto além dos globais — economia vazia, não conte este número` e sai cedo em vez de tabular vento.
|
|
73
|
+
- **AC-3 (sync incremental)**: `content_hash` por nó + `project_id`; nó inalterado é pulado antes de qualquer trabalho e o sync fecha com `N indexados · M inalterados (pulados) · K falhas`. O pulo é por hash, não por mtime — provado no teste que mexe o mtime e ainda assim pula.
|
|
74
|
+
- **Segundo defeito achado pelo caminho**: `memory-fresh`, o check que existe para avisar que o índice está velho, comparava o mtime do `.db` com o de `memory/`. Com WAL ativo, um sync pequeno escreve no `-wal` e **não toca no mtime do banco** — o check dizia "índice em dia" para índice velho, exatamente o caso que deveria pegar. Reparo duplo: o sync grava `sync_meta(last_sync)` e faz `wal_checkpoint(TRUNCATE)`, e o check lê o timestamp registrado (mtime só como fallback para banco de versão anterior). Testado nos dois lados.
|
|
75
|
+
- **AC-4 (código por relevância)**: `byRelevance` (termo no caminho > termo no conteúdo, depois camada `domain → application → infrastructure → presentation`, depois caminho para o desempate ser sempre o mesmo) + `withinBudget` de `CODE_TOKEN_BUDGET = 6000` tokens, com `codeOmitted` no pacote e no rodapé do comando — nunca corte calado. `--full` repõe a fatia inteira, e é o que `token:economy` usa explicitamente para não passar a medir outra coisa.
|
|
76
|
+
- **AC-5 (contrato)**: formatos antigos seguem válidos — os testes de regressão do pack checam `**Path**: \`…\`` e os consumidores de `docs/commands.md` não mudaram de forma. Um segundo ponto de entrada morto (CLI module-level em `lib/context-builder.ts`, com usage apontando para um `scripts/context-builder.mjs` que não existe) foi removido; o caminho vivo é `forja context:smart`.
|
|
77
|
+
- **AC-5 no Windows (rodada de CI de 2026-11-06)**: dois níveis. (a) *Renderização*: `code:context` e `context:smart` agora escrevem caminho com `/` (`relFrom()`; `**Path**` normalizado), porque um pacote colado no contexto de um agente não pode mudar de letra conforme a máquina. Provado na rodada 2 (os dois testes desta wave que falhavam passaram). (b) *Identidade do nó*: o caminho **gravado** no banco ainda saía com outra forma no Windows — `path.relative()` entre unidades diferentes devolve caminho absoluto, e o atalho `startsWith('..')` lia isso como "está dentro". Corrigido por contenção (`inside()` + forma canônica nos dois lados em `scripts/sync-universal-memory.ts`); em unix o caminho direto continua vencendo, então nada muda aqui (666/666). A confirmação é a célula Windows, onde o contrato do `modo task` ainda estava vermelho.
|
|
78
|
+
- **Limitação assumida**: tokens = bytes/4 em todo o framework (Wave 3 traz tokenizer real). Os percentuais acima são da mesma régua usada antes, então a *comparação* é válida mesmo que o valor absoluto não seja.
|
|
79
|
+
- **Cobertura (gate da SPEC-056 no caminho desta wave)**: `forja quality:coverage` reprovava em 86,1–86,9% contra o piso 87 — e o número mudava entre execuções idênticas. Isolado: a variação vinha dos CLIs filhos escrevendo cobertura no mesmo agregador do Node (não desta wave). Com a medição consertada em `test/isolate-workspace.mjs`, o estado aqui é **`OK 91,80% (piso subido para 90)`**, exit 0, reproduzido duas vezes com o mesmo valor, 662/662 verdes.
|
|
80
|
+
- **Terceiro ponto de entrada morto removido**: o bloco CLI de módulo em `lib/context-builder.ts` (usage apontando para um `scripts/context-builder.mjs` que nunca existiu) — dois caminhos para o mesmo comando é o que gera documentação que mente.
|
|
81
|
+
- **Defeito achado no smoke do AC-4 (e que a suíte não via)**: `forja code:context <domínio> --full` **não chegava ao script**. Comandos roteados como capability não recebem o argv do usuário: o roteador o parseia contra `params` declarados e reconstrói — flag não declarada é descartada em silêncio. `--full`, o `[termo]` e `--project` estavam fora dos params de `code.context`, então o help prometia três flags mortas. Corrigido nos params, e o teste novo em `test/cli-params.test.js` agora atravessa o `usage` de todo comando-capability e reprova qualquer `--flag` anunciada que não esteja declarada — a mesma varredura pegou dois drifts pré-existentes (`orchestrate:status`/`advance` prometiam `--slug` para um script que lê `argv[0]`; usage corrigido para `<slug>`).
|
|
82
|
+
- **Estado final da wave**: `npm test` → 666/666 verdes; `npm run types:check` → 0 erros; `forja quality:coverage` → `OK 91,80% (piso 90%)`; `forja tools:doctor` → ressalva só de `handoff-orphans` (35, pré-existente) e da ferramenta opcional `codegraph`.
|
|
83
|
+
- AC-2 será evidenciado com números antes/depois do `token-economy` na mesma base de referência.
|
|
84
|
+
- **Rastreabilidade fechada (2026-11-09)**: `spec:trace v6-token-economy` marcava **3/5**. AC-1 e AC-5 já tinham teste real — a política de trecho nas unidades puras e no pack FTS5/`LIKE` (`test/context-builder.test.js`), e o `**Path**: \`…\`` preservado com separador POSIX — mas nenhum dos dois citava o critério, que é o que o trace lê. Marcados, sem teste novo. Estado medido: **5/5** e suíte **683/683** com 0 skipped, o que transforma o AC-5 ("nenhum teste existente quebra") de afirmação em número.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
{
|
|
2
|
+
"id": "adr",
|
|
3
|
+
"title": "Decisão vira ADR no lugar certo",
|
|
4
|
+
"prompt": "Decidimos usar PostgreSQL como banco principal deste produto: precisamos de transações e de colunas JSONB, e o time já opera Postgres. Registre essa decisão no projeto. Não escreva código.",
|
|
5
|
+
"checks": [
|
|
6
|
+
{
|
|
7
|
+
"type": "file",
|
|
8
|
+
"desc": "ADR novo em memory/90-decisions/ com Postgres, Contexto e Decisão",
|
|
9
|
+
"glob": "memory/90-decisions/*.md",
|
|
10
|
+
"contains": [
|
|
11
|
+
"postgres",
|
|
12
|
+
"^#+ *Contexto",
|
|
13
|
+
"^#+ *Decis[aã]o"
|
|
14
|
+
],
|
|
15
|
+
"exclude": [
|
|
16
|
+
"memory/90-decisions/_template.md"
|
|
17
|
+
]
|
|
18
|
+
},
|
|
19
|
+
{
|
|
20
|
+
"type": "unchanged",
|
|
21
|
+
"desc": "não mexeu no template de ADR",
|
|
22
|
+
"glob": "memory/90-decisions/_template.md"
|
|
23
|
+
}
|
|
24
|
+
]
|
|
25
|
+
}
|