forjajs 1.3.2 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/AGENTS.md +5 -0
  2. package/CHANGELOG.md +74 -0
  3. package/README.en.md +1 -0
  4. package/README.md +11 -4
  5. package/boilerplates/06-clean-arch/WHEN-CLEAN-WHEN-LEAN.md +37 -8
  6. package/dist/lib/agent-topology.d.ts +38 -0
  7. package/dist/lib/agent-topology.js +65 -0
  8. package/dist/lib/code-context.d.ts +41 -0
  9. package/dist/lib/code-context.js +108 -0
  10. package/dist/lib/core/doc-graph.d.ts +13 -0
  11. package/dist/lib/core/doc-graph.js +47 -0
  12. package/dist/lib/core/gates.d.ts +36 -0
  13. package/dist/lib/core/gates.js +35 -0
  14. package/dist/lib/core/health.js +64 -1
  15. package/dist/lib/core/project-smoke.d.ts +46 -0
  16. package/dist/lib/core/project-smoke.js +248 -0
  17. package/dist/lib/core/registry.d.ts +30 -0
  18. package/dist/lib/core/registry.js +30 -0
  19. package/dist/lib/core/release.d.ts +30 -0
  20. package/dist/lib/generators/memory-generator.d.ts +1 -0
  21. package/dist/lib/generators/memory-generator.js +44 -0
  22. package/dist/lib/generators/readme-generator.js +1 -0
  23. package/dist/lib/memory-audit.d.ts +31 -0
  24. package/dist/lib/memory-audit.js +81 -0
  25. package/dist/lib/project-upgrade.d.ts +28 -0
  26. package/dist/lib/project-upgrade.js +74 -0
  27. package/dist/scripts/agent-router.js +1 -1
  28. package/dist/scripts/code-context.d.ts +12 -0
  29. package/dist/scripts/code-context.js +73 -0
  30. package/dist/scripts/gates.d.ts +10 -0
  31. package/dist/scripts/gates.js +44 -0
  32. package/dist/scripts/memory-audit.d.ts +11 -0
  33. package/dist/scripts/memory-audit.js +49 -0
  34. package/dist/scripts/project-smoke.d.ts +14 -0
  35. package/dist/scripts/project-smoke.js +44 -0
  36. package/dist/scripts/project-upgrade.d.ts +11 -0
  37. package/dist/scripts/project-upgrade.js +61 -0
  38. package/dist/scripts/token-economy.d.ts +20 -0
  39. package/dist/scripts/token-economy.js +140 -0
  40. package/memory/90-decisions/0025-coerencia-da-documentacao.md +10 -0
  41. package/memory/90-decisions/0026-migracao-typescript-runtime-duplo.md +66 -0
  42. package/memory/90-decisions/0027-clean-arch-calibrada.md +34 -3
  43. package/memory/90-decisions/0029-gate-do-projeto-gerado.md +59 -0
  44. package/memory/90-decisions/0030-projeto-gerado-herda-os-gates.md +53 -0
  45. package/package.json +1 -1
  46. package/specs/code-context/spec.md +56 -0
  47. package/specs/gates/spec.md +63 -0
  48. package/specs/memory-audit/spec.md +54 -0
  49. package/specs/orchestration-coherent/spec.md +95 -0
  50. package/specs/project-smoke/spec.md +96 -0
  51. package/specs/project-upgrade/spec.md +58 -0
