forjajs 1.1.6 → 1.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/.claude/settings.json +7 -7
- package/CHANGELOG.md +62 -0
- package/README.en.md +33 -5
- package/README.md +35 -4
- package/boilerplates/06-clean-arch/README.md +48 -0
- package/boilerplates/06-clean-arch/WHEN-CLEAN-WHEN-LEAN.md +42 -0
- package/boilerplates/06-clean-arch/backend/package.json +43 -0
- package/boilerplates/06-clean-arch/backend/src/app.module.ts +20 -0
- package/boilerplates/06-clean-arch/backend/src/main.ts +10 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/application/place-order.usecase.ts +47 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/application/ship-order.usecase.ts +28 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/money.vo.ts +30 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order-status.vo.ts +36 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.entity.ts +85 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.repository.ts +17 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/order.orm-entity.ts +24 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/typeorm-order.repository.ts +57 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/orders.module.ts +28 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.controller.ts +31 -0
- package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.http.dto.ts +30 -0
- package/boilerplates/06-clean-arch/backend/src/modules/products/product.entity.ts +20 -0
- package/boilerplates/06-clean-arch/backend/src/modules/products/products.controller.ts +43 -0
- package/boilerplates/06-clean-arch/backend/src/modules/products/products.module.ts +11 -0
- package/boilerplates/06-clean-arch/backend/src/shared/result.ts +32 -0
- package/boilerplates/06-clean-arch/backend/test/orders/place-order.spec.ts +46 -0
- package/boilerplates/06-clean-arch/backend/tsconfig.json +16 -0
- package/boilerplates/06-clean-arch/boilerplate.manifest.json +43 -0
- package/boilerplates/06-clean-arch/memory/30-domains/orders/context.md +39 -0
- package/boilerplates/06-clean-arch/memory/30-domains/products/context.md +23 -0
- package/boilerplates/README.md +20 -0
- package/dist/bin/create-memory-nest-kit.d.ts +2 -0
- package/dist/bin/create-memory-nest-kit.js +110 -0
- package/dist/bin/forja.d.ts +13 -0
- package/dist/bin/forja.js +136 -0
- package/dist/bin/init-project.d.ts +2 -0
- package/dist/bin/init-project.js +516 -0
- package/dist/lib/audit.d.ts +67 -0
- package/dist/lib/audit.js +143 -0
- package/dist/lib/context-builder.d.ts +58 -0
- package/dist/lib/context-builder.js +233 -0
- package/dist/lib/core/checks.d.ts +91 -0
- package/dist/lib/core/checks.js +119 -0
- package/dist/lib/core/doc-graph.d.ts +60 -0
- package/dist/lib/core/doc-graph.js +235 -0
- package/dist/lib/core/health.d.ts +103 -0
- package/dist/lib/core/health.js +538 -0
- package/dist/lib/core/registry.d.ts +296 -0
- package/dist/lib/core/registry.js +317 -0
- package/dist/lib/core/release.d.ts +334 -0
- package/dist/lib/core/release.js +465 -0
- package/dist/lib/generators/memory-generator.d.ts +83 -0
- package/{lib → dist/lib}/generators/memory-generator.js +107 -178
- package/dist/lib/generators/nest-generator.d.ts +15 -0
- package/{lib → dist/lib}/generators/nest-generator.js +47 -71
- package/dist/lib/generators/readme-generator.d.ts +15 -0
- package/{lib → dist/lib}/generators/readme-generator.js +9 -14
- package/dist/lib/governance-report.d.ts +49 -0
- package/dist/lib/governance-report.js +170 -0
- package/dist/lib/templates/harness/code-intel.d.mts +2 -0
- package/dist/lib/templates/harness/code-intel.mjs +126 -0
- package/dist/lib/utils/file-helpers.d.ts +9 -0
- package/dist/lib/utils/file-helpers.js +34 -0
- package/dist/lib/validators/structure-validator.d.ts +48 -0
- package/dist/lib/validators/structure-validator.js +232 -0
- package/dist/lib/workspace.d.ts +40 -0
- package/dist/lib/workspace.js +174 -0
- package/dist/scripts/agent-harness.d.ts +2 -0
- package/dist/scripts/agent-harness.js +556 -0
- package/dist/scripts/agent-router.d.ts +30 -0
- package/dist/scripts/agent-router.js +208 -0
- package/dist/scripts/audit-query.d.ts +2 -0
- package/dist/scripts/audit-query.js +43 -0
- package/dist/scripts/audit-sync.d.ts +2 -0
- package/dist/scripts/audit-sync.js +19 -0
- package/dist/scripts/build-smart-context.d.ts +1 -0
- package/dist/scripts/build-smart-context.js +75 -0
- package/dist/scripts/check-standards.d.ts +1 -0
- package/dist/scripts/check-standards.js +87 -0
- package/dist/scripts/compress-memory.d.ts +16 -0
- package/dist/scripts/compress-memory.js +157 -0
- package/dist/scripts/compress-project-memory.d.ts +1 -0
- package/dist/scripts/compress-project-memory.js +48 -0
- package/dist/scripts/context-ops.d.ts +2 -0
- package/dist/scripts/context-ops.js +464 -0
- package/dist/scripts/dev.d.ts +96 -0
- package/dist/scripts/dev.js +312 -0
- package/dist/scripts/extract-global-knowledge.d.ts +1 -0
- package/dist/scripts/extract-global-knowledge.js +43 -0
- package/dist/scripts/generate-dashboard.d.ts +1 -0
- package/dist/scripts/generate-dashboard.js +48 -0
- package/dist/scripts/governance-dashboard.d.ts +2 -0
- package/dist/scripts/governance-dashboard.js +36 -0
- package/dist/scripts/hook-guard-paths.d.ts +17 -0
- package/dist/scripts/hook-guard-paths.js +68 -0
- package/dist/scripts/hook-post-edit.d.ts +20 -0
- package/dist/scripts/hook-post-edit.js +70 -0
- package/dist/scripts/hook-session-start.d.ts +17 -0
- package/dist/scripts/hook-session-start.js +108 -0
- package/dist/scripts/hook-user-prompt.d.ts +22 -0
- package/dist/scripts/hook-user-prompt.js +193 -0
- package/dist/scripts/memory-schema.d.ts +6 -0
- package/{scripts/memory-schema.mjs → dist/scripts/memory-schema.js} +27 -20
- package/dist/scripts/query-universal-memory.d.ts +1 -0
- package/dist/scripts/query-universal-memory.js +44 -0
- package/dist/scripts/release-check.d.ts +14 -0
- package/dist/scripts/release-check.js +48 -0
- package/dist/scripts/spec-cli.d.ts +29 -0
- package/dist/scripts/spec-cli.js +261 -0
- package/dist/scripts/sprint-manager.d.ts +1 -0
- package/dist/scripts/sprint-manager.js +187 -0
- package/dist/scripts/sync-universal-memory.d.ts +1 -0
- package/dist/scripts/sync-universal-memory.js +277 -0
- package/dist/scripts/token-benchmark.d.ts +20 -0
- package/dist/scripts/token-benchmark.js +181 -0
- package/dist/scripts/tools-doctor.d.ts +20 -0
- package/dist/scripts/tools-doctor.js +120 -0
- package/docs/personas/architect/README.md +4 -4
- package/docs/personas/developer/README.md +3 -3
- package/docs/personas/qa/README.md +3 -3
- package/docs/quick-reference.md +9 -9
- package/docs/structure.md +3 -3
- package/memory/90-decisions/0025-coerencia-da-documentacao.md +95 -0
- package/memory/90-decisions/0027-clean-arch-calibrada.md +96 -0
- package/memory/90-decisions/0028-governanca-visivel.md +84 -0
- package/package.json +60 -56
- package/specs/clean-arch-boilerplate/plan.md +137 -0
- package/specs/clean-arch-boilerplate/spec.md +121 -0
- package/specs/clean-arch-boilerplate/tasks.md +70 -0
- package/specs/coerencia-do-sistema/plan.md +155 -0
- package/specs/coerencia-do-sistema/spec.md +15 -14
- package/specs/coerencia-do-sistema/tasks.md +115 -0
- package/specs/governanca-visivel/plan.md +122 -0
- package/specs/governanca-visivel/spec.md +112 -0
- package/specs/governanca-visivel/tasks.md +60 -0
- package/specs/ts-migration/plan.md +199 -0
- package/specs/ts-migration/spec.md +119 -0
- package/specs/ts-migration/tasks.md +110 -0
- package/bin/create-memory-nest-kit.js +0 -125
- package/bin/forja.mjs +0 -143
- package/bin/init-project.js +0 -612
- package/lib/context-builder.js +0 -257
- package/lib/core/checks.mjs +0 -138
- package/lib/core/health.mjs +0 -475
- package/lib/core/registry.mjs +0 -289
- package/lib/core/release.mjs +0 -452
- package/lib/templates/harness/code-intel.mjs +0 -119
- package/lib/templates/harness/mcp.json +0 -10
- package/lib/utils/file-helpers.js +0 -40
- package/lib/validators/structure-validator.js +0 -253
- package/lib/workspace.mjs +0 -213
- package/scripts/agent-harness.mjs +0 -578
- package/scripts/agent-router.mjs +0 -189
- package/scripts/build-smart-context.js +0 -87
- package/scripts/check-standards.js +0 -98
- package/scripts/compress-memory.mjs +0 -198
- package/scripts/compress-project-memory.js +0 -58
- package/scripts/context-ops.mjs +0 -463
- package/scripts/dev.mjs +0 -349
- package/scripts/extract-global-knowledge.js +0 -52
- package/scripts/generate-dashboard.js +0 -59
- package/scripts/hook-guard-paths.mjs +0 -75
- package/scripts/hook-post-edit.mjs +0 -79
- package/scripts/hook-session-start.mjs +0 -104
- package/scripts/hook-user-prompt.mjs +0 -185
- package/scripts/pre-commit.sh +0 -102
- package/scripts/query-universal-memory.js +0 -50
- package/scripts/release-check.mjs +0 -56
- package/scripts/spec-cli.mjs +0 -260
- package/scripts/sprint-manager.js +0 -200
- package/scripts/sync-universal-memory.js +0 -286
- package/scripts/token-benchmark.mjs +0 -203
- package/scripts/tools-doctor.mjs +0 -132
package/docs/quick-reference.md
CHANGED
|
@@ -345,11 +345,11 @@ logger.error('Auth failed', error); // Erro
|
|
|
345
345
|
|
|
346
346
|
| Recurso | Link |
|
|
347
347
|
|---------|------|
|
|
348
|
-
| Documentation Map | [DOC-MAP.md](DOC-MAP.md) |
|
|
349
|
-
|
|
|
350
|
-
|
|
|
351
|
-
| Architecture | [
|
|
352
|
-
| Personas | [
|
|
348
|
+
| Documentation Map | [DOC-MAP.md](../DOC-MAP.md) |
|
|
349
|
+
| Getting Started | [README.md](../README.md) |
|
|
350
|
+
| Boilerplates | [boilerplates/](../boilerplates/README.md) |
|
|
351
|
+
| Architecture | [AGENTS.md](../AGENTS.md) |
|
|
352
|
+
| Personas | [personas/](personas/) |
|
|
353
353
|
|
|
354
354
|
---
|
|
355
355
|
|
|
@@ -399,10 +399,10 @@ open http://localhost:3000/api/health
|
|
|
399
399
|
|
|
400
400
|
| Dúvida | Arquivo |
|
|
401
401
|
|--------|---------|
|
|
402
|
-
| "Como começar?" | [
|
|
403
|
-
| "Como codificar?" | [
|
|
404
|
-
| "Como arquitetar?" | [
|
|
405
|
-
| "Qual minha persona?" | [DOC-MAP.md](DOC-MAP.md) |
|
|
402
|
+
| "Como começar?" | [README.md](../README.md) |
|
|
403
|
+
| "Como codificar?" | [boilerplates/](../boilerplates/README.md) |
|
|
404
|
+
| "Como arquitetar?" | [AGENTS.md](../AGENTS.md) |
|
|
405
|
+
| "Qual minha persona?" | [DOC-MAP.md](../DOC-MAP.md) |
|
|
406
406
|
|
|
407
407
|
---
|
|
408
408
|
|
package/docs/structure.md
CHANGED
|
@@ -355,6 +355,6 @@ node backend/scripts/memory-db-query.mjs --table improvement_items
|
|
|
355
355
|
---
|
|
356
356
|
|
|
357
357
|
**Para mais detalhes**, veja:
|
|
358
|
-
- [
|
|
359
|
-
- [
|
|
360
|
-
- [
|
|
358
|
+
- [README.md](../README.md)
|
|
359
|
+
- [AGENTS.md](../AGENTS.md)
|
|
360
|
+
- [DOC-MAP.md](../DOC-MAP.md)
|
|
@@ -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.
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
# ADR-0028: Governança visível — auditoria consultável + painel estático-gerado
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-19
|
|
5
|
+
- **Autor(es)**: Allan Pablo
|
|
6
|
+
- **Tags**: governance, audit, dashboard, token-economy
|
|
7
|
+
|
|
8
|
+
## Contexto
|
|
9
|
+
|
|
10
|
+
O core grava toda execução em `.context/forja-runs.jsonl` (ADR-0020): `{ts, cmd, args, exitCode,
|
|
11
|
+
durationMs}`. É o dado mais rico de governança do framework — a resposta viva para *"o processo foi
|
|
12
|
+
seguido? o que reprovou? quanto custou?"* — e era **write-only**. Para saber "quantas vezes o
|
|
13
|
+
`release:check` reprovou", alguém abria um `.jsonl` de centenas de linhas e contava na mão. Dado que
|
|
14
|
+
existe mas não é consultável é dado morto — a mesma classe que a sessão inteira atacou.
|
|
15
|
+
|
|
16
|
+
E faltava superfície visual. A tentativa anterior (SPEC-002) foi **congelada** (ADR-0022) — mas o
|
|
17
|
+
motivo não foi "ser visual": foi ser um **servidor** com rotas que *executavam* processos
|
|
18
|
+
(`POST .../run/:role`), um passivo de manutenção e de segurança. A lição é "sem servidor, sem
|
|
19
|
+
execução", não "sem visual".
|
|
20
|
+
|
|
21
|
+
## Decisão
|
|
22
|
+
|
|
23
|
+
Três comandos no domínio `governanca`, todos passando pelo core:
|
|
24
|
+
|
|
25
|
+
- **`audit:sync`** — projeta o `.jsonl` numa tabela `audit_runs` do `universal.db`. A tabela é
|
|
26
|
+
**projeção reconstruível**; o `.jsonl` segue sendo a fonte de verdade append-only.
|
|
27
|
+
- **`audit:query`** — consulta estruturada (`--failed`, `--cmd`, `--since 7d`).
|
|
28
|
+
- **`governance:dashboard`** — gera um HTML **estático, self-contained** (gates, pipeline SDD,
|
|
29
|
+
auditoria, métricas). Um arquivo, aberto com `file://`. **Não executa nada.**
|
|
30
|
+
|
|
31
|
+
Princípios:
|
|
32
|
+
|
|
33
|
+
- **D1 — A tabela é projeção; o `.jsonl` é a verdade.** Gravar direto no SQLite no core acoplaria
|
|
34
|
+
toda execução ao banco (que pode estar morto, ADR-0021). O log em arquivo é resiliente; a tabela é
|
|
35
|
+
derivada, reconstruível por `audit:sync`.
|
|
36
|
+
- **D2 — Idempotência por `line_hash`**, não por cursor. Hash do conteúdo da linha como PK +
|
|
37
|
+
`INSERT OR IGNORE`. Robusto a re-sync e a truncamento do log.
|
|
38
|
+
- **D3 — SQL estruturado, não FTS5.** O dado é colunar (`cmd`, `exit`, `duração`, `ts`); query por
|
|
39
|
+
coluna responde as perguntas reais. FTS5 seria over-engineering aqui.
|
|
40
|
+
- **D4 — O painel não executa gates.** Mostra os checks de cada catálogo (`health`/`release`) + o
|
|
41
|
+
**último exit** daquele comando na auditoria. Estado real, sem reexecutar — reforça o "sem
|
|
42
|
+
execução" do ADR-0022.
|
|
43
|
+
- **D5 — Comando novo, não estender `project:dashboard`.** Aquele é markdown sobre o ecossistema de
|
|
44
|
+
projetos; este é HTML sobre a saúde do framework. Coexistem.
|
|
45
|
+
- **D6 — Self-contained obrigatório.** CSS inline, zero asset externo, zero `<script>`. Abre com
|
|
46
|
+
`file://`. É o que separa este painel do servidor congelado.
|
|
47
|
+
|
|
48
|
+
## Alternativas consideradas
|
|
49
|
+
|
|
50
|
+
- **Ressuscitar o dashboard-servidor** — rejeitada: é exatamente o que o ADR-0022 congelou.
|
|
51
|
+
Artefato gerado entrega o visual sem o passivo.
|
|
52
|
+
- **Gravar a auditoria direto no SQLite** — rejeitada: acopla execução ao banco e perde a
|
|
53
|
+
resiliência do log em arquivo (D1).
|
|
54
|
+
- **FTS5 na auditoria** — rejeitada: o dado é estruturado; SQL por coluna basta (D3).
|
|
55
|
+
- **O painel executar os gates para mostrar o estado atual** — rejeitada: lento, com efeito
|
|
56
|
+
colateral, e reintroduz "execução" na superfície visual. O último exit da auditoria é estado real
|
|
57
|
+
o suficiente (D4).
|
|
58
|
+
|
|
59
|
+
## Consequências
|
|
60
|
+
|
|
61
|
+
**Positivas**:
|
|
62
|
+
- "Quantas vezes o `release:check` reprovou?" passou de contagem manual a **uma query**. Medido em
|
|
63
|
+
campo na implementação: 34 runs, 9 reprovações (as reprovações reais da própria sessão).
|
|
64
|
+
- O Forja ganha superfície visual **sem** repetir o erro do ADR-0022 — é arquivo, não serviço.
|
|
65
|
+
- O resumo de auditoria que um agente lê é menor em tokens que o `.jsonl` cru — governança visível
|
|
66
|
+
também economiza contexto (ADR-0009).
|
|
67
|
+
|
|
68
|
+
**Negativas / Trade-offs**:
|
|
69
|
+
- O estado dos gates no painel é o *último* exit registrado, não um check ao vivo — pode estar
|
|
70
|
+
defasado se o gate não roda há tempo. É o preço consciente do "sem execução" (D4); quem quer o
|
|
71
|
+
estado agora roda `tools:doctor`.
|
|
72
|
+
- Duas superfícies de "dashboard" (`project:dashboard` markdown + `governance:dashboard` HTML). Uma
|
|
73
|
+
unificação futura é possível, mas fundir agora confundiria dois públicos (D5).
|
|
74
|
+
|
|
75
|
+
## Rastreamento
|
|
76
|
+
|
|
77
|
+
- Implementação: `lib/audit.mjs`, `lib/governance-report.mjs`, `scripts/audit-{sync,query}.mjs`,
|
|
78
|
+
`scripts/governance-dashboard.mjs`, `scripts/memory-schema.mjs` (tabela `audit_runs`)
|
|
79
|
+
- Spec: `specs/governanca-visivel/` (SPEC-014)
|
|
80
|
+
- ADRs relacionadas: ADR-0022 (dashboard congelado — a decisão que este responde corretamente),
|
|
81
|
+
ADR-0020 (o core que grava a auditoria), ADR-0021 (resiliência: log em arquivo > banco), ADR-0009
|
|
82
|
+
(economia de tokens)
|
|
83
|
+
- **Follow-up**: instrumentar custo de token por tarefa (o audit grava duração, não tokens); o painel
|
|
84
|
+
já tem lugar para isso.
|
package/package.json
CHANGED
|
@@ -1,18 +1,16 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "forjajs",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.3.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",
|
|
7
7
|
"bin": {
|
|
8
|
-
"forja": "bin/forja.
|
|
9
|
-
"init-project": "bin/init-project.js",
|
|
10
|
-
"create-memory-nest-kit": "bin/create-memory-nest-kit.js"
|
|
8
|
+
"forja": "dist/bin/forja.js",
|
|
9
|
+
"init-project": "dist/bin/init-project.js",
|
|
10
|
+
"create-memory-nest-kit": "dist/bin/create-memory-nest-kit.js"
|
|
11
11
|
},
|
|
12
12
|
"files": [
|
|
13
|
-
"
|
|
14
|
-
"lib/",
|
|
15
|
-
"scripts/",
|
|
13
|
+
"dist/",
|
|
16
14
|
"prompts/",
|
|
17
15
|
"boilerplates/",
|
|
18
16
|
"design-md/",
|
|
@@ -36,55 +34,57 @@
|
|
|
36
34
|
],
|
|
37
35
|
"scripts": {
|
|
38
36
|
"//prepublishOnly": "Gate do tarball (ADR-0024). NUNCA mova para prepack: o gate roda `npm pack`, e o prepack o dispararia de novo — recursão infinita. npm pack não dispara prepublishOnly, e é por isso que ele é o único hook seguro aqui.",
|
|
39
|
-
"prepublishOnly": "node bin/forja.
|
|
40
|
-
"forja": "node bin/forja.
|
|
41
|
-
"sync:universal": "node bin/forja.
|
|
42
|
-
"query:universal": "node bin/forja.
|
|
43
|
-
"dev": "node scripts/dev.
|
|
44
|
-
"init:project": "node bin/forja.
|
|
45
|
-
"sprint:start": "node bin/forja.
|
|
46
|
-
"sprint:status": "node bin/forja.
|
|
47
|
-
"sprint:complete": "node bin/forja.
|
|
48
|
-
"context:smart": "node bin/forja.
|
|
49
|
-
"memory:compress": "node bin/forja.
|
|
50
|
-
"memory:vacuum": "node bin/forja.
|
|
51
|
-
"memory:schema": "node bin/forja.
|
|
52
|
-
"memory:extract": "node bin/forja.
|
|
53
|
-
"project:check": "node bin/forja.
|
|
54
|
-
"project:dashboard": "node bin/forja.
|
|
55
|
-
"context:budget": "node bin/forja.
|
|
56
|
-
"context:sprint": "node bin/forja.
|
|
57
|
-
"agent:brief": "node bin/forja.
|
|
58
|
-
"catalog:assets": "node bin/forja.
|
|
59
|
-
"catalog:manifests": "node bin/forja.
|
|
60
|
-
"token:benchmark": "node bin/forja.
|
|
61
|
-
"spec:new": "node bin/forja.
|
|
62
|
-
"spec:plan": "node bin/forja.
|
|
63
|
-
"spec:tasks": "node bin/forja.
|
|
64
|
-
"spec:check": "node bin/forja.
|
|
65
|
-
"agent:route": "node bin/forja.
|
|
66
|
-
"workspace:init": "node bin/forja.
|
|
67
|
-
"project:new": "node bin/forja.
|
|
68
|
-
"project:list": "node bin/forja.
|
|
69
|
-
"workspace:project:check": "node bin/forja.
|
|
70
|
-
"hermes:handoff": "node bin/forja.
|
|
71
|
-
"gsd:plan": "node bin/forja.
|
|
72
|
-
"gsd:handoff": "node bin/forja.
|
|
73
|
-
"gsd:check": "node bin/forja.
|
|
74
|
-
"design:check": "node bin/forja.
|
|
75
|
-
"design:select": "node bin/forja.
|
|
76
|
-
"ops:plan": "node bin/forja.
|
|
77
|
-
"ops:handoff": "node bin/forja.
|
|
78
|
-
"ops:check": "node bin/forja.
|
|
79
|
-
"ops:sprint": "node bin/forja.
|
|
80
|
-
"code:index": "node bin/forja.
|
|
81
|
-
"code:sync": "node bin/forja.
|
|
82
|
-
"code:status": "node bin/forja.
|
|
83
|
-
"code:query": "node bin/forja.
|
|
84
|
-
"code:check": "node bin/forja.
|
|
85
|
-
"code:impact": "node bin/forja.
|
|
86
|
-
"tools:doctor": "node bin/forja.
|
|
87
|
-
"release:check": "node bin/forja.
|
|
37
|
+
"prepublishOnly": "node bin/forja.ts release:check -- --publish",
|
|
38
|
+
"forja": "node bin/forja.ts",
|
|
39
|
+
"sync:universal": "node bin/forja.ts sync:universal",
|
|
40
|
+
"query:universal": "node bin/forja.ts query:universal",
|
|
41
|
+
"dev": "node scripts/dev.ts",
|
|
42
|
+
"init:project": "node bin/forja.ts init:project",
|
|
43
|
+
"sprint:start": "node bin/forja.ts sprint:start",
|
|
44
|
+
"sprint:status": "node bin/forja.ts sprint:status",
|
|
45
|
+
"sprint:complete": "node bin/forja.ts sprint:complete",
|
|
46
|
+
"context:smart": "node bin/forja.ts context:smart",
|
|
47
|
+
"memory:compress": "node bin/forja.ts memory:compress",
|
|
48
|
+
"memory:vacuum": "node bin/forja.ts memory:vacuum",
|
|
49
|
+
"memory:schema": "node bin/forja.ts memory:schema",
|
|
50
|
+
"memory:extract": "node bin/forja.ts memory:extract",
|
|
51
|
+
"project:check": "node bin/forja.ts project:check",
|
|
52
|
+
"project:dashboard": "node bin/forja.ts project:dashboard",
|
|
53
|
+
"context:budget": "node bin/forja.ts context:budget",
|
|
54
|
+
"context:sprint": "node bin/forja.ts context:sprint",
|
|
55
|
+
"agent:brief": "node bin/forja.ts agent:brief",
|
|
56
|
+
"catalog:assets": "node bin/forja.ts catalog:assets",
|
|
57
|
+
"catalog:manifests": "node bin/forja.ts catalog:manifests",
|
|
58
|
+
"token:benchmark": "node bin/forja.ts token:benchmark",
|
|
59
|
+
"spec:new": "node bin/forja.ts spec:new",
|
|
60
|
+
"spec:plan": "node bin/forja.ts spec:plan",
|
|
61
|
+
"spec:tasks": "node bin/forja.ts spec:tasks",
|
|
62
|
+
"spec:check": "node bin/forja.ts spec:check",
|
|
63
|
+
"agent:route": "node bin/forja.ts agent:route",
|
|
64
|
+
"workspace:init": "node bin/forja.ts workspace:init",
|
|
65
|
+
"project:new": "node bin/forja.ts project:new",
|
|
66
|
+
"project:list": "node bin/forja.ts project:list",
|
|
67
|
+
"workspace:project:check": "node bin/forja.ts workspace:project:check",
|
|
68
|
+
"hermes:handoff": "node bin/forja.ts hermes:handoff",
|
|
69
|
+
"gsd:plan": "node bin/forja.ts gsd:plan",
|
|
70
|
+
"gsd:handoff": "node bin/forja.ts gsd:handoff",
|
|
71
|
+
"gsd:check": "node bin/forja.ts gsd:check",
|
|
72
|
+
"design:check": "node bin/forja.ts design:check",
|
|
73
|
+
"design:select": "node bin/forja.ts design:select",
|
|
74
|
+
"ops:plan": "node bin/forja.ts gsd:plan",
|
|
75
|
+
"ops:handoff": "node bin/forja.ts gsd:handoff",
|
|
76
|
+
"ops:check": "node bin/forja.ts gsd:check",
|
|
77
|
+
"ops:sprint": "node bin/forja.ts sprint:status",
|
|
78
|
+
"code:index": "node bin/forja.ts code:index",
|
|
79
|
+
"code:sync": "node bin/forja.ts code:sync",
|
|
80
|
+
"code:status": "node bin/forja.ts code:status",
|
|
81
|
+
"code:query": "node bin/forja.ts code:query",
|
|
82
|
+
"code:check": "node bin/forja.ts code:check",
|
|
83
|
+
"code:impact": "node bin/forja.ts code:impact",
|
|
84
|
+
"tools:doctor": "node bin/forja.ts tools:doctor",
|
|
85
|
+
"release:check": "node bin/forja.ts release:check",
|
|
86
|
+
"build": "tsc -p tsconfig.build.json",
|
|
87
|
+
"types:check": "tsc --noEmit",
|
|
88
88
|
"test": "node --test test/*.test.js"
|
|
89
89
|
},
|
|
90
90
|
"keywords": [
|
|
@@ -108,5 +108,9 @@
|
|
|
108
108
|
},
|
|
109
109
|
"allowScripts": {
|
|
110
110
|
"better-sqlite3@12.11.1": true
|
|
111
|
+
},
|
|
112
|
+
"devDependencies": {
|
|
113
|
+
"@types/node": "^26.1.1",
|
|
114
|
+
"typescript": "^5.9.3"
|
|
111
115
|
}
|
|
112
116
|
}
|
|
@@ -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.
|