forjajs 1.2.0 → 1.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (132) hide show
  1. package/.claude/settings.json +7 -7
  2. package/CHANGELOG.md +41 -0
  3. package/README.en.md +5 -0
  4. package/README.md +5 -0
  5. package/dist/bin/create-memory-nest-kit.d.ts +2 -0
  6. package/dist/bin/create-memory-nest-kit.js +110 -0
  7. package/dist/bin/forja.d.ts +13 -0
  8. package/dist/bin/forja.js +136 -0
  9. package/dist/bin/init-project.d.ts +2 -0
  10. package/dist/bin/init-project.js +516 -0
  11. package/dist/lib/audit.d.ts +67 -0
  12. package/dist/lib/audit.js +143 -0
  13. package/dist/lib/context-builder.d.ts +58 -0
  14. package/dist/lib/context-builder.js +233 -0
  15. package/dist/lib/core/checks.d.ts +91 -0
  16. package/dist/lib/core/checks.js +119 -0
  17. package/dist/lib/core/doc-graph.d.ts +60 -0
  18. package/dist/lib/core/doc-graph.js +235 -0
  19. package/dist/lib/core/health.d.ts +103 -0
  20. package/dist/lib/core/health.js +538 -0
  21. package/dist/lib/core/registry.d.ts +296 -0
  22. package/dist/lib/core/registry.js +317 -0
  23. package/dist/lib/core/release.d.ts +334 -0
  24. package/dist/lib/core/release.js +465 -0
  25. package/dist/lib/generators/memory-generator.d.ts +83 -0
  26. package/{lib → dist/lib}/generators/memory-generator.js +107 -178
  27. package/dist/lib/generators/nest-generator.d.ts +15 -0
  28. package/{lib → dist/lib}/generators/nest-generator.js +47 -71
  29. package/dist/lib/generators/readme-generator.d.ts +15 -0
  30. package/{lib → dist/lib}/generators/readme-generator.js +9 -14
  31. package/dist/lib/governance-report.d.ts +49 -0
  32. package/dist/lib/governance-report.js +170 -0
  33. package/dist/lib/templates/harness/code-intel.d.mts +2 -0
  34. package/dist/lib/templates/harness/code-intel.mjs +126 -0
  35. package/dist/lib/utils/file-helpers.d.ts +9 -0
  36. package/dist/lib/utils/file-helpers.js +34 -0
  37. package/dist/lib/validators/structure-validator.d.ts +48 -0
  38. package/dist/lib/validators/structure-validator.js +232 -0
  39. package/dist/lib/workspace.d.ts +40 -0
  40. package/dist/lib/workspace.js +174 -0
  41. package/dist/scripts/agent-harness.d.ts +2 -0
  42. package/dist/scripts/agent-harness.js +556 -0
  43. package/dist/scripts/agent-router.d.ts +30 -0
  44. package/dist/scripts/agent-router.js +208 -0
  45. package/dist/scripts/audit-query.d.ts +2 -0
  46. package/dist/scripts/audit-query.js +43 -0
  47. package/dist/scripts/audit-sync.d.ts +2 -0
  48. package/dist/scripts/audit-sync.js +19 -0
  49. package/dist/scripts/build-smart-context.d.ts +1 -0
  50. package/dist/scripts/build-smart-context.js +75 -0
  51. package/dist/scripts/check-standards.d.ts +1 -0
  52. package/dist/scripts/check-standards.js +87 -0
  53. package/dist/scripts/compress-memory.d.ts +16 -0
  54. package/dist/scripts/compress-memory.js +157 -0
  55. package/dist/scripts/compress-project-memory.d.ts +1 -0
  56. package/dist/scripts/compress-project-memory.js +48 -0
  57. package/dist/scripts/context-ops.d.ts +2 -0
  58. package/dist/scripts/context-ops.js +464 -0
  59. package/dist/scripts/dev.d.ts +96 -0
  60. package/dist/scripts/dev.js +312 -0
  61. package/dist/scripts/extract-global-knowledge.d.ts +1 -0
  62. package/dist/scripts/extract-global-knowledge.js +43 -0
  63. package/dist/scripts/generate-dashboard.d.ts +1 -0
  64. package/dist/scripts/generate-dashboard.js +48 -0
  65. package/dist/scripts/governance-dashboard.d.ts +2 -0
  66. package/dist/scripts/governance-dashboard.js +36 -0
  67. package/dist/scripts/hook-guard-paths.d.ts +17 -0
  68. package/dist/scripts/hook-guard-paths.js +68 -0
  69. package/dist/scripts/hook-post-edit.d.ts +20 -0
  70. package/dist/scripts/hook-post-edit.js +70 -0
  71. package/dist/scripts/hook-session-start.d.ts +17 -0
  72. package/dist/scripts/hook-session-start.js +108 -0
  73. package/dist/scripts/hook-user-prompt.d.ts +22 -0
  74. package/dist/scripts/hook-user-prompt.js +193 -0
  75. package/dist/scripts/memory-schema.d.ts +6 -0
  76. package/{scripts/memory-schema.mjs → dist/scripts/memory-schema.js} +27 -20
  77. package/dist/scripts/query-universal-memory.d.ts +1 -0
  78. package/dist/scripts/query-universal-memory.js +44 -0
  79. package/dist/scripts/release-check.d.ts +14 -0
  80. package/dist/scripts/release-check.js +48 -0
  81. package/dist/scripts/spec-cli.d.ts +29 -0
  82. package/dist/scripts/spec-cli.js +261 -0
  83. package/dist/scripts/sprint-manager.d.ts +1 -0
  84. package/dist/scripts/sprint-manager.js +187 -0
  85. package/dist/scripts/sync-universal-memory.d.ts +1 -0
  86. package/dist/scripts/sync-universal-memory.js +277 -0
  87. package/dist/scripts/token-benchmark.d.ts +20 -0
  88. package/dist/scripts/token-benchmark.js +181 -0
  89. package/dist/scripts/tools-doctor.d.ts +20 -0
  90. package/dist/scripts/tools-doctor.js +120 -0
  91. package/memory/90-decisions/0028-governanca-visivel.md +84 -0
  92. package/package.json +54 -56
  93. package/specs/governanca-visivel/plan.md +122 -0
  94. package/specs/governanca-visivel/spec.md +112 -0
  95. package/specs/governanca-visivel/tasks.md +60 -0
  96. package/specs/ts-migration/plan.md +24 -13
  97. package/bin/create-memory-nest-kit.js +0 -125
  98. package/bin/forja.mjs +0 -143
  99. package/bin/init-project.js +0 -612
  100. package/lib/context-builder.js +0 -257
  101. package/lib/core/checks.mjs +0 -155
  102. package/lib/core/doc-graph.mjs +0 -231
  103. package/lib/core/health.mjs +0 -577
  104. package/lib/core/registry.mjs +0 -312
  105. package/lib/core/release.mjs +0 -492
  106. package/lib/templates/harness/code-intel.mjs +0 -119
  107. package/lib/templates/harness/mcp.json +0 -10
  108. package/lib/utils/file-helpers.js +0 -40
  109. package/lib/validators/structure-validator.js +0 -253
  110. package/lib/workspace.mjs +0 -213
  111. package/scripts/agent-harness.mjs +0 -580
  112. package/scripts/agent-router.mjs +0 -189
  113. package/scripts/build-smart-context.js +0 -87
  114. package/scripts/check-standards.js +0 -98
  115. package/scripts/compress-memory.mjs +0 -198
  116. package/scripts/compress-project-memory.js +0 -58
  117. package/scripts/context-ops.mjs +0 -466
  118. package/scripts/dev.mjs +0 -349
  119. package/scripts/extract-global-knowledge.js +0 -52
  120. package/scripts/generate-dashboard.js +0 -59
  121. package/scripts/hook-guard-paths.mjs +0 -76
  122. package/scripts/hook-post-edit.mjs +0 -79
  123. package/scripts/hook-session-start.mjs +0 -104
  124. package/scripts/hook-user-prompt.mjs +0 -185
  125. package/scripts/pre-commit.sh +0 -102
  126. package/scripts/query-universal-memory.js +0 -50
  127. package/scripts/release-check.mjs +0 -56
  128. package/scripts/spec-cli.mjs +0 -261
  129. package/scripts/sprint-manager.js +0 -200
  130. package/scripts/sync-universal-memory.js +0 -286
  131. package/scripts/token-benchmark.mjs +0 -203
  132. package/scripts/tools-doctor.mjs +0 -132
