forjajs 5.1.0 → 5.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +76 -0
- package/README.md +37 -4
- package/README.pt-BR.md +39 -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 +349 -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/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-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/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/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 +99 -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,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,99 @@
|
|
|
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
|
+
- [ ] 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. **Levantado (2026-11-06)**: macOS 665/665; Windows 23 → 14 → 11 → 10 em quatro rodadas, com 7 causas de produto/robustez fechadas no caminho e o *skip justificado* escrito para o caso SIGTERM. Restam 3 causas no inventário — uma delas (runtime de agentes) é lacuna de produto, não teste. 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 aberto (a célula está `continue-on-error` só por isto)** — 3 causas, 10 casos na rodada 4:
|
|
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**: tirar `continue-on-error` da matriz é o gate de que o inventário zerou. A linha existe no `ci.yml` com esta frase ao lado, para não virar mobília.
|
|
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.
|
|
@@ -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
|
+
}
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
{
|
|
2
|
+
"id": "memoria",
|
|
3
|
+
"title": "Resposta vem da memória do projeto",
|
|
4
|
+
"prompt": "Um cliente perguntou em quantos dias úteis vence um boleto no nosso produto. Qual é a regra e em que arquivo do projeto ela está registrada? Não altere nada.",
|
|
5
|
+
"seed": {
|
|
6
|
+
"files": {
|
|
7
|
+
"memory/30-domains/cobranca/context.md": "# Cobrança — contexto\n\n## Regras\n\n- Boleto vence em **3 dias úteis** a partir da emissão.\n- Pix expira em 30 minutos.\n- Cartão é capturado na hora.\n"
|
|
8
|
+
}
|
|
9
|
+
},
|
|
10
|
+
"checks": [
|
|
11
|
+
{
|
|
12
|
+
"type": "answer",
|
|
13
|
+
"desc": "responde 3 dias úteis",
|
|
14
|
+
"matches": [
|
|
15
|
+
"\\b3\\b|\\btr[eê]s\\b",
|
|
16
|
+
"[uú]teis"
|
|
17
|
+
]
|
|
18
|
+
},
|
|
19
|
+
{
|
|
20
|
+
"type": "answer",
|
|
21
|
+
"desc": "cita o arquivo de memória",
|
|
22
|
+
"matches": [
|
|
23
|
+
"memory/30-domains/cobranca"
|
|
24
|
+
]
|
|
25
|
+
},
|
|
26
|
+
{
|
|
27
|
+
"type": "unchanged",
|
|
28
|
+
"desc": "não alterou a memória",
|
|
29
|
+
"glob": "memory/**"
|
|
30
|
+
}
|
|
31
|
+
]
|
|
32
|
+
}
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
{
|
|
2
|
+
"id": "proxima-acao",
|
|
3
|
+
"title": "Próxima ação vem do forja",
|
|
4
|
+
"prompt": "Acabei de voltar de férias. O que devo fazer agora neste projeto? Seja breve e não altere nada.",
|
|
5
|
+
"seed": {
|
|
6
|
+
"files": {
|
|
7
|
+
"specs/exportar-relatorios/spec.md": "# Spec: exportar-relatorios\n\n- **ID**: SPEC-001\n- **Status**: approved\n- **Owner**: time\n- **Criado em**: 2026-10-01\n\n## 1. Problema\nClientes copiam a tabela de relatórios à mão para a planilha.\n\n## 4. Critérios de aceite (Definition of Done)\n- [ ] AC-1: o relatório mensal pode ser baixado em CSV.\n"
|
|
8
|
+
}
|
|
9
|
+
},
|
|
10
|
+
"checks": [
|
|
11
|
+
{
|
|
12
|
+
"type": "ran",
|
|
13
|
+
"desc": "consultou forja next ou status",
|
|
14
|
+
"matches": "forja\\s+(next|status)|mcp__forja__(next|status)"
|
|
15
|
+
},
|
|
16
|
+
{
|
|
17
|
+
"type": "answer",
|
|
18
|
+
"desc": "recomenda o plano da spec aprovada",
|
|
19
|
+
"matches": [
|
|
20
|
+
"spec:plan|plan\\.md|plano"
|
|
21
|
+
]
|
|
22
|
+
},
|
|
23
|
+
{
|
|
24
|
+
"type": "unchanged",
|
|
25
|
+
"desc": "não alterou specs",
|
|
26
|
+
"glob": "specs/**"
|
|
27
|
+
}
|
|
28
|
+
]
|
|
29
|
+
}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
{
|
|
2
|
+
"id": "spec-nova",
|
|
3
|
+
"title": "Feature nova começa por spec, pelo spec:new",
|
|
4
|
+
"prompt": "Queremos que o cliente consiga exportar o extrato da conta em PDF. Comece essa feature do jeito que este projeto pede. Não escreva código ainda.",
|
|
5
|
+
"checks": [
|
|
6
|
+
{
|
|
7
|
+
"type": "ran",
|
|
8
|
+
"desc": "criou a spec com forja spec:new",
|
|
9
|
+
"matches": "forja\\s+spec:new|mcp__forja__spec_new"
|
|
10
|
+
},
|
|
11
|
+
{
|
|
12
|
+
"type": "file",
|
|
13
|
+
"desc": "spec com ID e critério de aceite preenchido",
|
|
14
|
+
"glob": "specs/*/spec.md",
|
|
15
|
+
"contains": [
|
|
16
|
+
"\\*\\*ID\\*\\*: *SPEC-\\d+",
|
|
17
|
+
"^- \\[ \\] \\**AC-1\\b[^:\\n]*: *[^<\\s]"
|
|
18
|
+
]
|
|
19
|
+
},
|
|
20
|
+
{
|
|
21
|
+
"type": "unchanged",
|
|
22
|
+
"desc": "não escreveu código",
|
|
23
|
+
"glob": "src/**"
|
|
24
|
+
}
|
|
25
|
+
]
|
|
26
|
+
}
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
{
|
|
2
|
+
"id": "teste-do-criterio",
|
|
3
|
+
"title": "Teste cita o critério que prova",
|
|
4
|
+
"prompt": "Escreva o teste automatizado que prova o critério AC-1 da spec de pagamentos. Use o executor de testes nativo do Node (node --test). Não altere o código de produção.",
|
|
5
|
+
"seed": {
|
|
6
|
+
"files": {
|
|
7
|
+
"specs/pagamentos/spec.md": "# Spec: pagamentos\n\n- **ID**: SPEC-001\n- **Status**: approved\n- **Owner**: time\n- **Criado em**: 2026-10-01\n\n## 1. Problema\nPagamentos com valor zero ou negativo chegam ao gateway e são recusados lá, tarde demais.\n\n## 4. Critérios de aceite (Definition of Done)\n- [ ] AC-1: `validarValor` rejeita valor zero ou negativo com erro \"valor inválido\".\n- [ ] AC-2: `validarValor` devolve o valor quando ele é positivo.\n",
|
|
8
|
+
"src/pagamentos.js": "export function validarValor(valor) {\n if (!(valor > 0)) throw new Error('valor inválido');\n return valor;\n}\n"
|
|
9
|
+
}
|
|
10
|
+
},
|
|
11
|
+
"checks": [
|
|
12
|
+
{
|
|
13
|
+
"type": "criterion",
|
|
14
|
+
"desc": "um teste cita SPEC-001 AC-1 (spec:trace)",
|
|
15
|
+
"spec": "pagamentos",
|
|
16
|
+
"ac": "AC-1"
|
|
17
|
+
},
|
|
18
|
+
{
|
|
19
|
+
"type": "command",
|
|
20
|
+
"desc": "os testes passam",
|
|
21
|
+
"run": "node --test"
|
|
22
|
+
},
|
|
23
|
+
{
|
|
24
|
+
"type": "unchanged",
|
|
25
|
+
"desc": "não mexeu no código de produção",
|
|
26
|
+
"glob": "src/pagamentos.js"
|
|
27
|
+
}
|
|
28
|
+
]
|
|
29
|
+
}
|
|
@@ -33,6 +33,7 @@ forja spec:set-status <slug> spec approved # depois da revisão
|
|
|
33
33
|
forja spec:plan <slug> # plan.md (exige spec aprovada)
|
|
34
34
|
forja spec:tasks <slug> # tasks.md
|
|
35
35
|
forja spec:check <slug> # gate de completude
|
|
36
|
+
forja spec:trace <slug> # critérios AC-N × testes que os citam
|
|
36
37
|
forja orchestrate "<objetivo>" --slug <slug> # corrida guardada por gates
|
|
37
38
|
forja orchestrate:advance # roda o gate da etapa aberta
|
|
38
39
|
```
|
|
@@ -45,8 +46,13 @@ forja code:impact <símbolo> # quem chama e o que quebra
|
|
|
45
46
|
forja project:check # documentação de fundação
|
|
46
47
|
forja tools:doctor # saúde do Forja e das ferramentas
|
|
47
48
|
forja project:wire --check # IA, hooks e MCP conectados a este projeto
|
|
49
|
+
forja spec:trace <slug> --strict # todo critério da spec tem teste (exit 2 se não)
|
|
48
50
|
```
|
|
49
51
|
|
|
52
|
+
Teste que prova um critério cita a spec e o critério no nome ou num comentário: `SPEC-NNN AC-N`
|
|
53
|
+
(ex.: `test('SPEC-004 AC-2: estorno parcial', …)`). É o que o `spec:trace` lê.
|
|
54
|
+
Fixture com citações de exemplo fica entre comentários `spec-trace:off` e `spec-trace:on`.
|
|
55
|
+
|
|
50
56
|
## Onde fica cada coisa
|
|
51
57
|
|
|
52
58
|
```
|
|
@@ -56,6 +62,7 @@ memory/20-architecture/ design técnico
|
|
|
56
62
|
memory/30-domains/ regras por domínio
|
|
57
63
|
memory/40-delivery/ roadmap, sprint, backlog
|
|
58
64
|
memory/50-orchestration/ topologia e handoffs
|
|
65
|
+
memory/60-runs/sessions/ checkpoint de cada sessão do Claude Code (gerado pelos hooks; não edite)
|
|
59
66
|
memory/70-summaries/ resumos compactos (prefira a arquivos brutos)
|
|
60
67
|
memory/90-decisions/ ADRs
|
|
61
68
|
specs/<slug>/ spec → plan → tasks
|
|
@@ -3,7 +3,8 @@
|
|
|
3
3
|
## Claude Code neste projeto
|
|
4
4
|
|
|
5
5
|
- Os hooks em `.claude/settings.json` abrem cada sessão com o estado do projeto (`forja hook:session-start`)
|
|
6
|
-
e anexam a spec citada no prompt (`forja hook:user-prompt`)
|
|
7
|
-
`forja
|
|
6
|
+
e anexam a spec citada no prompt (`forja hook:user-prompt`); ao fim de cada turno e antes de compactar,
|
|
7
|
+
`forja hook:session-memory` grava o checkpoint da sessão em `memory/60-runs/sessions/`. Se o
|
|
8
|
+
briefing não aparecer, rode `forja project:wire --check`.
|
|
8
9
|
- O servidor MCP `forja` (`.mcp.json`) expõe as capacidades do Forja como ferramentas.
|
|
9
10
|
- Sub-agents de cada papel ficam em `.claude/agents/`. Delegue a eles quando a tarefa cruzar papéis.
|
|
@@ -95,7 +95,7 @@ Feche com **Pendentes**: regras que dependem de suposições não confirmadas e
|
|
|
95
95
|
|
|
96
96
|
## No Forja
|
|
97
97
|
|
|
98
|
-
No Forja, os critérios de aceite estão em `specs/<slug>/spec.md` (§4, `AC-n`). Nomeie os casos citando o `AC-
|
|
98
|
+
No Forja, os critérios de aceite estão em `specs/<slug>/spec.md` (§4, `AC-n`). Nomeie os casos citando a spec e o critério que cobrem, `SPEC-NNN AC-N` (ex.: `test('SPEC-004 AC-2: estorno parcial', …)`), e confira com `forja spec:trace <slug>`: critérios sem teste e citações a critérios que não existem mais aparecem ali. Registre a evidência na seção "Evidências e estado real" da spec.
|
|
99
99
|
|
|
100
100
|
## Evite
|
|
101
101
|
|