forjajs 1.1.2 → 1.1.3
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/release-auditor.md +39 -7
- package/CHANGELOG.md +21 -0
- package/DOC-MAP.md +2 -2
- package/README.md +2 -2
- package/memory/90-decisions/0021-guardrails-de-harness.md +5 -1
- package/memory/90-decisions/0022-congelar-dashboard-web.md +101 -0
- package/package.json +4 -7
- package/scripts/spec-cli.mjs +5 -2
- package/specs/reestruturacao-forja-v2/plan.md +1 -1
- package/specs/reestruturacao-forja-v2/spec.md +16 -12
- package/specs/reestruturacao-forja-v2/tasks.md +1 -1
- package/docs/dashboard.md +0 -102
- package/specs/agent-dashboard/plan.md +0 -165
- package/specs/agent-dashboard/spec.md +0 -89
- package/specs/agent-dashboard/tasks.md +0 -168
|
@@ -10,18 +10,37 @@ instala?**
|
|
|
10
10
|
|
|
11
11
|
O repositório mente sobre isso. No repo, tudo resolve: `node_modules` existe com devDeps,
|
|
12
12
|
todos os arquivos estão presentes, o `cwd` é a raiz do projeto. Nada disso vale para quem
|
|
13
|
-
roda `npm i -g forjajs`.
|
|
13
|
+
roda `npm i -g forjajs`. Quatro classes de bug vivem exatamente nessa lacuna e só aparecem
|
|
14
14
|
em produção:
|
|
15
15
|
|
|
16
16
|
1. **Arquivo fora do `files[]`** — o `package.json` lista os paths publicados à mão. Um
|
|
17
17
|
`import` para um arquivo não listado quebra só depois do publish.
|
|
18
18
|
2. **Dependência de runtime declarada como `devDependency`** — não é instalada pelo
|
|
19
19
|
usuário. O comando estoura com `ERR_MODULE_NOT_FOUND`.
|
|
20
|
+
3. **Dependência declarada e nunca importada** — não quebra nada, mas todo mundo que
|
|
21
|
+
instala baixa peso morto.
|
|
22
|
+
4. **Árvore suja no momento do publish** — `npm publish` empacota o **disco**, não o commit.
|
|
23
|
+
Qualquer arquivo alterado e não commitado entra no tarball, e o que foi publicado deixa
|
|
24
|
+
de corresponder à tag de release.
|
|
20
25
|
|
|
21
|
-
Grep e leitura de código não provam ausência
|
|
26
|
+
Grep e leitura de código não provam ausência das três primeiras. Instalação prova.
|
|
27
|
+
A quarta nenhuma instalação pega: só o `git status` pega, e só se rodado no instante certo.
|
|
22
28
|
|
|
23
29
|
## Procedimento
|
|
24
30
|
|
|
31
|
+
0. **Exija árvore limpa, antes de tudo.** Se houver qualquer modificação não commitada,
|
|
32
|
+
reprove imediatamente e pare — não adianta auditar um tarball que não é o que será
|
|
33
|
+
publicado.
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
git status --short # qualquer saída = reprovado
|
|
37
|
+
git describe --tags --exact-match # HEAD deve estar na tag de release
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Um `npm install` casual entre a auditoria e o `npm publish` já basta para reescrever o
|
|
41
|
+
`package.json` do disco. Foi assim que `otplib` e `qrcode` entraram na v1.1.1 publicada
|
|
42
|
+
sem jamais existirem no git (ADR-0021).
|
|
43
|
+
|
|
25
44
|
1. **Empacote e instale de verdade**, num diretório temporário fora do repo:
|
|
26
45
|
|
|
27
46
|
```bash
|
|
@@ -46,19 +65,32 @@ Grep e leitura de código não provam ausência dessas falhas. Instalação prov
|
|
|
46
65
|
transitivamente e confirme que todo path resolvido cai sob um prefixo listado em
|
|
47
66
|
`files[]`. Reporte os que não caem.
|
|
48
67
|
|
|
49
|
-
4. **Confira a fronteira deps/devDeps.** Todo pacote importado por código
|
|
50
|
-
precisa estar em `dependencies
|
|
51
|
-
e por scripts
|
|
68
|
+
4. **Confira a fronteira deps/devDeps, nos dois sentidos.** Todo pacote importado por código
|
|
69
|
+
sob `files[]` precisa estar em `dependencies`; `devDependencies` só pode ser importado por
|
|
70
|
+
`test/` e por scripts não publicados. E toda entrada de `dependencies` precisa ser
|
|
71
|
+
importada por alguém — declarada e nunca usada é peso morto no tarball de todo usuário.
|
|
52
72
|
|
|
53
73
|
```bash
|
|
54
|
-
|
|
74
|
+
# para cada dep declarada, prove que alguém a importa
|
|
75
|
+
node -e "console.log(Object.keys(require('./package.json').dependencies||{}).join('\n'))" |
|
|
76
|
+
while read dep; do
|
|
77
|
+
grep -rqE "from '$dep'|require\('$dep'\)" bin/ lib/ scripts/ ||
|
|
78
|
+
echo "REPROVADO: '$dep' está em dependencies e ninguém a importa"
|
|
79
|
+
done
|
|
55
80
|
```
|
|
56
81
|
|
|
82
|
+
5. **Reconfirme a árvore limpa ao final.** A auditoria só vale para o disco no instante em
|
|
83
|
+
que rodou. Se algo mudou desde o passo 0, o resultado está vencido: recomece.
|
|
84
|
+
|
|
57
85
|
## Regras
|
|
58
86
|
|
|
59
87
|
- Output estruturado: ✓ aprovado / ✗ reprovado, com motivos numerados.
|
|
60
88
|
- Nunca rode `npm publish`. Você audita; publicar é decisão do usuário.
|
|
61
89
|
- Nunca aprove com base em leitura de código. Se você não instalou o tarball e rodou
|
|
62
90
|
um comando real, você não sabe — diga que não sabe.
|
|
91
|
+
- Sua aprovação é **perecível**: vale para aquele disco, naquele instante. Ao aprovar,
|
|
92
|
+
diga explicitamente que qualquer `npm install`, `npm uninstall` ou edição posterior
|
|
93
|
+
invalida o parecer e exige nova auditoria.
|
|
63
94
|
- Limpe `/tmp/forja-audit` ao final.
|
|
64
|
-
- Se reprovar, aponte a linha exata: o import ofensor
|
|
95
|
+
- Se reprovar, aponte a linha exata: o import ofensor, a entrada faltante no `files[]`,
|
|
96
|
+
ou o arquivo sujo no `git status`.
|
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,27 @@ Histórico consolidado das mudanças estruturais do framework. Para decisões ar
|
|
|
4
4
|
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
+
## [1.1.3] — 2026-07-09 — Dashboard congelado
|
|
8
|
+
|
|
9
|
+
SPEC-002 (`specs/agent-dashboard/`) passa a `abandoned`. O código permanece em `dashboard/`,
|
|
10
|
+
versionado e com os 68 testes verdes, mas deixa de ser superfície pública. Ver
|
|
11
|
+
ADR-0022 (`memory/90-decisions/0022-congelar-dashboard-web.md`) para rationale e condições de retomada.
|
|
12
|
+
|
|
13
|
+
### Corrigido
|
|
14
|
+
- **Bug de release**: `docs/dashboard.md` e o script `npm run dashboard` eram publicados no npm,
|
|
15
|
+
mas a pasta `dashboard/` nunca esteve no `files[]`. Quem instalava o pacote recebia a documentação
|
|
16
|
+
e o comando, sem o código. Ambos saíram do tarball.
|
|
17
|
+
- `README.md` descrevia o dashboard como "visão opcional read-only"; ele expõe rotas que executam
|
|
18
|
+
processos (`POST /api/workflow/:project/run/:role`). Descrição corrigida.
|
|
19
|
+
- `scripts/spec-cli.mjs` — `abandoned` é status válido, mas o `check` o rejeitava como incoerente
|
|
20
|
+
quando havia `plan.md`/`tasks.md`, derrubando o gate com exit 1. Agora é tratado como terminal,
|
|
21
|
+
junto de `done`.
|
|
22
|
+
|
|
23
|
+
### Removido
|
|
24
|
+
- Scripts `dashboard`, `dashboard:dev`, `dashboard:install`, `dashboard:web:dev` e
|
|
25
|
+
`dashboard:web:build` do `package.json` do root.
|
|
26
|
+
- `docs/dashboard.md` e `specs/agent-dashboard/` do `files[]` do pacote npm.
|
|
27
|
+
|
|
7
28
|
## [Unreleased] — Workspace separado
|
|
8
29
|
|
|
9
30
|
SPEC-028 (`specs/reestruturacao-forja-v2/`): separação do framework Forja do workspace de produção.
|
package/DOC-MAP.md
CHANGED
|
@@ -27,7 +27,7 @@ Ponto de entrada por papel. Para histórico de fases ver `CHANGELOG.md`; para de
|
|
|
27
27
|
- `docs/examples.md` — snippets prontos
|
|
28
28
|
- `docs/dev-workflow.md`
|
|
29
29
|
- `docs/init-project.md` — como gerar novo projeto
|
|
30
|
-
- `docs/dashboard.md` — painel web local (
|
|
30
|
+
- `docs/dashboard.md` — painel web local (**congelado**, ver ADR-0021; não distribuído no pacote npm)
|
|
31
31
|
|
|
32
32
|
### QA
|
|
33
33
|
- `docs/personas/qa/README.md`
|
|
@@ -56,7 +56,7 @@ Ponto de entrada por papel. Para histórico de fases ver `CHANGELOG.md`; para de
|
|
|
56
56
|
| Publicação npm | `docs/publishing.md` |
|
|
57
57
|
| Estrutura gerada | `docs/structure.md` |
|
|
58
58
|
| Exemplos de código | `docs/examples.md` |
|
|
59
|
-
| Dashboard web | `docs/dashboard.md` |
|
|
59
|
+
| Dashboard web (congelado) | `docs/dashboard.md` |
|
|
60
60
|
|
|
61
61
|
---
|
|
62
62
|
|
package/README.md
CHANGED
|
@@ -28,7 +28,7 @@ A **Forja** é o estúdio em volta da IA. Ela coordena **6 papéis de agentes**
|
|
|
28
28
|
**Spec-Driven (SDD)** + **Get-Stuff-Done (GSD)**, mantém uma **memória hierárquica**
|
|
29
29
|
indexada em SQLite que sobrevive entre sessões, e amarra tudo num **core CLI único com
|
|
30
30
|
gates e trilha de auditoria** (`forja`, ADR-0020). Multi-IA por design (Claude, Copilot,
|
|
31
|
-
Gemini, Codex)
|
|
31
|
+
Gemini, Codex). A operação é inteiramente via CLI.
|
|
32
32
|
|
|
33
33
|
**Para quem**: o dev solo ou time pequeno que opera múltiplos produtos com IA como
|
|
34
34
|
principal força de trabalho — e precisa da disciplina de um time grande sem ter esse time.
|
|
@@ -184,7 +184,7 @@ npm run context:smart # smart-context
|
|
|
184
184
|
|
|
185
185
|
# Qualidade & visão
|
|
186
186
|
npm run project:check # standards do framework
|
|
187
|
-
npm run dashboard
|
|
187
|
+
npm run project:dashboard # relatório estático de status
|
|
188
188
|
```
|
|
189
189
|
|
|
190
190
|
## Separação framework × workspace
|
|
@@ -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)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "forjajs",
|
|
3
|
-
"version": "1.1.
|
|
3
|
+
"version": "1.1.3",
|
|
4
4
|
"description": "Forja — framework CLI-first de orquestração multiagente, memória hierárquica e geração de projetos com IA",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "index.js",
|
|
@@ -29,7 +29,9 @@
|
|
|
29
29
|
"AGENTS.md",
|
|
30
30
|
"DOC-MAP.md",
|
|
31
31
|
"CHANGELOG.md",
|
|
32
|
-
"CONTRIBUTING.md"
|
|
32
|
+
"CONTRIBUTING.md",
|
|
33
|
+
"!docs/dashboard.md",
|
|
34
|
+
"!specs/agent-dashboard/"
|
|
33
35
|
],
|
|
34
36
|
"scripts": {
|
|
35
37
|
"forja": "node bin/forja.mjs",
|
|
@@ -72,11 +74,6 @@
|
|
|
72
74
|
"ops:handoff": "node bin/forja.mjs gsd:handoff",
|
|
73
75
|
"ops:check": "node bin/forja.mjs gsd:check",
|
|
74
76
|
"ops:sprint": "node bin/forja.mjs sprint:status",
|
|
75
|
-
"dashboard": "cd dashboard && npm start",
|
|
76
|
-
"dashboard:dev": "cd dashboard && npm run dev",
|
|
77
|
-
"dashboard:install": "cd dashboard && npm install && cd web && npm install",
|
|
78
|
-
"dashboard:web:dev": "cd dashboard/web && npm run dev",
|
|
79
|
-
"dashboard:web:build": "cd dashboard/web && npm run build",
|
|
80
77
|
"code:index": "node bin/forja.mjs code:index",
|
|
81
78
|
"code:sync": "node bin/forja.mjs code:sync",
|
|
82
79
|
"code:status": "node bin/forja.mjs code:status",
|
package/scripts/spec-cli.mjs
CHANGED
|
@@ -123,15 +123,18 @@ function checkFeature(slug) {
|
|
|
123
123
|
result.stages[stage] = status;
|
|
124
124
|
}
|
|
125
125
|
// Regras
|
|
126
|
+
// `abandoned` é terminal: uma feature pode ter avançado até plan/tasks antes de parar,
|
|
127
|
+
// e isso não é incoerência — é história. Ver ADR-0022.
|
|
128
|
+
const ALLOWS_NEXT_STAGE = ['approved', 'implementing', 'done', 'abandoned'];
|
|
126
129
|
if (!result.stages.spec) {
|
|
127
130
|
result.ok = false;
|
|
128
131
|
result.errors.push('spec.md ausente');
|
|
129
132
|
}
|
|
130
|
-
if (result.stages.plan && !
|
|
133
|
+
if (result.stages.plan && !ALLOWS_NEXT_STAGE.includes(result.stages.spec)) {
|
|
131
134
|
result.ok = false;
|
|
132
135
|
result.errors.push(`plan.md existe mas spec status = ${result.stages.spec}`);
|
|
133
136
|
}
|
|
134
|
-
if (result.stages.tasks && !
|
|
137
|
+
if (result.stages.tasks && !ALLOWS_NEXT_STAGE.includes(result.stages.plan)) {
|
|
135
138
|
result.ok = false;
|
|
136
139
|
result.errors.push(`tasks.md existe mas plan status = ${result.stages.plan}`);
|
|
137
140
|
}
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
# Spec: reestruturacao-forja-v2
|
|
2
2
|
|
|
3
3
|
- **ID**: SPEC-028
|
|
4
|
-
- **Status**:
|
|
4
|
+
- **Status**: done
|
|
5
5
|
- **Owner**: apk
|
|
6
6
|
- **Criado em**: 2026-07-01
|
|
7
7
|
- **Sprint alvo**: <S?>
|
|
8
|
-
- **ADRs relacionadas**:
|
|
8
|
+
- **ADRs relacionadas**: ADR-0019 (workspace separado), ADR-0020 (core CLI única)
|
|
9
9
|
|
|
10
10
|
## 1. Problema
|
|
11
11
|
O Forja hoje mistura o **framework** (motor) com os **produtos gerados** dentro do mesmo repositório. A pasta `projects/` é gitignored, a memória universal dos produtos (`memory/30-projects/`, `.memory/sqlite/universal.db`) fica no repo do framework e não há um "canto fixo" claro onde os projetos vão parar. Isso causa:
|
|
@@ -23,16 +23,20 @@ Separar o framework Forja do workspace de produção em um diretório fixo (`~/f
|
|
|
23
23
|
- **Como** arquiteto, **quero** um comando `forja workspace:init` e `forja project:new`, **para que** o harness GSD seja operado de forma unificada.
|
|
24
24
|
|
|
25
25
|
## 4. Critérios de aceite (Definition of Done)
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
- [
|
|
31
|
-
- [
|
|
32
|
-
- [
|
|
33
|
-
- [
|
|
34
|
-
- [
|
|
35
|
-
- [
|
|
26
|
+
|
|
27
|
+
> Verificados em 2026-07-09. A spec estava `approved` com o trabalho já concluído — os checkboxes
|
|
28
|
+
> nunca foram marcados. Auditoria confirmou os 10 critérios contra o código.
|
|
29
|
+
|
|
30
|
+
- [x] AC-1: Workspace padrão `~/forja-workspace` é criado e configurado automaticamente na primeira operação.
|
|
31
|
+
- [x] AC-2: `init-project` cria projetos obrigatoriamente dentro de `~/forja-workspace/projects/<nome>` (não mais dentro do repo do framework).
|
|
32
|
+
- [x] AC-3: Memória universal (SQLite) e `memory/30-projects/` dos produtos são movidos/criados no workspace, não no repo do framework.
|
|
33
|
+
- [x] AC-4: Scripts `sync:universal`, `query:universal`, `context:smart` e `build-smart-context` passam a operar sobre o workspace. — `query-universal-memory.js` não referencia o workspace diretamente; delega a `getDbPath()` de `memory-schema.mjs`, que resolve para `~/forja-workspace/memory/sqlite/universal.db`.
|
|
34
|
+
- [x] AC-5: Novo módulo `lib/workspace.mjs` centraliza a descoberta do workspace (env `FORJA_WORKSPACE` > `.forjarc.json` > default `~/forja-workspace`).
|
|
35
|
+
- [x] AC-6: ~~`npm run dev -- workspace:init`~~ → **interface mudou** para `node bin/forja.mjs workspace:init` (ADR-0020, core CLI única). Comando presente no registry.
|
|
36
|
+
- [x] AC-7: ~~`npm run dev -- project:new <nome>`~~ → **interface mudou** para `node bin/forja.mjs project:new`. Presente no registry, junto de `project:list` e `workspace:project:check`.
|
|
37
|
+
- [x] AC-8: AGENTS.md, README.md, .gitignore, docs/ e ADRs são atualizados para refletir a separação framework/workspace. — ADR-0019 documenta a decisão.
|
|
38
|
+
- [x] AC-9: `project:check` continua passando no framework e passa a aceitar projeto alvo pelo path absoluto/relativo ao workspace.
|
|
39
|
+
- [x] AC-10: Teste de fumaça: criar um projeto de exemplo no workspace e rodar `project:check` sobre ele. — `~/forja-workspace/projects/forja-smoke-test`.
|
|
36
40
|
|
|
37
41
|
## 5. Escopo
|
|
38
42
|
**Dentro**:
|
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
|
|
@@ -1,168 +0,0 @@
|
|
|
1
|
-
# Tasks: agent-dashboard
|
|
2
|
-
|
|
3
|
-
- **Spec**: ./spec.md
|
|
4
|
-
- **Plan**: ./plan.md
|
|
5
|
-
- **Criado em**: 2026-05-11
|
|
6
|
-
|
|
7
|
-
Decomposição em 12 tasks. Estimativas: P=≤2h, M=2-6h, G=6h+. Ordem reflete execução padrão; T2-T9 podem rodar em paralelo após T1.
|
|
8
|
-
|
|
9
|
-
---
|
|
10
|
-
|
|
11
|
-
## T1 — Bootstrap do projeto `dashboard/`
|
|
12
|
-
- **Owner**: Worker
|
|
13
|
-
- **Estimativa**: P
|
|
14
|
-
- **Depende de**: —
|
|
15
|
-
- **Paths**: `dashboard/package.json`, `dashboard/server/index.mjs`, `dashboard/.gitignore`, `package.json` (root)
|
|
16
|
-
- **Done quando**:
|
|
17
|
-
- [ ] `dashboard/package.json` com fastify, @fastify/static, @fastify/cors, better-sqlite3
|
|
18
|
-
- [ ] `dashboard/server/index.mjs` sobe Fastify em 127.0.0.1:7777 com `GET /api/health` → `{ok:true}`
|
|
19
|
-
- [ ] Root `package.json` ganha script `"dashboard": "cd dashboard && npm start"`
|
|
20
|
-
- [ ] `.gitignore` ignora `dashboard/node_modules`, `dashboard/web/dist`
|
|
21
|
-
- [ ] `npm run dashboard` sobe sem erro
|
|
22
|
-
|
|
23
|
-
## T2 — Allowlist + util de spawn seguro
|
|
24
|
-
- **Owner**: Worker
|
|
25
|
-
- **Estimativa**: P
|
|
26
|
-
- **Depende de**: T1
|
|
27
|
-
- **Paths**: `dashboard/server/lib/allowlist.mjs`, `dashboard/server/lib/run-command.mjs`
|
|
28
|
-
- **Done quando**:
|
|
29
|
-
- [ ] `allowlist.mjs` exporta `COMMAND_ALLOWLIST` exato como no plan §4
|
|
30
|
-
- [ ] `run-command.mjs` valida nome, faz `spawn` sem `shell: true`
|
|
31
|
-
- [ ] Teste: comando fora da allowlist → throw `CommandNotAllowed`
|
|
32
|
-
- [ ] Teste: comando válido devolve stream readable de stdout
|
|
33
|
-
|
|
34
|
-
## T3 — Rota Specs (read-only)
|
|
35
|
-
- **Owner**: Worker
|
|
36
|
-
- **Estimativa**: P
|
|
37
|
-
- **Depende de**: T1
|
|
38
|
-
- **Paths**: `dashboard/server/routes/specs.mjs`
|
|
39
|
-
- **Done quando**:
|
|
40
|
-
- [ ] `GET /api/specs` lê `specs/*/spec.md`, retorna array conforme contrato §4
|
|
41
|
-
- [ ] `GET /api/specs/:slug` devolve conteúdo cru de spec/plan/tasks
|
|
42
|
-
- [ ] Teste de integração com fixture: 2 specs fake → 2 itens
|
|
43
|
-
|
|
44
|
-
## T4 — Rota Handoffs com transição
|
|
45
|
-
- **Owner**: Worker
|
|
46
|
-
- **Estimativa**: M
|
|
47
|
-
- **Depende de**: T1
|
|
48
|
-
- **Paths**: `dashboard/server/routes/handoffs.mjs`
|
|
49
|
-
- **Done quando**:
|
|
50
|
-
- [ ] `GET /api/handoffs?status=&to=` consulta `universal.db.handoffs`
|
|
51
|
-
- [ ] `POST /api/handoffs/:id/transition` valida `to ∈ {in_progress,done,cancelled}` e shell-out para `agent-router.mjs`
|
|
52
|
-
- [ ] Teste: transição inválida → 400; válida → 200 + status atualizado
|
|
53
|
-
|
|
54
|
-
## T5 — Rota Projects
|
|
55
|
-
- **Owner**: Worker
|
|
56
|
-
- **Estimativa**: P
|
|
57
|
-
- **Depende de**: T1
|
|
58
|
-
- **Paths**: `dashboard/server/routes/projects.mjs`
|
|
59
|
-
- **Done quando**:
|
|
60
|
-
- [ ] `GET /api/projects` lê `projects/*`, cruza com SQLite por slug
|
|
61
|
-
- [ ] `last_commit` via `git -C` (null se não-git)
|
|
62
|
-
- [ ] `memory_bytes` = `du -sb` de `projects/<name>/memory/`
|
|
63
|
-
|
|
64
|
-
## T6 — Rota Tokens (estimador)
|
|
65
|
-
- **Owner**: Worker
|
|
66
|
-
- **Estimativa**: M
|
|
67
|
-
- **Depende de**: T1
|
|
68
|
-
- **Paths**: `dashboard/server/routes/tokens.mjs`, `dashboard/server/lib/token-estimator.mjs`
|
|
69
|
-
- **Done quando**:
|
|
70
|
-
- [ ] `token-estimator.mjs` calcula chars/4 sobre `.context/*` e `memory/60-runs/*.json` agregado por dia
|
|
71
|
-
- [ ] `GET /api/tokens?project=&days=30` devolve série temporal
|
|
72
|
-
- [ ] Resposta < 500ms p95 com 10 projetos (kill criterion §8)
|
|
73
|
-
- [ ] Cada datapoint rotulado como "estimativa"
|
|
74
|
-
|
|
75
|
-
## T7 — Rota Commands com SSE
|
|
76
|
-
- **Owner**: Worker
|
|
77
|
-
- **Estimativa**: M
|
|
78
|
-
- **Depende de**: T2
|
|
79
|
-
- **Paths**: `dashboard/server/routes/commands.mjs`
|
|
80
|
-
- **Done quando**:
|
|
81
|
-
- [ ] `POST /api/commands/:name` valida allowlist, abre SSE
|
|
82
|
-
- [ ] Eventos `stdout`, `stderr`, `exit` (com código)
|
|
83
|
-
- [ ] Fora da allowlist → 403 `{error:"command not allowlisted"}`
|
|
84
|
-
- [ ] E2E: dispara `spec:check` e recebe ≥1 evento `stdout` + `exit:0`
|
|
85
|
-
|
|
86
|
-
## T8 — Rota Briefing → spec
|
|
87
|
-
- **Owner**: Worker
|
|
88
|
-
- **Estimativa**: M
|
|
89
|
-
- **Depende de**: T2
|
|
90
|
-
- **Paths**: `dashboard/server/routes/briefing.mjs`, `dashboard/server/lib/briefing-parser.mjs`
|
|
91
|
-
- **Done quando**:
|
|
92
|
-
- [ ] Parser: split parágrafos, detecta keywords (`problema`, `queremos`, `para que <persona>`, `como <persona>`), preenche seções 1-3
|
|
93
|
-
- [ ] `POST /api/briefing` valida `slug` kebab-case, cria via `spec-cli.mjs new`, sobrescreve seções 1-3
|
|
94
|
-
- [ ] Status fica em `draft` (nunca `approved` automático)
|
|
95
|
-
- [ ] Teste com 3 briefings de exemplo: cada um produz spec parseável
|
|
96
|
-
|
|
97
|
-
## T9 — Frontend bootstrap (Vite + Tailwind + shadcn)
|
|
98
|
-
- **Owner**: Worker
|
|
99
|
-
- **Estimativa**: M
|
|
100
|
-
- **Depende de**: T1
|
|
101
|
-
- **Paths**: `dashboard/web/`
|
|
102
|
-
- **Done quando**:
|
|
103
|
-
- [ ] `dashboard/web/` com Vite + React + Tailwind
|
|
104
|
-
- [ ] shadcn instalado, 3-4 componentes copiados (button, card, badge, dialog)
|
|
105
|
-
- [ ] Layout base: sidebar com 6 links (Briefing, Specs, Handoffs, Tokens, Comandos, Projetos)
|
|
106
|
-
- [ ] `vite build` < 500KB gzipped (NFR)
|
|
107
|
-
- [ ] `npm run dashboard` serve `dist/` via @fastify/static
|
|
108
|
-
|
|
109
|
-
## T10 — Telas Specs + Handoffs + Projetos
|
|
110
|
-
- **Owner**: Worker
|
|
111
|
-
- **Estimativa**: G
|
|
112
|
-
- **Depende de**: T3, T4, T5, T9
|
|
113
|
-
- **Paths**: `dashboard/web/src/pages/{Specs,Handoffs,Projects}.tsx`
|
|
114
|
-
- **Done quando**:
|
|
115
|
-
- [ ] Specs: tabela com status colorido + drawer com spec/plan/tasks markdown renderizado
|
|
116
|
-
- [ ] Handoffs: 3 colunas kanban com botão de transição
|
|
117
|
-
- [ ] Projetos: cards com badges (specs, handoffs, último commit, memória)
|
|
118
|
-
- [ ] Polling 30s em cada tela
|
|
119
|
-
|
|
120
|
-
## T11 — Telas Tokens + Comandos + Briefing
|
|
121
|
-
- **Owner**: Worker
|
|
122
|
-
- **Estimativa**: G
|
|
123
|
-
- **Depende de**: T6, T7, T8, T9
|
|
124
|
-
- **Paths**: `dashboard/web/src/pages/{Tokens,Commands,Briefing}.tsx`
|
|
125
|
-
- **Done quando**:
|
|
126
|
-
- [ ] Tokens: gráfico de linha (Recharts) 30d com toggle de projeto
|
|
127
|
-
- [ ] Comandos: 5 botões, painel lateral com stdout/stderr ao vivo via EventSource
|
|
128
|
-
- [ ] Briefing: textarea ≥10 linhas + select de projeto + botão "Gerar spec" → redireciona para `/specs/<slug>`
|
|
129
|
-
|
|
130
|
-
## T12 — Documentação + handoff de governance
|
|
131
|
-
- **Owner**: Worker → Governance
|
|
132
|
-
- **Estimativa**: P
|
|
133
|
-
- **Depende de**: T10, T11
|
|
134
|
-
- **Paths**: `docs/dashboard.md`, `DOC-MAP.md`, `CHANGELOG.md`
|
|
135
|
-
- **Done quando**:
|
|
136
|
-
- [ ] `docs/dashboard.md` cobre: como subir, porta, allowlist, troubleshooting
|
|
137
|
-
- [ ] `DOC-MAP.md` ganha entrada para o dashboard
|
|
138
|
-
- [ ] `CHANGELOG.md` ganha entrada `[Unreleased]`
|
|
139
|
-
- [ ] Handoff `worker → governance` aberto via `agent-router append`
|
|
140
|
-
- [ ] `npm test` e `npm run spec:check` ambos verdes
|
|
141
|
-
|
|
142
|
-
---
|
|
143
|
-
|
|
144
|
-
## Caminho crítico
|
|
145
|
-
|
|
146
|
-
```
|
|
147
|
-
T1 ─┬─ T2 ─┬─ T7 ─┐
|
|
148
|
-
├─ T3 ─┤ │
|
|
149
|
-
├─ T4 ─┤ ├─ T10 ─┐
|
|
150
|
-
├─ T5 ─┤ │ ├─ T12
|
|
151
|
-
├─ T6 ─┤ ├─ T11 ─┘
|
|
152
|
-
├─ T9 ─┘ │
|
|
153
|
-
└─ T2 → T8 ───┘
|
|
154
|
-
```
|
|
155
|
-
|
|
156
|
-
T1 destrava todas. T10 espera rotas read-only + frontend base. T11 espera rotas mutáveis + frontend base. T12 fecha com Governance.
|
|
157
|
-
|
|
158
|
-
## Handoffs sugeridos
|
|
159
|
-
|
|
160
|
-
Quando T1 concluir:
|
|
161
|
-
```bash
|
|
162
|
-
node scripts/agent-router.mjs append '{"from":"sdd-architect","to":"worker","intent":"implement","context":"specs/agent-dashboard/plan.md §2-§5; tasks.md T2-T9 destravadas","acceptance":"rotas /api/* respondem com schema do plan §4; testes verdes","constraints":"allowlist hard-coded; bind 127.0.0.1; sem shell:true","return":"PR + handoff para governance","spec_slug":"agent-dashboard"}'
|
|
163
|
-
```
|
|
164
|
-
|
|
165
|
-
Antes do merge (após T11):
|
|
166
|
-
```bash
|
|
167
|
-
node scripts/agent-router.mjs append '{"from":"worker","to":"governance","intent":"review","context":"PR agent-dashboard; rotas + 5 telas + allowlist","acceptance":"project:check verde, spec:check verde, auditoria de RCE na rota /api/commands","constraints":"bloquear merge se allowlist contornável","return":"veredicto APROVADO ou findings","spec_slug":"agent-dashboard"}'
|
|
168
|
-
```
|