@@ -0,0 +1,140 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * token-economy — mede, não argumenta (fecha a dívida do ADR-0027; ADR-0009 e ADR-0003).
4
+ *
5
+ * Dois eixos, porque a economia de token do Forja tem dois eixos e eles são diferentes:
6
+ *
7
+ * 1. ARQUITETURA (clean vs flat) — camadas custam tokens. Numa feature pequena, o flat é mais
8
+ * barato. É honesto, e desmente a versão ingênua de "Clean Architecture economiza tokens".
9
+ *
10
+ * 2. MEMÓRIA (frio vs quente) — o `context.md` é o mapa. Sem ele, um agente varre o código da
11
+ * fatia para localizar a regra; com ele, vai direto ao agregado. AQUI está a economia real do
12
+ * framework (ADR-0009), e ela COMPÕE: paga-se o scaffold uma vez, e o mapa economiza a cada
13
+ * tarefa futura pela vida do projeto.
14
+ *
15
+ * O `token:economy` sozinho não captura o custo de gerar do zero (isso é custo líquido, único). Ele
16
+ * captura o regime permanente — o projeto já levantado, onde a memória persistente paga de volta.
17
+ *
18
+ * Token ≈ bytes/4 (o mesmo proxy do resto do framework). Não é preciso; é reproduzível e honesto.
19
+ */
20
+ import fs from 'node:fs';
21
+ import path from 'node:path';
22
+ import { fileURLToPath } from 'node:url';
23
+ import { domainsOf, buildContextPack } from "../lib/code-context.js";
24
+ const __filename = fileURLToPath(import.meta.url);
25
+ const root = path.resolve(path.dirname(__filename), '..');
26
+ /**
27
+ * Modo `--project <path>`: mede o eixo memória nos domínios REAIS do usuário, não na fixture. Para
28
+ * cada domínio, o mapa (`context.md`) vs ler todo o código da fatia — o número fica dele.
29
+ */
30
+ function projectMode(projectRoot) {
31
+ const domains = domainsOf(projectRoot);
32
+ console.log(`\nToken economy — eixo memória nos domínios de ${projectRoot} (ADR-0009)\n`);
33
+ if (!domains.length) {
34
+ console.log(`Nenhum domínio em ${path.join(projectRoot, 'memory/30-domains')}. Rode dentro de um projeto gerado.`);
35
+ return;
36
+ }
37
+ console.log('Para cada domínio: ler o mapa (context.md) vs ler todo o código da fatia.\n');
38
+ const rows = [];
39
+ for (const domain of domains) {
40
+ const pack = buildContextPack({ projectRoot, domain, includeCode: true });
41
+ const economy = pack.codeTokens === 0 ? '—' : `−${Math.round(((pack.codeTokens - pack.mapTokens) / pack.codeTokens) * 100)}%`;
42
+ rows.push({ domínio: domain, mapa_tok: pack.mapTokens, código_tok: pack.codeTokens, mapa_vs_código: economy });
43
+ console.log(`■ ${domain}`);
44
+ console.log(` mapa (context.md): ${String(pack.mapTokens).padStart(5)} tok`);
45
+ console.log(` código da fatia: ${String(pack.codeTokens).padStart(5)} tok (${pack.code.length} arq.)`);
46
+ console.log(` o mapa custa ${economy} do código — é o resumo que substitui a leitura da árvore\n`);
47
+ }
48
+ console.log('O mapa é o resumo do domínio: lê-lo custa uma fração de ler a fatia inteira. Essa é a');
49
+ console.log('economia da memória, medida no SEU projeto. (Sem mapa? rode `forja memory:audit`.)\n');
50
+ if (process.argv.includes('--json'))
51
+ console.log(JSON.stringify(rows, null, 2));
52
+ }
53
+ const CLEAN = 'boilerplates/06-clean-arch/backend/src/modules/orders';
54
+ const CLEAN_CTX = 'boilerplates/06-clean-arch/memory/30-domains/orders/context.md';
55
+ const SHARED = 'boilerplates/06-clean-arch/backend/src/shared/result.ts';
56
+ const FLAT = 'benchmarks/clean-vs-flat/orders-flat';
57
+ /** Todo o código da fatia Orders (clean) — o que se varre "no frio", sem mapa. */
58
+ const CLEAN_CODE = [
59
+ `${CLEAN}/domain/order.entity.ts`,
60
+ `${CLEAN}/domain/order-status.vo.ts`,
61
+ `${CLEAN}/domain/money.vo.ts`,
62
+ `${CLEAN}/domain/order.repository.ts`,
63
+ `${CLEAN}/application/place-order.usecase.ts`,
64
+ `${CLEAN}/application/ship-order.usecase.ts`,
65
+ `${CLEAN}/infrastructure/order.orm-entity.ts`,
66
+ `${CLEAN}/infrastructure/typeorm-order.repository.ts`,
67
+ `${CLEAN}/presentation/orders.controller.ts`,
68
+ `${CLEAN}/presentation/orders.http.dto.ts`,
69
+ `${CLEAN}/orders.module.ts`,
70
+ SHARED,
71
+ ];
72
+ const SCENARIOS = [
73
+ {
74
+ axis: 'arquitetura',
75
+ name: 'entender a feature inteira',
76
+ question: 'ler todo o código da fatia para entender o que ela faz',
77
+ a: { label: 'clean', files: CLEAN_CODE },
78
+ b: {
79
+ label: 'flat',
80
+ files: [`${FLAT}/order.entity.ts`, `${FLAT}/orders.service.ts`, `${FLAT}/orders.controller.ts`],
81
+ },
82
+ },
83
+ {
84
+ axis: 'arquitetura',
85
+ name: 'mudar a regra de envio',
86
+ question: 'alterar a invariante "não envia sem pagamento" — o contexto mínimo suficiente',
87
+ a: { label: 'clean', files: [CLEAN_CTX, `${CLEAN}/domain/order.entity.ts`, `${CLEAN}/domain/order-status.vo.ts`] },
88
+ b: { label: 'flat', files: [`${FLAT}/orders.service.ts`] },
89
+ },
90
+ {
91
+ axis: 'memória',
92
+ name: 'trabalhar no domínio — com vs sem o mapa da memória',
93
+ question: 'localizar e mexer na regra numa fatia já existente (ADR-0009) — o regime permanente',
94
+ // Quente: a memória (context.md) aponta o agregado + a máquina de estados. Vai direto.
95
+ a: { label: 'quente (memória)', files: [CLEAN_CTX, `${CLEAN}/domain/order.entity.ts`, `${CLEAN}/domain/order-status.vo.ts`] },
96
+ // Frio: sem mapa, varre o código da fatia para descobrir onde a regra vive.
97
+ b: { label: 'frio (sem memória)', files: CLEAN_CODE },
98
+ },
99
+ ];
100
+ const tokensOf = (rel) => {
101
+ try {
102
+ return Math.round(fs.readFileSync(path.join(root, rel), 'utf8').length / 4);
103
+ }
104
+ catch {
105
+ return 0;
106
+ }
107
+ };
108
+ const sum = (files) => files.reduce((acc, f) => acc + tokensOf(f), 0);
109
+ const pct = (a, b) => (b === 0 ? '—' : `${a <= b ? '−' : '+'}${Math.abs(Math.round(((a - b) / b) * 100))}%`);
110
+ // `--project <path>`: mede o eixo memória no projeto real e sai. Sem ele, o benchmark de fixture.
111
+ const projIdx = process.argv.indexOf('--project');
112
+ if (projIdx >= 0) {
113
+ projectMode(path.resolve(process.argv[projIdx + 1] || process.cwd()));
114
+ process.exit(0);
115
+ }
116
+ console.log('\nToken economy — o custo do CONTEXTO por cenário (ADR-0027, ADR-0009)\n');
117
+ console.log('Token ≈ bytes/4. Não mede o custo de gerar do zero (custo único); mede o regime permanente.\n');
118
+ const out = [];
119
+ for (const s of SCENARIOS) {
120
+ const a = sum(s.a.files);
121
+ const b = sum(s.b.files);
122
+ out.push({ eixo: s.axis, cenário: s.name, [s.a.label]: a, [s.b.label]: b, a_vs_b: pct(a, b) });
123
+ console.log(`■ [${s.axis}] ${s.name}`);
124
+ console.log(` ${s.question}`);
125
+ console.log(` ${s.a.label.padEnd(18)} ${String(a).padStart(5)} tok (${s.a.files.length} arq.)`);
126
+ console.log(` ${s.b.label.padEnd(18)} ${String(b).padStart(5)} tok (${s.b.files.length} arq.)`);
127
+ console.log(` ${s.a.label} vs ${s.b.label}: ${pct(a, b)}\n`);
128
+ }
129
+ const arch = out[1]; // mudar a regra, clean vs flat
130
+ const mem = out[2]; // frio vs quente
131
+ console.log('Veredito (derivado dos números):');
132
+ console.log(` • EIXO ARQUITETURA: numa feature pequena, camadas custam MAIS token (${arch.a_vs_b} para`);
133
+ console.log(` a mudança isolada). "Clean Architecture economiza tokens" não se sustenta nessa escala —`);
134
+ console.log(` a justificativa das camadas é isolamento e testabilidade, não token.`);
135
+ console.log(` • EIXO MEMÓRIA: o mapa (context.md) faz o contexto mínimo custar ${mem.a_vs_b} vs varrer`);
136
+ console.log(` a fatia no frio. É AQUI que a economia mora — e ela COMPÕE: o scaffold é custo único,`);
137
+ console.log(` o mapa economiza a cada tarefa futura. Depois do projeto levantado, a memória paga de volta.\n`);
138
+ if (process.argv.includes('--json')) {
139
+ console.log(JSON.stringify(out, null, 2));
140
+ }
@@ -33,6 +33,16 @@ Três checks novos no catálogo de `health.mjs` (`scope: repo`), sobre um scanne
33
33
  instrução existe no registry. Comando fantasma faz o agente agir errado — trava.