@@ -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.2.0",
3
+ "version": "1.3.1",
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.mjs",
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
- "bin/",
14
- "lib/",
15
- "scripts/",
13
+ "dist/",
16
14
  "prompts/",
17
15
  "boilerplates/",
18
16
  "design-md/",
@@ -36,55 +34,55 @@
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.mjs release:check -- --publish",
40
- "forja": "node bin/forja.mjs",
41
- "sync:universal": "node bin/forja.mjs sync:universal",
42
- "query:universal": "node bin/forja.mjs query:universal",
43
- "dev": "node scripts/dev.mjs",
44
- "init:project": "node bin/forja.mjs init:project",
45
- "sprint:start": "node bin/forja.mjs sprint:start",
46
- "sprint:status": "node bin/forja.mjs sprint:status",
47
- "sprint:complete": "node bin/forja.mjs sprint:complete",
48
- "context:smart": "node bin/forja.mjs context:smart",
49
- "memory:compress": "node bin/forja.mjs memory:compress",
50
- "memory:vacuum": "node bin/forja.mjs memory:vacuum",
51
- "memory:schema": "node bin/forja.mjs memory:schema",
52
- "memory:extract": "node bin/forja.mjs memory:extract",
53
- "project:check": "node bin/forja.mjs project:check",
54
- "project:dashboard": "node bin/forja.mjs project:dashboard",
55
- "context:budget": "node bin/forja.mjs context:budget",
56
- "context:sprint": "node bin/forja.mjs context:sprint",
57
- "agent:brief": "node bin/forja.mjs agent:brief",
58
- "catalog:assets": "node bin/forja.mjs catalog:assets",
59
- "catalog:manifests": "node bin/forja.mjs catalog:manifests",
60
- "token:benchmark": "node bin/forja.mjs token:benchmark",
61
- "spec:new": "node bin/forja.mjs spec:new",
62
- "spec:plan": "node bin/forja.mjs spec:plan",
63
- "spec:tasks": "node bin/forja.mjs spec:tasks",
64
- "spec:check": "node bin/forja.mjs spec:check",
65
- "agent:route": "node bin/forja.mjs agent:route",
66
- "workspace:init": "node bin/forja.mjs workspace:init",
67
- "project:new": "node bin/forja.mjs project:new",
68
- "project:list": "node bin/forja.mjs project:list",
69
- "workspace:project:check": "node bin/forja.mjs workspace:project:check",
70
- "hermes:handoff": "node bin/forja.mjs hermes:handoff",
71
- "gsd:plan": "node bin/forja.mjs gsd:plan",
72
- "gsd:handoff": "node bin/forja.mjs gsd:handoff",
73
- "gsd:check": "node bin/forja.mjs gsd:check",
74
- "design:check": "node bin/forja.mjs design:check",
75
- "design:select": "node bin/forja.mjs design:select",
76
- "ops:plan": "node bin/forja.mjs gsd:plan",
77
- "ops:handoff": "node bin/forja.mjs gsd:handoff",
78
- "ops:check": "node bin/forja.mjs gsd:check",
79
- "ops:sprint": "node bin/forja.mjs sprint:status",
80
- "code:index": "node bin/forja.mjs code:index",
81
- "code:sync": "node bin/forja.mjs code:sync",
82
- "code:status": "node bin/forja.mjs code:status",
83
- "code:query": "node bin/forja.mjs code:query",
84
- "code:check": "node bin/forja.mjs code:check",
85
- "code:impact": "node bin/forja.mjs code:impact",
86
- "tools:doctor": "node bin/forja.mjs tools:doctor",
87
- "release:check": "node bin/forja.mjs release:check",
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",
88
86
  "build": "tsc -p tsconfig.build.json",
