forjajs 1.1.2 → 1.1.4

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 (36) hide show
  1. package/.claude/agents/governance.md +33 -10
  2. package/.claude/agents/release-auditor.md +44 -45
  3. package/CHANGELOG.md +74 -0
  4. package/DOC-MAP.md +2 -2
  5. package/README.md +2 -2
  6. package/docs/agent-harnesses.md +30 -3
  7. package/docs/token-optimization.md +28 -20
  8. package/lib/core/checks.mjs +138 -0
  9. package/lib/core/health.mjs +475 -0
  10. package/lib/core/registry.mjs +6 -1
  11. package/lib/core/release.mjs +452 -0
  12. package/memory/40-delivery/current-sprint.md +13 -7
  13. package/memory/90-decisions/0021-guardrails-de-harness.md +5 -1
  14. package/memory/90-decisions/0022-congelar-dashboard-web.md +101 -0
  15. package/memory/90-decisions/0023-doctor-como-gate-do-nucleo.md +114 -0
  16. package/memory/90-decisions/0024-gate-do-tarball.md +103 -0
  17. package/package.json +7 -7
  18. package/prompts/governance-agent.md +2 -1
  19. package/scripts/hook-session-start.mjs +29 -39
  20. package/scripts/release-check.mjs +56 -0
  21. package/scripts/spec-cli.mjs +80 -13
  22. package/scripts/tools-doctor.mjs +65 -10
  23. package/specs/coerencia-do-sistema/spec.md +122 -0
  24. package/specs/doctor-do-nucleo/plan.md +165 -0
  25. package/specs/doctor-do-nucleo/spec.md +139 -0
  26. package/specs/doctor-do-nucleo/tasks.md +172 -0
  27. package/specs/reestruturacao-forja-v2/plan.md +1 -1
  28. package/specs/reestruturacao-forja-v2/spec.md +16 -12
  29. package/specs/reestruturacao-forja-v2/tasks.md +1 -1
  30. package/specs/release-gate/plan.md +174 -0
  31. package/specs/release-gate/spec.md +122 -0
  32. package/specs/release-gate/tasks.md +183 -0
  33. package/docs/dashboard.md +0 -102
  34. package/specs/agent-dashboard/plan.md +0 -165
  35. package/specs/agent-dashboard/spec.md +0 -89
  36. package/specs/agent-dashboard/tasks.md +0 -168