34
34
  - **`commands-documented`** (warn): todo comando do registry é mencionado em ao menos um `.md`.
35
35
  - **`docs-links`** (warn): todo link markdown relativo entre arquivos versionados resolve.
36
+ - **`adr-refs`** (warn, adicionado depois): toda citação `ADR-NNNN` em doc/spec/ADR aponta para um
37
+ ADR que existe. Fecha o último invariante que vivia por disciplina ("toda decisão vira ADR") pelo
38
+ lado verificável: referência a decisão inexistente é trilha que apodrece. Pegou o `ADR-0026`
39
+ pendurado (citado pela SPEC-012, nunca escrito) na primeira execução.
40
+ - **`agent-topology`** (warn, SPEC-019): a topologia de orquestração é descrita em três fontes
41
+ (`VALID_AGENTS` do router, `.claude/agents/*.md`, `AGENTS.md`) e pode divergir em silêncio — o
42
+ namesake do framework (orquestração multiagente) vivendo por disciplina. O check cruza as três:
43
+ sub-agent sem rota, papel roteável sem executor, agente não documentado. `user`/`worker` são
44
+ endpoints isentos. Pegou o `release-auditor` (executável, sem rota) na primeira execução. Mesma
45
+ classe dos checks acima, aplicada a quem-orquestra-quem.
36
46
 
37
47
  Princípios:
38
48
 
