forjajs 1.1.6 → 1.2.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 (60) hide show
  1. package/CHANGELOG.md +37 -0
  2. package/README.en.md +28 -5
  3. package/README.md +30 -4
  4. package/bin/forja.mjs +3 -3
  5. package/boilerplates/06-clean-arch/README.md +48 -0
  6. package/boilerplates/06-clean-arch/WHEN-CLEAN-WHEN-LEAN.md +42 -0
  7. package/boilerplates/06-clean-arch/backend/package.json +43 -0
  8. package/boilerplates/06-clean-arch/backend/src/app.module.ts +20 -0
  9. package/boilerplates/06-clean-arch/backend/src/main.ts +10 -0
  10. package/boilerplates/06-clean-arch/backend/src/modules/orders/application/place-order.usecase.ts +47 -0
  11. package/boilerplates/06-clean-arch/backend/src/modules/orders/application/ship-order.usecase.ts +28 -0
  12. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/money.vo.ts +30 -0
  13. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order-status.vo.ts +36 -0
  14. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.entity.ts +85 -0
  15. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.repository.ts +17 -0
  16. package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/order.orm-entity.ts +24 -0
  17. package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/typeorm-order.repository.ts +57 -0
  18. package/boilerplates/06-clean-arch/backend/src/modules/orders/orders.module.ts +28 -0
  19. package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.controller.ts +31 -0
  20. package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.http.dto.ts +30 -0
  21. package/boilerplates/06-clean-arch/backend/src/modules/products/product.entity.ts +20 -0
  22. package/boilerplates/06-clean-arch/backend/src/modules/products/products.controller.ts +43 -0
  23. package/boilerplates/06-clean-arch/backend/src/modules/products/products.module.ts +11 -0
  24. package/boilerplates/06-clean-arch/backend/src/shared/result.ts +32 -0
  25. package/boilerplates/06-clean-arch/backend/test/orders/place-order.spec.ts +46 -0
  26. package/boilerplates/06-clean-arch/backend/tsconfig.json +16 -0
  27. package/boilerplates/06-clean-arch/boilerplate.manifest.json +43 -0
  28. package/boilerplates/06-clean-arch/memory/30-domains/orders/context.md +39 -0
  29. package/boilerplates/06-clean-arch/memory/30-domains/products/context.md +23 -0
  30. package/boilerplates/README.md +20 -0
  31. package/docs/personas/architect/README.md +4 -4
  32. package/docs/personas/developer/README.md +3 -3
  33. package/docs/personas/qa/README.md +3 -3
  34. package/docs/quick-reference.md +9 -9
  35. package/docs/structure.md +3 -3
  36. package/lib/core/checks.mjs +20 -3
  37. package/lib/core/doc-graph.mjs +231 -0
  38. package/lib/core/health.mjs +131 -29
  39. package/lib/core/registry.mjs +23 -0
  40. package/lib/core/release.mjs +48 -8
  41. package/lib/templates/harness/code-intel.mjs +2 -2
  42. package/memory/90-decisions/0025-coerencia-da-documentacao.md +95 -0
  43. package/memory/90-decisions/0027-clean-arch-calibrada.md +96 -0
  44. package/package.json +7 -1
  45. package/scripts/agent-harness.mjs +7 -5
  46. package/scripts/context-ops.mjs +7 -4
  47. package/scripts/dev.mjs +2 -2
  48. package/scripts/hook-guard-paths.mjs +1 -0
  49. package/scripts/hook-user-prompt.mjs +1 -1
  50. package/scripts/spec-cli.mjs +4 -3
  51. package/scripts/tools-doctor.mjs +1 -1
  52. package/specs/clean-arch-boilerplate/plan.md +137 -0
  53. package/specs/clean-arch-boilerplate/spec.md +121 -0
  54. package/specs/clean-arch-boilerplate/tasks.md +70 -0
  55. package/specs/coerencia-do-sistema/plan.md +155 -0
  56. package/specs/coerencia-do-sistema/spec.md +15 -14
  57. package/specs/coerencia-do-sistema/tasks.md +115 -0
  58. package/specs/ts-migration/plan.md +188 -0
  59. package/specs/ts-migration/spec.md +119 -0
  60. package/specs/ts-migration/tasks.md +110 -0
@@ -16,7 +16,7 @@ import { spawnSync } from 'node:child_process';
16
16
 
