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
|
@@ -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.
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# Tasks: clean-arch-boilerplate
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Plan**: ./plan.md
|
|
5
|
+
- **Status**: approved
|
|
6
|
+
- **Criado em**: 2026-07-18
|
|
7
|
+
|
|
8
|
+
> Decomposição executável. O boilerplate é **conteúdo de template** (código do projeto gerado), não
|
|
9
|
+
> código do framework — não roda na CI do Forja. Escrever para ser referência idiomática correta.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## T1 — Esqueleto + `shared/`
|
|
14
|
+
- **Owner**: Worker · **Estimativa**: P · **Depende de**: —
|
|
15
|
+
- **Paths**: `boilerplates/06-clean-arch/backend/src/{shared,main.ts,app.module.ts}`
|
|
16
|
+
- **Done**: `Result`/erros de domínio/base VO; `main.ts`/`app.module.ts`; `package.json` + `tsconfig`
|
|
17
|
+
do projeto (com `test:e2e`, `start:dev` etc. — entram na allowlist derivada do SPEC-011).
|
|
18
|
+
|
|
19
|
+
## T2 — Fatia rica: Orders (as 4 camadas) — AC-1/2/3/5
|
|
20
|
+
- **Owner**: Worker · **Estimativa**: M · **Depende de**: T1
|
|
21
|
+
- **Paths**: `.../modules/orders/{domain,application,infrastructure,presentation}/*`, `orders.module.ts`
|
|
22
|
+
- **Done**:
|
|
23
|
+
- [ ] `domain/`: `Order` (agregado, invariantes: não confirma sem estoque, não envia sem pagamento),
|
|
24
|
+
`order-status.vo.ts`, `order.repository.ts` (porta = interface + token). **Zero `@nestjs`/ORM.**
|
|
25
|
+
- [ ] `application/`: `place-order`/`ship-order` use-cases com input/output tipados (contrato legível).
|
|
26
|
+
- [ ] `infrastructure/`: adapter TypeORM implementa a porta + mapper domínio↔orm-entity.
|
|
27
|
+
- [ ] `presentation/`: controller + HTTP DTOs mapeando p/ use-case.
|
|
28
|
+
- [ ] `orders.module.ts`: bind `{ provide: ORDER_REPOSITORY, useClass: TypeOrmOrderRepository }`.
|
|
29
|
+
|
|
30
|
+
## T3 — Teste da invariante sem Nest — AC-8
|
|
31
|
+
- **Owner**: Worker · **Estimativa**: P · **Depende de**: T2
|
|
32
|
+
- **Paths**: `.../backend/test/orders/place-order.spec.ts`
|
|
33
|
+
- **Done**: testa a invariante de domínio **instanciando só o agregado** (sem `Test.createTestingModule`,
|
|
34
|
+
sem ORM). É a prova concreta do isolamento — se precisar do Nest, o domínio vazou.
|
|
35
|
+
|
|
36
|
+
## T4 — Caminho enxuto: Products (1 camada) — AC-4
|
|
37
|
+
- **Owner**: Worker · **Estimativa**: P · **Depende de**: T1
|
|
38
|
+
- **Paths**: `.../modules/products/*`, `WHEN-CLEAN-WHEN-LEAN.md`
|
|
39
|
+
- **Done**: CRUD controller→repo direto, **sem** use-case/porta; o doc ensina o critério de escolha.
|
|
40
|
+
Kill criteria: se Products virar 4 camadas, a spec falhou.
|
|
41
|
+
|
|
42
|
+
## T5 — Memória por contexto (o vetor de token) — AC-6
|
|
43
|
+
- **Owner**: Worker · **Estimativa**: P · **Depende de**: T2, T4
|
|
44
|
+
- **Paths**: `.../memory/30-domains/{orders,products}/context.md`
|
|
45
|
+
- **Done**: cada contexto descrito na linguagem ubíqua — o que o agente lê **antes** do código.
|
|
46
|
+
Orders documenta as invariantes e os use-cases; Products, o CRUD raso.
|
|
47
|
+
|
|
48
|
+
## T6 — Manifesto + catálogo + README — AC-7
|
|
49
|
+
- **Owner**: Worker · **Estimativa**: P · **Depende de**: T1-T5
|
|
50
|
+
- **Paths**: `.../boilerplate.manifest.json`, `.../README.md`, `boilerplates/README.md`
|
|
51
|
+
- **Done**: manifesto no schema 1.0 (stack/useCases/commands); entrada no catálogo; README explicando
|
|
52
|
+
a estrutura e apontando o `WHEN-CLEAN-WHEN-LEAN.md`.
|
|
53
|
+
|
|
54
|
+
## T7 — Medir o token (métrica-norte) + ADR-0027 — AC-6/AC-10
|
|
55
|
+
- **Owner**: SDD Architect + Governance · **Estimativa**: P · **Depende de**: T5, T6
|
|
56
|
+
- **Paths**: `memory/90-decisions/0027-*.md`
|
|
57
|
+
- **Done**:
|
|
58
|
+
- [ ] Medir o pacote de contexto de "adicionar uma regra ao contexto orders" aqui vs. no
|
|
59
|
+
`02-saas-starter` flat. **Registrar os números.**
|
|
60
|
+
- [ ] ADR-0027: Clean Architecture calibrada; o porquê da calibração e o resultado da medição.
|
|
61
|
+
Se o token não caiu, o ADR diz isso e recalibra — não maquia.
|
|
62
|
+
|
|
63
|
+
## T8 — Gates (Governance) — AC-9
|
|
64
|
+
- **Owner**: Governance · **Estimativa**: P · **Depende de**: T6
|
|
65
|
+
- **Done**: `release:check` (boilerplate no `files[]`, instala limpo), `tools:doctor` (docs-commands
|
|
66
|
+
não acusa fantasma), `npm test` do Forja verde. spec → `done`.
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
## Handoffs
|
|
70
|
+
Worker (T1-T6), SDD Architect + Governance (T7-T8). `forja agent:route` a cada fronteira (ADR-0005).
|
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
# Plan: coerencia-do-sistema
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Criado em**: 2026-07-15
|
|
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
|
+
Três checks novos no catálogo de `health.mjs`, no molde dos que já existem (`runtime-deps`,
|
|
12
|
+
`mcp-json`): `scope: repo`, guardados por `isFrameworkRepo(env)`, cada um nomeando arquivo, linha e
|
|
13
|
+
correção. **Nenhuma máquina nova** — o runner de `checks.mjs` já roda tudo isso.
|
|
14
|
+
|
|
15
|
+
O que é genuinamente novo é a **leitura da documentação como dado**. Hoje o `health.mjs` lê código
|
|
16
|
+
(imports, `package.json`, `.mcp.json`); agora precisa ler os `.md` e extrair duas coisas: comandos
|
|
17
|
+
citados e links relativos. Isso vira `lib/core/doc-graph.mjs` — um scanner puro, sem opinião sobre
|
|
18
|
+
severidade, testável isoladamente. Os três checks são finos: chamam o scanner e comparam com a
|
|
19
|
+
verdade (o registry, o sistema de arquivos).
|
|
20
|
+
|
|
21
|
+
O ponto que decide se a spec vale a pena é o **AC-2**: a allowlist de comandos do projeto gerado
|
|
22
|
+
tem que ser *derivada*, não escrita. Confirmei em campo que dá: parsear o bloco `"scripts"` dos
|
|
23
|
+
`lib/generators/*.js` produz exatamente `start:dev`, `test:cov`, `memory:db:*` etc. — os 7 falsos
|
|
24
|
+
positivos que a auditoria manual pegou. Lista manual mente com o tempo; a derivada acompanha o
|
|
25
|
+
gerador sozinha.
|
|
26
|
+
|
|
27
|
+
## 2. Módulos afetados
|
|
28
|
+
|
|
29
|
+
| Caminho | Mudança | Risco |
|
|
30
|
+
|---|---|---|
|
|
31
|
+
| `lib/core/doc-graph.mjs` | **criar** — scanner puro: cita comandos, coleta links, deriva allowlist | M |
|
|
32
|
+
| `lib/core/health.mjs` | editar — 3 checks novos no `CHECKS[]` | B |
|
|
33
|
+
| `test/doc-graph.test.js` | **criar** — o scanner, isolado | B |
|
|
34
|
+
| `test/health.test.js` | editar — os 3 checks nos dois estados, incluindo o falso positivo do AC-2 | B |
|
|
35
|
+
| `docs/token-optimization.md` etc. | corrigir o que o check acusar (já limpo na v1.1.4, mas o gate é quem confirma) | B |
|
|
36
|
+
| `README`/`docs` | documentar `memory:extract` (AC-10) | B |
|
|
37
|
+
| `memory/90-decisions/0025-*.md` | **criar** — ADR | B |
|
|
38
|
+
|
|
39
|
+
Risco no `doc-graph.mjs`, não no `health.mjs`: os checks são triviais; a dificuldade toda é o
|
|
40
|
+
scanner não gerar falso positivo. Um `docs-commands` que acusa demais reprova a documentação
|
|
41
|
+
inteira e é desligado no primeiro dia — pior que não existir.
|
|
42
|
+
|
|
43
|
+
## 3. Diagrama de fluxo
|
|
44
|
+
|
|
45
|
+
```
|
|
46
|
+
tools:doctor (scope: repo)
|
|
47
|
+
│
|
|
48
|
+
▼
|
|
49
|
+
┌──────────────── lib/core/doc-graph.mjs ────────────────┐
|
|
50
|
+
│ scanDocs(env) → [{ file, line, command }] │ citações forja/npm run
|
|
51
|
+
│ scanLinks(env) → [{ file, line, target }] │ links markdown relativos
|
|
52
|
+
│ projectCommands(env) → Set<string> │ derivada de lib/generators/
|
|
53
|
+
└────────────────────────────────────────────────────────┘
|
|
54
|
+
│ │ │
|
|
55
|
+
▼ ▼ ▼
|
|
56
|
+
docs-commands docs-links commands-documented
|
|
57
|
+
(critical) (warn) (warn)
|
|
58
|
+
citado ∈ registry target existe registry ⊆ citados
|
|
59
|
+
∪ projectCommands nos .md
|
|
60
|
+
│ │ │
|
|
61
|
+
└──────────── Result[] { file, line, detail, fix } ──────────┘
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## 4. Contratos (API/CLI/Schema)
|
|
65
|
+
|
|
66
|
+
```js
|
|
67
|
+
// lib/core/doc-graph.mjs — leitura pura, sem juízo de severidade
|
|
68
|
+
|
|
69
|
+
/** Superfícies de instrução escaneadas. docs/archive, boilerplates e specs ficam de fora (§5 D3). */
|
|
70
|
+
export const DOC_SURFACES; // ['docs', 'prompts', '.claude/agents', 'AGENTS.md', 'CLAUDE.md', 'README.md', 'README.en.md', 'DOC-MAP.md']
|
|
71
|
+
|
|
72
|
+
/** Comandos citados como `forja x:y` ou `npm run x:y` em bloco de código. { file, line, command } */
|
|
73
|
+
export function scanCommands(env);
|
|
74
|
+
|
|
75
|
+
/** Links markdown relativos (não http, âncora ignorada). { file, line, target } */
|
|
76
|
+
export function scanLinks(env);
|
|
77
|
+
|
|
78
|
+
/** Allowlist DERIVADA: keys do bloco "scripts" dos geradores. Nunca uma lista literal. */
|
|
79
|
+
export function projectCommands(env); // -> Set<string>
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
**Regex de comando** — casa `(?:forja |npm run )` seguido de um token **com ao menos um `:`**
|
|
83
|
+
(`spec:new`, `code:impact`). O `:` é o discriminador: todo comando do registry o tem, e nenhuma
|
|
84
|
+
prosa (`"forja does X"`) o casa por acidente. Só dentro de bloco/span de código — prosa livre.
|
|
85
|
+
|
|
86
|
+
**Contrato dos checks** (severidade honesta, AC-6):
|
|
87
|
+
|
|
88
|
+
| Check | Severity | Reprova quando | Fix prescrito |
|
|
89
|
+
|---|---|---|---|
|
|
90
|
+
| `docs-commands` | critical | comando citado ∉ registry ∪ `projectCommands` | "renomeie para `<x>` ou remova a citação em `file:line`" |
|
|
91
|
+
| `commands-documented` | warn | comando do registry citado em nenhum `.md` | "documente `<cmd>` em algum `.md` (ou remova do registry)" |
|
|
92
|
+
| `docs-links` | warn | link relativo aponta para inexistente | "crie o alvo ou corrija o link em `file:line`" |
|
|
93
|
+
|
|
94
|
+
## 5. Decisões e alternativas
|
|
95
|
+
|
|
96
|
+
**D1: Scanner puro separado dos checks.** `doc-graph.mjs` lê e devolve dados; os checks julgam.
|
|
97
|
+
Permite testar o parsing (a parte difícil) sem montar o ambiente do doctor, e permite que um quarto
|
|
98
|
+
consumidor use o mesmo scan amanhã. Alternativa rejeitada: lógica de parsing embutida em cada check
|
|
99
|
+
— foi assim que o `runtime-deps` e o `release.mjs` acabaram com dois parsers de import quase iguais.
|
|
100
|
+
|
|
101
|
+
**D2: Allowlist derivada dos geradores (AC-2).** A prova de fogo da spec. `projectCommands(env)`
|
|
102
|
+
parseia o bloco `"scripts"` dos `lib/generators/*.js`. Alternativa rejeitada: lista literal no
|
|
103
|
+
código — é a armadilha do `.gitignore` da SPEC-009, onde a allow-list manual engoliu uma spec em
|
|
104
|
+
silêncio. Uma lista que não acompanha o gerador vira mentira no primeiro comando novo do boilerplate.
|
|
105
|
+
|
|
106
|
+
**D3: Escopo do scan — instrução, não histórico.** Escaneia `docs/` (menos `archive/`), `prompts/`,
|
|
107
|
+
`.claude/agents/` e os `.md` de raiz. **Fora**: `docs/archive/` (legado, off-limits), `boilerplates/`
|
|
108
|
+
(é conteúdo do projeto gerado — cita comandos do projeto, não do Forja), `specs/` e `memory/90-*`
|
|
109
|
+
(registro histórico: uma spec ou ADR pode legitimamente citar um comando proposto ou já removido).
|
|
110
|
+
O gate protege o que instrui o agente *agora*, não o que registrou o passado.
|
|
111
|
+
|
|
112
|
+
**D4: `:` como discriminador de comando.** Em vez de tentar entender a gramática do CLI, exijo o
|
|
113
|
+
`:`. Simples, e cobre 42/42 do registry. Um comando futuro sem `:` escaparia — mas hoje nenhum
|
|
114
|
+
existe, e inventar parser de gramática para um caso inexistente é criar o problema que não temos.
|
|
115
|
+
|
|
116
|
+
**D5: `docs-commands` é o único crítico.** Comando fantasma faz o agente agir errado — trava.
|
|
117
|
+
Comando não-documentado e link quebrado atrapalham mas não param ninguém: `warn`. Reprovar release
|
|
118
|
+
por um link quebrado num doc é como o `deps-unused` seria se fosse crítico — ensina o time a ignorar
|
|
119
|
+
o gate.
|
|
120
|
+
|
|
121
|
+
**D6: `memory:extract` — decisão adiada para as tasks.** É o único órfão real. Documentar ou remover
|
|
122
|
+
é chamada de quem conhece o uso dele; o plano não força a mão. O que o plano garante é que, depois,
|
|
123
|
+
o `commands-documented` não deixa nascer um órfão novo.
|
|
124
|
+
|
|
125
|
+
D1, D2 e D3 são estruturais → **ADR-0025**, referenciando ADR-0023/0024 (mesma família de gate,
|
|
126
|
+
terceira fronteira: a instrução) e ADR-0021 (a classe "erra sem avisar").
|
|
127
|
+
|
|
128
|
+
## 6. Dependências
|
|
129
|
+
|
|
130
|
+
- **Specs**: SPEC-009 (`health.mjs`/`checks.mjs` são a base). Já `done`.
|
|
131
|
+
- **Pacotes npm**: **nenhum novo.** `node:fs` e regex. Parsear markdown com um lexer completo seria
|
|
132
|
+
peso morto — precisamos de citações em code-span e links, não de um AST de CommonMark.
|
|
133
|
+
- **Migrações**: nenhuma.
|
|
134
|
+
|
|
135
|
+
## 7. Rollout
|
|
136
|
+
|
|
137
|
+
- [ ] **Ordem**: `doc-graph.mjs` + seus testes primeiro (nada o consome ainda) → os 3 checks →
|
|
138
|
+
rodar o doctor e **corrigir o que ele acusar** → CI já pega de graça (o doctor já é step, ADR-0024).
|
|
139
|
+
- [x] Doc/persona: governança ganha mais um critério; nenhuma persona muda de fluxo.
|
|
140
|
+
- [ ] **Validar o AC-2 de verdade**: adicionar um `"foo:bar"` temporário aos scripts de um gerador e
|
|
141
|
+
confirmar que `docs-commands` **não** passa a exigir `foo:bar` na doc. Se exigir, a derivação
|
|
142
|
+
não está pegando o gerador certo.
|
|
143
|
+
- [ ] O primeiro `npm run tools:doctor` depois disto é o teste real: ele deve passar (a doc já foi
|
|
144
|
+
limpa na v1.1.4), provando que o gate concorda com a correção manual — não inventa trabalho.
|
|
145
|
+
|
|
146
|
+
## 8. Sinais de fracasso (kill criteria)
|
|
147
|
+
|
|
148
|
+
- **`docs-commands` gera um falso positivo crítico.** Se acontecer uma vez com comando legítimo, ele
|
|
149
|
+
é rebaixado a `warn` até o scanner ser corrigido — um crítico que mente é pior que um warning
|
|
150
|
+
honesto, e aqui ele bloquearia o CI de todo mundo.
|
|
151
|
+
- **O scanner fica caro.** Se ler os `.md` todos passar de ~1s, o scan vira lazy/cacheado por mtime —
|
|
152
|
+
mas os checks são `scope: repo`, fora do `SessionStart`, então a folga é grande.
|
|
153
|
+
- **A regra vira desincentivo a documentar.** Se alguém parar de escrever doc para não "brigar com o
|
|
154
|
+
gate", erramos: o gate só cobre citação de *comando*, e isso precisa estar claro na mensagem de
|
|
155
|
+
erro (que aponta a linha e diz "renomeie ou remova a citação", nunca "não escreva").
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# Spec: coerencia-do-sistema
|
|
2
2
|
|
|
3
3
|
- **ID**: SPEC-011
|
|
4
|
-
- **Status**:
|
|
4
|
+
- **Status**: done
|
|
5
5
|
- **Owner**: apk
|
|
6
6
|
- **Criado em**: 2026-07-14
|
|
7
7
|
- **Sprint alvo**: S?
|
|
@@ -53,28 +53,29 @@ agente.
|
|
|
53
53
|
|
|
54
54
|
## 4. Critérios de aceite (Definition of Done)
|
|
55
55
|
|
|
56
|
-
- [
|
|
56
|
+
- [x] AC-1: Check `docs-commands` (`scope: repo`, catálogo de `health.mjs`): todo `npm run <cmd>` /
|
|
57
57
|
`forja <cmd>` citado em `docs/`, `prompts/`, `.claude/agents/`, `AGENTS.md`, `CLAUDE.md` e
|
|
58
58
|
`README.md` existe no registry (ADR-0020).
|
|
59
|
-
- [
|
|
59
|
+
- [x] AC-2: **Comandos do projeto gerado não contam.** `start:dev`, `test:cov`, `memory:db:*` e
|
|
60
60
|
afins são do NestJS/Jest do projeto que o Forja **gera**, não do Forja. A allowlist é derivada
|
|
61
61
|
dos geradores, **não escrita à mão** — uma lista manual mente com o tempo (foi a lição do
|
|
62
62
|
`.gitignore` na SPEC-009). 7 dos 11 "fantasmas" da auditoria eram isto.
|
|
63
|
-
- [
|
|
64
|
-
mencionado em pelo menos um `.md` versionado. Hoje
|
|
65
|
-
|
|
63
|
+
- [x] AC-3: Check `commands-documented` (**warn**, `scope: repo`): todo comando do registry é
|
|
64
|
+
mencionado em pelo menos um `.md` versionado. Hoje 1 de 42 não é (`memory:extract`) — a
|
|
65
|
+
reescrita canônica do README na v1.1.5 já documentou `workspace:project:check`.
|
|
66
|
+
- [x] AC-4: Check `docs-links` (**warn**, `scope: repo`): todo link markdown relativo entre arquivos
|
|
66
67
|
versionados resolve. `docs/DEPLOYMENT.md` era link para o nada.
|
|
67
|
-
- [
|
|
68
|
+
- [x] AC-5: Os três checks entram no `tools:doctor` e, por consequência, no CI — que já roda o
|
|
68
69
|
doctor na matriz (ADR-0024).
|
|
69
|
-
- [
|
|
70
|
+
- [x] AC-6: **Severidades honestas.** `docs-commands` é `critical` (comando fantasma faz o agente
|
|
70
71
|
agir errado). `commands-documented` e `docs-links` são `warn` (atrapalham, não impedem). Um
|
|
71
72
|
gate que reprova o que não impede trabalho é um gate que se aprende a ignorar.
|
|
72
|
-
- [
|
|
73
|
+
- [x] AC-7: Toda reprovação nomeia **arquivo e linha** e prescreve a correção. O gate que diz "algo
|
|
73
74
|
está errado" sem dizer onde é só mais um step obscuro.
|
|
74
|
-
- [
|
|
75
|
-
- [
|
|
76
|
-
- [
|
|
77
|
-
|
|
75
|
+
- [x] AC-8: Testes com fixture para cada check nos dois estados, incluindo o falso positivo do AC-2.
|
|
76
|
+
- [x] AC-9: ADR-0025 registrando a decisão.
|
|
77
|
+
- [x] AC-10: O comando órfão restante (`memory:extract`) é documentado — ou removido do registry,
|
|
78
|
+
se não servir mais. Capacidade obscura é capacidade morta.
|
|
78
79
|
|
|
79
80
|
## 5. Escopo
|
|
80
81
|
|
|
@@ -82,7 +83,7 @@ agente.
|
|
|
82
83
|
- `lib/core/health.mjs` — os três checks novos (o catálogo do repo).
|
|
83
84
|
- `lib/core/doc-graph.mjs` — varredura dos `.md` versionados: comandos citados, links relativos.
|
|
84
85
|
- Derivação automática da allowlist de comandos do projeto gerado, a partir de `lib/generators/`.
|
|
85
|
-
- Documentar
|
|
86
|
+
- Documentar o comando órfão restante (`memory:extract`), ou removê-lo.
|
|
86
87
|
- ADR-0025 + testes.
|
|
87
88
|
|
|
88
89
|
**Fora** (explícito):
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
# Tasks: coerencia-do-sistema
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Plan**: ./plan.md
|
|
5
|
+
- **Status**: done
|
|
6
|
+
- **Criado em**: 2026-07-15
|
|
7
|
+
|
|
8
|
+
> Decomposição executável. Cada task tem dono claro, critério de done e referência a arquivos.
|
|
9
|
+
|
|
10
|
+
Ordem do plano §7: o scanner e seus testes primeiro (nada o consome), depois os três checks, depois
|
|
11
|
+
rodar o doctor e corrigir o que ele acusar. O CI pega de graça — `tools:doctor` já é step (ADR-0024).
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## T1 — `doc-graph.mjs`: o scanner puro
|
|
16
|
+
- **Owner**: Worker
|
|
17
|
+
- **Estimativa**: M
|
|
18
|
+
- **Depende de**: —
|
|
19
|
+
- **Paths**: `lib/core/doc-graph.mjs`, `test/doc-graph.test.js`
|
|
20
|
+
- **Escopo**: leitura pura, zero juízo de severidade. É a parte difícil — todo o risco da spec mora
|
|
21
|
+
aqui, no não-gerar-falso-positivo.
|
|
22
|
+
- **Done quando**:
|
|
23
|
+
- [ ] `scanCommands(env)` devolve `{ file, line, command }` para cada `forja <cmd>` / `npm run <cmd>`
|
|
24
|
+
onde `<cmd>` tem ao menos um `:` (o discriminador do plano §D4)
|
|
25
|
+
- [ ] `scanLinks(env)` devolve `{ file, line, target }` para links markdown **relativos**; ignora
|
|
26
|
+
`http(s)://` e âncoras (`#sec`). Link para diretório (`memory/90-decisions/`) conta como alvo
|
|
27
|
+
- [ ] `projectCommands(env)` **deriva** a allowlist das keys do bloco `"scripts"` dos
|
|
28
|
+
`lib/generators/*.js` — nunca uma lista literal (plano §D2). Retorna Set
|
|
29
|
+
- [ ] `DOC_SURFACES` exportado; escaneia `docs/` (menos `archive/`), `prompts/`, `.claude/agents/`
|
|
30
|
+
e os `.md` de raiz. **Não** varre `boilerplates/`, `specs/`, `memory/` (plano §D3)
|
|
31
|
+
- [ ] `env` injetável (`{ root, fs }`) no padrão de `checks.mjs`, para os testes não tocarem o disco
|
|
32
|
+
- [ ] `test/doc-graph.test.js`: fixtures cobrindo comando com/sem `:`, link relativo/http/âncora/
|
|
33
|
+
diretório, e a derivação pegando um `"foo:bar"` de um gerador de fixture
|
|
34
|
+
|
|
35
|
+
## T2 — Check `docs-commands` (critical)
|
|
36
|
+
- **Owner**: Worker
|
|
37
|
+
- **Estimativa**: P
|
|
38
|
+
- **Depende de**: T1
|
|
39
|
+
- **Paths**: `lib/core/health.mjs`, `test/health.test.js`
|
|
40
|
+
- **Done quando**:
|
|
41
|
+
- [ ] `scope: 'repo'`, guardado por `isFrameworkRepo(env)` — não roda numa instalação `forjajs`
|
|
42
|
+
- [ ] Reprova (critical) quando comando citado ∉ `registry ∪ projectCommands` (AC-1, AC-2)
|
|
43
|
+
- [ ] `detail` nomeia `file:line` e o comando ofensor; `fix` diz "renomeie ou remova a citação"
|
|
44
|
+
— nunca "não escreva" (kill criteria do plano §8)
|
|
45
|
+
- [ ] **Teste do falso positivo (AC-2, a prova de fogo)**: doc citando `npm run start:dev` (comando
|
|
46
|
+
do projeto gerado) **não** reprova; doc citando `forja fantasma:x` reprova
|
|
47
|
+
- [ ] Teste: comando real do registry citado passa
|
|
48
|
+
|
|
49
|
+
## T3 — Checks `commands-documented` e `docs-links` (warn)
|
|
50
|
+
- **Owner**: Worker
|
|
51
|
+
- **Estimativa**: P
|
|
52
|
+
- **Depende de**: T1
|
|
53
|
+
- **Paths**: `lib/core/health.mjs`, `test/health.test.js`
|
|
54
|
+
- **Done quando**:
|
|
55
|
+
- [ ] `commands-documented` (**warn**): comando do registry citado em nenhuma superfície → aviso
|
|
56
|
+
com "documente em algum `.md` ou remova do registry" (AC-3). `worstStatus` não escala warn
|
|
57
|
+
- [ ] `docs-links` (**warn**): link relativo sem alvo → aviso com `file:line` e o alvo (AC-4)
|
|
58
|
+
- [ ] Ambos `scope: 'repo'`, guardados por `isFrameworkRepo`
|
|
59
|
+
- [ ] Teste de cada um nos dois estados (são/quebrado)
|
|
60
|
+
- [ ] Teste garantindo que os três checks novos são `skipped` fora do repo do framework
|
|
61
|
+
|
|
62
|
+
## T4 — Rodar o gate e reconciliar a realidade
|
|
63
|
+
- **Owner**: Worker
|
|
64
|
+
- **Estimativa**: P
|
|
65
|
+
- **Depende de**: T2, T3
|
|
66
|
+
- **Paths**: `docs/`, `README.md`/`README.en.md`, conforme o gate acusar
|
|
67
|
+
- **Escopo**: o primeiro `tools:doctor` com os checks ligados é o teste real — ele deve **concordar
|
|
68
|
+
com as correções manuais** já feitas (a doc foi limpa na v1.1.4), não inventar trabalho novo.
|
|
69
|
+
- **Done quando**:
|
|
70
|
+
- [ ] `forja tools:doctor` roda com os 3 checks e o núcleo fica **verde ou só com warns**
|
|
71
|
+
- [ ] Qualquer `docs-commands` crítico remanescente é corrigido na fonte (renomear/remover citação)
|
|
72
|
+
- [ ] AC-10: `memory:extract` — documentar numa superfície escaneada **ou** remover do registry.
|
|
73
|
+
Decisão de quem conhece o uso; qualquer das duas fecha o `commands-documented` warn
|
|
74
|
+
- [ ] `docs-links` warns zerados ou reduzidos a alvos que se decide criar depois (registrar quais)
|
|
75
|
+
|
|
76
|
+
## T5 — Validação executável do AC-2
|
|
77
|
+
- **Owner**: Worker
|
|
78
|
+
- **Estimativa**: P
|
|
79
|
+
- **Depende de**: T2
|
|
80
|
+
- **Paths**: `test/health.test.js` (ou um teste dedicado)
|
|
81
|
+
- **Escopo**: garantir que a derivação é *real*, não que o teste passou por sorte.
|
|
82
|
+
- **Done quando**:
|
|
83
|
+
- [ ] Teste que injeta um `"foo:bar"` no bloco `scripts` de um gerador de fixture e confirma que
|
|
84
|
+
`docs-commands` passa a **aceitar** `foo:bar` na doc — provando que a allowlist segue o
|
|
85
|
+
gerador, não uma lista congelada (plano §7)
|
|
86
|
+
|
|
87
|
+
## T6 — ADR-0025 e CI
|
|
88
|
+
- **Owner**: SDD Architect + Worker
|
|
89
|
+
- **Estimativa**: P
|
|
90
|
+
- **Depende de**: T2, T3, T4
|
|
91
|
+
- **Paths**: `memory/90-decisions/0025-*.md`, `.github/workflows/ci.yml` (verificar)
|
|
92
|
+
- **Done quando**:
|
|
93
|
+
- [ ] ADR-0025 registra D1 (scanner puro), D2 (allowlist derivada) e D3 (escopo = instrução, não
|
|
94
|
+
histórico); referencia ADR-0023/0024 (a família de gate, terceira fronteira) e ADR-0021
|
|
95
|
+
- [ ] Confirmar que o CI **já** exercita os checks via `tools:doctor` (step do ADR-0024) — não deve
|
|
96
|
+
precisar de mudança no workflow; se precisar, ajustar
|
|
97
|
+
- [ ] `npm test` verde, `spec:check` verde
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## Validação final
|
|
102
|
+
- [ ] Renomear um comando do registry num teste e confirmar que `docs-commands` **acusa** a doc que
|
|
103
|
+
ainda usa o nome antigo — a métrica de sucesso da spec (renomear vira ato detectável)
|
|
104
|
+
- [ ] Suíte completa verde; `tools:doctor` verde/warn; spec → `done`
|
|
105
|
+
|
|
106
|
+
## Nota de implementação — o code-span é endurecimento, não requisito
|
|
107
|
+
O plano §4 menciona "só dentro de bloco/span de código". A auditoria manual que originou esta spec
|
|
108
|
+
usou **scan de arquivo inteiro** + discriminador `:` e funcionou — os únicos falsos positivos foram
|
|
109
|
+
os comandos do projeto gerado, tratados pela allowlist (T2). Começar pelo scan de arquivo inteiro; só
|
|
110
|
+
adicionar consciência de code-span **se** T2/T4 revelarem um falso positivo que o `:` não filtre. Não
|
|
111
|
+
construir parser de markdown para um problema que ainda não apareceu (plano §6).
|
|
112
|
+
|
|
113
|
+
## Handoffs entre agentes
|
|
114
|
+
Worker (T1-T5), SDD Architect (T6). Handoff a cada fronteira via `forja agent:route` — 7 campos
|
|
115
|
+
(ADR-0005).
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
# Plan: governanca-visivel
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Criado em**: 2026-07-19
|
|
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
|
+
Três comandos no domínio `governanca`, todos passando pelo core (auditados como os demais):
|
|
12
|
+
|
|
13
|
+
- `audit:sync` — ingest do `.context/forja-runs.jsonl` (fonte de verdade append-only) numa tabela
|
|
14
|
+
`audit_runs` do `universal.db` do workspace. A tabela é **projeção reconstruível**: o `.jsonl`
|
|
15
|
+
manda.
|
|
16
|
+
- `audit:query` — consulta estruturada (`--since`, `--cmd`, `--gate`, `--failed`).
|
|
17
|
+
- `governance:dashboard` — gera um HTML **estático e self-contained** de governança.
|
|
18
|
+
|
|
19
|
+
O painel **não executa nada** — lê specs, ADRs e a tabela de auditoria e escreve um arquivo. É a
|
|
20
|
+
resposta correta ao ADR-0022: o dashboard antigo era servidor com rotas; este é um *artefato*, como
|
|
21
|
+
o `project:dashboard` já é (só que HTML e sobre governança). O design do HTML reaproveita o protótipo
|
|
22
|
+
já validado nesta sessão.
|
|
23
|
+
|
|
24
|
+
## 2. Módulos afetados
|
|
25
|
+
|
|
26
|
+
| Caminho | Mudança | Risco |
|
|
27
|
+
|---|---|---|
|
|
28
|
+
| `scripts/memory-schema.mjs` | criar tabela `audit_runs` (+ índices) | B |
|
|
29
|
+
| `lib/audit.mjs` | **criar** — ingest do jsonl + queries (puro, testável) | M |
|
|
30
|
+
| `scripts/audit-sync.mjs` · `scripts/audit-query.mjs` | **criar** — CLIs finos sobre `lib/audit.mjs` | B |
|
|
31
|
+
| `lib/governance-report.mjs` | **criar** — coleta (specs/ADRs/audit/métricas) + render HTML self-contained | M |
|
|
32
|
+
| `scripts/governance-dashboard.mjs` | **criar** — CLI que escreve o arquivo | B |
|
|
33
|
+
| `lib/core/registry.mjs` | 3 entradas novas (`governanca`) | B |
|
|
34
|
+
| `test/audit.test.js` · `test/governance-report.test.js` | **criar** | B |
|
|
35
|
+
| `memory/90-decisions/0028-*.md` | **criar** — ADR | B |
|
|
36
|
+
|
|
37
|
+
Risco mora na coleta (`governance-report`): ler dados reais sem quebrar quando faltam (repo sem runs,
|
|
38
|
+
sem workspace). A renderização é mecânica; o design já está provado.
|
|
39
|
+
|
|
40
|
+
## 3. Fluxo
|
|
41
|
+
|
|
42
|
+
```
|
|
43
|
+
.context/forja-runs.jsonl ──audit:sync──► audit_runs (universal.db)
|
|
44
|
+
(append-only, verdade) │
|
|
45
|
+
├──► audit:query (--since/--cmd/--failed)
|
|
46
|
+
│
|
|
47
|
+
specs/* + memory/90-decisions/* + registry ─┴──► governance:dashboard
|
|
48
|
+
│
|
|
49
|
+
▼
|
|
50
|
+
governance.html (estático, file://)
|
|
51
|
+
zero rota · zero processo · leitura
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## 4. Contratos
|
|
55
|
+
|
|
56
|
+
```js
|
|
57
|
+
// lib/audit.mjs — puro, env injetável ({ fs, dbPath, jsonlPath })
|
|
58
|
+
export function syncAudit(env); // jsonl → audit_runs; idempotente. -> { ingested, total }
|
|
59
|
+
export function queryAudit(env, { since, cmd, gate, failed }); // -> Run[]
|
|
60
|
+
export function auditSummary(env); // p/ o painel: { total, fails, byCmd, slowest, recent }
|
|
61
|
+
|
|
62
|
+
// lib/governance-report.mjs — puro, devolve string HTML
|
|
63
|
+
export function collect(env); // { specs, adrs, gates, audit, metrics }
|
|
64
|
+
export function renderHtml(data); // -> HTML self-contained (CSS/JS inline, zero asset externo)
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
**Schema `audit_runs`**: `line_hash TEXT PRIMARY KEY` (idempotência — hash da linha do jsonl),
|
|
68
|
+
`ts TEXT`, `cmd TEXT`, `args TEXT` (json), `exit_code INTEGER`, `duration_ms INTEGER`. Índices em
|
|
69
|
+
`cmd` e `ts`. Sem FTS5: o dado é colunar; query por coluna basta (D3).
|
|
70
|
+
|
|
71
|
+
## 5. Decisões e alternativas
|
|
72
|
+
|
|
73
|
+
**D1: A tabela é projeção; o `.jsonl` é a verdade.** `audit:sync` reconstrói do zero a qualquer
|
|
74
|
+
momento. Alternativa rejeitada: gravar direto no SQLite no core — acoplaria toda execução ao banco
|
|
75
|
+
(e o banco pode estar morto, ADR-0021). O log em arquivo é resiliente; a tabela é derivada.
|
|
76
|
+
|
|
77
|
+
**D2: Idempotência por `line_hash`, não por cursor.** Hash do conteúdo da linha como PK + `INSERT OR
|
|
78
|
+
IGNORE`. Robusto a re-sync e a truncamento do jsonl. Um cursor (contar linhas) quebra se o arquivo
|
|
79
|
+
for reescrito.
|
|
80
|
+
|
|
81
|
+
**D3: SQL estruturado, não FTS5.** O dado é `{cmd, exit, duração, ts}` — colunar. Query por coluna e
|
|
82
|
+
janela de tempo resolve as perguntas reais ("release:check reprovou quantas vezes"). FTS5 seria
|
|
83
|
+
over-engineering aqui; entra só se a busca por texto livre em `args` provar valer.
|
|
84
|
+
|
|
85
|
+
**D4: O painel não executa gates — lê o último resultado da auditoria.** Rodar `tools:doctor`/
|
|
86
|
+
`release:check` na geração seria lento e com efeito colateral. O painel mostra os checks de cada
|
|
87
|
+
catálogo (de `health`/`release`) + o **último exit** daquele comando na auditoria. Estado real, sem
|
|
88
|
+
reexecutar. Reforça o AC-4 (zero processo).
|
|
89
|
+
|
|
90
|
+
**D5: Comando novo, não estender `project:dashboard`.** O `project:dashboard` é markdown sobre o
|
|
91
|
+
ecossistema de projetos; este é HTML sobre a saúde do framework. Fundir confundiria dois públicos.
|
|
92
|
+
Coexistem (spec §5).
|
|
93
|
+
|
|
94
|
+
**D6: HTML self-contained, reaproveitando o protótipo.** CSS/JS inline, zero asset externo — abre com
|
|
95
|
+
`file://`. O design (gates, quadro SDD, métricas, tema claro/escuro) já foi validado como artifact
|
|
96
|
+
nesta sessão; vira template do gerador.
|
|
97
|
+
|
|
98
|
+
D1, D4 e D5 são estruturais → **ADR-0028** (auditoria consultável; painel estático-gerado como a
|
|
99
|
+
resposta correta ao ADR-0022), referenciando ADR-0022, ADR-0020 e ADR-0021.
|
|
100
|
+
|
|
101
|
+
## 6. Dependências
|
|
102
|
+
|
|
103
|
+
- **Specs**: nenhuma bloqueante. Usa o `universal.db` (SPEC-009/reestruturacao) e o audit (ADR-0020).
|
|
104
|
+
- **Pacotes**: **nenhum novo.** `better-sqlite3` (já runtime dep) + `node:fs`. HTML é string.
|
|
105
|
+
- **Migrações**: `audit_runs` é `CREATE TABLE IF NOT EXISTS` — aditivo, sem migração de dado.
|
|
106
|
+
|
|
107
|
+
## 7. Rollout
|
|
108
|
+
|
|
109
|
+
- [ ] Schema `audit_runs` + `lib/audit.mjs` (sync/query/summary) + testes, com env injetável.
|
|
110
|
+
- [ ] `audit:sync` e `audit:query` no registry; provar contra os 255 runs reais do workspace.
|
|
111
|
+
- [ ] `lib/governance-report.mjs` (coleta + render) + `governance:dashboard`; abrir o HTML e conferir.
|
|
112
|
+
- [ ] Degradação (AC-6): sem workspace/db, avisa e segue. Repo sem runs → "sem atividade", não quebra.
|
|
113
|
+
- [ ] ADR-0028; gates (`release:check`, `tools:doctor`, `npm test`).
|
|
114
|
+
|
|
115
|
+
## 8. Sinais de fracasso (kill criteria)
|
|
116
|
+
|
|
117
|
+
- **Qualquer coisa que execute na geração do painel** — se o gerador rodar um gate ou abrir um
|
|
118
|
+
processo, virou a SPEC-002 de novo. O painel só lê e escreve um arquivo (AC-4).
|
|
119
|
+
- **O HTML puxa asset externo** (CDN, fonte, imagem remota) — quebra o "abre com `file://`". Tudo
|
|
120
|
+
inline.
|
|
121
|
+
- **A tabela vira a fonte de verdade** — se alguém passar a gravar só no SQLite e largar o `.jsonl`,
|
|
122
|
+
perdemos a resiliência do log em arquivo (D1). A tabela é sempre derivável.
|