forjajs 1.1.1 → 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.
@@ -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`. Duas classes de bug vivem exatamente nessa lacuna e só aparecem
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 dessas falhas. Instalação prova.
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 sob `files[]`
50
- precisa estar em `dependencies`. `devDependencies` só pode ser importado por `test/`
51
- e por scripts que não são publicados.
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
- grep -rn "from 'better-sqlite3'\|require('better-sqlite3')" bin/ lib/ scripts/
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 ou a entrada faltante no `files[]`.
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 (`npm run dashboard`)
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) — o dashboard web é apenas uma visão opcional read-only.
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 # front opcional (http://127.0.0.1:7777)
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.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",
@@ -103,8 +100,6 @@
103
100
  "author": "Allan Pablo",
104
101
  "license": "MIT",
105
102
  "dependencies": {
106
- "better-sqlite3": "^12.11.1",
107
- "otplib": "^13.4.1",
108
- "qrcode": "^1.5.4"
103
+ "better-sqlite3": "^12.11.1"
109
104
  }
110
105
  }
@@ -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 && !['approved', 'implementing', 'done'].includes(result.stages.spec)) {
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 && !['approved', 'implementing', 'done'].includes(result.stages.plan)) {
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,7 +1,7 @@
1
1
  # Plan: reestruturacao-forja-v2
2
2
 
3
3
  - **Spec**: ./spec.md
4
- - **Status**: approved
4
+ - **Status**: done
5
5
  - **Criado em**: 2026-07-01
6
6
 
7
7
  > Como vamos construir o que a spec define. Sem código aqui — só estrutura e decisões.
@@ -1,11 +1,11 @@
1
1
  # Spec: reestruturacao-forja-v2
2
2
 
3
3
  - **ID**: SPEC-028
4
- - **Status**: approved
4
+ - **Status**: done
5
5
  - **Owner**: apk
6
6
  - **Criado em**: 2026-07-01
7
7
  - **Sprint alvo**: <S?>
8
- - **ADRs relacionadas**: <links para memory/90-decisions/>
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
- - [ ] AC-1: Workspace padrão `~/forja-workspace` é criado e configurado automaticamente na primeira operação.
27
- - [ ] AC-2: `init-project` cria projetos obrigatoriamente dentro de `~/forja-workspace/projects/<nome>` (não mais dentro do repo do framework).
28
- - [ ] AC-3: Memória universal (SQLite) e `memory/30-projects/` dos produtos são movidos/criados no workspace, não no repo do framework.
29
- - [ ] AC-4: Scripts `sync:universal`, `query:universal`, `context:smart` e `build-smart-context` passam a operar sobre o workspace.
30
- - [ ] AC-5: Novo módulo `lib/workspace.mjs` centraliza a descoberta do workspace (env `FORJA_WORKSPACE` > `.forjarc.json` > default `~/forja-workspace`).
31
- - [ ] AC-6: Comando `npm run dev -- workspace:init` cria a estrutura base do workspace.
32
- - [ ] AC-7: Comando `npm run dev -- project:new <nome>` substitui/encapsula `init-project` com workspace fixo.
33
- - [ ] AC-8: AGENTS.md, README.md, .gitignore, docs/ e ADRs são atualizados para refletir a separação framework/workspace.
34
- - [ ] AC-9: `project:check` continua passando no framework e passa a aceitar projeto alvo pelo path absoluto/relativo ao workspace.
35
- - [ ] AC-10: Teste de fumaça: criar um projeto de exemplo no workspace e rodar `project:check` sobre ele.
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**:
@@ -2,7 +2,7 @@
2
2
 
3
3
  - **Spec**: ./spec.md
4
4
  - **Plan**: ./plan.md
5
- - **Status**: approved
5
+ - **Status**: done
6
6
  - **Criado em**: 2026-07-01
7
7
 
8
8
  > Decomposição executável. Cada task tem dono claro, critério de done e referência a arquivos.
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
- ```