@@ -0,0 +1,66 @@
1
+ # ADR-0026: Migração TypeScript com runtime duplo (fonte `.ts`, publicado `dist/`)
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-07-19
5
+ - **Autor(es)**: apk
6
+ - **Tags**: typescript, build, runtime, sdd
7
+
8
+ ## Contexto
9
+
10
+ A SPEC-012 migrou o framework de `.mjs`/checkJs para TypeScript de verdade. Dois requisitos em
11
+ tensão organizaram todas as decisões:
12
+
13
+ - **NFR inegociável**: o dev roda `sem build`. `node bin/forja.ts <cmd>` tem que funcionar direto,
14
+ ou o loop de desenvolvimento morre.
15
+ - **`engines.node >= 20`**: o pacote publicado precisa rodar em Node 20/21, que **não** executam
16
+ `.ts` (strip-types nativo só existe a partir do Node 22.6).
17
+
18
+ Essas duas verdades não cabem no mesmo artefato: no instante em que a fonte vira `.ts`, um pacote
19
+ publicado sem compilar quebra para quem está em Node 20.
20
+
21
+ ## Decisão
22
+
23
+ **Runtime duplo, resolvido por um único ponto.**
24
+
25
+ 1. **D1 — Layout plano, `dist/` espelha a árvore.** `tsc rootDir=. outDir=dist` → `dist/bin`,
26
+ `dist/lib`, `dist/scripts`. Não movemos a fonte para `src/`: trocaria todo import, path de
27
+ registry e hook — blast radius enorme, contra o "verde contínuo".
28
+ 2. **D2 — Registry + `resolveScript` (o coração).** O registry nomeia os scripts; o `resolveScript`
29
+ tenta as extensões na ordem `['.ts', '.js', '.mjs']`, fazendo strip da extensão declarada. Em dev
30
+ acha o `.ts`; no publicado acha o `dist/*.js`. Um resolver, dois mundos — sem dois registries
31
+ (a divergência que a SPEC-009 matou).
32
+ 3. **D3 — Dual runtime.** Dev roda `.ts` nativo (Node ≥22.6, exigência de contribuir); o publicado
33
+ embarca `dist/*.js` (Node ≥20). O acoplamento de Node-floor vive só na fronteira do publicado.
34
+ 4. **D4 (revisado) — o gate constrói o `dist/`.** O `release:check` roda `npm run build` **antes de
35
+ empacotar** (quando `files[]` inclui `dist/`). Como `npm publish` empacota o disco e o gate
36
+ empacota o mesmo disco recém-buildado, o tarball provado é o publicado — sem `dist/` no git, sem
37
+ step de build no `ci.yml`, sem janela de staleness. O gate é self-contained.
38
+ 5. **D9 — publicar `dist/` desde sempre desacopla o risco.** Enquanto a fonte ainda era `.mjs`, o
39
+ build era uma cópia; quando virou `.ts`, virou compilação. Em ambos os casos o publicado é JS
40
+ runnable, então o `.ts`-não-roda-em-Node-20 nunca morde o usuário final.
41
+
42
+ ## Alternativas consideradas
43
+
44
+ - **Guardar `.js` compilado no git e exigir build em dev** — rejeitada: mata o NFR "roda sem build".
45
+ - **Publicar a fonte `.ts` crua** — rejeitada: quebra em Node 20/21; o `release:check` reprovaria.
46
+ - **Dois registries (dev/publicado)** — rejeitada: duas verdades que divergem (defeito da SPEC-009).
47
+ - **Mover a fonte para `src/`** — rejeitada: blast radius desproporcional para ganho estético.
48
+
49
+ ## Consequências
50
+
51
+ **Positivas**:
52
+ - Dev roda `.ts` nativo, zero build; usuário final roda `dist/*.js`, Node ≥20. Cada um paga só o seu.
53
+ - Uma máquina (`resolveScript`) resolve os dois mundos; o gate prova o tarball real.
54
+ - `noImplicitAny` ligado ao fim: o ratchet força todo código futuro a ser tipado.
55
+
56
+ **Negativas / Trade-offs**:
57
+ - Contribuir passa a exigir Node ≥22.6; o job `test` do CI cai fora do Node 20 (o suporte a 20 do
58
+ publicado é provado pelo `release-gate`, que instala o tarball `.js`).
59
+ - O `resolveScript` carrega três extensões por dívida histórica (`.mjs` legado) — barato, mas é
60
+ estado que um dia se limpa.
61
+
62
+ ## Rastreamento
63
+ - Spec: `specs/ts-migration/` (SPEC-012)
64
+ - Implementação: `lib/core/registry.ts` (resolveScript), `lib/core/release.ts` (gate builda),
65
+ `tsconfig.json` / `tsconfig.build.json`, `.github/workflows/ci.yml`
66
+ - ADRs relacionadas: ADR-0021 (NFR "roda sem build"; classe "dist mente"), ADR-0024 (gate do tarball)
@@ -62,9 +62,40 @@ rica com lógica pobre, não arquitetura com arquitetura.
62
62
 
63
63
  **Conclusão honesta**: o ganho é **navegacional** (não recarregar código não-relacionado + o mapa),
64
64
  não de tamanho de arquivo. A medida crua feita aqui é um proxy fraco e **não prova** a economia. A