@@ -0,0 +1,114 @@
1
+ # ADR-0023: Doctor como gate do núcleo, não relatório de ferramentas
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-07-13
5
+ - **Autor(es)**: Allan Pablo
6
+ - **Tags**: harness, governance, memory, hooks, diagnostics
7
+
8
+ ## Contexto
9
+
10
+ O ADR-0021 nomeou uma classe de falha do framework: erros que **erram sem avisar** — nenhum teste
11
+ quebra, nada aparece no `git status`, e o resultado é trabalho errado com aparência de trabalho
12
+ certo. Quatro casos foram corrigidos individualmente.
13
+
14
+ Em 2026-07-13 apareceu o quinto, e ele revelou por que corrigir caso a caso não fecha a classe.
15
+
16
+ Com o `better-sqlite3` compilado contra o ABI do Node 24 num runtime Node 26, a memória universal
17
+ morreu inteira: `query:universal`, `sync:universal`, `context:smart`, `agent:route`,
18
+ `memory:compress` e `project:dashboard`, todos inoperantes. A aposta nº 1 da visão — *"memória que
19
+ sobrevive"* — simplesmente não existia. As três superfícies de diagnóstico reagiram assim:
20
+
21
+ | Superfície | O que fez |
22
+ |---|---|
23
+ | `tools:doctor` | Reportou `2/5 ferramentas disponíveis` e saiu com **exit 0** |
24
+ | `SessionStart` | Detectou, mas prescreveu `npm install` — que **não** recompila binário nativo |
25
+ | `npm test` | Stack trace cru de `ERR_DLOPEN_FAILED` |
26
+
27
+ A correção real era `npm rebuild better-sqlite3`.
28
+
29
+ Dois problemas estruturais, não um bug:
30
+
31
+ 1. **O doctor auditava o que não importa.** Ele checava cinco ferramentas *opcionais*, sobre as
32
+ quais ele mesmo declarava: *"o fluxo nunca trava por elas"*. Era cego para tudo que trava. Um
33
+ raio-x que só olha o que não pode quebrar.
34
+ 2. **Cada superfície tinha heurística própria.** O hook resolvia a saúde da memória com um
35
+ `catch { return null }` que colapsava *sem `node_modules`*, *ABI incompatível* e *banco ausente*
36
+ no mesmo `null` — e então prescrevia a correção de apenas uma das três. Um operador seguindo a
37
+ instrução do próprio framework não consertaria nada, e concluiria que o problema era outro.
38
+ Uma prescrição errada é pior que silêncio: consome o tempo do operador e ainda desvia a
39
+ investigação.
40
+
41
+ ## Decisão
42
+
43
+ **O doctor passa a ser o gate do núcleo. As três superfícies passam a ler a mesma fonte.**
44
+
45
+ - **`lib/core/health.mjs`** — os checks viram **dados** (`CHECKS[]`), com um runner que os executa
46
+ e devolve resultados estruturados. `tools:doctor`, `SessionStart` e (futuramente) o
47
+ `release-auditor` são apenas apresentação. Nenhuma superfície volta a ter heurística local.
48
+ - **Probes classificam a causa; o runner nunca colapsa em booleano.** `ERR_DLOPEN_FAILED` →
49
+ `npm rebuild better-sqlite3`. `ERR_MODULE_NOT_FOUND` → `npm install`. Banco ausente →
50
+ `npm run sync:universal`. Causas distintas, correções distintas.
51
+ - **Cascata via `dependsOn`.** Um check cuja dependência falhou é `skipped`, não `fail`. Com o ABI
52
+ quebrado, os checks de memória não têm o que observar; reportá-los como falha multiplicaria uma
53
+ causa em três linhas vermelhas e esconderia a raiz. **Uma causa, uma linha vermelha.**
54
+ - **Dois contratos de exit code.** Núcleo crítico quebrado → `exit 1`. Ferramenta opcional ausente
55
+ → `exit 0`, preservando o ADR-0018 à risca. Só `critical` trava: `workspace` ausente e Node fora
56
+ do `engines` são avisos, porque não impedem trabalho.
57
+ - **Ausente ≠ quebrado.** Num clone novo — ou num CI — a memória simplesmente nunca foi indexada.
58
+ Isso é o ponto de partida de qualquer instalação, não uma falha, e um comando resolve. `memory-db`
59
+ distingue *não indexado* (aviso) de *existe mas não abre* (crítico). A primeira versão tratava os
60
+ dois como crítico e o CI reprovou de imediato: um gate que reprova todo mundo no primeiro dia é um
61
+ gate em que ninguém confia.
62
+ - **`scope: repo | runtime`.** `runtime-deps` e `mcp-json` — que convertem em gate executável dois
63
+ invariantes que o ADR-0021 corrigiu à mão — só rodam dentro do repo do framework. Numa instalação
64
+ `npm i -g forjajs` não há `devDependencies` nem `.mcp.json`, e rodá-los produziria falso positivo
65
+ crítico na máquina do usuário final.
66
+ - **`spec:new` mantém a allow-list do `.gitignore`.** Descoberto durante a implementação: `/specs/*`
67
+ é ignorado e as specs do framework entram por lista manual, então **toda spec nova nascia
68
+ invisível ao git** — inclusive a desta ADR. Aplicando o princípio do próprio ADR-0021 ("mover a
69
+ aplicação das regras do texto para o harness"), o comando passa a manter a lista.
70
+
71
+ ## Alternativas consideradas
72
+
73
+ - **Melhorar só a mensagem do hook** — rejeitada: produziria uma prescrição *genérica*, e o
74
+ problema foi exatamente uma prescrição genérica aplicada a um caso específico. A causa era o
75
+ `catch` que apagava a informação, não o texto.
76
+ - **Doctor com `--fix` que roda `npm rebuild` sozinho** — rejeitada: executar comandos de build sem
77
+ consentimento é a classe de risco oposta à que este ADR fecha. O doctor diagnostica e prescreve.
78
+ - **Fazer o índice defasado reprovar (`critical`)** — rejeitada: um gate que trava por aquilo que
79
+ não impede trabalho é um gate que se aprende a ignorar, e aí ele para de proteger do que importa.
80
+ - **Check `spec-allowlist` avisando que a spec está fora do `.gitignore`** — rejeitada em favor de
81
+ o `spec:new` manter a lista: trocaria uma falha silenciosa por um lembrete recorrente. Eliminar a
82
+ classe de erro é melhor que reportá-la.
83
+ - **Um novo comando (`core:doctor`) separado** — rejeitada: dois doctores é como se chega a duas
84
+ verdades divergentes sobre o mesmo sistema, que é precisamente o defeito que este ADR corrige.
85
+
86
+ ## Consequências
87
+
88
+ **Positivas**:
89
+ - A quebra do núcleo aparece no **primeiro** comando executado, com a correção certa ao lado — não
90
+ num sintoma indireto trinta minutos depois.
91
+ - Os invariantes do ADR-0021 ganham cobertura executável. Regressão em `.mcp.json` ou nas deps de
92
+ runtime passa a reprovar o gate, em vez de reaparecer em produção.
93
+ - Uma só definição de "saudável". O hook e o doctor não podem mais divergir, porque leem a mesma
94
+ lista.
95
+ - Check novo = entrada nova em `CHECKS[]`, e as três superfícies o ganham de graça.
96
+
97
+ **Negativas / Trade-offs**:
98
+ - `tools:doctor` pode agora **reprovar** (exit 1). Um ambiente já quebrado passa a falhar
99
+ explicitamente onde antes passava calado — é o objetivo, mas muda o contrato de quem o usasse em
100
+ script.
101
+ - `runtime-deps` usa parser estático conservador: import dinâmico não conta. Trocamos cobertura por
102
+ ausência de falso positivo, deliberadamente — um crítico que mente é pior que um warning honesto.
103
+ - O `SessionStart` ganhou uma dependência a mais no caminho quente. Mitigado por rodar só
104
+ `scope: 'runtime'` e nunca lançar: se a própria lib de health não carregar, o hook segue com o
105
+ resto do briefing.
106
+
107
+ ## Rastreamento
108
+
109
+ - Implementação: `lib/core/health.mjs`, `scripts/tools-doctor.mjs`, `scripts/hook-session-start.mjs`,
110
+ `scripts/spec-cli.mjs`, `test/health.test.js`
111
+ - Spec: `specs/doctor-do-nucleo/` (SPEC-009)
112
+ - ADRs relacionadas: ADR-0018 (ferramentas de processo — estendido), ADR-0021 (guardrails de
113
+ harness — a classe de falha que este fecha), ADR-0020 (core/registry), ADR-0009 (economia de
114
+ tokens: `query:universal` é o primeiro passo, e índice defasado o corrompe em silêncio)
@@ -0,0 +1,103 @@
1
+ # ADR-0024: Gate do tarball — o repositório mente sobre o pacote
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-07-14
5
+ - **Autor(es)**: Allan Pablo
6
+ - **Tags**: release, governance, npm, harness, ci
7
+
8
+ ## Contexto
9
+
10
+ O ADR-0023 fechou a classe "erra sem avisar" **dentro do repositório**. Fora dele, na fronteira do
11
+ pacote publicado, a mesma classe seguia intacta — e já tinha cobrado três vezes:
12
+
13
+ | Onde | O que foi publicado | Consequência |
14
+ |---|---|---|
15
+ | ADR-0021 §2 | `better-sqlite3` como `devDependency` | Dez comandos com `ERR_MODULE_NOT_FOUND` numa instalação limpa. O `forja` sem argumentos funcionava — o help não carrega os scripts — e isso mascarou a quebra. |
16
+ | v1.1.1 | `otplib` e `qrcode` no tarball, **sem jamais existirem no git** | `npm publish` empacota o *disco*, não o commit. Um `npm install` casual entre a auditoria e o publish reescreveu o `package.json`. |
17
+ | v1.1.3 | `docs/dashboard.md` e o script `npm run dashboard`, sem a pasta `dashboard/` | Quem instalava recebia a documentação e o comando, sem o código. |
18
+
19
+ Três releases, três bugs, uma raiz: **no repo tudo resolve.** `node_modules` tem as devDeps, todo
20
+ arquivo está presente, o `cwd` é a raiz. Nada disso vale para quem roda `npm i -g forjajs`. Todos
21
+ os três foram descobertos *depois* do publish, na máquina de quem instalou.
22
+
23
+ O agente `.claude/agents/release-auditor.md` já descrevia essa classe com precisão cirúrgica — as
24
+ quatro variantes, o procedimento, os comandos exatos. **Não era conhecimento que faltava; era
25
+ execução.** Ele é um agente: prosa, opt-in, invocado por quem lembrar. Pelo critério do próprio
26
+ ADR-0021 — *"uma regra que depende de memória não é uma regra; é uma sugestão"* — aquilo não era
27
+ gate. Era a última fronteira do framework que ainda funcionava por disciplina.
28
+
29
+ ## Decisão
30
+
31
+ **`release:check`**: o gate empacota, instala num diretório isolado, executa os comandos e reprova.
32
+
33
+ - **Grep não prova ausência; instalação prova.** O gate roda `npm pack` + `npm install` de verdade,
34
+ fora do repo, sem herdar `NODE_PATH` nem o `node_modules` vizinho. Um gate que enxerga o repo
35
+ mente verde.
36
+ - **Executar, não listar.** O `forja` sem argumentos passa mesmo com tudo quebrado. O gate roda
37
+ comandos reais (`tools:doctor`, `code:status`, `query:universal`) na instalação limpa.
38
+ - **Reprovar por assinatura de loader, nunca por exit code.** Numa instalação limpa não há workspace
39
+ nem `universal.db`, então `query:universal` sai com código ≠ 0 *legitimamente* — isso é o pacote
40
+ **funcionando**. O que denuncia tarball quebrado é `ERR_MODULE_NOT_FOUND` / `ERR_DLOPEN_FAILED`.
41
+ Reprovar por exit code reprovaria todo pacote saudável.
42
+ - **Dois modos.** Árvore suja é `warn` em dev (senão o gate é contornado) e `fail` sob `--publish`
43
+ (senão repete-se a v1.1.1).
44
+ - **A aprovação é perecível.** A árvore é reconferida ao final: vale para aquele disco, naquele
45
+ instante. Um `npm install` entre o check e o publish invalida tudo.
46
+ - **O runner é o mesmo do doctor.** `lib/core/checks.mjs` foi *extraído* de `health.mjs`, não
47
+ copiado. Duas máquinas iguais divergem com o tempo — e divergência entre superfícies que deveriam
48
+ concordar é exatamente o defeito que o ADR-0023 matou. Uma máquina, dois catálogos: `health.mjs`
49
+ guarda o repo, `release.mjs` guarda o tarball.
50
+ - **O que o Forja *escreve* não é o que o Forja *executa*.** Duas camadas de defesa contra essa
51
+ confusão, ambas descobertas em campo:
52
+ 1. `stripTemplateLiterals` — os geradores emitem `import { INestApplication } from
53
+ '@nestjs/common'` dentro de crases. Como a linha começa com `import`, o parser casava.
54
+ 2. Só `bin/`, `lib/` e `scripts/` contam como código. `boilerplates/` também é publicado e também
55
+ é `.js`, mas é **conteúdo**: o `next.config.js` de um boilerplate importa `next`, dependência
56
+ do projeto do *usuário*. Na primeira execução real, o gate exigiu `npm i -S next` no framework.
57
+ - **O gate nunca publica.** Ele autoriza; `npm publish` continua sendo um ato humano deliberado.
58
+ - **`prepublishOnly`, jamais `prepack`.** O gate roda `npm pack`. Amarrá-lo ao `prepack` faria o
59
+ `npm pack` do gate disparar o `prepack`, que chama o gate, que roda `npm pack`… `npm pack` **não**
60
+ dispara `prepublishOnly`, e é por isso que ele é o único hook seguro.
61
+
62
+ ## Alternativas consideradas
63
+
64
+ - **Manter o `release-auditor` como agente** — rejeitada: é o estado atual, e ele não impediu
65
+ nenhum dos três bugs. Conhecimento correto que ninguém executa no momento certo é decoração.
66
+ - **Análise estática do tarball, sem instalar** — rejeitada: foi tentada à mão durante o estudo e
67
+ produziu falso positivo em minutos (imports dentro de template literal). Grep não distingue código
68
+ de texto; o interpretador distingue.
69
+ - **`--fix` que corrige `files[]`/`dependencies` sozinho** — rejeitada, mesma razão do ADR-0023: o
70
+ gate diagnostica e prescreve. Editar o manifesto de publicação sem consentimento é a classe de
71
+ risco oposta.
72
+ - **`deps-unused` como `critical`** — rejeitada: peso morto no tarball incomoda, não quebra.
73
+ Reprovar um release por isso ensina o time a usar `--no-verify`.
74
+ - **Rodar o gate na matriz de três Nodes** — rejeitada: o custo é o `npm install` compilando o
75
+ `better-sqlite3` do zero, e instalar três vezes não prova mais que instalar uma. O `tools:doctor`
76
+ é que roda na matriz — o `native-abi` só faz sentido contra várias versões.
77
+
78
+ ## Consequências
79
+
80
+ **Positivas**:
81
+ - Os três bugs históricos foram **reintroduzidos um a um e o gate reprovou os três**. Um gate que
82
+ nunca viu a falha que promete pegar não está testado — está escrito. Este viu.
83
+ - A evidência do release passa a viver no log do CI, e não na memória de quem publicou.
84
+ - `release:check` e `tools:doctor` compartilham runner, vocabulário e contrato de exit code. Check
85
+ novo é entrada nova num catálogo.
86
+
87
+ **Negativas / Trade-offs**:
88
+ - O gate é **lento** (dezenas de segundos): o custo é o build nativo do `better-sqlite3` na
89
+ instalação limpa. Aceito — roda antes de publicar e no CI, nunca no pre-commit.
90
+ - `prepublishOnly` é a peça de risco alto: um falso positivo ali **impede publicar qualquer coisa**.
91
+ Por isso entrou por último, depois de o gate rodar verde no CI. Se reprovar um release saudável
92
+ uma única vez, o `tree-clean` estrito sai do `prepublishOnly` e fica só no CI.
93
+ - A análise estática é conservadora por escolha: import dinâmico e template literal não contam.
94
+ Trocamos cobertura por ausência de falso positivo — um crítico que mente é pior que um warning
95
+ honesto. A cobertura real vem do `smoke-commands`, que executa e não opina.
96
+
97
+ ## Rastreamento
98
+
99
+ - Implementação: `lib/core/checks.mjs` (runner), `lib/core/release.mjs` (catálogo),
100
+ `scripts/release-check.mjs`, `.github/workflows/ci.yml`, `test/release.test.js`
101
+ - Spec: `specs/release-gate/` (SPEC-010)
102
+ - ADRs relacionadas: ADR-0023 (mesma filosofia, fronteira anterior), ADR-0021 (a classe que ambos
103
+ fecham), ADR-0020 (registry), ADR-0018 (ferramentas de processo)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "forjajs",
3
- "version": "1.1.2",
3
+ "version": "1.1.4",
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",
@@ -29,9 +29,13 @@
29
29
  "AGENTS.md",
30
30
  "DOC-MAP.md",
31
31
  "CHANGELOG.md",
32
- "CONTRIBUTING.md"
32
+ "CONTRIBUTING.md",
33
+ "!docs/dashboard.md",
34
+ "!specs/agent-dashboard/"
33
35
  ],