17
17
  function runCodegraph(args) {
18
18
  const result = spawnSync('codegraph', args, { encoding: 'utf8' });
19
- if (result.error && result.error.code === 'ENOENT') return { missing: true };
19
+ if (result.error && /** @type {any} */ (result.error).code === 'ENOENT') return { missing: true };
20
20
  return {
21
21
  missing: false,
22
22
  status: result.status ?? 1,
@@ -30,7 +30,7 @@ function codegraphStatus() {
30
30
  if (res.missing) return { missing: true };
31
31
  let data = null;
32
32
  try {
33
- data = JSON.parse(res.stdout);
33
+ data = JSON.parse(/** @type {string} */ (res.stdout));
34
34
  } catch {
35
35
  return { missing: false, parseError: true, raw: res.stdout || res.stderr };
36
36
  }
@@ -0,0 +1,95 @@
1
+ # ADR-0025: Coerência da documentação como gate
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-07-18
5
+ - **Autor(es)**: Allan Pablo
6
+ - **Tags**: governance, docs, harness, diagnostics, registry
7
+
8
+ ## Contexto
9
+
10
+ Os ADRs 0023 e 0024 fecharam a classe "erra sem avisar" (ADR-0021) no **núcleo** e no **tarball**.
11
+ Faltava a fronteira mais barata de corromper e a mais cara de perceber: a **palavra escrita**.
12
+
13
+ O Forja é operado por agentes que leem a documentação e executam o que ela manda. Quando a doc e o
14
+ código divergem, o agente não erra por burrice — erra por **obediência**. Uma auditoria manual em
15
+ 2026-07-14 encontrou, entre outras coisas:
16
+
17
+ - `docs/token-optimization.md` — o documento que ensina a economia de tokens (ADR-0009) — mandava
18
+ rodar **quatro comandos que não existem** (`context:build`, `memory:db:reindex`, …) e linkava um
19
+ `docs/DEPLOYMENT.md` que nunca existiu.
20
+ - O Governance descrevia `tools:doctor` pela definição anterior ao ADR-0023.
21
+ - Comandos do registry sem menção em lugar nenhum — capacidade obscura é capacidade morta.
22
+
23
+ Nada disso quebrava um teste nem aparecia no `git status`. A correção manual apagou os sintomas do
24
+ dia; nada impedia a reincidência. Toda vez que um comando é renomeado ou um gate muda de contrato, a
25
+ doc pode silenciosamente passar a mentir.
26
+
27
+ ## Decisão
28
+
29
+ Três checks novos no catálogo de `health.mjs` (`scope: repo`), sobre um scanner puro
30
+ `lib/core/doc-graph.mjs` que lê os `.md` de instrução como dado:
31
+
32
+ - **`docs-commands`** (critical): todo `forja <cmd>` / `npm run <cmd>` citado numa superfície de
33
+ instrução existe no registry. Comando fantasma faz o agente agir errado — trava.
34
+ - **`commands-documented`** (warn): todo comando do registry é mencionado em ao menos um `.md`.
35
+ - **`docs-links`** (warn): todo link markdown relativo entre arquivos versionados resolve.
36
+
37
+ Princípios:
38
+
39
+ - **Scanner puro, checks finos.** `doc-graph.mjs` lê e devolve dados (`scanCommands`, `scanLinks`,
40
+ `projectCommands`); os checks julgam. Testar o parsing — a parte difícil — não exige montar o
41
+ ambiente do doctor.
42
+ - **Allowlist derivada, jamais literal.** Os comandos do projeto *gerado* (`start:dev`, `test:e2e`,
43
+ `memory:db:*`) não são do Forja e não podem reprovar. A allowlist deriva de **duas** fontes: os
44
+ blocos `"scripts"` inline dos geradores **e** os `package.json` dos boilerplates. Foi `test:e2e`
45
+ — que vive no boilerplate, não no gerador — que provou que uma fonte só produz falso positivo. Uma
46
+ lista manual mente no primeiro comando novo do boilerplate (a lição do `.gitignore`, SPEC-009).
47
+ - **Escopo = instrução, não histórico.** Escaneia `docs/` (menos `archive/`), `prompts/`,
48
+ `.claude/agents/` e os `.md` de raiz. **Fora**: `boilerplates/` (conteúdo do projeto gerado),
49
+ `specs/` e `memory/90-*` (registro histórico — uma spec ou ADR pode legitimamente citar um comando
50
+ proposto ou já removido). O gate protege o que instrui o agente *agora*.
51
+ - **`:` como discriminador de comando.** Cobre 42/42 do registry e nenhuma prosa (`"forja does X"`)
52
+ casa por acidente. Inventar parser de gramática para um comando-sem-`:` inexistente seria criar o
53
+ problema que não temos.
54
+ - **Severidade honesta.** Só `docs-commands` é crítico. Comando não-documentado e link quebrado
55
+ atrapalham, não impedem — `warn`. Um gate que reprova o que não trava é um gate que se aprende a
56
+ ignorar.
57
+
58
+ ## Alternativas consideradas
59
+
60
+ - **Manter a auditoria manual** — rejeitada: ela apaga sintomas, não fecha a classe. Reincide na
61
+ próxima renomeação.
62
+ - **Lista literal de comandos do projeto gerado** — rejeitada: é a armadilha do `.gitignore` da
63
+ SPEC-009. Uma lista que não acompanha o gerador vira mentira.
64
+ - **Parsear markdown com um lexer de CommonMark** — rejeitada: peso morto. Precisamos de citações e
65
+ links, não de um AST. Regex + o discriminador `:` bastam.
66
+ - **Gerar a doc a partir do registry** — rejeitada: doc gerada por máquina descreve o *quê*, nunca o
67
+ *porquê*, e o porquê é o que importa. O gate cobra que a explicação exista; não escreve por você.
68
+ - **Escanear `specs/` e `memory/` também** — rejeitada: são registro histórico. Reprovar um ADR por
69
+ citar um comando já removido puniria a memória por lembrar.
70
+
71
+ ## Consequências
72
+
73
+ **Positivas**:
74
+ - Renomear um comando vira **ato detectável**: a doc que ficou para trás reprova o CI (o
75
+ `tools:doctor` já é step, ADR-0024) — não espera a próxima auditoria manual.
76
+ - Os quatro comandos-fantasma e os 22 links quebrados da auditoria manual viram zero, verificado a
77
+ cada CI. `memory:extract` (o único órfão) passou a ser documentado.
78
+ - O gate pegou o **próprio autor**: ao corrigir os links, um erro de profundidade relativa
79
+ (`../../` vs `../../../`) foi detectado na hora, antes do commit. É a prova de que ele mede o que
80
+ deve.
81
+
82
+ **Negativas / Trade-offs**:
83
+ - Análise estática conservadora: o `:` como discriminador deixaria escapar um futuro comando sem
84
+ `:`. Aceito — nenhum existe, e falso negativo raro é melhor que falso positivo crítico.
85
+ - Os checks leem todos os `.md` de instrução a cada `tools:doctor`. Barato hoje (< 1s); se crescer,
86
+ vira lazy por mtime. São `scope: repo`, fora do `SessionStart`.
87
+
88
+ ## Rastreamento
89
+
90
+ - Implementação: `lib/core/doc-graph.mjs`, `lib/core/health.mjs` (checks `docs-commands`,
91
+ `commands-documented`, `docs-links`), `test/doc-graph.test.js`, `test/health.test.js`
92
+ - Spec: `specs/coerencia-do-sistema/` (SPEC-011)
93
+ - ADRs relacionadas: ADR-0023 (gate do núcleo) e ADR-0024 (gate do tarball) — a mesma família, agora
94
+ na terceira fronteira: a instrução. ADR-0021 (a classe "erra sem avisar"). ADR-0020 (registry como
95
+ fonte da verdade dos comandos).
@@ -0,0 +1,96 @@
1
+ # ADR-0027: Boilerplate Clean Architecture calibrada
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-07-18
5
+ - **Autor(es)**: Allan Pablo
6
+ - **Tags**: boilerplate, ddd, clean-architecture, token-economy
7
+
8
+ ## Contexto
9
+
10
+ Os boilerplates do Forja eram NestJS-flat: o `service` fala direto com a entity do ORM, a regra de
11
+ negócio fica diluída no service acoplada ao framework. Dois preços — manutenção (testar regra exige
12
+ subir o Nest; trocar ORM é cirurgia) e **tokens** (ADR-0009): um agente precisa ler a implementação
13
+ inteira para entender uma feature, porque não há contrato legível separado da execução.
14
+
15
+ A resposta ingênua — "aplicar Clean Architecture" — tem o preço oposto: quatro camadas para um CRUD
16
+ são mais arquivos para ler, não menos. Cargo-cult de arquitetura é o anti-padrão de token com nome
17
+ bonito.
18
+
19
+ ## Decisão
20
+
21
+ Um boilerplate (`boilerplates/06-clean-arch`) que demonstra **os dois padrões lado a lado**:
22
+
23
+ - **Fatia rica (Orders)**: 4 camadas (domain / application / infrastructure / presentation) com
24
+ inversão de dependência. Invariantes de negócio (não envia sem pagamento; total derivado; máquina
25
+ de estados) vivem no domínio, em TypeScript puro — **zero `@nestjs`, zero ORM**. Testáveis sem
26
+ subir o Nest.
27
+ - **Caminho enxuto (Products)**: CRUD numa camada, controller→repo direto, sem use-case nem porta.
28
+ - **`WHEN-CLEAN-WHEN-LEAN.md`**: o critério de qual padrão usar. É o coração — a calibração é a
29
+ decisão, não as camadas.
30
+ - **Memória por bounded context** (`memory/30-domains/<ctx>/context.md`): a linguagem ubíqua que o
31
+ agente lê antes do código.
32
+
33
+ Inversão via DI do Nest: a porta é `interface` no domínio + token; o adapter a implementa; o módulo
34
+ faz o bind numa linha. O domínio e a aplicação não sabem que TypeORM existe.
35
+
36
+ ## A medição de token — honesta (o que a spec exigiu)
37
+
38
+ A SPEC-013 fez da economia de token a métrica-norte e mandou **reconhecer se não cair, não maquiar**.
39
+ Então:
40
+
41
+ Medida crua (bytes/4) do custo de "ler o domínio para editar uma regra":
42
+
43
+ | | tokens aprox. |
44
+ |---|---|
45
+ | Clean-arch: `context.md` (476) + `order.entity.ts` (690) | **~1167** |
46
+ | Flat 02-saas: `billing.service.ts` (486) + `invoice.entity.ts` (244) | **~730** |
47
+
48
+ **Na contagem crua, Clean-arch não ganha — é maior.** E a comparação é injusta: o domínio de Orders
49
+ tem máquina de estados e invariantes reais; o service de billing é fino. Estamos comparando lógica
50
+ rica com lógica pobre, não arquitetura com arquitetura.
51
+
52
+ **Onde o benefício de token realmente está** (e o que a medida crua não captura):
53
+
54
+ 1. **Localização.** Para editar uma regra em Clean-arch, o agente lê o `context.md` (que aponta
55
+ "a regra está em `order.entity.ts`") e o agregado — e **não carrega** infraestrutura, controller
56
+ nem use-cases. No flat, a regra está no service misturada a acesso a dados; para ter certeza de
57
+ achar toda a lógica, o agente varre mais.
58
+ 2. **O `context.md` como mapa.** 476 tokens lidos primeiro que substituem exploração. No flat não há
59
+ mapa: o agente greps/lê para descobrir onde a regra vive.
60
+ 3. **Ler assinatura, não implementação.** Para *entender* (não editar), o `context.md` + a assinatura
61
+ do use-case bastam; no flat, lê-se o service.
62
+
63
+ **Conclusão honesta**: o ganho é **navegacional** (não recarregar código não-relacionado + o mapa),
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.
68
+
69
+ ## Alternativas consideradas
70
+
71
+ - **Clean Architecture em tudo** — rejeitada: é o cargo-cult que a calibração existe para evitar. O
72
+ `WHEN-CLEAN-WHEN-LEAN.md` + o Products enxuto são o guardrail.
73
+ - **Clean Architecture no framework Forja** — rejeitada (fora do escopo da SPEC-013): over-engineering
74
+ para um CLI. O framework ganha só modelos de domínio tipados, ride na migração TS (SPEC-012).
75
+ - **Refatorar os boilerplates 01-05** — rejeitada: aditivo, não migração. Os flat servem o CRUD.
76
+
77
+ ## Consequências
78
+
79
+ **Positivas**:
80
+ - Um esqueleto onde a regra de negócio é isolada, testável sem framework, e sobrevive a troca de ORM.
81
+ - A calibração é **visível em código** (Orders rico vs. Products enxuto), não só documentada.
82
+ - O guardrail contra token-bloat é explícito e reprovável (o Products *tem* que ser 1 camada).
83
+
84
+ **Negativas / Trade-offs**:
85
+ - A economia de token **não está provada** — está argumentada (navegacional) e medida cruamente com
86
+ resultado inconclusivo. O benchmark real é follow-up. Registrar isto é a honestidade que a spec
87
+ cobrou; claim de vitória não-medida seria maquiar.
88
+ - Mais conceitos para o dev absorver na fatia rica. Mitigado: uma fatia rica só; o resto enxuto.
89
+
90
+ ## Rastreamento
91
+
92
+ - Implementação: `boilerplates/06-clean-arch/`
93
+ - Spec: `specs/clean-arch-boilerplate/` (SPEC-013)
94
+ - ADRs relacionadas: ADR-0009 (economia de tokens — a métrica-norte), ADR-0001 (memória por contexto),
95
+ ADR-0016 (harness), SPEC-012 (TS — o domínio tipado)
96
+ - **Follow-up**: benchmark `context:smart` de uma tarefa-tipo, mesma feature nas duas arquiteturas.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "forjajs",
3
- "version": "1.1.6",
3
+ "version": "1.2.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",
@@ -85,6 +85,8 @@
85
85
  "code:impact": "node bin/forja.mjs code:impact",
86
86
  "tools:doctor": "node bin/forja.mjs tools:doctor",
87
87
  "release:check": "node bin/forja.mjs release:check",
88
+ "build": "tsc -p tsconfig.build.json",
89
+ "types:check": "tsc --noEmit",
88
90
  "test": "node --test test/*.test.js"
89
91
  },
90
92
  "keywords": [
@@ -108,5 +110,9 @@
108
110
  },
109
111
  "allowScripts": {
110
112
  "better-sqlite3@12.11.1": true
113
+ },
114
+ "devDependencies": {
115
+ "@types/node": "^26.1.1",
116
+ "typescript": "^5.9.3"
111
117
  }
112
118
  }
@@ -94,10 +94,10 @@ function readText(file) {
94
94
 
95
95
  function runCodegraph(args) {
96
96
  const result = spawnSync('codegraph', args, { cwd: root, encoding: 'utf8' });
97
- if (result.error && result.error.code === 'ENOENT') {
97
+ if (result.error && /** @type {any} */ (result.error).code === 'ENOENT') {
98
98
  return { missing: true };
99
99
  }
100
- if (result.error && result.error.code === 'EPERM') {
100
+ if (result.error && /** @type {any} */ (result.error).code === 'EPERM') {
101
101
  const quote = (value) => `'${String(value).replace(/'/g, `'\\''`)}'`;
102
102
  const fallback = spawnSync('/bin/sh', ['-lc', ['codegraph', ...args.map(quote)].join(' ')], {
103
103
  cwd: root,
@@ -125,7 +125,7 @@ function codegraphStatus() {
125
125
  if (res.missing) return { missing: true };
126
126
  let data = null;
127
127
  try {
128
- data = JSON.parse(res.stdout);
128
+ data = JSON.parse(/** @type {string} */ (res.stdout));
129
129
  } catch {
130
130
  return { missing: false, parseError: true, raw: res.stdout || res.stderr };
131
131
  }
@@ -533,7 +533,9 @@ Design / Code intelligence:
533
533
  `);
534
534
  }
535
535
 
536
- const [command, ...args] = process.argv.slice(2);
536
+ const [command, ...rest] = process.argv.slice(2);
537
+ /** dispatch heterogêneo: cada cmd consome os args do seu jeito (Fase 1) */
538
+ const args = /** @type {any} */ (rest);
537
539
 
538
540
  switch (command) {
539
541
  case 'workspace:init':
@@ -567,7 +569,7 @@ switch (command) {
567
569
  cmdGsdCheck(args);
568
570
  break;
569
571
  case 'code:check':
570
- cmdCodeCheck(args);
572
+ cmdCodeCheck();
571
573
  break;
572
574
  case 'code:impact':
573
575
  cmdCodeImpact(args);
@@ -4,7 +4,7 @@ import fs from 'node:fs';
4
4
  import path from 'node:path';
5
5
  import Database from 'better-sqlite3';
6
6
  import { fileURLToPath } from 'node:url';
7
- import { ensureSchema, dbPath } from './memory-schema.mjs';
7
+ import { ensureSchema, getDbPath } from './memory-schema.mjs';
8
8
 
9
9
  const __dirname = path.dirname(fileURLToPath(import.meta.url));
10
10
  const root = path.resolve(__dirname, '..');
@@ -77,9 +77,10 @@ function listSpecs() {
77
77
 
78
78
  function openDb() {
79
79
  ensureSchema({ silent: true });
80
- return new Database(dbPath, { timeout: 5000 });
80
+ return new Database(getDbPath(), { timeout: 5000 });
81
81
  }
82
82
 
83
+ /** @param {number|null} [limitTokens] */
83
84
  function recordContextRun(kind, slug, filePath, content, limitTokens = null) {
84
85
  const db = openDb();
85
86
  const tokens = estimateTokens(content);
@@ -116,7 +117,7 @@ function upsertSpecSummary(slug, content) {
116
117
  }
117
118
 
118
119
  function getOpenHandoffs(slug = null) {
119
- if (!fs.existsSync(dbPath)) return [];
120
+ if (!fs.existsSync(getDbPath())) return [];
120
121
  const db = openDb();
121
122
  let rows;
122
123
  try {
@@ -450,7 +451,9 @@ Comandos:
450
451
  `);
451
452
  }
452
453
 
453
- const [cmd, ...args] = process.argv.slice(2);
454
+ const [cmd, ...rest] = process.argv.slice(2);
455
+ /** dispatch heterogêneo: cada cmd consome os args do seu jeito (Fase 1) */
456
+ const args = /** @type {any} */ (rest);
454
457
  switch (cmd) {
455
458
  case 'budget': cmdBudget(args); break;
456
459
  case 'sprint-pack': cmdSprintPack(); break;
package/scripts/dev.mjs CHANGED
@@ -16,7 +16,7 @@
16
16
 
17
17
  import fs from 'node:fs';
18
18
  import path from 'node:path';
19
- import { spawnSync } from 'node:child_process';
19
+ import { spawn, spawnSync } from 'node:child_process';
20
20
  import { fileURLToPath } from 'node:url';
21
21
  import { getDbPath, ensureSchema } from './memory-schema.mjs';
22
22
 
@@ -119,7 +119,7 @@ Exemplos:
119
119
  * Run subprocess
120
120
  */
121
121
  function runScript(scriptPath, args = []) {
122
- return new Promise((resolve, reject) => {
122
+ return new Promise((/** @type {(v?: unknown) => void} */ resolve, reject) => {
123
123
  const proc = spawn('node', [scriptPath, ...args], {
124
124
  stdio: 'inherit',
125
125
  cwd: root,
@@ -44,6 +44,7 @@ function readStdin() {
44
44
  }
45
45
 
46
46
  /** Falha aberta: um guard quebrado não pode travar a sessão inteira. */
47
+ /** @returns {never} */
47
48
  function allow() { process.exit(0); }
48
49
 
49
50
  (async function main() {
@@ -110,7 +110,7 @@ function buildTaskContext(slug, capBytes) {
110
110
  [`specs/${slug}/tasks.md`, 2500],
111
111
  [`.context/gsd-${slug}.md`, 1500],
112
112
  ];
113
- for (const [rel, sliceCap] of candidates) {
113
+ for (const [rel, sliceCap] of /** @type {[string, number][]} */ (candidates)) {
114
114
  try {
115
115
  const c = fs.readFileSync(path.join(root, rel), 'utf8');
116
116
  pieces.push(`### ${rel}\n\n${c.slice(0, sliceCap)}`);
@@ -28,6 +28,7 @@ const STAGES = ['spec', 'plan', 'tasks'];
28
28
  const STATUS_RE = /-\s*\*\*Status\*\*:\s*([a-z]+)[^\n]*/i;
29
29
  const VALID_STATUSES = ['draft', 'review', 'approved', 'implementing', 'done', 'abandoned'];
30
30
 
31
+ /** @returns {never} */
31
32
  function fail(msg) {
32
33
  fs.writeSync(2, `[spec-cli] ${msg}\n`);
33
34
  process.exit(1);
@@ -178,7 +179,7 @@ function cmdNextStage(stage, feature) {
178
179
 
179
180
  function checkFeature(slug) {
180
181
  const dir = path.join(specsDir, slug);
181
- const result = { slug, stages: {}, ok: true, errors: [] };
182
+ const result = { slug, stages: /** @type {Record<string,string|null>} */ ({}), ok: true, errors: /** @type {string[]} */ ([]) };
182
183
  for (const stage of STAGES) {
183
184
  const status = readStatus(path.join(dir, `${stage}.md`));
184
185
  result.stages[stage] = status;
@@ -191,11 +192,11 @@ function checkFeature(slug) {
191
192
  result.ok = false;
192
193
  result.errors.push('spec.md ausente');
193
194
  }
194
- if (result.stages.plan && !ALLOWS_NEXT_STAGE.includes(result.stages.spec)) {
195
+ if (result.stages.plan && !ALLOWS_NEXT_STAGE.includes(result.stages.spec ?? '')) {
195
196
  result.ok = false;
196
197
  result.errors.push(`plan.md existe mas spec status = ${result.stages.spec}`);
197
198
  }
198
- if (result.stages.tasks && !ALLOWS_NEXT_STAGE.includes(result.stages.plan)) {
199
+ if (result.stages.tasks && !ALLOWS_NEXT_STAGE.includes(result.stages.plan ?? '')) {
199
200
  result.ok = false;
200
201
  result.errors.push(`tasks.md existe mas plan status = ${result.stages.plan}`);
201
202
  }
@@ -62,7 +62,7 @@ const TOOLS = [
62
62
 
63
63
  function detect(cmd, args) {
64
64
  const res = spawnSync(cmd, args, { encoding: 'utf8' });
65
- if (res.error && res.error.code === 'ENOENT') return { ok: false };
65
+ if (res.error && /** @type {any} */ (res.error).code === 'ENOENT') return { ok: false };
66
66
  const version = (res.stdout || res.stderr || '').trim().split('\n')[0] || 'instalado';
67
67
  return { ok: true, version };
68
68
  }
@@ -0,0 +1,137 @@
1
+ # Plan: clean-arch-boilerplate
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Status**: approved
5
+ - **Criado em**: 2026-07-18
6
+
7
+ > Como vamos construir o que a spec define. Sem código aqui — só estrutura e decisões.
8
+
9
+ ## 1. Abordagem técnica
10
+
11
+ Um boilerplate NestJS + TypeScript com a **regra de dependência para dentro** (Clean Architecture /
12
+ Hexagonal). A fatia rica é **Order** (invariante: não confirma sem estoque, não envia sem
13
+ pagamento) — vive no domínio, testável sem Nest. O contraponto enxuto é **Product** (CRUD),
14
+ demonstrando o caminho de 1 camada. O `WHEN-CLEAN-WHEN-LEAN.md` é o coração da spec: ensina o
15
+ critério, não a ceremônia.
16
+
17
+ O mecanismo de inversão no Nest: a **porta é uma `interface` no domínio + um token de injeção**; o
18
+ adapter (repo ORM) a implementa; o módulo faz o bind `{ provide: ORDER_REPO, useClass: TypeOrmOrderRepo }`.
19
+ O use-case injeta a porta, nunca o adapter. É o padrão documentado uma vez e repetido.
20
+
21
+ ## 2. Estrutura de diretórios (o contrato visual)
22
+
23
+ ```
24
+ boilerplates/06-clean-arch/
25
+ backend/src/
26
+ modules/orders/ # FATIA RICA — as 4 camadas
27
+ domain/
28
+ order.entity.ts # agregado: invariantes vivem aqui (pure TS, zero Nest/ORM)
29
+ order-status.vo.ts # value object (máquina de estados)
30
+ order.repository.ts # PORTA (interface) + token ORDER_REPOSITORY
31
+ application/
32
+ place-order.usecase.ts # input/output tipados; orquestra domínio + porta
33
+ ship-order.usecase.ts
34
+ dtos.ts # contratos de aplicação (não HTTP)
35
+ infrastructure/
36
+ typeorm-order.repository.ts # ADAPTER: implementa a porta
37
+ order.orm-entity.ts # entity do ORM (mapper domínio↔persistência)
38
+ presentation/
39
+ orders.controller.ts # HTTP DTOs + mapeia p/ use-case
40
+ orders.http.dto.ts
41
+ orders.module.ts # bind porta→adapter (inversão)
42
+ modules/products/ # CAMINHO ENXUTO — CRUD, 1 camada
43
+ products.controller.ts # controller → repo direto; sem use-case/porta
44
+ product.entity.ts
45
+ products.module.ts
46
+ shared/ # Result/Either, base VO, erros de domínio
47
+ main.ts · app.module.ts
48
+ backend/test/
49
+ orders/place-order.spec.ts # testa a INVARIANTE sem subir o Nest (AC-8)
50
+ memory/30-domains/orders/context.md # linguagem ubíqua — o agente lê ISTO antes do código
51
+ memory/30-domains/products/context.md
52
+ WHEN-CLEAN-WHEN-LEAN.md # o critério de calibração
53
+ boilerplate.manifest.json · README.md
54
+ ```
55
+
56
+ O `orders/` e o `products/` lado a lado **são** a spec: um mostra Clean Architecture onde se paga, o
57
+ outro mostra o custo evitado. O dev/agente vê os dois e entende o critério pela estrutura.
58
+
59
+ ## 3. Fluxo de dependência (a regra)
60
+
61
+ ```
62
+ presentation ─┐
63
+ ├─► application ─► domain ◄─ (ports: interfaces)
64
+ infrastructure┘ ▲
65
+ (adapters implementam ports) ─┘
66
+ dependências apontam p/ DENTRO. domain não importa nada de fora.
67
+ ```
68
+
69
+ ## 4. Contratos (o que se lê sem a implementação)
70
+
71
+ ```ts
72
+ // domain/order.repository.ts — a PORTA
73
+ export const ORDER_REPOSITORY = Symbol('OrderRepository');
74
+ export interface OrderRepository {
75
+ save(order: Order): Promise<void>;
76
+ byId(id: OrderId): Promise<Order | null>;
77
+ }
78
+
79
+ // application/place-order.usecase.ts — o contrato legível (AC-5)
80
+ export interface PlaceOrderInput { customerId: string; items: OrderLine[]; }
81
+ export interface PlaceOrderOutput { orderId: string; total: Money; }
82
+ // a assinatura basta para o agente saber o que a feature faz — sem ler o corpo
83
+ ```
84
+
85
+ ## 5. Decisões e alternativas
86
+
87
+ **D1: Order como fatia rica.** Invariante cross-aggregate universal e reconhecível ("não envia sem
88
+ pagamento"). Alternativa (Subscription/máquina de estados) é boa mas menos imediata; fica como VO
89
+ dentro de Order (`order-status.vo.ts`), aproveitando os dois.
90
+
91
+ **D2: Product como caminho enxuto — lado a lado, não escondido.** A calibração precisa ser *visível*.
92
+ Um CRUD que atravessa controller→repo direto, sem use-case nem porta, no mesmo boilerplate. É o AC-4
93
+ materializado em código, não só no doc.
94
+
95
+ **D3: Porta = interface no domínio + token Nest.** O domínio define o contrato; o Nest só faz o bind.
96
+ Alternativa rejeitada: repositório abstrato como classe base (acopla o domínio ao mecanismo de
97
+ herança e, na prática, ao Nest). Interface + token mantém o domínio puro.
98
+
99
+ **D4: Domínio puro, zero `@nestjs` e zero ORM.** É o que torna o teste-sem-Nest (AC-8) possível e é a
100
+ prova concreta do isolamento. O ORM vive só em `infrastructure/`, com mapper explícito
101
+ domínio↔orm-entity. Sem `@Entity` decorando o agregado de domínio.
102
+
103
+ **D5: Memória por contexto é o vetor de token (AC-6).** `context.md` descreve o domínio na linguagem
104
+ ubíqua. O agente lê ele + a assinatura do use-case; só desce ao código quando vai *editar*. É onde a
105
+ economia de token se materializa — e onde a mediremos.
106
+
107
+ **D6: Aditivo, sem tocar 01-05.** Novo diretório, novo manifesto. Os geradores existentes não mudam;
108
+ só o catálogo de boilerplates ganha uma entrada.
109
+
110
+ D1–D5 são estruturais → **ADR-0027** (Clean Architecture calibrada; o porquê da calibração e do token).
111
+
112
+ ## 6. Dependências
113
+
114
+ - **Specs**: SPEC-012 (TS) — o domínio é tipado; alinhado, não bloqueante.
115
+ - **Pacotes** (do projeto *gerado*, não do Forja): `@nestjs/*`, `typeorm`, `jest`. Ficam no
116
+ `package.json` do boilerplate — e por isso entram na allowlist derivada do `docs-commands` (SPEC-011).
117
+ - **Migrações**: nenhuma no framework.
118
+
119
+ ## 7. Rollout
120
+
121
+ - [ ] Esqueleto + `shared/` (Result, erros de domínio, base VO) primeiro.
122
+ - [ ] Fatia rica Orders (domain → application → infra → presentation), com o teste-sem-Nest a cada camada.
123
+ - [ ] Caminho enxuto Products.
124
+ - [ ] Memória por contexto + `WHEN-CLEAN-WHEN-LEAN.md`.
125
+ - [ ] Manifesto + entrada no catálogo + `boilerplates/README.md`.
126
+ - [ ] **Medir (AC-6/métrica-norte)**: `context:smart` para "adicionar regra ao contexto orders" aqui
127
+ vs. no `02-saas-starter` flat. Registrar os números no ADR. Se não cair, recalibra antes de fechar.
128
+ - [ ] Gates: `release:check` (boilerplate no `files[]`, instala limpo), `tools:doctor` (coerência de doc).
129
+
130
+ ## 8. Sinais de fracasso (kill criteria)
131
+
132
+ - **O caminho enxuto não existe de verdade** — se no fim tudo virou 4 camadas, a spec falhou (o
133
+ cargo-cult que ela existe para evitar). Products tem que ser genuinamente 1 camada.
134
+ - **O token não cai** (AC-6). Se o pacote de contexto não encolher vs. o flat, a arquitetura virou
135
+ custo. Reconhecer e recalibrar, não maquiar.
136
+ - **O domínio importa `@nestjs` ou ORM.** Qualquer import de framework no `domain/` quebra a premissa
137
+ inteira; o teste-sem-Nest é o detector.
@@ -0,0 +1,121 @@
1
+ # Spec: clean-arch-boilerplate
2
+
3
+ - **ID**: SPEC-013
4
+ - **Status**: approved
5
+ - **Owner**: apk
6
+ - **Criado em**: 2026-07-18
7
+ - **Sprint alvo**: S?
8
+ - **ADRs relacionadas**: [ADR-0009](../../memory/90-decisions/0009-claude-hooks-token-economy.md) (economia de tokens), [ADR-0016](../../memory/90-decisions/0016-integracao-capacidades-externas.md) (harness), [ADR-0001](../../memory/90-decisions/0001-memoria-hierarquica.md) (memória hierárquica)
9
+
10
+ ## 1. Problema
11
+
12
+ Os boilerplates atuais são **NestJS-flat**: `modules/<x>/{controller, service, entities, dto}`, com o
13
+ service falando direto com a entity do TypeORM. A infraestrutura (ORM) vaza para dentro da regra de
14
+ negócio, não há inversão de dependência, e a regra de domínio — quando existe — fica presa dentro de
15
+ um `service` acoplado ao framework. Isso cobra dois preços:
16
+
17
+ 1. **De manutenção**: trocar ORM, testar regra sem subir o Nest, ou mover uma invariante para onde
18
+ ela pertence exige cirurgia.
19
+ 2. **De tokens** — o que mais importa aqui (ADR-0009). Um agente que opera um projeto flat precisa
20
+ **ler a implementação inteira** para entender o que uma feature faz, porque a regra está diluída
21
+ no service junto do acesso a dados e do HTTP. Não há contrato legível separado da execução.
22
+
23
+ Ao mesmo tempo, a resposta ingênua — "aplicar Clean Architecture" — tem um preço oposto e igualmente
24
+ real: **quatro camadas para um CRUD são mais arquivos para ler, não menos.** Um boilerplate que força
25
+ use-case + porta + adapter + mapper por endpoint trivial é o anti-padrão de token que estamos tentando
26
+ evitar, com nome bonito.
27
+
28
+ ## 2. Proposta de valor
29
+
30
+ Um boilerplate Clean Architecture que **sabe quando NÃO ser Clean Architecture.** Camadas ricas onde
31
+ há regra de negócio de verdade; caminho enxuto explícito onde é CRUD. Estruturado para **navegação
32
+ barata por agente**: o contrato de um use-case se lê pela assinatura de tipo, não pela implementação;
33
+ cada bounded context tem um doc de memória na linguagem ubíqua que o agente lê **em vez** do código.
34
+ Arquitetura como compressão de contexto, não como cerimônia.
35
+
36
+ ## 3. User stories
37
+
38
+ - **Como** dev iniciando um produto, **quero** um esqueleto com domínio isolado de framework e ORM,
39
+ **para que** a regra de negócio seja testável e sobreviva a troca de infraestrutura.
40
+ - **Como** agente operando o projeto gerado, **quero** ler o contrato tipado de um use-case e o doc
41
+ de contexto do módulo, **para que** eu entenda a feature sem carregar a implementação inteira —
42
+ menos tokens por tarefa.
43
+ - **Como** dev com uma feature CRUD trivial, **quero** um caminho enxuto documentado, **para que** eu
44
+ não pague 4 camadas por um `GET /x`.
45
+ - **Como** arquiteto, **quero** uma fatia vertical rica de referência (com invariante de negócio de
46
+ verdade), **para que** o padrão Clean Architecture seja demonstrado onde ele se paga, não abstrato.
47
+
48
+ ## 4. Critérios de aceite (Definition of Done)
49
+
50
+ - [ ] AC-1: Novo boilerplate `boilerplates/06-clean-arch/` com as 4 camadas e a **regra de
51
+ dependência** para dentro: `domain` (puro: entities, value objects, ports/interfaces — zero
52
+ NestJS, zero ORM) → `application` (use-cases orquestrando domínio + portas) → `infrastructure`
53
+ (adapters: repos ORM, mappers, serviços externos) + `presentation` (controllers, DTOs HTTP).
54
+ - [ ] AC-2: **Inversão de dependência real** via DI do NestJS: as portas são tokens de injeção
55
+ (`interface` no domínio), os adapters as implementam e são bound no módulo. O use-case depende
56
+ da porta, nunca da implementação.
57
+ - [ ] AC-3: **Fatia vertical rica de referência** — um bounded context com invariante de negócio
58
+ genuína (não CRUD) que vive **no domínio** (ex.: um `Order` que não pode ser enviado sem
59
+ pagamento; ou `Subscription` como máquina de estados). Prova que a separação se paga.
60
+ - [ ] AC-4: **Caminho enxuto explícito** (a calibração). Um módulo CRUD simples demonstrado com o
61
+ mínimo de camadas, e um doc `WHEN-CLEAN-WHEN-LEAN.md` que ensina o critério de escolha. O
62
+ boilerplate não força ceremônia.
63
+ - [ ] AC-5: **Contratos legíveis** — todo use-case tem input/output tipados (TS) que se leem sem a
64
+ implementação. O domínio é a linguagem ubíqua tipada.
65
+ - [ ] AC-6: **Memória por bounded context** (ADR-0001): cada contexto tem um doc em
66
+ `memory/30-domains/<ctx>/context.md` na linguagem ubíqua, que o agente lê **antes** do código.
67
+ Medir: o pacote de contexto de uma tarefa cai vs. o boilerplate flat (ADR-0009).
68
+ - [ ] AC-7: Manifesto (`boilerplate.manifest.json`) + integração com o gerador (o boilerplate aparece
69
+ como opção, gera com a memória e os agentes multi-IA como os outros).
70
+ - [ ] AC-8: **Testes de domínio sem framework**: a invariante da AC-3 tem teste unitário que roda
71
+ **sem subir o Nest** — a prova concreta de que o domínio está isolado.
72
+ - [ ] AC-9: O boilerplate passa pelos gates do próprio Forja: `release:check` (está no `files[]`,
73
+ instala limpo) e a coerência de doc (SPEC-011) não acusa comando fantasma nos seus docs.
74
+ - [ ] AC-10: ADR registrando a decisão (Clean Architecture calibrada como boilerplate; o *porquê* da
75
+ calibração e do ângulo de token).
76
+
77
+ ## 5. Escopo
78
+
79
+ **Dentro**:
80
+ - `boilerplates/06-clean-arch/` completo: as 4 camadas, a fatia rica, o módulo enxuto, o
81
+ `WHEN-CLEAN-WHEN-LEAN.md`, a memória por contexto, o manifesto.
82
+ - Integração com o gerador (`lib/generators/`) para o boilerplate ser selecionável.
83
+ - ADR + a atualização de `boilerplates/README.md`.
84
+
85
+ **Fora** (explícito):
86
+ - **Refatorar os boilerplates existentes** (01-05). Eles ficam; este é aditivo. Migrar os antigos é
87
+ outra decisão.
88
+ - **Aplicar Clean Architecture ao framework Forja.** Decidido: over-engineering para um CLI; o
89
+ framework ganha só modelos de domínio tipados, e isso ride na migração TS (SPEC-012), não aqui.
90
+ - **Frontend.** Este boilerplate é backend (NestJS). Um par frontend é outra spec.
91
+ - **Prescrever ORM único.** O ponto é o domínio não saber do ORM; qual ORM o adapter usa é detalhe do
92
+ boilerplate, não da arquitetura.
93
+
94
+ ## 6. NFRs / restrições
95
+
96
+ - **Token-first (a régua)**: o ganho tem que ser *medível*. AC-6 exige comparar o pacote de contexto
97
+ de uma tarefa-tipo neste boilerplate vs. no flat. Se não cair, a arquitetura virou custo, não
98
+ economia — e aí recalibra.
99
+ - **Calibração inegociável**: a existência do caminho enxuto (AC-4) é o que separa esta spec de um
100
+ cargo-cult. Sem ele, reprovado.
101
+ - **TypeScript**: alinhado com a migração em curso (SPEC-012) — o domínio é tipado de primeira classe.
102
+ - **Compatibilidade**: aditivo; não muda os geradores dos boilerplates existentes.
103
+
104
+ ## 7. Riscos e mitigação
105
+
106
+ | Risco | Prob | Impacto | Mitigação |
107
+ |---|---|---|---|
108
+ | Vira cargo-cult: 4 camadas por CRUD, +tokens | **A** | A | AC-4 (caminho enxuto) + AC-6 (medir tokens) são gate; sem eles, reprova |
109
+ | Complexidade assusta o dev/agente | M | M | A fatia rica é 1 só; o resto é enxuto. `WHEN-CLEAN-WHEN-LEAN.md` guia |
110
+ | Inversão de dependência no Nest fica verbosa | M | M | Padrão de porta-como-token documentado uma vez; repetível |
111
+ | O ganho de token não se materializa | M | A | Medir cedo (AC-6). Se não cair, a spec falhou seu propósito — honesto reconhecer |
112
+
113
+ ## 8. Métricas de sucesso
114
+
115
+ - **Tokens por tarefa** num projeto gerado com este boilerplate **caem** vs. o flat, para uma
116
+ tarefa-tipo ("adicionar uma regra ao contexto X") — medido via `context:smart`/`token:benchmark`.
117
+ É a métrica-norte; sem ela a arquitetura não se justifica.
118
+ - Um dev pega a fatia rica e adiciona uma invariante de negócio **sem tocar em infraestrutura**.
119
+ - A invariante de domínio é testável **sem subir o Nest** (AC-8).
120
+ - 90 dias depois: os projetos novos do usuário escolhem este boilerplate quando há regra de negócio,
121
+ e o flat quando é CRUD puro — a calibração usada na prática, não só documentada.