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,183 @@
1
+ # Tasks: release-gate
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Plan**: ./plan.md
5
+ - **Status**: done
6
+ - **Criado em**: 2026-07-14
7
+
8
+ > Decomposição executável. Cada task tem dono claro, critério de done e referência a arquivos.
9
+
10
+ Ordem do plano §7: refactor puro primeiro (nada muda de comportamento), depois o catálogo, depois
11
+ as superfícies. O `prepublishOnly` vai **por último** — é a única peça que, com falso positivo,
12
+ impede publicar qualquer coisa.
13
+
14
+ ---
15
+
16
+ ## T1 — Extrair o runner para `lib/core/checks.mjs`
17
+ - **Owner**: Worker
18
+ - **Estimativa**: P
19
+ - **Depende de**: —
20
+ - **Paths**: `lib/core/checks.mjs`, `lib/core/health.mjs`, `test/health.test.js`
21
+ - **Escopo**: refactor puro. Nenhum comportamento muda; a suíte existente é o teste.
22
+ - **Done quando**:
23
+ - [ ] `runChecks` e `worstStatus` saem de `health.mjs` para `checks.mjs`, sem alteração de lógica
24
+ - [ ] `health.mjs` **re-exporta** ambos — `tools-doctor` e `hook-session-start` não mudam uma linha
25
+ - [ ] Os 36 testes de `test/health.test.js` passam **sem edição** (se precisarem mudar, não foi
26
+ refactor puro — foi mudança de comportamento disfarçada)
27
+ - [ ] Suíte completa verde
28
+
29
+ ## T2 — `withCleanInstall`: empacotar e instalar isolado
30
+ - **Owner**: Worker
31
+ - **Estimativa**: M
32
+ - **Depende de**: T1
33
+ - **Paths**: `lib/core/release.mjs`, `test/release.test.js`
34
+ - **Escopo**: a fundação do gate. Sem instalação real, nada aqui prova nada (D2).
35
+ - **Done quando**:
36
+ - [ ] `npm pack` → diretório temporário fora do repo; `npm init -y` + `npm i <tgz>`
37
+ - [ ] **Isolamento**: sem herdar `NODE_PATH` nem o `node_modules` do repo. Um gate que enxerga o
38
+ repo mente verde (NFR)
39
+ - [ ] Limpa o temporário **sempre**, inclusive em erro (`finally`)
40
+ - [ ] Teste: o diretório temporário some depois da execução, mesmo quando o callback lança
41
+
42
+ ## T3 — Checks do tarball: `registry-scripts`, `imports-resolve`
43
+ - **Owner**: Worker
44
+ - **Estimativa**: M
45
+ - **Depende de**: T2
46
+ - **Paths**: `lib/core/release.mjs`, `test/release.test.js`
47
+ - **Done quando**:
48
+ - [ ] `registry-scripts` (critical): todo comando do registry tem seu `node:` presente no tarball.
49
+ Hoje são 41/41 — o gate torna permanente o que hoje é verdade acidental (AC-5)
50
+ - [ ] `imports-resolve` (critical): todo import **relativo** de script publicado resolve dentro do
51
+ tarball (AC-6)
52
+ - [ ] **Template literals apagados antes do parse** (D3): os geradores contêm código NestJS que
53
+ eles *escrevem*, não que executam. Sem isso o check acusa `./app.module` como quebrado —
54
+ já observado em campo
55
+ - [ ] Fixture: tarball com arquivo fora do `files[]` **reprova** (bug real da v1.1.3)
56
+
57
+ ## T4 — Checks de dependência: `deps-declared`, `deps-unused`
58
+ - **Owner**: Worker
59
+ - **Estimativa**: M
60
+ - **Depende de**: T2
61
+ - **Paths**: `lib/core/release.mjs`, `test/release.test.js`
62
+ - **Done quando**:
63
+ - [ ] `deps-declared` (critical): todo pacote importado por código sob `files[]` está em
64
+ `dependencies` (AC-6)
65
+ - [ ] `deps-unused` (**warn**, D7): `dependency` que ninguém importa é peso morto no tarball de
66
+ todo usuário — incomoda, não quebra
67
+ - [ ] Template literals apagados antes do parse, aqui também. Sem isso, `@nestjs/core` aparece
68
+ como dependência não declarada
69
+ - [ ] Fixture: `better-sqlite3` movido para `devDependencies` **reprova** (bug real do ADR-0021)
70
+
71
+ ## T5 — `smoke-commands`: executar, não listar
72
+ - **Owner**: Worker
73
+ - **Estimativa**: M
74
+ - **Depende de**: T2
75
+ - **Paths**: `lib/core/release.mjs`, `test/release.test.js`
76
+ - **Escopo**: o check mais importante e o mais fácil de errar. O `forja` sem argumentos passa mesmo
77
+ com tudo quebrado — o help não carrega os scripts. Foi assim que a quebra do ADR-0021 se escondeu.
78
+ - **Done quando**:
79
+ - [ ] Executa comandos sem efeito colateral na instalação limpa: help, `tools:doctor`,
80
+ `code:status`, `query:universal` (AC-4)
81
+ - [ ] **Reprova por assinatura no stderr, nunca por exit code** (D8): `ERR_MODULE_NOT_FOUND`,
82
+ `ERR_DLOPEN_FAILED`, `Cannot find module`. Numa instalação limpa não há workspace nem
83
+ `universal.db`, então exit ≠ 0 é o pacote **funcionando** — reprovar ali seria repetir a
84
+ armadilha do `memory-db` na SPEC-009
85
+ - [ ] Teste: comando que sai ≠ 0 por falta de workspace **passa**; comando com
86
+ `ERR_MODULE_NOT_FOUND` **reprova**
87
+
88
+ ## T6 — `tree-clean` e os dois modos
89
+ - **Owner**: Worker
90
+ - **Estimativa**: P
91
+ - **Depende de**: T2
92
+ - **Paths**: `lib/core/release.mjs`, `test/release.test.js`
93
+ - **Done quando**:
94
+ - [ ] `git status --short` com qualquer saída: `fail` sob `--publish`, `warn` sem ele (D4)
95
+ - [ ] Roda **antes** de empacotar: auditar um tarball que não é o que será publicado é auditar
96
+ ficção
97
+ - [ ] **Reconferido ao final** (D5): a aprovação é perecível. Um `npm install` entre o check e o
98
+ publish invalida tudo — foi exatamente a causa da v1.1.1
99
+ - [ ] Fixture: árvore suja + `--publish` **reprova** (bug real da v1.1.1)
100
+
101
+ ## T7 — `release:check` (CLI + registry)
102
+ - **Owner**: Worker
103
+ - **Estimativa**: P
104
+ - **Depende de**: T3, T4, T5, T6
105
+ - **Paths**: `scripts/release-check.mjs`, `lib/core/registry.mjs`, `package.json`
106
+ - **Done quando**:
107
+ - [ ] Saída com o mesmo vocabulário do `tools:doctor` (OK/AVISO/FALHA + correção ao lado)
108
+ - [ ] `exit 1` se e somente se algum `critical` falhar (AC-1)
109
+ - [ ] Entrada no registry (ADR-0020); `test/forja-core.test.js` verde
110
+ - [ ] Flag `--publish` documentada no help
111
+
112
+ ## T8 — Endurecer `runtime-deps` (dívida do ADR-0023)
113
+ - **Owner**: Worker
114
+ - **Estimativa**: P
115
+ - **Depende de**: T1
116
+ - **Paths**: `lib/core/health.mjs`, `test/health.test.js`
117
+ - **Contexto**: o check que entregamos na SPEC-009 passa **por sorte**. Os geradores contêm
118
+ `import { Module } from '@nestjs/common'` em template string; hoje não quebra porque `@nestjs/*`
119
+ não está nas devDeps. No dia em que estiver, ele trava o gate com falso positivo crítico.
120
+ - **Done quando**:
121
+ - [ ] Template literals apagados antes do parse, como em T3/T4 (AC-11)
122
+ - [ ] Teste com um gerador contendo `import` de devDependency **dentro de crases**: não reprova
123
+ - [ ] Teste com import real de devDependency fora de crases: continua reprovando
124
+
125
+ ## T9 — CI: `tools:doctor` e `release:check` como steps
126
+ - **Owner**: Worker
127
+ - **Estimativa**: P
128
+ - **Depende de**: T7
129
+ - **Paths**: `.github/workflows/ci.yml`
130
+ - **Done quando**:
131
+ - [ ] `tools:doctor` vira step (AC-9) — o gate do ADR-0023 existe e hoje **nada o executa**
132
+ - [ ] `release:check` vira step. Roda uma vez (não na matriz inteira): o custo é o `npm i`
133
+ compilando o `better-sqlite3` do zero, e três vezes não prova mais que uma
134
+ - [ ] O CI verde vira a **evidência** do release, no log, em vez de na memória de quem publicou
135
+
136
+ ## T10 — ADR-0024 e documentação
137
+ - **Owner**: SDD Architect
138
+ - **Estimativa**: P
139
+ - **Depende de**: T7
140
+ - **Paths**: `memory/90-decisions/0024-*.md`, `docs/publishing.md`, `CLAUDE.md`
141
+ - **Done quando**:
142
+ - [ ] ADR-0024 registra D1 (runner extraído), D8 (stderr, não exit code) e D9 (`prepublishOnly`,
143
+ nunca `prepack`), referenciando ADR-0023 e ADR-0021
144
+ - [ ] Os três bugs históricos citados como evidência — são o argumento da decisão
145
+ - [ ] `docs/publishing.md` passa a mandar rodar o gate, não a confiar no ritual
146
+
147
+ ## T11 — `release-auditor` consome o gate
148
+ - **Owner**: Worker
149
+ - **Estimativa**: P
150
+ - **Depende de**: T7
151
+ - **Paths**: `.claude/agents/release-auditor.md`
152
+ - **Done quando**:
153
+ - [ ] O agente **roda `release:check`** e interpreta o resultado, em vez de reimplementar o
154
+ procedimento em prosa (AC-10)
155
+ - [ ] Some o passo-a-passo manual de `npm pack`/`grep`: virou código, e código não esquece
156
+ - [ ] Permanece o que só um agente faz: julgar o que o gate não sabe julgar, e recomendar
157
+
158
+ ## T12 — `prepublishOnly` (por último)
159
+ - **Owner**: Governance
160
+ - **Estimativa**: P
161
+ - **Depende de**: T9 verde por um ciclo
162
+ - **Paths**: `package.json`
163
+ - **Escopo**: a peça de risco alto. Com falso positivo aqui, **ninguém publica nada**.
164
+ - **Done quando**:
165
+ - [ ] `"prepublishOnly": "npm run release:check -- --publish"` (AC-8)
166
+ - [ ] Comentário no `package.json`: **nunca** amarrar ao `prepack` — o gate roda `npm pack`, e
167
+ isso seria recursão infinita (D9)
168
+ - [ ] Validado com `npm publish --dry-run`
169
+ - [ ] Só entra **depois** de o gate rodar verde no CI por um ciclo (plano §7)
170
+
171
+ ---
172
+
173
+ ## Validação final (Governance)
174
+ - [ ] Os **três bugs históricos**, reintroduzidos um a um, reprovam o gate: `better-sqlite3` em
175
+ devDeps (ADR-0021), arquivo fora do `files[]` (v1.1.3), árvore suja no publish (v1.1.1).
176
+ Um gate que nunca viu a falha que promete pegar não está testado — está escrito.
177
+ - [ ] `npm test`, `project:check`, `tools:doctor` e `gitleaks` verdes
178
+ - [ ] Suíte completa verde; spec → `done`
179
+
180
+ ## Handoffs entre agentes
181
+
182
+ Worker (T1-T9, T11), SDD Architect (T10), Governance (T12 + validação). Handoff a cada fronteira
183
+ via `npm run agent:route` — 7 campos (ADR-0005).
package/docs/dashboard.md DELETED
@@ -1,102 +0,0 @@
1
- # Dashboard
2
-
3
- Painel web local para monitorar specs, handoffs e tokens do framework, e disparar comandos da CLI canônica.
4
-
5
- - **Localização**: `dashboard/`
6
- - **Bind**: `127.0.0.1` (nunca expõe a rede — kill criterion da SPEC-002)
7
- - **Porta default**: `7777` (override via `DASHBOARD_PORT`)
8
-
9
- ## Subir
10
-
11
- ```bash
12
- # Primeira vez — instala backend + frontend
13
- npm run dashboard:install
14
-
15
- # Build do frontend
16
- npm run dashboard:web:build
17
-
18
- # Sobe servidor (serve SPA + API)
19
- npm run dashboard
20
- # → http://127.0.0.1:7777
21
- ```
22
-
23
- Modo dev (HMR no frontend, backend separado):
24
-
25
- ```bash
26
- # terminal 1 — API
27
- npm run dashboard
28
- # terminal 2 — Vite com proxy /api → 7777
29
- npm run dashboard:web:dev
30
- # → http://127.0.0.1:5173
31
- ```
32
-
33
- ## Telas
34
-
35
- | Rota | O quê | Fonte |
36
- |---|---|---|
37
- | `/` (Briefing) | Textarea → POST `/api/briefing` → `spec.md` em status `draft` | parser heurístico (D5) |
38
- | `/specs` | Tabela com status colorido + drawer com spec/plan/tasks | `specs/*/` |
39
- | `/handoffs` | Kanban 3 colunas com botões de transição | `universal.db.handoffs` |
40
- | `/tokens` | Linha 30d por projeto, totais agregados | `.context/*` + `60-runs/*.json` |
41
- | `/commands` | 5 botões com painel SSE ao vivo | allowlist hard-coded |
42
- | `/projects` | Cards com badges (specs, handoffs, commit, memória) | `projects/*` + git + SQLite |
43
-
44
- Polling 30s em todas as telas (pausa quando aba não-visível).
45
-
46
- ## Allowlist de comandos (ADR-0009 + plan §4 D4)
47
-
48
- Hard-coded em `dashboard/server/lib/allowlist.mjs`. Qualquer outro nome → `403`.
49
-
50
- | Nome | Comando |
51
- |---|---|
52
- | `spec:check` | `node scripts/spec-cli.mjs check` |
53
- | `sync:universal` | `node scripts/sync-universal-memory.js` |
54
- | `memory:vacuum` | `node scripts/compress-memory.mjs` |
55
- | `project:check` | `node scripts/check-standards.js` |
56
- | `sprint:status` | `node scripts/sprint-manager.js status` |
57
-
58
- Para adicionar comando novo: edite a constante, adicione teste, documente aqui — exige PR e revisão.
59
-
60
- ## Endpoints (API)
61
-
62
- ```
63
- GET /api/health
64
- GET /api/specs
65
- GET /api/specs/:slug
66
- GET /api/handoffs?status=&to=&from=&spec=&limit=
67
- GET /api/handoffs/:id
68
- POST /api/handoffs/:id/transition body { to }
69
- GET /api/projects
70
- GET /api/tokens?project=&days=30
71
- GET /api/commands
72
- POST /api/commands/:name SSE
73
- POST /api/briefing body { brief, slug, projectHint? }
74
- ```
75
-
76
- ## Troubleshooting
77
-
78
- **`EADDRINUSE: 7777`** — outra instância já está rodando. Mate com `lsof -ti:7777 | xargs kill` ou use `DASHBOARD_PORT=7778 npm run dashboard`.
79
-
80
- **`/api/handoffs` retorna `[]` no primeiro acesso** — `universal.db` ainda não foi criado. Rode `node scripts/agent-router.mjs schema` ou abra qualquer handoff via `agent-router append`.
81
-
82
- **SPA mostra placeholder em vez das telas** — `dashboard/web/dist/` não existe. Rode `npm run dashboard:web:build`.
83
-
84
- **Briefing recusa slug** — kebab-case, 2-64 caracteres, começando com letra/dígito. Use o auto-slug do form.
85
-
86
- **SSE corta no meio** — alguns proxies bufferizam SSE. Mantenha o dashboard em `127.0.0.1` direto, sem reverse proxy.
87
-
88
- ## Segurança
89
-
90
- - Bind exclusivo em `127.0.0.1` (não há flag para abrir para rede — proposital)
91
- - Allowlist literal em código (não config) — ADR-0009 D4
92
- - `spawn` sem `shell: true`; sem interpolação de args do body
93
- - `POST /api/briefing` valida slug com regex e bloqueia conflito de spec existente
94
- - `POST /api/handoffs/:id/transition` aceita só `in_progress | done | cancelled`
95
- - 95% das telas são read-only; mutação só via shell-out para a CLI canônica
96
-
97
- ## Limites conhecidos (v1)
98
-
99
- - Briefing usa heurística simples — não LLM (D5). Sucesso depende do briefing seguir padrão "Hoje…", "Queremos…", "Como X, quero Y, para que Z".
100
- - Tokens são estimativa por `chars/4`, não consumo real da API.
101
- - Polling 30s; sem WebSocket.
102
- - Sem auth, sem multi-usuário (intencional — kill criterion).
@@ -1,165 +0,0 @@
1
- # Plan: agent-dashboard
2
-
3
- - **Spec**: ./spec.md
4
- - **Status**: approved
5
- - **Criado em**: 2026-05-11
6
-
7
- ## 1. Abordagem técnica
8
-
9
- Servidor único Node (Fastify) servindo: **(a)** JSON API que lê `universal.db` + filesystem, **(b)** SPA estática buildada do `dashboard/web/`. Não há SSR, não há processo separado. SPA chama `/api/*`. Comandos do framework são disparados via `child_process.spawn` com **allowlist hard-coded**, stream de stdout/stderr via SSE (Server-Sent Events — mais simples que WebSocket, suficiente para output linear). Briefing → spec é shell-out para `scripts/spec-cli.mjs` + um parser de heurística (sem LLM nesta versão).
10
-
11
- Tudo isolado em `dashboard/` com seu próprio `package.json`. O kit raiz não ganha dependência runtime nova — `npm run dashboard` no root delega para `cd dashboard && npm start`.
12
-
13
- ## 2. Módulos afetados
14
-
15
- | Caminho | Mudança | Risco |
16
- |---|---|---|
17
- | `dashboard/package.json` | criar — deps: fastify, better-sqlite3 (já existe no kit), execa | B |
18
- | `dashboard/server/index.mjs` | criar — bootstrap Fastify + registro de rotas | B |
19
- | `dashboard/server/routes/specs.mjs` | criar — `GET /api/specs`, `GET /api/specs/:slug` | B |
20
- | `dashboard/server/routes/handoffs.mjs` | criar — `GET /api/handoffs`, `POST /api/handoffs/:id/transition` | M |
21
- | `dashboard/server/routes/tokens.mjs` | criar — `GET /api/tokens?project=&days=30` | M |
22
- | `dashboard/server/routes/projects.mjs` | criar — `GET /api/projects` | B |
23
- | `dashboard/server/routes/commands.mjs` | criar — `POST /api/commands/:name` com SSE; allowlist | A (RCE) |
24
- | `dashboard/server/routes/briefing.mjs` | criar — `POST /api/briefing` → cria spec | M |
25
- | `dashboard/server/lib/allowlist.mjs` | criar — fonte única de comandos permitidos | A |
26
- | `dashboard/server/lib/briefing-parser.mjs` | criar — heurística texto → seções spec | M |
27
- | `dashboard/server/lib/token-estimator.mjs` | criar — chars/4 + leitura de `60-runs/` | B |
28
- | `dashboard/web/` (Vite+React) | criar — 5 telas + layout | M |
29
- | `package.json` (root) | editar — adicionar `dashboard` script | B |
30
- | `.gitignore` | editar — ignorar `dashboard/web/dist`, `dashboard/node_modules` | B |
31
- | `docs/dashboard.md` | criar — uso, troubleshooting, allowlist | B |
32
-
33
- ## 3. Diagrama de fluxo
34
-
35
- ```
36
- Browser (localhost:7777)
37
- │
38
- ├─ HTML/JS estático ──→ dashboard/web/dist/
39
- │
40
- └─ /api/* ──→ Fastify ──┬─ better-sqlite3 ──→ .memory/sqlite/universal.db
41
- ├─ fs ──→ specs/, projects/, memory/60-runs/
42
- └─ spawn (allowlist) ──→ scripts/spec-cli.mjs
43
- ──→ scripts/agent-router.mjs
44
- ──→ scripts/compress-memory.mjs
45
- ──→ scripts/sync-universal-memory.js
46
- ──→ scripts/check-standards.js
47
- ──→ scripts/sprint-manager.js
48
-
49
- SSE stream de stdout/stderr ─────────────────→ painel lateral da UI
50
- ```
51
-
52
- ## 4. Contratos (API)
53
-
54
- Todas as rotas montadas sob `/api`. Retorno padrão JSON. Erros 4xx/5xx em `{error: string, code: string}`.
55
-
56
- ### Leitura
57
-
58
- ```ts
59
- GET /api/specs
60
- → [{ slug, status, file, sprint, owner, hasplan, hastasks }]
61
-
62
- GET /api/specs/:slug
63
- → { slug, spec: string, plan: string|null, tasks: string|null }
64
-
65
- GET /api/handoffs?status=open|in_progress|done&to=<agent>
66
- → [{ id, created_at, from_agent, to_agent, intent, status, spec_slug, ... }]
67
-
68
- POST /api/handoffs/:id/transition
69
- body: { to: "in_progress"|"done"|"cancelled" }
70
- → { id, status }
71
-
72
- GET /api/projects
73
- → [{ name, path, specs_open, handoffs_open, last_commit, memory_bytes }]
74
-
75
- GET /api/tokens?project=<name>&days=30
76
- → { project, days, series: [{ date, tokens_in, tokens_out, mode_breakdown }] }
77
- ```
78
-
79
- ### Mutação controlada
80
-
81
- ```ts
82
- POST /api/commands/:name
83
- body: { args?: string[] } // args só usado se a entrada na allowlist permitir
84
- → SSE stream (text/event-stream): evento "stdout"|"stderr"|"exit"
85
-
86
- :name ∈ COMMAND_ALLOWLIST (commands.mjs)
87
-
88
- POST /api/briefing
89
- body: { brief: string, slug?: string, projectHint?: string }
90
- → { slug, specPath, parsed: { problem, value, stories } }
91
- ```
92
-
93
- ### Allowlist (hard-coded)
94
-
95
- ```js
96
- export const COMMAND_ALLOWLIST = {
97
- 'spec:check': { cmd: 'node', args: ['scripts/spec-cli.mjs', 'check'] },
98
- 'sync:universal': { cmd: 'node', args: ['scripts/sync-universal-memory.js'] },
99
- 'memory:vacuum': { cmd: 'node', args: ['scripts/compress-memory.mjs'] },
100
- 'project:check': { cmd: 'node', args: ['scripts/check-standards.js'] },
101
- 'sprint:status': { cmd: 'node', args: ['scripts/sprint-manager.js', 'status'] },
102
- };
103
- ```
104
-
105
- Qualquer outro `:name` retorna `403 { error: "command not allowlisted" }`. Sem interpolação de shell — `spawn` direto sem `shell: true`. `args` do body só é apendado se a entrada da allowlist marcar `acceptsArgs: true` (nenhuma marca isso na v1).
106
-
107
- ## 5. Decisões e alternativas
108
-
109
- **D1 — Fastify em vez de Express**
110
- Razão: mais rápido, hooks de erro estritos, schema validation embutida. Rejeitada: Express (mais boilerplate, precisa ajv separado).
111
-
112
- **D2 — Vite + React + shadcn/ui**
113
- Razão: shadcn é copy-paste (não vira dep gigante), Tailwind já é stack confortável, ecossistema rico de tabelas/kanban/charts. Rejeitada: htmx puro (gráfico precisa Recharts); Svelte (menos componentes prontos).
114
-
115
- **D3 — SSE em vez de WebSocket**
116
- Razão: stdout/stderr é unidirecional. SSE roda em HTTP simples, sem upgrade, sem libs. Rejeitada: WebSocket (over-engineering); polling em log file (latência, cleanup).
117
-
118
- **D4 — Allowlist literal em código, não config**
119
- Razão: arquivo editável aumenta superfície (quem escreve no `.allowlist.json` ganha RCE). Hard-coded em `.mjs` exige PR + revisão. Rejeitada: regex `spec:*` (escapa para `spec:; rm -rf` se algum dia passar via shell).
120
-
121
- **D5 — Briefing parser heurístico, sem LLM nesta versão**
122
- Razão: dep zero, custo zero, latência zero. Heurística: split em parágrafos, busca palavras-chave ("problema", "queremos", "para que <persona>"), preenche seções 1-3 do template. Saída fica em `draft` — revisão humana obrigatória. Rejeitada nesta versão: Anthropic API (env var, custo, latência, dep). Evolui para v2 (potencial ADR-0011).
123
-
124
- **D6 — Pasta `dashboard/` isolada com próprio `package.json`**
125
- Razão: zero impacto em quem só usa o kit como scaffold. Rejeitada: workspaces npm (complica `npm publish` do kit).
126
-
127
- **D7 — Token estimator: chars/4, sem chamada API real**
128
- Razão: spec §5 já marca "custo real" como fora de escopo. Estimativa rotulada na UI. Fonte: agrega `memory/60-runs/*.json` se existir, lê tamanho dos packs em `.context/` por projeto. Rejeitada: Anthropic Usage API (exige API key local, expõe credencial).
129
-
130
- **D8 — Porta 7777 default, configurável via `DASHBOARD_PORT`**
131
- Razão: porta raramente ocupada. Override por env var resolve conflito.
132
-
133
- > Nenhuma destas decisões parece estrutural-irreversível o suficiente para abrir ADR. Se durante a impl emergir uma irreversível, abrir ADR-0010.
134
-
135
- ## 6. Dependências
136
-
137
- - **Specs**: depende de SPEC-001 (já em `implementing`) — usa `spec-cli.mjs` e `agent-router.mjs`
138
- - **Pacotes npm novos** (todos em `dashboard/package.json`, não no root):
139
- - `fastify`, `@fastify/static`, `@fastify/cors`
140
- - `better-sqlite3` (já é devDep no root — duplicado no dashboard)
141
- - Front: `vite`, `react`, `react-dom`, `react-router-dom`, `tailwindcss`, `recharts`
142
- - shadcn/ui via CLI (copy-paste, não vira dep)
143
- - **Migrações de memória**: nenhuma — `projects`, `memory_nodes`, `handoffs` já existem em `universal.db`
144
-
145
- ## 7. Rollout
146
-
147
- - [x] Feature flag: não — `npm run dashboard` é opt-in por natureza
148
- - [x] Migração de dados: não
149
- - [ ] Doc/persona: criar `docs/dashboard.md`, linkar em `DOC-MAP.md`; mencionar em `docs/personas/developer/` como ferramenta visual
150
-
151
- ## 8. Sinais de fracasso (kill criteria)
152
-
153
- Abandonar / refatorar profundamente se:
154
- - Allowlist for desviada via injection (qualquer comando fora dela conseguir rodar)
155
- - Polling 30s × 10 projetos passar de 500ms p95 em `/api/tokens` — estimativa por leitura de arquivos não escala
156
- - Briefing heurístico produzir spec reescrita 100% em > 80% dos casos — sinal de que precisa LLM
157
- - Dashboard aberto < 1×/semana após 30d — leitura ASCII era suficiente
158
-
159
- ## Próximo handoff
160
- SDD Architect → Product (revisar plan) → SDD Architect (gerar `tasks.md`) → Worker (impl).
161
- Quando este plan for aprovado, rodar:
162
- ```bash
163
- node scripts/spec-cli.mjs tasks agent-dashboard
164
- node scripts/agent-router.mjs done 2
165
- ```
@@ -1,89 +0,0 @@
1
- # Spec: agent-dashboard
2
-
3
- - **ID**: SPEC-002
4
- - **Status**: implementing
5
- - **Owner**: apk
6
- - **Criado em**: 2026-05-11
7
- - **Sprint alvo**: refator-2026-05 (próximo após SPEC-001)
8
- - **ADRs relacionadas**: ADR-0002 (SQLite/FTS5), ADR-0005 (handoff 7 campos), ADR-0008 (sub-agents)
9
-
10
- ## 1. Problema
11
-
12
- Hoje só dá pra acompanhar o framework pelo terminal: `agent-router list`, `spec:check`, ler `60-runs/` na unha. Resultado:
13
-
14
- - **Visibilidade**: difícil ver de relance o estado dos 10 projetos em `projects/` — quantas specs ativas, handoffs travados, sprint em curso, sem rodar 3-4 comandos.
15
- - **Custo invisível**: smart-context economiza tokens (40-60%, ADR-0003), mas não há gráfico de consumo ao longo do tempo. Não dá pra responder "qual projeto come mais token?".
16
- - **Onboarding de feature novo**: começar uma feature exige saber a CLI inteira (`spec:new`, mexer em `vision.md`, rodar `sync:universal`). Para o próprio autor é OK; para qualquer outro humano é fricção.
17
- - **Briefing perdido**: quando uma feature nasce de uma conversa, o "porquê" original some entre WhatsApp/Notion/cabeça. Falta um ponto de captura inicial que vire `spec.md` direito.
18
-
19
- ## 2. Proposta de valor
20
-
21
- Um painel web local (`npm run dashboard`) que: **(a)** mostra estado de specs/handoffs/tokens em tempo quase-real, **(b)** permite iniciar uma feature a partir de um briefing em texto livre que vira `spec.md`, e **(c)** dispara os comandos principais do framework com 1 clique. CLI continua canônica — a UI é leitura + atalho de entrada.
22
-
23
- ## 3. User stories
24
-
25
- - **Como** autor do framework, **quero** ver num gráfico quanto cada projeto consumiu de tokens nos últimos 30 dias, **para que** eu decida onde investir compressão/cache.
26
- - **Como** Product Agent, **quero** colar um briefing em texto livre e receber um rascunho de `spec.md` pré-preenchido, **para que** eu salte a página em branco.
27
- - **Como** Orchestrator, **quero** ver handoffs abertos em kanban (open / in_progress / done), **para que** eu detecte gargalo (ex: 4 handoffs parados em `sdd-architect`).
28
- - **Como** dev de outro projeto, **quero** botões para `spec:check`, `sync:universal` e `memory:vacuum`, **para que** eu não precise memorizar a CLI.
29
- - **Como** Governance Agent, **quero** ver quais features estão em `implementing` sem ADR referenciada no plan, **para que** eu bloqueie a tempo.
30
-
31
- ## 4. Critérios de aceite
32
-
33
- - [x] **AC-1**: `npm run dashboard` sobe servidor local (Vite ou Express estático) em `localhost:<porta>` e abre o browser
34
- - [x] **AC-2**: Tela "Specs" lista todas as features de `specs/<slug>/` com status colorido (draft/review/approved/implementing/done/abandoned) e link para spec.md/plan.md/tasks.md
35
- - [x] **AC-3**: Tela "Handoffs" mostra 3 colunas (open / in_progress / done) lidas de `universal.db.handoffs`; permite marcar como `done` ou `in_progress` via botão (chama `agent-router`)
36
- - [x] **AC-4**: Tela "Tokens" mostra gráfico (linha) de tokens estimados por dia nos últimos 30d, agregado por projeto, lido de `memory_nodes` + `60-runs/`
37
- - [x] **AC-5**: Tela "Novo briefing" tem um `<textarea>` ≥10 linhas + select de projeto-alvo. Botão "Gerar spec" envia o texto para um endpoint que: (a) cria `specs/<slug>/` via `spec-cli.mjs new`, (b) pré-preenche seções 1-3 (Problema/Valor/User stories) com o briefing em prosa estruturada, (c) deixa o status em `draft` para o usuário revisar
38
- - [x] **AC-6**: Tela "Comandos" tem botões para: `spec:check`, `sync:universal`, `memory:vacuum`, `project:check`, `sprint:status` — cada um abre painel lateral com stdout/stderr em tempo real
39
- - [x] **AC-7**: Tela "Projetos" lista `projects/*` com badges (specs ativas, handoffs abertos, último commit, tamanho da memória)
40
- - [x] **AC-8**: Polling de 30s atualiza dados sem refresh manual
41
- - [x] **AC-9**: Acessível somente a `localhost` (binding em `127.0.0.1`), sem auth; documentado como "ferramenta de dev local"
42
- - [x] **AC-10**: `npm run dashboard` funciona sem instalar nada além de `npm install` no repo
43
-
44
- ## 5. Escopo
45
-
46
- **Dentro**:
47
- - Backend Express/Fastify minimalista (1 arquivo, lê SQLite e fs)
48
- - Frontend Vite + React + shadcn/ui (ou alternativa mais leve se justificada no plan)
49
- - 5 telas: Specs, Handoffs, Tokens, Briefing, Comandos, Projetos
50
- - Polling simples (30s) — sem WebSocket
51
- - "Pré-preenchimento" de spec via heurística simples (regex/keywords no briefing) — sem LLM nesta primeira versão
52
- - Cores e estados ligados a ADR-0007 (status SDD) e ADR-0008 (status handoff)
53
-
54
- **Fora** (explícito, evita scope creep):
55
- - Edição livre de spec.md/plan.md/tasks.md pela UI (só status via comando)
56
- - Pré-preenchimento via LLM real (Anthropic/OpenAI API) — fica para v2
57
- - ~~WebSocket / SSE / push em tempo real~~ — **revisado 2026-05-11: SSE de eventos adicionado para que toda ação da UI exiba o comando executando ao vivo**
58
- - WebSocket bidirecional (mantém SSE simples)
59
- - Auth, multi-usuário, deploy remoto
60
- - Custo real consumido na API Anthropic (depende de plumbing extra)
61
- - Mobile / responsive sério (desktop-first; degrada graciosamente)
62
- - Dark mode toggle (segue OS, sem switch)
63
- - i18n (pt-BR fixo)
64
-
65
- ## 6. NFRs / restrições
66
-
67
- - **Performance**: primeira pintura < 1s em localhost; polling não pode passar de 200ms na rota mais pesada (tokens)
68
- - **Segurança**: bind em `127.0.0.1` apenas; nunca expõe a rede; endpoints que invocam scripts (Comandos, Briefing) precisam allowlist explícita — `npm` arbitrário NÃO
69
- - **Compatibilidade**: não quebra nenhum script npm existente; CLI continua sendo a fonte da verdade
70
- - **Observabilidade**: cada ação que dispara comando loga em `60-runs/dashboard-<ts>.json`
71
- - **Dependências**: zero novas runtime deps no kit base (só dev). Frontend isolado em `dashboard/` com seu próprio `package.json`
72
- - **Tamanho do bundle**: front com menos de 500KB gzipped
73
-
74
- ## 7. Riscos e mitigação
75
-
76
- | Risco | P | I | Mitigação |
77
- |---|---|---|---|
78
- | Dashboard vira "fonte da verdade" e dessincroniza com CLI | M | A | Read-only em 95% das telas; mutações sempre via shell-out para o script CLI canônico |
79
- | Endpoint de comandos vira RCE local | B | A | Allowlist hard-coded de scripts permitidos; sem `npm run <arbitrário>` |
80
- | Gráfico de tokens mente (estimativa ≠ real) | A | M | Rotular como "estimativa baseada em chars/4"; documentar fórmula |
81
- | Briefing → spec produz texto ruim | A | M | Marcar status `draft` e exigir revisão humana antes de mudar pra `review` |
82
- | Adicionar bundle JS pesado complica o repo | M | M | Frontend em pasta isolada; CI roda `npm test` no kit sem precisar buildar dashboard |
83
-
84
- ## 8. Métricas de sucesso (30d)
85
-
86
- - Autor abre o dashboard ≥3×/semana
87
- - ≥1 spec criada via briefing (versus 100% via CLI hoje)
88
- - 0 incidentes de comando executado fora da allowlist
89
- - Tempo médio "abriu dashboard → identificou gargalo" < 60s