34
36
  "scripts": {
37
+ "//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.",
38
+ "prepublishOnly": "node bin/forja.mjs release:check -- --publish",
35
39
  "forja": "node bin/forja.mjs",
36
40
  "sync:universal": "node bin/forja.mjs sync:universal",
37
41
  "query:universal": "node bin/forja.mjs query:universal",
@@ -72,11 +76,6 @@
72
76
  "ops:handoff": "node bin/forja.mjs gsd:handoff",
73
77
  "ops:check": "node bin/forja.mjs gsd:check",
74
78
  "ops:sprint": "node bin/forja.mjs sprint:status",
75
- "dashboard": "cd dashboard && npm start",
76
- "dashboard:dev": "cd dashboard && npm run dev",
77
- "dashboard:install": "cd dashboard && npm install && cd web && npm install",
78
- "dashboard:web:dev": "cd dashboard/web && npm run dev",
79
- "dashboard:web:build": "cd dashboard/web && npm run build",
80
79
  "code:index": "node bin/forja.mjs code:index",
81
80
  "code:sync": "node bin/forja.mjs code:sync",
82
81
  "code:status": "node bin/forja.mjs code:status",
@@ -84,6 +83,7 @@
84
83
  "code:check": "node bin/forja.mjs code:check",
85
84
  "code:impact": "node bin/forja.mjs code:impact",
86
85
  "tools:doctor": "node bin/forja.mjs tools:doctor",
86
+ "release:check": "node bin/forja.mjs release:check",
87
87
  "test": "node --test test/*.test.js"
88
88
  },