65
- prova rigorosa precisa do `context:smart`/`token:benchmark` sobre uma **mesma tarefa** num projeto
66
- gerado, com a mesma feature nas duas arquiteturas — o boilerplate flat não tem um equivalente rico ao
67
- Order, então esse benchmark é trabalho de follow-up, não algo a forjar agora.
65
+ prova rigorosa precisa do benchmark sobre uma **mesma tarefa**, com a mesma feature nas duas
66
+ arquiteturas — o boilerplate flat não tinha um equivalente rico ao Order, então ficou como follow-up.
67
+
68
+ ### Follow-up resolvido — o benchmark same-feature (`forja token:economy`)
69
+
70
+ A dívida acima foi fechada: existe um `benchmarks/clean-vs-flat/orders-flat/` (a MESMA feature —
71
+ place + ship + "não envia sem pagamento" — no estilo flat) e o comando `token:economy` mede **dois
72
+ eixos**, porque a economia de token do Forja tem dois eixos e eles são diferentes:
73
+
74
+ **Eixo 1 — arquitetura (clean vs flat).** Desmente a versão ingênua da claim:
75
+
76
+ | Cenário | Clean | Flat | Clean vs flat |
77
+ |---|---|---|---|
78
+ | Entender a feature inteira | ~3684 tok (12 arq.) | ~1298 tok (3 arq.) | **+184%** |
79
+ | Mudar a regra de envio (contexto mínimo) | ~1419 tok (3 arq.) | ~910 tok (1 arq.) | **+56%** |
80
+
81
+ Para uma feature pequena, **o clean-arch custa MAIS tokens** — inclusive na mudança localizada. A
82
+ camada cobra adiantado e, com dois casos de uso, não se paga. **A justificativa de `orders` em
83
+ camadas passa a ser isolamento e testabilidade, não token.**
84
+
85
+ **Eixo 2 — memória (frio vs quente).** É aqui que a economia real do framework mora (ADR-0009):
86
+
87
+ | Cenário | Quente (com `context.md`) | Frio (sem mapa) | Economia |
88
+ |---|---|---|---|
89
+ | Localizar e mexer numa regra da fatia | ~1419 tok (3 arq.) | ~3684 tok (12 arq.) | **−61%** |
90
+
91
+ O `context.md` é o mapa: com ele, o agente vai direto ao agregado + à máquina de estados; sem ele,
92
+ varre a fatia inteira para descobrir onde a regra vive. **E essa economia COMPÕE**: gerar do zero é
93
+ custo único (o scaffold), mas o mapa poupa a cada tarefa futura, pela vida do projeto. O
94
+ `token:economy` não mede o custo de gerar — mede o regime permanente, depois do projeto levantado.
95
+
96
+ Conclusão corrigida: a economia de token do Forja **não é das camadas — é da memória persistente**,
97
+ amortizada no tempo. As camadas se pagam só a partir de certa escala (tamanho da feature × nº de
98
+ casos de uso); a memória se paga desde a segunda tarefa. Tudo reproduzível: `forja token:economy`.
68
99
 
69
100
  ## Alternativas consideradas
70
101
 