89
87
  "types:check": "tsc --noEmit",
90
88
  "test": "node --test test/*.test.js"
@@ -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.
@@ -0,0 +1,112 @@
1
+ # Spec: governanca-visivel
2
+
3
+ - **ID**: SPEC-014
4
+ - **Status**: done
5
+ - **Owner**: apk
6
+ - **Criado em**: 2026-07-18
7
+ - **Sprint alvo**: S?
8
+ - **ADRs relacionadas**: [ADR-0020](../../memory/90-decisions/0020-forja-core-cli-unica.md) (core/registry + auditoria), [ADR-0022](../../memory/90-decisions/0022-congelar-dashboard-web.md) (dashboard congelado), [ADR-0009](../../memory/90-decisions/0009-claude-hooks-token-economy.md) (economia de tokens), [ADR-0002](../../memory/90-decisions/0002-sqlite-fts5-busca.md) (SQLite FTS5)
9
+
10
+ ## 1. Problema
11
+
12
+ O core grava **toda execução** em `.context/forja-runs.jsonl` (ADR-0020): comando, args, exit code,
13
+ duração, timestamp. São 255 runs registrados hoje. É o dado mais rico de governança que o framework
14
+ tem — a resposta viva para *"o processo foi seguido? o que rodou? o que reprovou? quanto custou?"*.
15
+
16
+ E é **write-only.** Nada lê. Para responder "quantas vezes o `release:check` reprovou este mês" ou
17
+ "qual gate está mais lento", alguém abre um `.jsonl` de 255 linhas e conta na mão. O dado existe e é
18
+ inerte — a mesma classe do problema que a sessão inteira atacou (conhecimento que existe mas não é
19
+ consultável vira conhecimento morto).
20
+
21
+ E há uma segunda ausência: o Forja **não tem superfície visual**. A tentativa anterior (SPEC-002) foi
22
+ **congelada** (ADR-0022) — mas não por ser visual, e sim por ser um **servidor** com rotas que
23
+ *executam* processos (`POST .../run/:role`): virou passivo de manutenção e de segurança. A lição não
24
+ é "sem visual"; é "sem servidor, sem execução". Um artefato **estático, gerado por comando**, de
25
+ leitura, não repete o erro — é a mesma natureza do `project:dashboard` (que já gera um relatório),
26
+ só que sobre governança e legível de relance.
27
+
28
+ ## 2. Proposta de valor
29
+
30
+ A trilha de auditoria deixa de ser um arquivo que ninguém abre: vira **consultável** por comando, e
31
+ **visível** num painel de governança **estático e gerado** — leitura, sem servidor (a lição do
32
+ ADR-0022). "O processo foi seguido?" passa a ter resposta de relance, do dado real.
33
+
34
+ ## 3. User stories
35
+
36
+ - **Como** governança, **quero** consultar a auditoria por comando/gate/período, **para que**
37
+ "quantas vezes o `release:check` reprovou" seja uma query, não uma contagem manual.
38
+ - **Como** operador, **quero** um painel de relance com o estado dos gates, do pipeline SDD e da
39
+ atividade recente, **para que** eu veja a saúde do framework sem ler dez arquivos.
40
+ - **Como** quem opera vários projetos, **quero** que o painel seja um **artefato gerado** (HTML
41
+ estático, sem servidor), **para que** eu não reintroduza o passivo que congelou o dashboard antigo.
42
+ - **Como** agente, **quero** ler o resumo da auditoria em vez do `.jsonl` cru, **para que** eu gaste
43
+ menos tokens entendendo o que já rodou.
44
+
45
+ ## 4. Critérios de aceite (Definition of Done)
46
+
47
+ - [x] AC-1: **Ingest** — um comando (`audit:sync`) lê `.context/forja-runs.jsonl` (a fonte de verdade
48
+ append-only) e o projeta numa tabela SQLite consultável no workspace. Idempotente: rodar duas
49
+ vezes não duplica.
50
+ - [x] AC-2: **Query** — `audit:query` responde por comando, gate, exit code e janela de tempo
51
+ (ex.: `--since 7d`, `--cmd release:check`, `--failed`). Saída legível + contagem.
52
+ - [x] AC-3: **Painel gerado** — um comando gera um **HTML estático e self-contained** (CSS/JS
53
+ inline, zero asset externo) com: estado dos gates, quadro do pipeline SDD (specs × stages),
54
+ atividade recente da auditoria (últimos runs, reprovações, gates mais lentos) e as métricas
55
+ (comandos, testes, ADRs).
56
+ - [x] AC-4: **Sem servidor, leitura, gerado** (ADR-0022): o painel é um arquivo escrito em disco,
57
+ regenerado sob demanda. **Zero** rota, zero processo executável, zero `POST`. O rodapé declara
58
+ isso.
59
+ - [x] AC-5: **Dado real, não fixture** — o painel e as queries leem a auditoria e as specs de
60
+ verdade; nada hard-coded. Um repo sem runs mostra "sem atividade", não quebra.
61
+ - [x] AC-6: **Degrada sem workspace/db** — como todo o resto (ADR-0021): sem `universal.db`, os
62
+ comandos avisam com a correção (`sync:universal`/`audit:sync`), não estouram.
63
+ - [x] AC-7: Entradas no registry (ADR-0020); os comandos passam pelo core e são auditados como os
64
+ demais.
65
+ - [x] AC-8: Gates do próprio Forja: `release:check` (scripts no `files[]`), `tools:doctor`
66
+ (docs-commands não acusa fantasma), `npm test` verde. Testes dos comandos novos.
67
+ - [x] AC-9: ADR-0028 registrando a decisão (auditoria consultável; painel estático-gerado como a
68
+ resposta correta ao ADR-0022).
69
+
70
+ ## 5. Escopo
71
+
72
+ **Dentro**:
73
+ - `audit:sync` (ingest jsonl → tabela) e `audit:query` (consulta).
74
+ - O comando gerador do painel HTML estático de governança.
75
+ - Schema da tabela de auditoria (no `memory-schema`/workspace db).
76
+ - ADR-0028 + testes.
77
+
78
+ **Fora** (explícito):
79
+ - **Servidor, rotas, execução pela web.** É exatamente o que o ADR-0022 congelou. Inegociável.
80
+ - **Instrumentar token por tarefa.** O painel tem lugar para isso, mas medir o custo de token de
81
+ cada tarefa é outra frente (o audit hoje grava duração, não tokens). Follow-up.
82
+ - **Substituir o `project:dashboard`** (markdown, ecossistema de projetos). Este é sobre governança
83
+ do framework; coexistem. Uma futura unificação é outra decisão.
84
+ - **Tempo real / auto-refresh.** O painel é gerado sob demanda; quem quer atualizar, regenera.
85
+
86
+ ## 6. NFRs / restrições
87
+
88
+ - **Estático e self-contained (inegociável)**: o HTML abre com `file://`, sem rede, sem servidor. É o
89
+ que separa esta spec da SPEC-002 congelada.
90
+ - **Fonte de verdade preservada**: o `.jsonl` continua sendo o log append-only; a tabela é uma
91
+ projeção reconstruível (`audit:sync` do zero recria).
92
+ - **Token-aware**: o resumo da auditoria que o agente lê é menor que o `.jsonl` cru — a própria
93
+ feature serve o ADR-0009.
94
+ - **Resiliência (ADR-0021)**: sem workspace/db, avisa e segue; nunca estoura.
95
+
96
+ ## 7. Riscos e mitigação
97
+
98
+ | Risco | Prob | Impacto | Mitigação |
99
+ |---|---|---|---|
100
+ | Virar "dashboard servidor" de novo | B | **A** | AC-4 é gate: zero rota/processo. O painel é arquivo, não serviço |
101
+ | FTS5 vs SQL estruturado — over-engineering | M | B | O dado é estruturado (cmd/exit/duração); query por coluna. FTS só nos args, se valer |
102
+ | Painel gerado fica pesado/externo | M | M | Self-contained obrigatório (AC-3); mesmo princípio do prototipo já validado |
103
+ | Auditoria esparsa deixa o painel vazio | M | B | AC-5: "sem atividade" é estado válido, não erro. O dado cresce com o uso |
104
+
105
+ ## 8. Métricas de sucesso
106
+
107
+ - "O `release:check` reprovou quantas vezes?" passa de contagem manual num `.jsonl` a **uma query**.
108
+ - O painel responde "o framework está saudável?" de relance, do dado real — e é um **arquivo**, não
109
+ um serviço rodando (a lição do ADR-0022, aplicada).
110
+ - O resumo de auditoria que o agente lê é menor em tokens que o `.jsonl` cru — a governança visível
111
+ também economiza contexto (ADR-0009).
112
+ - 90 dias: ninguém abre o `forja-runs.jsonl` na mão; a pergunta de governança vira comando ou painel.
@@ -0,0 +1,60 @@
1
+ # Tasks: governanca-visivel
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Plan**: ./plan.md
5
+ - **Status**: done
6
+ - **Criado em**: 2026-07-19
7
+
8
+ > Ordem: dado consultável primeiro (audit), painel depois (que lê o audit). Env injetável em toda a
9
+ > lógica pura, para os testes não tocarem o workspace real.
10
+
11
+ ---
12
+
13
+ ## T1 — Schema + `lib/audit.mjs`
14
+ - **Owner**: Worker · **Estimativa**: M · **Depende de**: —
15
+ - **Paths**: `scripts/memory-schema.mjs`, `lib/audit.mjs`, `test/audit.test.js`
16
+ - **Done**:
17
+ - [ ] Tabela `audit_runs` (`line_hash` PK, `ts`, `cmd`, `args`, `exit_code`, `duration_ms`; índices em `cmd`/`ts`).
18
+ - [ ] `syncAudit(env)`: lê o jsonl, `INSERT OR IGNORE` por `line_hash` — idempotente (AC-1). Linha malformada é pulada, não derruba.
19
+ - [ ] `queryAudit(env, {since,cmd,gate,failed})` e `auditSummary(env)` (total, fails, byCmd, slowest, recent) — AC-2.
20
+ - [ ] `env` injetável (`fs`/`dbPath`/`jsonlPath`); testes com jsonl de fixture, incl. idempotência e linha corrompida.
21
+
22
+ ## T2 — `audit:sync` + `audit:query` (registry)
23
+ - **Owner**: Worker · **Estimativa**: P · **Depende de**: T1
24
+ - **Paths**: `scripts/audit-sync.mjs`, `scripts/audit-query.mjs`, `lib/core/registry.mjs`
25
+ - **Done**:
26
+ - [ ] CLIs finos sobre `lib/audit.mjs`; entradas no registry (domínio `governanca`), passam pelo core.
27
+ - [ ] Degradam sem workspace/db: avisam com `sync:universal`/`audit:sync`, não estouram (AC-6).
28
+ - [ ] **Prova real**: `audit:sync` ingere os 255 runs do workspace; `audit:query --failed` e `--cmd release:check` respondem.
29
+
30
+ ## T3 — `lib/governance-report.mjs` (coleta + render)
31
+ - **Owner**: Worker · **Estimativa**: M · **Depende de**: T1
32
+ - **Paths**: `lib/governance-report.mjs`, `test/governance-report.test.js`
33
+ - **Done**:
34
+ - [ ] `collect(env)`: specs (status por stage), ADRs (contagem/lista de `memory/90-decisions`), gates (checks de `health`/`release` + último exit da auditoria — **sem reexecutar**, D4), métricas (comandos do registry).
35
+ - [ ] `renderHtml(data)`: HTML **self-contained** — CSS/JS inline, **zero asset externo** (AC-3/AC-4). Tema claro/escuro. Reaproveita o design do protótipo.
36
+ - [ ] Dado real, não fixture (AC-5): repo sem runs → seção "sem atividade", não quebra.
37
+ - [ ] Teste: `renderHtml` não emite `http`/`src=`/`@import` externo; `collect` degrada sem db.
38
+
39
+ ## T4 — `governance:dashboard` (registry)
40
+ - **Owner**: Worker · **Estimativa**: P · **Depende de**: T3
41
+ - **Paths**: `scripts/governance-dashboard.mjs`, `lib/core/registry.mjs`
42
+ - **Done**:
43
+ - [ ] Escreve o HTML num arquivo (default `<workspace>/.context/governance.html`), reporta o caminho.
44
+ - [ ] **Zero execução** na geração — só lê e escreve (AC-4 / kill criteria). Entrada no registry.
45
+ - [ ] **Prova real**: gera o arquivo, abre e confere que os gates/SDD/auditoria refletem o repo.
46
+
47
+ ## T5 — ADR-0028
48
+ - **Owner**: SDD Architect · **Estimativa**: P · **Depende de**: T2, T4
49
+ - **Paths**: `memory/90-decisions/0028-*.md`
50
+ - **Done**: registra D1 (tabela = projeção), D4 (painel não executa), D5 (comando novo); referencia
51
+ ADR-0022 (a resposta correta ao dashboard congelado), ADR-0020, ADR-0021.
52
+
53
+ ## T6 — Gates (Governance)
54
+ - **Owner**: Governance · **Estimativa**: P · **Depende de**: T2, T4, T5
55
+ - **Done**: `release:check` (scripts no `files[]`), `tools:doctor` (docs-commands não acusa fantasma
56
+ nos comandos novos), `npm test` verde. spec → `done`.
57
+
58
+ ---
59
+ ## Handoffs
60
+ Worker (T1-T4), SDD Architect (T5), Governance (T6). `forja agent:route` a cada fronteira (ADR-0005).
@@ -37,7 +37,7 @@ renomeação não quebrou nada.
37
37
  | `lib/generators/*.js` → `.ts` | tipa a assinatura; o **conteúdo** (template string) fica string | B |
