forjajs 1.1.3 → 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.
- package/.claude/agents/governance.md +33 -10
- package/.claude/agents/release-auditor.md +44 -77
- package/CHANGELOG.md +53 -0
- package/docs/agent-harnesses.md +30 -3
- package/docs/token-optimization.md +28 -20
- package/lib/core/checks.mjs +138 -0
- package/lib/core/health.mjs +475 -0
- package/lib/core/registry.mjs +6 -1
- package/lib/core/release.mjs +452 -0
- package/memory/40-delivery/current-sprint.md +13 -7
- package/memory/90-decisions/0023-doctor-como-gate-do-nucleo.md +114 -0
- package/memory/90-decisions/0024-gate-do-tarball.md +103 -0
- package/package.json +4 -1
- package/prompts/governance-agent.md +2 -1
- package/scripts/hook-session-start.mjs +29 -39
- package/scripts/release-check.mjs +56 -0
- package/scripts/spec-cli.mjs +75 -11
- package/scripts/tools-doctor.mjs +65 -10
- package/specs/coerencia-do-sistema/spec.md +122 -0
- package/specs/doctor-do-nucleo/plan.md +165 -0
- package/specs/doctor-do-nucleo/spec.md +139 -0
- package/specs/doctor-do-nucleo/tasks.md +172 -0
- package/specs/release-gate/plan.md +174 -0
- package/specs/release-gate/spec.md +122 -0
- package/specs/release-gate/tasks.md +183 -0
|
@@ -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.
|
|
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",
|
|
@@ -34,6 +34,8 @@
|
|
|
34
34
|
"!specs/agent-dashboard/"
|
|
35
35
|
],
|
|
36
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",
|
|
37
39
|
"forja": "node bin/forja.mjs",
|
|
38
40
|
"sync:universal": "node bin/forja.mjs sync:universal",
|
|
39
41
|
"query:universal": "node bin/forja.mjs query:universal",
|
|
@@ -81,6 +83,7 @@
|
|
|
81
83
|
"code:check": "node bin/forja.mjs code:check",
|
|
82
84
|
"code:impact": "node bin/forja.mjs code:impact",
|
|
83
85
|
"tools:doctor": "node bin/forja.mjs tools:doctor",
|
|
86
|
+
"release:check": "node bin/forja.mjs release:check",
|
|
84
87
|
"test": "node --test test/*.test.js"
|
|
85
88
|
},
|
|
86
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. **
|
|
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
|
-
/**
|
|
38
|
-
async function
|
|
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(
|
|
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
|
-
*
|
|
73
|
-
*
|
|
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
|
|
76
|
-
if (!dbPath) return false;
|
|
60
|
+
async function coreHealth() {
|
|
77
61
|
try {
|
|
78
|
-
|
|
79
|
-
|
|
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
|
|
86
|
-
const
|
|
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 (
|
|
91
|
-
lines.push('
|
|
92
|
-
|
|
93
|
-
|
|
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
|
+
});
|
package/scripts/spec-cli.mjs
CHANGED
|
@@ -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
|
|
|
@@ -181,16 +242,19 @@ function cmdSetStatus(feature, stage, status) {
|
|
|
181
242
|
out(`✓ ${slug}/${stage}.md: ${previous} → ${status}`);
|
|
182
243
|
}
|
|
183
244
|
|
|
184
|
-
|
|
185
|
-
|
|
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];
|
|
186
249
|
|
|
187
|
-
switch (subcmd) {
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
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
|
+
}
|
|
196
260
|
}
|
package/scripts/tools-doctor.mjs
CHANGED
|
@@ -1,16 +1,27 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
/**
|
|
3
|
-
* tools-doctor — raio-x das ferramentas de processo (ADR-0018).
|
|
3
|
+
* tools-doctor — raio-x do núcleo (SPEC-009) e das ferramentas de processo (ADR-0018).
|
|
4
4
|
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
5
|
+
* Duas seções, dois contratos distintos:
|
|
6
|
+
*
|
|
7
|
+
* Núcleo O que impede o framework de trabalhar. Falha crítica → exit 1.
|
|
8
|
+
* Ferramentas Binários opcionais que potencializam o harness. Ausência nunca trava.
|
|
9
|
+
*
|
|
10
|
+
* A separação é o ponto. Este comando auditava só as ferramentas — sobre as quais ele mesmo
|
|
11
|
+
* dizia "o fluxo nunca trava por elas" — e era cego para tudo que trava. Quando o better-sqlite3
|
|
12
|
+
* ficou com ABI de outra major do Node e a memória universal morreu inteira, o doctor reportou
|
|
13
|
+
* "2/5 ferramentas disponíveis" e saiu com 0.
|
|
14
|
+
*
|
|
15
|
+
* Diagnostica e prescreve; não conserta. Rodar `npm rebuild` sem consentimento é a classe de
|
|
16
|
+
* risco oposta à que este comando existe para fechar.
|
|
8
17
|
*
|
|
9
18
|
* Uso: node scripts/tools-doctor.mjs
|
|
10
19
|
*/
|
|
11
20
|
|
|
12
21
|
import { spawnSync } from 'node:child_process';
|
|
13
22
|
|
|
23
|
+
import { runChecks, worstStatus } from '../lib/core/health.mjs';
|
|
24
|
+
|
|
14
25
|
const TOOLS = [
|
|
15
26
|
{
|
|
16
27
|
name: 'codegraph',
|
|
@@ -56,22 +67,66 @@ function detect(cmd, args) {
|
|
|
56
67
|
return { ok: true, version };
|
|
57
68
|
}
|
|
58
69
|
|
|
59
|
-
|
|
60
|
-
|
|
70
|
+
const TAG = {
|
|
71
|
+
ok: 'OK ',
|
|
72
|
+
warn: 'AVISO',
|
|
73
|
+
fail: 'FALHA',
|
|
74
|
+
skipped: '— ',
|
|
75
|
+
};
|
|
76
|
+
|
|
77
|
+
function printCore(results) {
|
|
78
|
+
console.log('Núcleo — o que impede o framework de trabalhar (SPEC-009)\n');
|
|
79
|
+
|
|
80
|
+
for (const r of results) {
|
|
81
|
+
console.log(`${TAG[r.status]} ${r.id.padEnd(13)} ${r.detail}`);
|
|
82
|
+
if (r.fix) console.log(` corrigir: ${r.fix}`);
|
|
83
|
+
console.log('');
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
function printTools() {
|
|
88
|
+
console.log('Ferramentas de processo — opcionais (ADR-0018)\n');
|
|
89
|
+
|
|
61
90
|
let installed = 0;
|
|
62
91
|
for (const tool of TOOLS) {
|
|
63
92
|
const [cmd, args] = tool.probe;
|
|
64
93
|
const { ok, version } = detect(cmd, args);
|
|
65
94
|
if (ok) installed += 1;
|
|
66
|
-
|
|
67
|
-
console.log(`${tag} ${tool.name.padEnd(13)} ${ok ? version : '(ausente)'}`);
|
|
95
|
+
console.log(`${ok ? TAG.ok : 'FALTA'} ${tool.name.padEnd(13)} ${ok ? version : '(ausente)'}`);
|
|
68
96
|
console.log(` papel: ${tool.role}`);
|
|
69
97
|
console.log(` gate: ${tool.gate}`);
|
|
70
98
|
if (!ok) console.log(` instalar: ${tool.install}`);
|
|
71
99
|
console.log('');
|
|
72
100
|
}
|
|
73
|
-
|
|
74
|
-
console.log(
|
|
101
|
+
|
|
102
|
+
console.log(`${installed}/${TOOLS.length} ferramentas disponíveis.`);
|
|
103
|
+
console.log('Ferramentas ausentes apenas desativam seus gates — o fluxo nunca trava por elas.\n');
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
async function main() {
|
|
107
|
+
console.log('\nForja doctor\n');
|
|
108
|
+
|
|
109
|
+
const core = await runChecks();
|
|
110
|
+
printCore(core);
|
|
111
|
+
printTools();
|
|
112
|
+
|
|
113
|
+
// Só o núcleo decide o exit code. Ferramenta ausente nunca reprova — o contrato do ADR-0018
|
|
114
|
+
// é preservado à risca.
|
|
115
|
+
const verdict = worstStatus(core);
|
|
116
|
+
|
|
117
|
+
if (verdict === 'fail') {
|
|
118
|
+
const raiz = core.filter((r) => r.status === 'fail' && r.severity === 'critical');
|
|
119
|
+
console.log(`Núcleo quebrado — ${raiz.length} ${raiz.length === 1 ? 'falha' : 'falhas'} crítica(s).`);
|
|
120
|
+
for (const r of raiz) console.log(` ${r.id}: ${r.fix || 'sem correção automática'}`);
|
|
121
|
+
process.exit(1);
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
if (verdict === 'warn') {
|
|
125
|
+
console.log('Núcleo operante, com ressalvas. Nada trava o fluxo.');
|
|
126
|
+
return;
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
console.log('Núcleo saudável.');
|
|
75
130
|
}
|
|
76
131
|
|
|
77
132
|
main();
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
# Spec: coerencia-do-sistema
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-011
|
|
4
|
+
- **Status**: review
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **Criado em**: 2026-07-14
|
|
7
|
+
- **Sprint alvo**: S?
|
|
8
|
+
- **ADRs relacionadas**: [ADR-0024](../../memory/90-decisions/0024-gate-do-tarball.md) (gate do tarball), [ADR-0023](../../memory/90-decisions/0023-doctor-como-gate-do-nucleo.md) (gate do núcleo), [ADR-0021](../../memory/90-decisions/0021-guardrails-de-harness.md) (guardrails), [ADR-0020](../../memory/90-decisions/0020-forja-core-cli-unica.md) (registry), [ADR-0009](../../memory/90-decisions/0009-claude-hooks-token-economy.md) (economia de tokens)
|
|
9
|
+
|
|
10
|
+
## 1. Problema
|
|
11
|
+
|
|
12
|
+
**Nenhum step do sistema pode ser obscuro.** O Forja é operado por agentes que leem a documentação
|
|
13
|
+
e executam o que ela manda. Quando a doc e o código divergem, o agente não erra por burrice — erra
|
|
14
|
+
por obediência.
|
|
15
|
+
|
|
16
|
+
Em 2026-07-14, uma auditoria manual encontrou:
|
|
17
|
+
|
|
18
|
+
| O que | Onde | Consequência |
|
|
19
|
+
|---|---|---|
|
|
20
|
+
| `context:build`, `memory:db:reindex`, `memory:db:stats`, `cache:clear` — **quatro comandos que não existem em lugar nenhum** | `docs/token-optimization.md` | É o documento que ensina a **economia de tokens** (ADR-0009), o mecanismo central do framework. Um agente obediente executa comandos fantasma |
|
|
21
|
+
| Link para `docs/DEPLOYMENT.md`, que nunca existiu | idem | — |
|
|
22
|
+
| `tools:doctor` descrito como *"saber quais gates opcionais estão disponíveis"* | `.claude/agents/governance.md`, `prompts/governance-agent.md` | É a definição de **antes** do ADR-0023. O papel que reprova merges não sabia que o gate reprova |
|
|
23
|
+
| `release:check` desconhecido pelo Governance | idem | Criamos o gate do tarball e não contamos a quem deveria usá-lo |
|
|
24
|
+
| 2 comandos do registry **nunca mencionados** em doc, prompt, agente ou ADR | `workspace:project:check`, `memory:extract` | Existem e ninguém sabe para quê. Capacidade obscura é capacidade morta |
|
|
25
|
+
|
|
26
|
+
Nada disso quebrou um teste. Nada apareceu no `git status`. É a classe que o ADR-0021 nomeia —
|
|
27
|
+
*erra sem avisar* — aplicada à **camada de instrução**: o sistema descreve a si mesmo de forma
|
|
28
|
+
incorreta, e quem age sobre essa descrição produz trabalho errado com aparência de trabalho certo.
|
|
29
|
+
|
|
30
|
+
Os ADRs 0023 e 0024 fecharam essa classe no núcleo e no tarball. Falta a fronteira onde ela é mais
|
|
31
|
+
barata de introduzir e mais cara de perceber: **a palavra escrita.** Toda vez que um comando é
|
|
32
|
+
renomeado, um gate muda de contrato ou uma capacidade nasce, a documentação pode silenciosamente
|
|
33
|
+
passar a mentir — e hoje nada percebe.
|
|
34
|
+
|
|
35
|
+
## 2. Proposta de valor
|
|
36
|
+
|
|
37
|
+
**O sistema é obrigado a explicar a si mesmo, e a explicação é verificada.** Comando citado existe;
|
|
38
|
+
comando que existe é citado; gate que reprova diz como corrigir. Divergência entre o que o Forja
|
|
39
|
+
faz e o que ele diz que faz passa a reprovar o gate — em vez de virar armadilha para o próximo
|
|
40
|
+
agente.
|
|
41
|
+
|
|
42
|
+
## 3. User stories
|
|
43
|
+
|
|
44
|
+
- **Como** agente lendo a documentação, **quero** que todo comando citado exista de verdade,
|
|
45
|
+
**para que** eu não execute um fantasma e conclua que o ambiente está quebrado.
|
|
46
|
+
- **Como** operador, **quero** que toda capacidade do registry esteja explicada em algum lugar,
|
|
47
|
+
**para que** eu não descubra por acaso que o framework já fazia o que fui construir à mão.
|
|
48
|
+
- **Como** governança, **quero** que a mudança de contrato de um gate **quebre** a doc que o
|
|
49
|
+
descreve errado, **para que** o `tools:doctor` não fique mais um dia sendo apresentado como
|
|
50
|
+
"inventário de ferramentas opcionais" depois de virar gate.
|
|
51
|
+
- **Como** quem mantém o framework, **quero** que renomear um comando seja um ato **detectável**,
|
|
52
|
+
**para que** a renomeação não deixe um rastro de documentação morta.
|
|
53
|
+
|
|
54
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
55
|
+
|
|
56
|
+
- [ ] AC-1: Check `docs-commands` (`scope: repo`, catálogo de `health.mjs`): todo `npm run <cmd>` /
|
|
57
|
+
`forja <cmd>` citado em `docs/`, `prompts/`, `.claude/agents/`, `AGENTS.md`, `CLAUDE.md` e
|
|
58
|
+
`README.md` existe no registry (ADR-0020).
|
|
59
|
+
- [ ] AC-2: **Comandos do projeto gerado não contam.** `start:dev`, `test:cov`, `memory:db:*` e
|
|
60
|
+
afins são do NestJS/Jest do projeto que o Forja **gera**, não do Forja. A allowlist é derivada
|
|
61
|
+
dos geradores, **não escrita à mão** — uma lista manual mente com o tempo (foi a lição do
|
|
62
|
+
`.gitignore` na SPEC-009). 7 dos 11 "fantasmas" da auditoria eram isto.
|
|
63
|
+
- [ ] AC-3: Check `commands-documented` (**warn**, `scope: repo`): todo comando do registry é
|
|
64
|
+
mencionado em pelo menos um `.md` versionado. Hoje 2 de 42 não são.
|
|
65
|
+
- [ ] AC-4: Check `docs-links` (**warn**, `scope: repo`): todo link markdown relativo entre arquivos
|
|
66
|
+
versionados resolve. `docs/DEPLOYMENT.md` era link para o nada.
|
|
67
|
+
- [ ] AC-5: Os três checks entram no `tools:doctor` e, por consequência, no CI — que já roda o
|
|
68
|
+
doctor na matriz (ADR-0024).
|
|
69
|
+
- [ ] AC-6: **Severidades honestas.** `docs-commands` é `critical` (comando fantasma faz o agente
|
|
70
|
+
agir errado). `commands-documented` e `docs-links` são `warn` (atrapalham, não impedem). Um
|
|
71
|
+
gate que reprova o que não impede trabalho é um gate que se aprende a ignorar.
|
|
72
|
+
- [ ] AC-7: Toda reprovação nomeia **arquivo e linha** e prescreve a correção. O gate que diz "algo
|
|
73
|
+
está errado" sem dizer onde é só mais um step obscuro.
|
|
74
|
+
- [ ] AC-8: Testes com fixture para cada check nos dois estados, incluindo o falso positivo do AC-2.
|
|
75
|
+
- [ ] AC-9: ADR-0025 registrando a decisão.
|
|
76
|
+
- [ ] AC-10: Os 2 comandos órfãos (`workspace:project:check`, `memory:extract`) são documentados —
|
|
77
|
+
ou removidos do registry, se não servirem mais. Capacidade obscura é capacidade morta.
|
|
78
|
+
|
|
79
|
+
## 5. Escopo
|
|
80
|
+
|
|
81
|
+
**Dentro**:
|
|
82
|
+
- `lib/core/health.mjs` — os três checks novos (o catálogo do repo).
|
|
83
|
+
- `lib/core/doc-graph.mjs` — varredura dos `.md` versionados: comandos citados, links relativos.
|
|
84
|
+
- Derivação automática da allowlist de comandos do projeto gerado, a partir de `lib/generators/`.
|
|
85
|
+
- Documentar os 2 comandos órfãos.
|
|
86
|
+
- ADR-0025 + testes.
|
|
87
|
+
|
|
88
|
+
**Fora** (explícito):
|
|
89
|
+
- **Lint de prosa** (estilo, ortografia, tamanho de linha). Isto é `markdownlint`, já previsto no
|
|
90
|
+
ADR-0018 como ferramenta opcional. Aqui só verificamos o que é **verificável contra o código**.
|
|
91
|
+
- Validar links **externos** (http). Rede no gate é flakiness garantida.
|
|
92
|
+
- Gerar documentação automaticamente a partir do registry. Doc gerada por máquina não explica o
|
|
93
|
+
*porquê*, e o porquê é a parte que importa — o gate cobra que exista, não escreve por você.
|
|
94
|
+
- Traduzir os docs em inglês (`token-optimization.md` está em inglês; outros em português). É dívida
|
|
95
|
+
real, mas é outra spec.
|
|
96
|
+
|
|
97
|
+
## 6. NFRs / restrições
|
|
98
|
+
|
|
99
|
+
- **Performance**: os três checks são `scope: repo` e só leem `.md` — ficam fora do `SessionStart`
|
|
100
|
+
(que roda `scope: runtime`). O doctor completo continua < 2s.
|
|
101
|
+
- **Zero falso positivo crítico**: o AC-2 é a prova de fogo. A auditoria manual acusou 11 comandos,
|
|
102
|
+
e 7 eram legítimos. Um `docs-commands` ingênuo teria "corrigido" a documentação de onboarding
|
|
103
|
+
inteira — pior que não ter check nenhum.
|
|
104
|
+
- **Compatibilidade**: aditivo. Nenhum comando existente muda de contrato.
|
|
105
|
+
|
|
106
|
+
## 7. Riscos e mitigação
|
|
107
|
+
|
|
108
|
+
| Risco | Probabilidade | Impacto | Mitigação |
|
|
109
|
+
|---|---|---|---|
|
|
110
|
+
| Falso positivo com comandos do projeto gerado | **A** | A | AC-2: allowlist **derivada** dos geradores, nunca manual. Já observado: 7 de 11 |
|
|
111
|
+
| Regex casa comando dentro de bloco de exemplo hipotético | M | M | Só `npm run x` / `forja x` em bloco de código. Prosa não conta |
|
|
112
|
+
| `commands-documented` vira ruído a cada comando novo | M | B | É `warn`. E documentar comando novo é o comportamento desejado |
|
|
113
|
+
| O gate engessa a doc e desestimula escrever | B | M | Ele só cobra referências a **código**; prosa é livre |
|
|
114
|
+
|
|
115
|
+
## 8. Métricas de sucesso
|
|
116
|
+
|
|
117
|
+
- **Zero** comandos fantasma na documentação, verificado a cada CI — em vez de a cada auditoria
|
|
118
|
+
manual que alguém lembrar de fazer.
|
|
119
|
+
- Renomear um comando passa a **quebrar o CI** enquanto a doc não acompanhar. Hoje renomear é grátis
|
|
120
|
+
e a doc apodrece calada.
|
|
121
|
+
- Os 42 comandos do registry passam a ter, cada um, ao menos um lugar onde o sistema explica o que
|
|
122
|
+
ele faz. Nenhum step obscuro.
|