@@ -0,0 +1,59 @@
1
+ # ADR-0029: Gate do projeto gerado (`project:smoke`)
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-07-19
5
+ - **Autor(es)**: apk
6
+ - **Tags**: quality, gates, generators, sdd
7
+
8
+ ## Contexto
9
+
10
+ O `release:check` (ADR-0024) guarda uma fronteira com evidência: *o repositório mente sobre o
11
+ pacote*. Existe a **mesma classe de bug um nível acima, e estava descoberta**: nada provava que
12
+ `forja project:new` gera um projeto coerente.
13
+
14
+ O gerador escreve a partir de templates — `{{FEATURE}}`, blocos de `scripts`, configs. Cada
15
+ substituição é uma chance de mentira silenciosa: um placeholder que vaza, um `package.json` que não
16
+ parseia, uma estrutura incompleta. O `structure-validator` já sabia *validar* estrutura, mas nada
17
+ *executava* o gerador de ponta a ponta e reprovava. Conhecimento não faltava; execução, sim — o
18
+ mesmo diagnóstico da SPEC-010.
19
+
20
+ ## Decisão
21
+
22
+ Criar `project:smoke` (SPEC-015): um gate que **gera um projeto num diretório temporário isolado e o
23
+ inspeciona**, reusando o runner de `checks.ts` — a mesma máquina de probes do doctor e do release.
24
+
25
+ Dois tiers, espelhando o `release:check`:
26
+
27
+ - **Barato (default, roda no CI)**: sem rede. Prova que nenhum placeholder `{{...}}` vazou, que todo
28
+ `package.json` parseia, e que a estrutura passa no `validateProjectStructure`.
29
+ - **`--full` (opt-in, pré-release)**: `npm install` + `npm run build` no backend gerado, num ambiente
30
+ isolado (sem `NODE_PATH`/`npm_config_*` herdados). É o clean-install do release, na saída do gerador.
31
+
32
+ O gerador não sabe que está sendo auditado — o gate só o observa via spawn do entry real
33
+ (`create-memory-nest-kit`), como o release empacota o tarball real.
34
+
35
+ ## Alternativas consideradas
36
+
37
+ - **Importar as funções do gerador e chamá-las direto** — rejeitada: testaria as funções, não o
38
+ entry point que o usuário roda. O spawn do orquestrador pega bugs de orquestração também.
39
+ - **Rodar sempre o tier pesado (install+build)** — rejeitada: `npm install` de um NestJS é lento e
40
+ usa rede; um gate que reprova por flakiness de registry se contorna (a lição do CI na SPEC-009).
41
+ Por isso o tier barato é o gate de CI e o `--full` é opt-in.
42
+ - **Pôr no `tools:doctor`** — rejeitada: o doctor é o raio-x barato do núcleo; gerar um projeto tem
43
+ custo. É gate próprio, como o `release:check`.
44
+
45
+ ## Consequências
46
+
47
+ **Positivas**:
48
+ - A última fronteira do gerador que vivia por disciplina passa a viver no harness.
49
+ - Reuso total: runner de `checks.ts` + `structure-validator` existente — uma máquina, não duas.
50
+ - O tier barato é rápido o bastante para o CI; o `--full` dá a prova forte antes de publicar.
51
+
52
+ **Negativas / Trade-offs**:
53
+ - Cobre o caminho *default* do gerador; a matriz de boilerplates de stack fica para iteração futura.
54
+ - O `--full` depende de rede — mitigado por ser opt-in, fora do gate de CI.
55
+
56
+ ## Rastreamento
57
+ - Implementação: `lib/core/project-smoke.ts`, `scripts/project-smoke.ts`, `test/project-smoke.test.js`
58
+ - Spec: `specs/project-smoke/spec.md` (SPEC-015)
59
+ - ADRs relacionadas: ADR-0024 (gate do tarball — o padrão), ADR-0023 (doctor), ADR-0020 (core/registry)
@@ -0,0 +1,53 @@
1
+ # ADR-0030: O projeto gerado herda os gates do framework
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-07-19
5
+ - **Autor(es)**: apk
6
+ - **Tags**: generators, gates, memory, governance
7
+
8
+ ## Contexto
9
+
10
+ O framework construiu uma família de invariantes-que-rodam: `project:smoke`, `memory:audit`,
11
+ `adr-refs`, o `release:check`. Mas todos guardam o **framework**. O **projeto do usuário** não
12
+ herdava nenhum — gerava com mapas de memória honestos e, com o tempo, um rename sem atualizar o
13
+ `context.md` fazia o mapa mentir, silenciosamente, sem nada avisar. A economia de token da memória
14
+ (ADR-0009) se degrada, e ninguém percebe. É a mesma classe "vive por disciplina" que o ADR-0021
15
+ combate — só que na máquina do usuário, onde o framework não alcança por gate próprio.
16
+
17
+ ## Decisão
18
+
19
+ O gerador **emite um gate self-contained no projeto**: `scripts/check-memory-maps.mjs`, uma versão
20
+ sem dependências do `memory:audit` (coerência mapa↔código: mapa não cita código morto, módulo sem
21
+ mapa avisa). Zero acoplamento ao `forjajs` — Node puro, roda em qualquer CI com `node
22
+ scripts/check-memory-maps.mjs`. O `project:smoke` do framework passa a **verificar que o gate está
23
+ presente** no projeto gerado, fechando o laço: o framework prova que propaga o invariante.
24
+
25
+ A filosofia de invariantes deixa de ser só do mantenedor do Forja e passa a viajar com cada projeto.
26
+
27
+ ## Alternativas consideradas
28
+
29
+ - **Projeto depende de `forjajs` e roda `npx forja memory:audit`** — rejeitada: acopla um app NestJS
30
+ ao framework inteiro (e ao `better-sqlite3`), pesado para um gate que é Node puro.
31
+ - **Emitir um workflow `.github/` pronto** — rejeitada (por ora): imporia GitHub Actions a todo
32
+ projeto (alguns usam GitLab/outros). O script é portável; o usuário o pluga no CI que usa. Um
33
+ workflow opcional pode vir em follow-up.
34
+ - **Não propagar (deixar como doc)** — rejeitada: é exatamente o "regra que depende de memória" que
35
+ o framework existe para eliminar.
36
+
37
+ ## Consequências
38
+
39
+ **Positivas**:
40
+ - O invariante mapa↔código viaja com o projeto; a economia de token da memória fica protegida na
41
+ máquina do usuário, não só na do framework.
42
+ - Self-contained: sem dependência nova no projeto gerado.
43
+ - `project:smoke` prova a propagação (o gate está presente no output).
44
+
45
+ **Negativas / Trade-offs**:
46
+ - Duplicação de lógica (o `check-memory-maps.mjs` do projeto espelha o `lib/memory-audit.ts`). É o
47
+ preço de projetos independentes; a lógica é pequena e estável.
48
+ - O gate não roda sozinho até o usuário plugá-lo no CI — o script está presente, o wiring é dele.
49
+
50
+ ## Rastreamento
51
+ - Implementação: `lib/generators/memory-generator.ts` (emite o script),
52
+ `lib/core/project-smoke.ts` (check `gate-inherited`)
53
+ - ADRs relacionadas: ADR-0009 (economia de token), ADR-0021 (invariante > disciplina), ADR-0029 (project:smoke), SPEC-017 (memory:audit)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "forjajs",
3
- "version": "1.3.2",
3
+ "version": "1.6.0",
4
4
  "description": "Forja — framework CLI-first de orquestração multiagente, memória hierárquica e geração de projetos com IA",
5
5
  "type": "module",
6
6
  "main": "index.js",