38
38
  | `package.json` | `main`/`types`/`exports`/`bin` → `dist/`; `build`; `files[]` dist; `prepublishOnly` | **A** |
39
39
  | `.claude/settings.json` | hooks → `.ts` (dev roda nativo) | B |
40
- | `.github/workflows/ci.yml` | steps `types:check` e `build` | B |
40
+ | `.github/workflows/ci.yml` | só o step `types:check` (o build vive no `release:check`, D4) | B |
41
41
  | `memory/90-decisions/0026-*.md` | **criar** — ADR | B |
42
42
 
43
43
  Os três `A` são o registry, o dispatch e o `package.json` — a tríade que decide se o comando roda
@@ -95,7 +95,7 @@ export interface Check { id: string; title: string; severity: Severity; scope?:
95
95
  | `main` / `types` | `dist/lib/index.js` / `.d.ts` |
96
96
  | `files[]` | troca `bin/ lib/ scripts/` por `dist/` (o resto — memory/, docs/, boilerplates/ — fica) |
97
97
  | `scripts.build` | `tsc` |
98
- | `scripts.prepublishOnly` | `npm run build && node bin/forja.ts release:check -- --publish` |
98
+ | `scripts.prepublishOnly` | `node bin/forja.mjs release:check -- --publish` (o gate builda, D4) |
99
99
 
100
100
  ## 5. Decisões e alternativas
101
101
 
@@ -113,9 +113,15 @@ dois registries — é como se chega a duas verdades divergentes, o defeito que
113
113
  roda `.ts`); publicado roda `dist/.js`. `engines.node` fica `>=20` — por isso publicamos compilado.
