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,452 @@
1
+ /**
2
+ * lib/core/release.mjs — o gate do tarball.
3
+ *
4
+ * Guarda a fronteira que `health.mjs` não vê: **o repositório mente sobre o pacote**. No repo tudo
5
+ * resolve — `node_modules` tem as devDeps, todo arquivo está presente, o `cwd` é a raiz. Nada disso
6
+ * vale para quem roda `npm i -g forjajs`. Essa fronteira já cedeu três vezes (SPEC-010):
7
+ *
8
+ * ADR-0021 `better-sqlite3` como devDependency → dez comandos com ERR_MODULE_NOT_FOUND na
9
+ * instalação limpa. O `forja` sem argumentos funcionava, o que mascarava a quebra.
10
+ * v1.1.1 `otplib` e `qrcode` publicados sem jamais existirem no git — `npm publish` empacota o
11
+ * disco, não o commit.
12
+ * v1.1.3 `docs/dashboard.md` e o script publicados sem a pasta `dashboard/`.
13
+ *
14
+ * O princípio que organiza tudo aqui: **grep não prova ausência; instalação prova.** Por isso o
15
+ * gate empacota e instala de verdade, e por isso ele é lento — e tudo bem ser lento, porque roda
16
+ * antes de publicar, não a cada commit.
17
+ *
18
+ * O runner é o de `checks.mjs`, o mesmo do doctor. Uma máquina, duas fronteiras.
19
+ */
20
+
21
+ import { execFileSync } from 'node:child_process';
22
+ import fs from 'node:fs';
23
+ import os from 'node:os';
24
+ import path from 'node:path';
25
+ import { fileURLToPath } from 'node:url';
26
+
27
+ import { runChecks as run, worstStatus, stripTemplateLiterals } from './checks.mjs';
28
+ import { COMMANDS } from './registry.mjs';
29
+
30
+ export { worstStatus };
31
+
32
+ const __filename = fileURLToPath(import.meta.url);
33
+ const repoRoot = path.resolve(path.dirname(__filename), '..', '..');
34
+
35
+ /** Assinaturas de tarball quebrado. Exit code não serve — ver `smokeCommands`. */
36
+ const LOADER_ERRORS = /ERR_MODULE_NOT_FOUND|ERR_DLOPEN_FAILED|Cannot find module|ERR_PACKAGE_PATH_NOT_EXPORTED/;
37
+
38
+ function git(args, cwd = repoRoot) {
39
+ return execFileSync('git', args, { cwd, encoding: 'utf8' });
40
+ }
41
+
42
+ /**
43
+ * Empacota o repo e instala o tarball num diretório temporário isolado.
44
+ *
45
+ * Isolamento importa: um gate que enxerga o `node_modules` do repo mente verde. É justamente o
46
+ * `NODE_PATH` herdado e o `node_modules` vizinho que fariam um `import` quebrado resolver mesmo
47
+ * assim — e a quebra só apareceria na máquina do usuário.
48
+ *
49
+ * Limpa o temporário **sempre**, inclusive quando o callback lança.
50
+ *
51
+ * @param {(ctx: { pkgDir: string, installDir: string }) => Promise<T>|T} fn
52
+ * @returns {Promise<T>}
53
+ */
54
+ export async function withCleanInstall(fn, { root = repoRoot } = {}) {
55
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'forja-release-'));
56
+
57
+ // Isolamento de verdade — e ele vaza por onde não se espera.
58
+ //
59
+ // `NODE_PATH` é o óbvio. O traiçoeiro é o `npm_config_*`: quando o gate roda de dentro de um
60
+ // script npm (e o `prepublishOnly` é exatamente isso), o npm injeta dezenas dessas variáveis no
61
+ // ambiente. Elas carregam o `local_prefix` do repo e, sob `npm publish --dry-run`, um
62
+ // `npm_config_dry_run=true` que faz o `npm install` interno não instalar nada.
63
+ //
64
+ // Sem esta limpeza, o gate passa localmente e quebra justamente no `prepublishOnly` — o único
65
+ // lugar onde ele precisa funcionar.
66
+ const env = { ...process.env };
67
+ delete env.NODE_PATH;
68
+ for (const key of Object.keys(env)) {
69
+ if (key.startsWith('npm_')) delete env[key];
70
+ }
71
+
72
+ const npm = (args, cwd) => {
73
+ try {
74
+ return execFileSync('npm', args, { cwd, encoding: 'utf8', env, stdio: 'pipe' });
75
+ } catch (err) {
76
+ // Engolir o stderr aqui cega o diagnóstico exatamente quando ele importa.
77
+ const saida = `${err.stdout || ''}${err.stderr || ''}`.trim();
78
+ throw new Error(`npm ${args[0]} falhou em ${cwd}:\n${saida || err.message}`);
79
+ }
80
+ };
81
+
82
+ try {
83
+ const tgz = npm(['pack', '--silent', '--pack-destination', dir], root)
84
+ .trim()
85
+ .split('\n')
86
+ .pop();
87
+
88
+ npm(['init', '-y'], dir);
89
+ npm(['install', path.join(dir, tgz)], dir);
90
+
91
+ const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
92
+ const pkgDir = path.join(dir, 'node_modules', pkg.name);
93
+
94
+ return await fn({ pkgDir, installDir: dir });
95
+ } finally {
96
+ fs.rmSync(dir, { recursive: true, force: true });
97
+ }
98
+ }
99
+
100
+ // ---------------------------------------------------------------------------
101
+ // Checks
102
+ // ---------------------------------------------------------------------------
103
+
104
+ /**
105
+ * A falha da v1.1.1, e a única que nenhuma instalação pega: `npm publish` empacota o **disco**, não
106
+ * o commit. Um `npm install` casual entre a auditoria e o publish reescreve o `package.json`, e foi
107
+ * assim que `otplib` e `qrcode` chegaram ao npm sem jamais existirem no git.
108
+ *
109
+ * Severidade depende do modo: sob `--publish` é fatal; em dev é aviso — um gate que reprova todo
110
+ * desenvolvimento local é um gate que se contorna (a lição que o CI nos deu na SPEC-009).
111
+ */
112
+ const treeClean = {
113
+ id: 'tree-clean',
114
+ title: 'árvore limpa (o tarball é o commit)',
115
+ severity: 'critical',
116
+ probe(env) {
117
+ let dirty;
118
+ try {
119
+ dirty = git(['status', '--short'], env.root).trim();
120
+ } catch {
121
+ return { status: 'skipped', detail: 'fora de um repositório git', fix: null };
122
+ }
123
+
124
+ if (!dirty) return { status: 'ok', detail: 'nada não commitado', fix: null };
125
+
126
+ const n = dirty.split('\n').length;
127
+ const detalhe = `${n} arquivo(s) não commitado(s) — o tarball não corresponde a nenhum commit`;
128
+
129
+ return env.publish
130
+ ? { status: 'fail', detail: `${detalhe}. npm publish empacota o disco, não o commit`, fix: 'git commit' }
131
+ : { status: 'warn', detail: `${detalhe}. Ok para smoke; não para publicar`, fix: null };
132
+ },
133
+ };
134
+
135
+ /** Se o pacote não instala, todo o resto é irrelevante — daí todos dependerem deste. */
136
+ const install = {
137
+ id: 'install',
138
+ title: 'o pacote instala do zero',
139
+ severity: 'critical',
140
+ probe(env) {
141
+ return env.pkgDir && env.fs.existsSync(env.pkgDir)
142
+ ? { status: 'ok', detail: `instalado em ${path.basename(env.installDir)}`, fix: null }
143
+ : { status: 'fail', detail: 'o tarball não instalou', fix: 'npm pack && npm i <tgz> — investigue o erro' };
144
+ },
145
+ };
146
+
147
+ /**
148
+ * Todo comando anunciado pelo registry precisa existir no tarball. É o bug da v1.1.3, generalizado:
149
+ * `npm run dashboard` era publicado, a pasta `dashboard/` não.
150
+ */
151
+ const registryScripts = {
152
+ id: 'registry-scripts',
153
+ title: 'todo comando do registry existe no tarball',
154
+ severity: 'critical',
155
+ dependsOn: 'install',
156
+ probe(env) {
157
+ const faltando = [];
158
+ let total = 0;
159
+
160
+ for (const [name, def] of Object.entries(env.registry)) {
161
+ const rel = def.node || def.script;
162
+ if (!rel) continue;
163
+ total += 1;
164
+ if (!env.fs.existsSync(path.join(env.pkgDir, rel))) faltando.push(`${name} → ${rel}`);
165
+ }
166
+
167
+ if (faltando.length) {
168
+ return {
169
+ status: 'fail',
170
+ detail: `${faltando.length} comando(s) sem script no tarball: ${faltando.join(', ')}`,
171
+ fix: 'adicione o path ao files[] do package.json',
172
+ };
173
+ }
174
+
175
+ return { status: 'ok', detail: `${total}/${total} comandos com script presente`, fix: null };
176
+ },
177
+ };
178
+
179
+ /**
180
+ * O **código executável** do pacote — `bin/`, `lib/`, `scripts/`. Nada mais.
181
+ *
182
+ * `boilerplates/` também é publicado e também é `.js`, mas é **conteúdo**: templates copiados para
183
+ * o projeto gerado. O `next.config.js` de um boilerplate importa `next` — que é dependência do
184
+ * projeto do usuário, não do Forja. Varrer essas pastas faz o gate exigir `npm i -S next` no
185
+ * framework, o que é absurdo (observado na primeira execução real do gate).
186
+ *
187
+ * Mesmo princípio de `stripTemplateLiterals`, um nível acima: o que o Forja *escreve* não é o que
188
+ * o Forja *executa*.
189
+ */
190
+ const CODE_DIRS = ['bin', 'lib', 'scripts'];
191
+
192
+ function publishedSources(env) {
193
+ const out = [];
194
+
195
+ for (const dir of CODE_DIRS) {
196
+ const full = path.join(env.pkgDir, dir);
197
+ if (env.fs.existsSync(full)) walkDir(env, full, out);
198
+ }
199
+
200
+ return out;
201
+ }
202
+
203
+ function walkDir(env, dir, out) {
204
+ let entries;
205
+ try {
206
+ entries = env.fs.readdirSync(dir);
207
+ } catch {
208
+ return;
209
+ }
210
+ for (const entry of entries) {
211
+ const p = path.join(dir, entry);
212
+ let st;
213
+ try {
214
+ st = env.fs.statSync(p);
215
+ } catch {
216
+ continue;
217
+ }
218
+ if (st.isDirectory()) {
219
+ if (entry !== 'node_modules') walkDir(env, p, out);
220
+ } else if (/\.(mjs|js)$/.test(entry)) {
221
+ out.push(p);
222
+ }
223
+ }
224
+ }
225
+
226
+ const IMPORT_RE = /(?:^|\s)(?:import|export)[^'"]*?from\s*['"]([^'"]+)['"]|(?:^|\s)import\s*['"]([^'"]+)['"]/gm;
227
+
228
+ function importsOf(env, file) {
229
+ const src = stripTemplateLiterals(env.fs.readFileSync(file, 'utf8'));
230
+ const out = [];
231
+ for (const m of src.matchAll(IMPORT_RE)) out.push(m[1] || m[2]);
232
+ return out;
233
+ }
234
+
235
+ /** Pacote npm (não builtin, não relativo). `@scope/x/sub` → `@scope/x`. */
236
+ function packageName(specifier) {
237
+ if (!specifier || specifier.startsWith('.') || specifier.startsWith('/')) return null;
238
+ if (specifier.startsWith('node:')) return null;
239
+ const parts = specifier.split('/');
240
+ return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
241
+ }
242
+
243
+ /** Import relativo que não resolve dentro do tarball = arquivo fora do `files[]` (bug da v1.1.3). */
244
+ const importsResolve = {
245
+ id: 'imports-resolve',
246
+ title: 'imports relativos resolvem dentro do tarball',
247
+ severity: 'critical',
248
+ dependsOn: 'install',
249
+ probe(env) {
250
+ const quebrados = [];
251
+
252
+ for (const file of publishedSources(env)) {
253
+ for (const spec of importsOf(env, file)) {
254
+ if (!spec?.startsWith('.')) continue;
255
+ const alvo = path.resolve(path.dirname(file), spec);
256
+ const existe = env.fs.existsSync(alvo)
257
+ || ['.js', '.mjs', '.json'].some((ext) => env.fs.existsSync(alvo + ext));
258
+ if (!existe) quebrados.push(`${path.relative(env.pkgDir, file)} → ${spec}`);
259
+ }
260
+ }
261
+
262
+ if (quebrados.length) {
263
+ return {
264
+ status: 'fail',
265
+ detail: `${quebrados.length} import(s) sem destino no tarball: ${quebrados.slice(0, 3).join('; ')}`,
266
+ fix: 'adicione o arquivo ao files[] do package.json',
267
+ };
268
+ }
269
+
270
+ return { status: 'ok', detail: 'todo import relativo resolve', fix: null };
271
+ },
272
+ };
273
+
274
+ /** O bug do ADR-0021 §2: importado por script publicado, mas declarado como devDependency. */
275
+ const depsDeclared = {
276
+ id: 'deps-declared',
277
+ title: 'todo import externo está em dependencies',
278
+ severity: 'critical',
279
+ dependsOn: 'install',
280
+ probe(env) {
281
+ const pkg = JSON.parse(env.fs.readFileSync(path.join(env.pkgDir, 'package.json'), 'utf8'));
282
+ const deps = new Set(Object.keys(pkg.dependencies || {}));
283
+ const faltando = new Map();
284
+
285
+ for (const file of publishedSources(env)) {
286
+ for (const spec of importsOf(env, file)) {
287
+ const nome = packageName(spec);
288
+ if (!nome || deps.has(nome)) continue;
289
+ faltando.set(nome, path.relative(env.pkgDir, file));
290
+ }
291
+ }
292
+
293
+ if (faltando.size) {
294
+ const lista = [...faltando].map(([n, f]) => `${n} (${f})`).join(', ');
295
+ return {
296
+ status: 'fail',
297
+ detail: `importado pelo pacote mas não declarado em dependencies: ${lista}`,
298
+ fix: `npm i -S ${[...faltando.keys()].join(' ')}`,
299
+ };
300
+ }
301
+
302
+ return { status: 'ok', detail: `${deps.size} dependência(s), todas importadas por alguém`, fix: null };
303
+ },
304
+ };
305
+
306
+ /** Peso morto viaja no tarball de todo usuário. Incomoda; não quebra — por isso `warn` (D7). */
307
+ const depsUnused = {
308
+ id: 'deps-unused',
309
+ title: 'nenhuma dependency é peso morto',
310
+ severity: 'warn',
311
+ dependsOn: 'install',
312
+ probe(env) {
313
+ const pkg = JSON.parse(env.fs.readFileSync(path.join(env.pkgDir, 'package.json'), 'utf8'));
314
+ const deps = Object.keys(pkg.dependencies || {});
315
+ const usados = new Set();
316
+
317
+ for (const file of publishedSources(env)) {
318
+ for (const spec of importsOf(env, file)) {
319
+ const nome = packageName(spec);
320
+ if (nome) usados.add(nome);
321
+ }
322
+ }
323
+
324
+ const ociosos = deps.filter((d) => !usados.has(d));
325
+ if (ociosos.length) {
326
+ return {
327
+ status: 'warn',
328
+ detail: `declarada(s) e nunca importada(s): ${ociosos.join(', ')} — todo usuário baixa isso`,
329
+ fix: `npm rm ${ociosos.join(' ')}`,
330
+ };
331
+ }
332
+
333
+ return { status: 'ok', detail: 'nenhuma dependência ociosa', fix: null };
334
+ },
335
+ };
336
+
337
+ /**
338
+ * O check mais importante, e o mais fácil de errar.
339
+ *
340
+ * **Executar, não listar.** O `forja` sem argumentos passa mesmo com tudo quebrado — o help não
341
+ * carrega os scripts. Foi assim que a quebra do ADR-0021 §2 se escondeu: o help funcionava, e dez
342
+ * comandos estavam mortos.
343
+ *
344
+ * **Reprovar por stderr, nunca por exit code.** Numa instalação limpa não há workspace nem
345
+ * `universal.db`; `query:universal` sai com código ≠ 0 *legitimamente*, e isso é o pacote
346
+ * funcionando. O que denuncia tarball quebrado é a assinatura do carregamento. Reprovar por exit
347
+ * code reprovaria um pacote saudável — a mesma armadilha do `memory-db` na SPEC-009, um nível
348
+ * acima.
349
+ */
350
+ const smokeCommands = {
351
+ id: 'smoke-commands',
352
+ title: 'os comandos executam de verdade',
353
+ severity: 'critical',
354
+ dependsOn: 'install',
355
+ probe(env) {
356
+ const bin = path.join(env.pkgDir, 'bin', 'forja.mjs');
357
+ const quebrados = [];
358
+
359
+ for (const args of env.smokeCommands) {
360
+ const res = env.spawn(process.execPath, [bin, ...args], { cwd: env.installDir });
361
+ const saida = `${res.stdout || ''}${res.stderr || ''}`;
362
+ if (LOADER_ERRORS.test(saida)) {
363
+ const causa = saida.match(LOADER_ERRORS)[0];
364
+ quebrados.push(`${args[0] || '(help)'}: ${causa}`);
365
+ }
366
+ }
367
+
368
+ if (quebrados.length) {
369
+ return {
370
+ status: 'fail',
371
+ detail: `comando(s) não carregam na instalação limpa: ${quebrados.join('; ')}`,
372
+ fix: 'verifique files[] e dependencies — o repo resolve, o tarball não',
373
+ };
374
+ }
375
+
376
+ return {
377
+ status: 'ok',
378
+ detail: `${env.smokeCommands.length} comando(s) executam sem erro de carregamento`,
379
+ fix: null,
380
+ };
381
+ },
382
+ };
383
+
384
+ /** @type {import('./checks.mjs').Check[]} */
385
+ export const RELEASE_CHECKS = [
386
+ treeClean,
387
+ install,
388
+ registryScripts,
389
+ smokeCommands,
390
+ importsResolve,
391
+ depsDeclared,
392
+ depsUnused,
393
+ ];
394
+
395
+ /** Comandos sem efeito colateral. `tools:doctor` e `code:status` só leem; o help não prova nada sozinho. */
396
+ const DEFAULT_SMOKE = [[], ['tools:doctor'], ['code:status'], ['query:universal', 'teste']];
397
+
398
+ export function defaultEnv(overrides = {}) {
399
+ return {
400
+ root: repoRoot,
401
+ fs,
402
+ registry: COMMANDS,
403
+ smokeCommands: DEFAULT_SMOKE,
404
+ publish: false,
405
+ spawn: (cmd, args, opts) => {
406
+ try {
407
+ return {
408
+ stdout: execFileSync(cmd, args, { encoding: 'utf8', stdio: 'pipe', ...opts }),
409
+ stderr: '',
410
+ };
411
+ } catch (err) {
412
+ return { stdout: err.stdout || '', stderr: err.stderr || String(err) };
413
+ }
414
+ },
415
+ ...overrides,
416
+ };
417
+ }
418
+
419
+ /**
420
+ * Roda o gate completo: empacota, instala isolado, checa, limpa.
421
+ *
422
+ * A aprovação é **perecível** — vale para o disco naquele instante. Por isso a árvore é reconferida
423
+ * ao final: um `npm install` entre o check e o publish invalida tudo, e foi exatamente essa a causa
424
+ * da v1.1.1.
425
+ */
426
+ export async function runReleaseChecks({ publish = false, env: overrides = {} } = {}) {
427
+ const base = defaultEnv({ publish, ...overrides });
428
+
429
+ const arvoreAntes = git(['status', '--short'], base.root);
430
+
431
+ const results = await withCleanInstall(
432
+ ({ pkgDir, installDir }) => run({
433
+ checks: RELEASE_CHECKS,
434
+ env: { ...base, pkgDir, installDir },
435
+ }),
436
+ { root: base.root }
437
+ );
438
+
439
+ const arvoreDepois = git(['status', '--short'], base.root);
440
+ if (arvoreAntes !== arvoreDepois) {
441
+ results.push({
442
+ id: 'tree-stable',
443
+ title: 'a árvore não mudou durante a auditoria',
444
+ severity: 'critical',
445
+ status: 'fail',
446
+ detail: 'o disco mudou enquanto o gate rodava — este parecer está vencido',
447
+ fix: 'rode o gate de novo com a árvore parada',
448
+ });
449
+ }
450
+
451
+ return results;
452
+ }
@@ -1,16 +1,22 @@
1
1
  # Sprint Atual
2
2
 
3
3
  ## Projeto
4
- framework-root
4
+ framework-root (o repo do Forja — produtos vivem no workspace, ADR-0019)
5
5
 
6
6
  ## Objetivos
7
- - Completar itens P0/P1 do backlog com handoffs GSD registrados.
7
+ - Fechar a classe de falha "erra sem avisar" (ADR-0021) com gates executáveis, não correções pontuais.
8
8
 
9
9
  ## Itens da Sprint
10
- - [ ] P0: Inventario multiempresa + CRUD de ativos (RICE 24.0)
11
- - [ ] P0: Monitoramento de disponibilidade + status (RICE 15.8)
12
- - [ ] P1: Alertas (regras + notificacao) (RICE 14.0)
13
- - [ ] P1: Storage/NAS (capacidade/uso) (RICE 3.0)
10
+ - [x] SPEC-009 — Doctor do núcleo (`specs/doctor-do-nucleo/`, ADR-0023)
11
+ `tools:doctor` deixa de auditar só ferramentas opcionais e passa a ser gate do núcleo:
12
+ ABI nativa, memória, workspace, deps de runtime, `.mcp.json`. Exit 1 no que trava o fluxo.
13
+ - [x] `spec:new` mantém a allow-list do `.gitignore` — spec nova do framework nascia invisível ao git.
14
+
15
+ ## Próximos candidatos (sem spec ainda)
16
+ - `release-auditor` consumindo `lib/core/health.mjs` em vez de heurística própria — é a terceira
17
+ superfície prevista no ADR-0023 e a única que ainda não migrou.
18
+ - Checks de núcleo no CI (`tools:doctor` como step), fechando o ciclo: hoje o CI roda os testes,
19
+ mas não o gate.
14
20
 
15
21
  ## Ritual CLI
16
22
  - Planejar: npm run gsd:plan -- <slug> "<objetivo>"
@@ -18,4 +24,4 @@ framework-root
18
24
  - Handoff plan: npm run gsd:handoff -- plan <slug>
19
25
  - Handoff implement: npm run gsd:handoff -- implement <slug>
20
26
  - Validar: npm run gsd:check -- <slug>
21
- - Governanca: npm run project:check
27
+ - Governança: npm run project:check && npm run tools:doctor
@@ -59,7 +59,11 @@ para a execução.
59
59
  atualizada, eliminando a dependência de `lastInsertRowid`. O sync passa a purgar linhas órfãs
60
60
  do `search_idx` ao final, e o `title` volta a ser atualizado no conflito.
61
61
  - **Subagent `release-auditor`.** Audita o pacote instalando o tarball de verdade e exercitando
62
- comandos reais. Proibido aprovar por leitura de código.
62
+ comandos reais. Proibido aprovar por leitura de código. Exige árvore git limpa antes e depois:
63
+ `npm publish` empacota o **disco**, não o commit, e sua aprovação é perecível. A v1.1.1 saiu
64
+ publicada com `otplib` e `qrcode` em `dependencies` — instalados na árvore de trabalho para
65
+ gerar o código OTP do 2FA, nunca commitados, nunca importados por linha alguma do projeto.
66
+ A auditoria havia passado minutos antes, sobre um disco que deixou de existir.
63
67
  - **Skills `new-adr` e `new-command`.** Os dois rituais do repo viram etapas executáveis.
64
68
 
65
69
  ## Alternativas consideradas
@@ -0,0 +1,101 @@
1
+ # ADR-0022: Congelar o dashboard web
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-07-09
5
+ - **Autor(es)**: apk
6
+ - **Tags**: dashboard, cli, release, security, sdd
7
+
8
+ ## Contexto
9
+
10
+ O dashboard web (`dashboard/`, SPEC-002) foi implementado por inteiro: 15 rotas Fastify,
11
+ 12 telas React, 68 testes verdes, bundle de 190KB gzip. Entrou no repositório no commit
12
+ `b732e08` ("Forja v1.1 — release público inicial", 2026-07-06) e **nunca recebeu uma única
13
+ iteração** nos 12 commits seguintes. Não foi abandonado após uso — nasceu sem uso.
14
+
15
+ Três problemas concretos motivaram a decisão:
16
+
17
+ 1. **Bug de release já publicado.** O `files[]` do `package.json` nunca incluiu `dashboard/`,
18
+ mas incluía `docs/dashboard.md`, e o `package.json` publicado trazia o script
19
+ `"dashboard": "cd dashboard && npm start"`. O `README.md` documentava o comando. Resultado:
20
+ quem instalou o `forja` v1.1.2 do npm recebeu a documentação e o comando, mas não o código.
21
+ O comando quebra. O `release-auditor` não pegou porque valida o que os binários importam,
22
+ não o que a documentação promete.
23
+
24
+ 2. **Segunda fonte de verdade para comandos, já divergente.** O ADR-0020 estabeleceu que todo
25
+ comando de processo passa pelo core (`bin/forja.mjs` + `lib/core/registry.mjs`), com gates
26
+ transversais e auditoria em `.context/forja-runs.jsonl`. O dashboard mantém sua própria
27
+ `COMMAND_ALLOWLIST` hard-coded (decisão D4 da SPEC-002, por razões legítimas de segurança).
28
+ Na auditoria de 2026-07-09: o registry tem 41 comandos, a allowlist expõe 11, e
29
+ **`context:build` existe na allowlist mas não no registry** — executa via
30
+ `node scripts/dev.mjs context:build`, contornando os gates e a trilha de auditoria do core.
31
+ Um comando disparado pelo botão do dashboard não aparece na auditoria.
32
+
33
+ 3. **A documentação pública descrevia errado a superfície.** O `README.md` chamava o dashboard
34
+ de "visão opcional read-only". Ele expõe `POST /api/workflow/:project/run/:role` (dispara
35
+ execução de papéis), além de mutações em status de specs, notas de projeto e comandos.
36
+ A auditoria de RCE prevista na T12 da SPEC-002 nunca foi executada, e teria coberto apenas
37
+ `/api/commands` — as rotas `workflow` e `stacks` sequer existiam quando aquela task foi escrita.
38
+
39
+ ## Decisão
40
+
41
+ **Congelar o dashboard.** O código permanece em `dashboard/`, versionado e com os testes
42
+ passando, mas deixa de ser superfície pública e de ser tratado como parte do produto:
43
+
44
+ - `docs/dashboard.md` e `specs/agent-dashboard/` saem do `files[]` do pacote npm.
45
+ - Os cinco scripts `dashboard*` saem do `package.json` do root (o `package.json` é publicado
46
+ inteiro; não há como ter script "só local").
47
+ - `README.md` e `DOC-MAP.md` deixam de prometer o dashboard ao usuário do npm.
48
+ - SPEC-002 passa a `abandoned`. O status `parked` não existe no `spec-cli`
49
+ (`draft|review|approved|implementing|done|abandoned`), e `abandoned` é o único que não mente.
50
+
51
+ **Não unificar `registry` ↔ `allowlist` agora.** Era o caminho tecnicamente correto se o
52
+ dashboard tivesse futuro. Sem consumidor, seria infraestrutura elegante sustentando código
53
+ que ninguém roda. O `context:build` fantasma deixa de causar dano ao ser congelado junto.
54
+
55
+ ## Alternativas consideradas
56
+
57
+ - **Arquivar de vez** (mover para `docs/archive/`, fechar a spec como wontfix) — rejeitada
58
+ porque descarta 69 arquivos funcionais e testados por uma decisão reversível. O custo de
59
+ manter o código parado no repo é próximo de zero, uma vez removido das superfícies públicas.
60
+ - **Reviver: derivar a allowlist do registry** (campo `exposedToDashboard` + schema de args,
61
+ publicar `dashboard/` no `files[]`, auditar `workflow`/`stacks`) — rejeitada *por ora*
62
+ porque o dashboard nunca teve um usuário. Construir a infraestrutura antes da demanda inverte
63
+ a ordem. Continua sendo o caminho certo **se** a demanda aparecer; ver "Condições de retomada".
64
+ - **Manter como está** — rejeitada porque deixa um comando quebrado publicado no npm e um
65
+ bypass da auditoria do ADR-0020 em pé.
66
+
67
+ ## Consequências
68
+
69
+ **Positivas**:
70
+ - O pacote npm para de prometer um comando que não funciona.
71
+ - Some a segunda fonte de verdade para comandos; o `bin/forja.mjs` volta a ser a única.
72
+ - O bypass de auditoria do `context:build` deixa de ser alcançável.
73
+ - A documentação pública passa a descrever a realidade (CLI-first, sem front).
74
+ - Zero manutenção contínua: o código congelado não drifta porque não é superfície.
75
+
76
+ **Negativas / Trade-offs**:
77
+ - 69 arquivos funcionais ficam parados no repositório. É dívida visível, mas inerte.
78
+ - Quem clonar o repo vê uma pasta `dashboard/` sem entrada óbvia; mitigado por
79
+ `dashboard/README.md` explicando o estado e como subir manualmente.
80
+ - Se a demanda por uma interface visual voltar, parte do trabalho de reconciliação
81
+ (rotas novas × allowlist × registry) terá crescido no intervalo.
82
+
83
+ ## Condições de retomada
84
+
85
+ Descongelar exige, nesta ordem:
86
+
87
+ 1. Um usuário real e um caso de uso que o CLI não atenda. Sem isso, não retomar.
88
+ 2. Derivar a allowlist do registry — comando novo entra em `lib/core/registry.mjs` com
89
+ `exposedToDashboard: true` e schema de args declarado. Preserva a garantia do D4
90
+ (nada dinâmico, nada de regex, tudo em código) e mata a classe de bugs de sincronização.
91
+ 3. Auditoria de segurança das rotas mutáveis, com escopo explícito em `/api/commands`,
92
+ `/api/workflow/:project/run/:role` e `/api/stacks` — não apenas a primeira, como previa a T12.
93
+ 4. Incluir `dashboard/` no `files[]` **antes** de voltar a documentá-lo publicamente.
94
+
95
+ ## Rastreamento
96
+
97
+ - Implementação congelada: `dashboard/` (15 rotas, 12 telas, 68 testes)
98
+ - Spec: `specs/agent-dashboard/` (status `abandoned`)
99
+ - Docs: `docs/dashboard.md` (mantido no repo, fora do tarball)
100
+ - ADRs relacionadas: ADR-0020 (core CLI única — cuja fronteira o dashboard violava),
101
+ ADR-0021 (guardrails de harness)