@@ -0,0 +1,56 @@
1
+ # Spec: code-context
2
+
3
+ - **ID**: SPEC-016
4
+ - **Status**: done
5
+ - **Owner**: apk
6
+ - **ADRs relacionadas**: ADR-0009 (economia de token), ADR-0003 (smart-context), ADR-0020 (core/registry)
7
+
8
+ ## 1. Problema
9
+
10
+ O `token:economy` mediu a economia real do framework: o `context.md` de um domínio (o mapa) faz o
11
+ contexto mínimo custar **−61%** vs varrer a fatia no frio. Mas essa economia era **potencial, não
12
+ entregue**: o mapa é só um arquivo que alguém precisa lembrar de ler, e ainda montar o contexto na
13
+ mão (mapa + os arquivos certos). A economia medida não vira lever até virar comando.
14
+
15
+ ## 2. Proposta de valor
16
+
17
+ Um comando entrega o **pacote de contexto mínimo** de um domínio, pronto para colar, com o custo em
18
+ token à mostra: o −61% deixa de ser medição e vira ferramenta do dia a dia.
19
+
20
+ ## 3. User stories
21
+
22
+ - **Como** agente que vai mexer num domínio, **quero** um comando que me dê o mapa + (sob demanda) o
23
+ código da fatia, **para que** eu não pague o custo de explorar a árvore no frio.
24
+ - **Como** dev, **quero** ver o custo em token do pacote, **para que** a economia seja visível e eu
25
+ escolha entre "só o mapa" e "mapa + código".
26
+
27
+ ## 4. Critérios de aceite (Definition of Done)
28
+
29
+ - [x] AC-1: `forja code:context <domínio>` imprime o `context.md` do domínio (o mapa), pronto para
30
+ colar, com os tokens do mapa no rodapé.
31
+ - [x] AC-2: `--code` anexa os `.ts` da fatia (`backend/src/modules/<domínio>/`) e soma os tokens.
32
+ - [x] AC-3: `--project <path>` aponta para outro projeto (default: `cwd`). Sem domínio, lista os
33
+ disponíveis; domínio inexistente reprova com a lista.
34
+ - [x] AC-4: A lógica de montagem é pura e testável (`lib/code-context.ts`), com fixtures — sem tocar
35
+ o disco real.
36
+
37
+ ## 5. Escopo
38
+
39
+ **Dentro**: o mapa + o código da fatia, com custo em token. Composição com `code:impact` (blast
40
+ radius) documentada, não embutida.
41
+
42
+ **Fora** (explícito):
43
+ - Reindexar/consultar a memória via FTS5 — isso é `context:smart`/`query:universal`; este comando lê
44
+ o mapa direto do disco do projeto.
45
+ - Chamar codegraph internamente — o blast radius fica em `code:impact`, componível (`&&`).
46
+ - Editar ou resumir o código — entrega cru; resumir é decisão do agente que consome.
47
+
48
+ ## 6. NFRs / restrições
49
+
50
+ - **Compatibilidade**: comando novo; não muda nada existente.
51
+ - **Sem dependência de rede ou de codegraph** no caminho principal (mapa + código são leitura de disco).
52
+
53
+ ## 7. Métricas de sucesso
54
+
55
+ O pacote "só o mapa" de um domínio típico custa uma fração do "mapa + código" — e ambos, uma fração
56
+ de ler a fatia no frio. O `token:economy` já mostra o −61%; este comando o torna acionável.
@@ -0,0 +1,63 @@
1
+ # Spec: gates
2
+
3
+ - **ID**: SPEC-020
4
+ - **Status**: done
5
+ - **Owner**: apk
6
+ - **ADRs relacionadas**: ADR-0023 (doctor como gate), ADR-0024 (release gate), ADR-0029 (project:smoke), ADR-0020 (core/registry)
7
+
8
+ ## 1. Problema
9
+
10
+ O framework acumulou uma família de gates — `tools:doctor` (núcleo + coerência de doc + topologia),
11
+ `release:check` (tarball), `project:smoke` (projeto gerado). Cada um guarda uma fronteira, mas estão
12
+ **espalhados**: ninguém lembra de rodar os três antes de um PR, e a governança do Forja — que existe
13
+ justamente para não depender de memória — depende da memória de quem publica para *invocar* os gates.
14
+ É a mesma ironia do ADR-0021, um nível acima: os gates existem, mas rodá-los ainda é disciplina.
15
+
16
+ ## 2. Proposta de valor
17
+
18
+ Um comando roda **todos os gates aplicáveis ao framework** e dá **um veredito só**. "A casa está
19
+ coerente?" deixa de ser quatro comandos lembrados e vira um: `forja check:all`.
20
+
21
+ ## 3. User stories
22
+
23
+ - **Como** mantenedor, **quero** um comando que rode a bateria inteira antes do PR, **para que** eu
24
+ não esqueça um gate e descubra a quebra no CI (ou depois).
25
+ - **Como** quem publica, **quero** `--full` que inclua os gates caros (tarball, build do gerado),
26
+ **para que** o pré-release seja um comando, não um checklist.
27
+
28
+ ## 4. Critérios de aceite (Definition of Done)
29
+
30
+ - [ ] AC-1: `forja check:all` roda os gates de coerência (o catálogo do `tools:doctor`) **+** o
31
+ `project:smoke` (tier barato) e reporta **um veredito** (exit ≠ 0 se qualquer crítico falhar).
32
+ - [ ] AC-2: `--full` adiciona os gates caros: `release:check` (tarball) e `project:smoke --full`
33
+ (instala + builda o backend gerado).
34
+ - [ ] AC-3: A saída **agrupa por gate** (núcleo & coerência / projeto gerado / tarball) e resume o
35
+ pior status ao final — legível, não um despejo.
36
+ - [ ] AC-4: **Compõe os runners existentes** (`health`, `project-smoke`, `release`) — uma máquina,
37
+ zero reimplementação de check. Reusa `worstStatus` de `checks.ts`.
38
+ - [ ] AC-5: Lógica de composição pura e testável (env/runners injetáveis; teste com fakes que
39
+ devolvem status conhecidos, sem gerar projeto de verdade).
40
+
41
+ ## 5. Escopo
42
+
43
+ **Dentro**: compor os gates do framework num comando com veredito único e tiers.
44
+
45
+ **Fora** (explícito):
46
+ - `memory:audit` — é gate de **projeto gerado** (precisa de `memory/30-domains` de produto), não do
47
+ framework. Fica de fora do `check:all` do framework; roda no CI do projeto (ADR-0030).
48
+ - Reimplementar qualquer check — este comando só orquestra os catálogos que já existem.
49
+ - Substituir `tools:doctor`/`release:check`/`project:smoke` — eles seguem existindo, focados; o
50
+ `check:all` é o agregador, não o dono.
51
+
52
+ ## 6. NFRs / restrições
53
+
54
+ - **Custo consciente**: o tier barato inclui a geração de um projeto (`project:smoke`) — segundos, sem
55
+ rede. O `--full` é minutos (empacota o tarball, `npm install` do backend). O tier certo para o
56
+ momento certo, como no `release:check`.
57
+ - **Compatibilidade**: comando novo; não muda os gates que agrega.
58
+
59
+ ## 7. Métricas de sucesso
60
+
61
+ Um `forja check:all` antes do PR pega uma quebra que passaria (um gate esquecido) — a prova de que
62
+ reunir a bateria num comando valeu. A governança do framework deixa de depender de lembrar quais
63
+ gates rodar.
@@ -0,0 +1,54 @@
1
+ # Spec: memory-audit
2
+
3
+ - **ID**: SPEC-017
4
+ - **Status**: done
5
+ - **Owner**: apk
6
+ - **ADRs relacionadas**: ADR-0009 (economia de token), ADR-0025 (coerência da doc — a mesma classe), ADR-0020 (core/registry)
7
+
8
+ ## 1. Problema
9
+
10
+ A economia de token do Forja é o `context.md` como mapa do domínio (`token:economy` mede −61%). Mas
11
+ o mapa cita paths de código — "a regra mora em `domain/order.entity.ts`", "teste em
12
+ `test/orders/place-order.spec.ts`". Quando o código é renomeado ou movido e o mapa não acompanha, o
13
+ mapa passa a **mentir com confiança**: um agente lê o lugar errado, paga o custo, e chega à conclusão
14
+ errada. Um mapa desatualizado é *pior* que mapa nenhum. Nada verifica isso hoje — vive de disciplina.
15
+
16
+ ## 2. Proposta de valor
17
+
18
+ O mapa deixa de poder mentir em silêncio: **todo path de código citado num `context.md` é conferido**,
19
+ e uma referência pendurada reprova. É o `adr-refs` (ADR-0025) aplicado aos mapas de memória.
20
+
21
+ ## 3. User stories
22
+
23
+ - **Como** dev de um projeto gerado, **quero** um comando que reprove quando um mapa aponta para
24
+ arquivo que não existe mais, **para que** a economia de token da memória não se volte contra mim.
25
+ - **Como** CI de um projeto, **quero** rodar isso como gate, **para que** um rename sem atualizar o
26
+ mapa não passe batido.
27
+
28
+ ## 4. Critérios de aceite (Definition of Done)
29
+
30
+ - [x] AC-1: `forja memory:audit` varre `memory/30-domains/*/context.md`, extrai os paths de código
31
+ citados (entre crases, com `/` e terminando em `.ts`) e reprova (exit ≠ 0) se algum não existe.
32
+ - [x] AC-2: Resolve o path em múltiplas bases (relativo ao módulo, ao `backend/`, à raiz) — um mesmo
33
+ mapa cita as duas convenções (`domain/x.ts` e `test/x.spec.ts`).
34
+ - [x] AC-3: `--project <path>` aponta para outro projeto (default: `cwd`).
35
+ - [x] AC-4: Lógica pura e testável (`lib/memory-audit.ts`); reusa `domainsOf` de `code-context`.
36
+
37
+ ## 5. Escopo
38
+
39
+ **Dentro**: conferir paths de código `.ts` citados nos mapas de domínio.
40
+
41
+ **Fora** (explícito):
42
+ - Validar que o *conteúdo* do mapa (a linguagem ubíqua, as regras) ainda bate com o código — isso é
43
+ julgamento, não path. Este gate pega o path pendurado, que é o sinal barato e objetivo.
44
+ - Rodar dentro do `project:smoke` — lá o projeto é recém-gerado, o mapa é fresco por definição. A
45
+ divergência mapa↔código acontece com o tempo, num projeto existente; é aí que este comando roda.
46
+
47
+ ## 6. NFRs / restrições
48
+
49
+ - **Compatibilidade**: comando novo; não muda nada. Sem rede, sem codegraph — leitura de disco.
50
+
51
+ ## 7. Métricas de sucesso
52
+
53
+ Pelo menos um rename sem atualização de mapa pego antes do merge num projeto real — a prova de que a
54
+ fronteira estava descoberta.