114
114
  O usuário final não é obrigado a Node novo; o dev sim.
115
115
 
116
- **D4: `build-fresh` no `RELEASE_CHECKS`.** Sem ele, a migração reintroduz a classe do ADR-0021: um
117
- `dist/` que mente sobre o `src/`. O gate recompila num temp e faz diff com o `dist/` commitado;
118
- diferente → reprova com `npm run build`. É o `memory-fresh`, um nível abaixo.
116
+ **D4 (revisado na implementação): o gate builda o `dist/`, e o `dist/` não é commitado.** O plano
117
+ original commitava `dist/` e um check `build-fresh` fazia diff contra a fonte — mas isso guarda um
118
+ artefato de build no git e reintroduz staleness ("o `dist/` commitado bate com o `src/`?"). A versão
119
+ que shipou é mais simples: `dist/` é gitignored e o `release:check` roda `npm run build` **antes de
120
+ empacotar** (só quando `files[]` inclui `dist/`). Como `npm publish` empacota o disco e o gate
121
+ empacota o mesmo disco recém-buildado, o tarball provado é exatamente o publicado — sem diff, sem
122
+ artefato no git, sem janela de staleness. Efeito colateral que destravou a Fase 3: a prova fica
123
+ self-contained e **não precisa de um step de `build` no `ci.yml`** (que exigiria escopo de workflow e
124
+ acoplaria a prova ao CI). Uma máquina — o gate — constrói e prova.
119
125
 