89
89
  "keywords": [
@@ -5,7 +5,8 @@ Você é o guardião dos padrões do framework. Sua missão é garantir a integr
5
5
  ## Suas Atividades
6
6
  1. **Auditoria de Padrões**: Execute `npm run project:check` e barre deploys ou tarefas que não sigam os padrões.
7
7
  2. **Code intelligence (ADR-0017)**: Rode `npm run code:check`. Índice codegraph de outro worktree ou ausente torna a auditoria de código não-confiável → bloqueie.
8
- 3. **Ferramentas de processo (ADR-0018)**: Rode `npm run tools:doctor`. Se `gitleaks` estiver disponível, varra segredos antes de aprovar.
8
+ 3. **Gate do núcleo (ADR-0023)**: Rode `npm run tools:doctor`. Ele sai com `exit 1` quando o que impede o framework de trabalhar está quebrado (ABI do `better-sqlite3`, memória, deps de runtime, `.mcp.json`) — não é mais só um inventário de ferramentas opcionais. Ambiente reprovado aqui invalida qualquer outra auditoria: bloqueie. Se `gitleaks` estiver disponível, varra segredos antes de aprovar (ADR-0018).
9
+ 4. **Gate do tarball, antes de publicar (ADR-0024)**: Rode `npm run release:check -- --publish`. Ele empacota, instala limpo e prova que o pacote funciona na máquina de quem instala. O repositório mente sobre o pacote — três releases quebraram nessa fronteira. Reprovou, não publica.
9
10
  4. **Revisão de ADRs**: Garanta que todas as decisões arquiteturais estejam documentadas e sejam coerentes.
10
11
  5. **Segurança e LGPD**: Avalie riscos de privacidade e segurança em novas features.
11
12
 
@@ -8,12 +8,19 @@
8
8
  * Regra de ouro: este hook nunca pode derrubar a sessão. Todo acesso a SQLite é
9
9
  * lazy e envolto em try/catch — sem `node_modules`, degrada para o modo só-specs
10
10
  * em vez de abortar (ADR-0021).
11
+ *
12
+ * A saúde do núcleo vem de `lib/core/health.mjs` — zero heurística local (SPEC-009). O hook tinha
13
+ * a sua, e ela mentia: um `catch { return null }` colapsava "sem node_modules", "ABI incompatível"
14
+ * e "banco ausente" no mesmo `null`, e então prescrevia `npm install` — que não recompila binário
15
+ * nativo. Quem seguisse o conselho do próprio framework não consertava nada.
11
16
  */
12
17
 
13
18
  import fs from 'node:fs';
14
19
  import path from 'node:path';
15
20
  import { fileURLToPath } from 'node:url';
16
21
 
22
+ import { runChecks } from '../lib/core/health.mjs';
23
+
17
24
  const __filename = fileURLToPath(import.meta.url);
18
25
  const __dirname = path.dirname(__filename);
19
26
  const root = path.resolve(__dirname, '..');
@@ -34,63 +41,46 @@ function listSpecs() {
34
41
  return out;
35
42
  }
36
43
 
37
- /** Lazy: sem better-sqlite3 instalado, devolve null em vez de estourar. */
38
- async function resolveDbPath() {
39
- try {
40
- const { getDbPath, ensureSchema } = await import('./memory-schema.mjs');
41
- ensureSchema({ silent: true });
42
- const dbPath = getDbPath();
43
- return fs.existsSync(dbPath) ? dbPath : null;
44
- } catch { return null; }
45
- }
46
-
47
- async function openHandoffs(dbPath) {
48
- if (!dbPath) return [];
44
+ /** Handoffs só fazem sentido com a memória de pé — daí o `memoriaOk` do caller. */
45
+ async function openHandoffs() {
49
46
  try {
47
+ const { getWorkspaceDbPath } = await import('../lib/workspace.mjs');
50
48
  const { default: Database } = await import('better-sqlite3');
51
- const db = new Database(dbPath, { readonly: true });
49
+ const db = new Database(getWorkspaceDbPath(), { readonly: true });
52
50
  const rows = db.prepare(`SELECT id, from_agent, to_agent, intent, spec_slug FROM handoffs WHERE status='open' ORDER BY id DESC LIMIT 10`).all();
53
51
  db.close();
54
52
  return rows;
55
53
  } catch { return []; }
56
54
  }
57
55
 
58
- /** mtime do arquivo .md mais recente sob memory/, ignorando o que é arquivado. */
59
- function newestMemoryMtime(dir = path.join(root, 'memory'), acc = { t: 0 }) {
60
- for (const entry of safeReadDir(dir)) {
61
- if (entry.startsWith('.') || entry === 'archive') continue;
62
- const p = path.join(dir, entry);
63
- let st;
64
- try { st = fs.statSync(p); } catch { continue; }
65
- if (st.isDirectory()) newestMemoryMtime(p, acc);
66
- else if (entry.endsWith('.md') && st.mtimeMs > acc.t) acc.t = st.mtimeMs;
67
- }
68
- return acc.t;
69
- }
70
-
71
56
  /**
72
- * Índice defasado = `query:universal` responde sobre memória velha, calado.
73
- * É a falha mais cara do framework: erra sem avisar. Então avisamos.
57
+ * Nunca lança e nunca trava a sessão: o hook reporta, o `tools:doctor` é que é gate. Se a própria
58
+ * lib de health não carregar, seguimos com o resto do briefing em vez de abortar (ADR-0021).
74
59
  */
75
- function staleIndex(dbPath) {
76
- if (!dbPath) return false;
60
+ async function coreHealth() {
77
61
  try {
78
- const dbMtime = fs.statSync(dbPath).mtimeMs;
79
- return newestMemoryMtime() > dbMtime;
80
- } catch { return false; }
62
+ return await runChecks({ scope: 'runtime' });
63
+ } catch { return []; }
81
64
  }
82
65
 
83
66
  (async function main() {
84
67
  const specs = listSpecs();
85
- const dbPath = await resolveDbPath();
86
- const handoffs = await openHandoffs(dbPath);
68
+ const health = await coreHealth();
69
+ const problemas = health.filter((c) => c.status === 'fail' || c.status === 'warn');
70
+ const memoriaOk = !health.some((c) => c.status === 'fail');
71
+ const handoffs = memoriaOk ? await openHandoffs() : [];
72
+
87
73
  const lines = ['<framework-status>'];
88
74
  lines.push(`Framework: forja (SDD + orquestração)`);
89
75
 
90
- if (!dbPath) {
91
- lines.push('\n⚠ Memória indisponível: universal.db não abriu. Rode `npm install` e `npm run sync:universal`.');
92
- } else if (staleIndex(dbPath)) {
93
- lines.push('\n⚠ Índice defasado: memory/ mudou depois do último sync. `query:universal` vai responder sobre memória velha — rode `npm run sync:universal`.');
76
+ if (problemas.length) {
77
+ lines.push('');
78
+ for (const p of problemas) {
79
+ const icone = p.status === 'fail' ? '✖' : '⚠';
80
+ lines.push(`${icone} ${p.title}: ${p.detail}`);
81
+ if (p.fix) lines.push(` corrigir: ${p.fix}`);
82
+ }
83
+ lines.push(' raio-x completo: `npm run tools:doctor`');
94
84
  }
95
85
 
96
86
  if (specs.length) {
@@ -0,0 +1,56 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * release-check — o gate do tarball (SPEC-010, ADR-0024).
4
+ *
5
+ * Responde a uma pergunta com evidência: **o pacote funciona na máquina de quem instala?**
6
+ * Empacota, instala num diretório isolado, executa os comandos e reprova se algo só funcionava
7
+ * porque o repo estava por perto.
8
+ *
9
+ * npm run release:check árvore suja = aviso (smoke local)
10
+ * npm run release:check -- --publish árvore suja = falha (prepublishOnly, CI de release)
11
+ *
12
+ * Diagnostica e autoriza; nunca publica. `npm publish` continua sendo um ato humano.
13
+ */
14
+
15
+ import { runReleaseChecks, worstStatus } from '../lib/core/release.mjs';
16
+
17
+ const TAG = { ok: 'OK ', warn: 'AVISO', fail: 'FALHA', skipped: '— ' };
18
+
19
+ async function main() {
20
+ const publish = process.argv.includes('--publish');
21
+
22
+ console.log(`\nForja release gate${publish ? ' (modo publish)' : ''}\n`);
23
+ console.log('Empacotando e instalando num diretório isolado — isto leva alguns instantes.\n');
24
+
25
+ const results = await runReleaseChecks({ publish });
26
+
27
+ for (const r of results) {
28
+ console.log(`${TAG[r.status]} ${r.id.padEnd(17)} ${r.detail}`);
29
+ if (r.fix) console.log(` corrigir: ${r.fix}`);
30
+ console.log('');
31
+ }
32
+
33
+ const verdict = worstStatus(results);
34
+
35
+ if (verdict === 'fail') {
36
+ const raiz = results.filter((r) => r.status === 'fail' && r.severity === 'critical');
37
+ console.log(`REPROVADO — ${raiz.length} falha(s) crítica(s). O pacote não deve ser publicado.`);
38
+ for (const r of raiz) console.log(` ${r.id}: ${r.fix || 'sem correção automática'}`);
39
+ process.exit(1);
40
+ }
41
+
42
+ if (verdict === 'warn') {
43
+ console.log('Aprovado com ressalvas. Nada impede o pacote de funcionar.');
44
+ if (!publish) console.log('Para o parecer de publicação, rode com --publish.');
45
+ return;
46
+ }
47
+
48
+ console.log('APROVADO — instalação limpa funciona.');
49
+ console.log('O parecer é perecível: vale para este disco, neste instante. Qualquer npm install ou');
50
+ console.log('edição posterior o invalida.');
51
+ }
52
+
53
+ main().catch((err) => {
54
+ console.error(`\nrelease-check falhou: ${err.message}`);
55
+ process.exit(1);
56
+ });
@@ -77,6 +77,66 @@ function listFeatures() {
77
77
  .filter(name => fs.statSync(path.join(specsDir, name)).isDirectory());
78
78
  }
79
79
 
80
+ /**
81
+ * `.gitignore` ignora `/specs/*` e libera as specs do framework por allow-list. Uma spec nova
82
+ * nascia invisível ao git: criada, aprovada pelo check, e descartada em silêncio. A regra existia
83
+ * só como convenção — e convenção que depende de memória não é regra. Passa a viver no harness
84
+ * (ADR-0021).
85
+ *
86
+ * Puro de propósito: recebe e devolve conteúdo, para ser testável sem tocar no .gitignore real.
87
+ *
88
+ * @returns {{ changed: boolean, content: string, reason: 'added'|'already-present'|'no-block' }}
89
+ */
90
+ export function addSpecToAllowlist(content, slug) {
91
+ const line = `!/specs/${slug}`;
92
+ const lines = content.split('\n');
93
+
94
+ if (lines.some((l) => l.trim() === line)) {
95
+ return { changed: false, content, reason: 'already-present' };
96
+ }
97
+
98
+ // Insere após a última entrada do bloco, não no fim do arquivo: as regras seguintes do
99
+ // .gitignore dependem da ordem.
100
+ let anchor = -1;
101
+ for (let i = 0; i < lines.length; i += 1) {
102
+ if (lines[i].trim().startsWith('!/specs/')) anchor = i;
103
+ }
104
+ if (anchor === -1) return { changed: false, content, reason: 'no-block' };
105
+
106
+ lines.splice(anchor + 1, 0, line);
107
+ return { changed: true, content: lines.join('\n'), reason: 'added' };
108
+ }
109
+
110
+ function gitignorePath() {
111
+ return process.env.FORJA_GITIGNORE || path.join(repoRoot, '.gitignore');
112
+ }
113
+
114
+ /** Efeito colateral de `spec:new`. Nunca derruba a criação da spec — criar a spec é o trabalho. */
115
+ function ensureSpecVersioned(slug) {
116
+ const file = gitignorePath();
117
+ let raw;
118
+ try {
119
+ raw = fs.readFileSync(file, 'utf8');
120
+ } catch {
121
+ out(' ⚠ .gitignore não encontrado — confira se a spec será versionada.');
122
+ return;
123
+ }
124
+
125
+ const result = addSpecToAllowlist(raw, slug);
126
+ if (result.reason === 'no-block') {
127
+ out(' ⚠ bloco allow-list de specs ausente no .gitignore — versione a spec manualmente.');
128
+ return;
129
+ }
130
+ if (!result.changed) return;
131
+
132
+ try {
133
+ fs.writeFileSync(file, result.content);
134
+ out(` + .gitignore: !/specs/${slug}`);
135
+ } catch {
136
+ out(` ⚠ não foi possível escrever .gitignore — adicione "!/specs/${slug}" manualmente.`);
137
+ }
138
+ }
139
+
80
140
  function cmdNew(feature) {
81
141
  if (!feature) fail('uso: spec:new <feature>');
82
142
  const slug = slugify(feature);
@@ -92,6 +152,7 @@ function cmdNew(feature) {
92
152
  });
93
153
  fs.writeFileSync(path.join(dir, 'spec.md'), content);
94
154
  out(`✓ criada: specs/${slug}/spec.md`);
155
+ ensureSpecVersioned(slug);
95
156
  out(' edite, mude status para "review", peça revisão.');
96
157
  }
97
158
 
@@ -123,15 +184,18 @@ function checkFeature(slug) {
123
184
  result.stages[stage] = status;
124
185
  }
125
186
  // Regras
187
+ // `abandoned` é terminal: uma feature pode ter avançado até plan/tasks antes de parar,
188
+ // e isso não é incoerência — é história. Ver ADR-0022.
189
+ const ALLOWS_NEXT_STAGE = ['approved', 'implementing', 'done', 'abandoned'];
126
190
  if (!result.stages.spec) {
127
191
  result.ok = false;
128
192
  result.errors.push('spec.md ausente');
129
193
  }
130
- if (result.stages.plan && !['approved', 'implementing', 'done'].includes(result.stages.spec)) {
194
+ if (result.stages.plan && !ALLOWS_NEXT_STAGE.includes(result.stages.spec)) {
131
195
  result.ok = false;
132
196
  result.errors.push(`plan.md existe mas spec status = ${result.stages.spec}`);
133
197
  }
134
- if (result.stages.tasks && !['approved', 'implementing', 'done'].includes(result.stages.plan)) {
198
+ if (result.stages.tasks && !ALLOWS_NEXT_STAGE.includes(result.stages.plan)) {
135
199
  result.ok = false;
136
200
  result.errors.push(`tasks.md existe mas plan status = ${result.stages.plan}`);
137
201
  }
@@ -178,16 +242,19 @@ function cmdSetStatus(feature, stage, status) {
178
242
  out(`✓ ${slug}/${stage}.md: ${previous} → ${status}`);
179
243
  }
180
244
 
181
- const [, , subcmd, ...rest] = process.argv;
182
- const arg = rest[0];
245
+ // Só despacha quando executado como CLI. Importado (pelos testes), expõe as funções sem rodar nada.
246
+ if (process.argv[1] && path.resolve(process.argv[1]) === __filename) {
247
+ const [, , subcmd, ...rest] = process.argv;
248
+ const arg = rest[0];
183
249
 
184
- switch (subcmd) {
185
- case 'new': cmdNew(arg); break;
186
- case 'plan': cmdNextStage('plan', arg); break;
187
- case 'tasks': cmdNextStage('tasks', arg); break;
188
- case 'check': cmdCheck(arg); break;
189
- case 'set-status': cmdSetStatus(rest[0], rest[1], rest[2]); break;
190
- default:
191
- out('Uso: spec-cli <new|plan|tasks|check|set-status> [args]');
192
- process.exit(1);
250
+ switch (subcmd) {
251
+ case 'new': cmdNew(arg); break;
252
+ case 'plan': cmdNextStage('plan', arg); break;
253
+ case 'tasks': cmdNextStage('tasks', arg); break;
254
+ case 'check': cmdCheck(arg); break;
255
+ case 'set-status': cmdSetStatus(rest[0], rest[1], rest[2]); break;
256
+ default:
257
+ out('Uso: spec-cli <new|plan|tasks|check|set-status> [args]');
258
+ process.exit(1);
259
+ }
193
260
  }