120
126
  **D5: `checkJs` antes de renomear; leaf-first depois.** Ordem por dependência:
121
127
  `workspace → checks → registry → doc-graph → health/release → scripts → hooks → bin → generators`.
@@ -162,15 +168,20 @@ classe "dist mente") e ADR-0024 (o gate que ganha o `build-fresh`).
162
168
 
163
169
  ## 7. Rollout
164
170
 
165
- - [ ] **Fase 0 — on-ramp.** `tsconfig` com `checkJs, strict, noEmit`; `types:check` no registry e
171
+ - [x] **Fase 0 — on-ramp.** `tsconfig` com `checkJs, strict, noEmit`; `types:check` no registry e
166
172
  no CI. Corrigir os erros com os arquivos ainda `.mjs`. Nada renomeado ainda.
167
- - [ ] **Fase 1 — resolver.** Trocar o registry para paths sem extensão e o dispatch para o resolver
168
- `.ts/.js/.mjs`, **ainda em `.mjs`**. Suíte verde. É a mudança de comportamento de menor risco,
169
- isolada e testável antes de qualquer renomeação.
170
- - [ ] **Fase 2 — renomear leaf-first.** Um módulo por vez (D5), `npm test` verde a cada um.
171
- - [ ] **Fase 3 — build + publish.** `tsc` emitindo `dist/`; `build-fresh`; `package.json` apontando
172
- para `dist/`; `prepublishOnly` build→gate. Validar com `release:check --publish` e
173
- `npm publish --dry-run`.
173
+ - [x] **Fase 1 — resolver.** Registry sem extensão (na verdade: registry mantém `.mjs` e o
174
+ `resolveScript` faz strip + tenta `.ts/.js/.mjs`), dispatch pelo resolver. Suíte verde.
175
+ - [~] **Fase 2 — renomear leaf-first.** Um módulo por vez (D5), `npm test` verde a cada um.
176
+ **Entregue: todos os 21 módulos `.mjs` do framework** (`lib/core/`, `lib/{audit,governance-report,
177
+ workspace}`, `bin/forja`, todos os `scripts/` incl. hooks). Os typedefs JSDoc viraram `interface`
178
+ real; `allowImportingTsExtensions` no type-check (build reescreve `.ts→.js`). Dois achados
179
+ recorrentes no `.ts` estrito: `[]`→`never[]` (anotação inline) e os casts-comentário
180
+ `/** @type */ (x)` não narram (viram `as`). **Restam**: os 16 `.js` (entries públicos
181
+ `init-project`/`create-memory-nest-kit` + generators + scaffolding), que seguem no checkJs; e o
182
+ `noImplicitAny: true` (endurecimento final — hoje off, ~280 params a tipar).
183
+ - [x] **Fase 3 — build + publish.** `tsc` emitindo `dist/`; `package.json` apontando para `dist/`;
184
+ `prepublishOnly` = gate (o gate builda, D4 revisado). Provado por `release:check` (#15).
174
185
  - [x] Doc/persona: governança ganha o `build-fresh`; `docs/` e `CONTRIBUTING` ganham o "dev roda
175
186
  `.ts`, publicado roda `dist`".
176
187
  - [ ] **Prova final**: `release:check` aprova o tarball com `dist/` fresco; reintroduzir um `dist/`