forjajs 1.5.0 → 1.6.1
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/AGENTS.md +5 -0
- package/CHANGELOG.md +32 -0
- package/README.en.md +37 -27
- package/README.md +30 -25
- package/dist/lib/agent-topology.d.ts +38 -0
- package/dist/lib/agent-topology.js +65 -0
- package/dist/lib/core/gates.d.ts +36 -0
- package/dist/lib/core/gates.js +35 -0
- package/dist/lib/core/health.js +35 -0
- package/dist/lib/core/project-smoke.js +3 -1
- package/dist/lib/core/registry.d.ts +5 -0
- package/dist/lib/core/registry.js +5 -0
- package/dist/lib/core/release.d.ts +5 -0
- package/dist/scripts/agent-router.js +1 -1
- package/dist/scripts/gates.d.ts +10 -0
- package/dist/scripts/gates.js +44 -0
- package/dist/scripts/project-upgrade.js +5 -1
- package/memory/90-decisions/0025-coerencia-da-documentacao.md +6 -0
- package/package.json +1 -1
- package/specs/gates/spec.md +63 -0
- package/specs/orchestration-coherent/spec.md +95 -0
package/AGENTS.md
CHANGED
|
@@ -66,6 +66,11 @@ Handoffs entre eles passam pela tabela `handoffs` em `~/forja-workspace/memory/s
|
|
|
66
66
|
**Faz**: roda `project:check`, audita handoffs por completude, valida 12-Factor/LGPD/segurança, bloqueia se algo falta.
|
|
67
67
|
**Não faz**: aprovar "ficou bom" sem referência verificável.
|
|
68
68
|
|
|
69
|
+
## 7. Release Auditor
|
|
70
|
+
**Quando**: antes de publicar no npm — o especialista de release da governança.
|
|
71
|
+
**Faz**: roda `release:check --publish`, interpreta o parecer e autoriza (ou barra) a publicação. Pega quebras que só apareceriam na máquina de quem instala (SPEC-010, ADR-0024).
|
|
72
|
+
**Não faz**: publicar — `npm publish` é ato humano. Ele diagnostica e autoriza.
|
|
73
|
+
|
|
69
74
|
---
|
|
70
75
|
|
|
71
76
|
## Fluxo SDD padrão
|
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,38 @@ Histórico consolidado das mudanças estruturais do framework. Para decisões ar
|
|
|
4
4
|
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
+
## [1.6.1] — 2026-07-20 — Correção: `project:upgrade` no pacote publicado
|
|
8
|
+
|
|
9
|
+
### Corrigido
|
|
10
|
+
- **`project:upgrade` quebrava com `Cannot find module .../create-memory-nest-kit.ts`** no pacote
|
|
11
|
+
instalado. O spawn do gerador cravava a extensão `.ts`; em dev funciona, mas o `dist/` publicado
|
|
12
|
+
tem `.js`. Agora resolve dinamicamente via `resolveScript` (`.ts` em dev, `.js` no publicado). O
|
|
13
|
+
`project:smoke` tinha o mesmo defeito, também corrigido. Teste de regressão guarda a classe.
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## [1.6.0] — 2026-07-20 — A orquestração coerente e a governança num comando
|
|
18
|
+
|
|
19
|
+
A governança do framework ganha um ponto de entrada e o namesake — orquestração multiagente — deixa
|
|
20
|
+
de viver por prosa.
|
|
21
|
+
|
|
22
|
+
### Adicionado
|
|
23
|
+
- **`check:all`** (SPEC-020): roda a **bateria inteira de gates** e dá um veredito só. Tier barato:
|
|
24
|
+
coerência (`tools:doctor`) + `project:smoke`; `--full`: + tarball (`release:check`) + build do
|
|
25
|
+
gerado. Compõe os runners existentes — zero check reimplementado. "A casa está coerente?" num
|
|
26
|
+
comando, não num checklist lembrado.
|
|
27
|
+
- **`agent-topology`** (check no `tools:doctor`, SPEC-019): a topologia de orquestração é descrita em
|
|
28
|
+
três fontes (`VALID_AGENTS`, `.claude/agents/*.md`, `AGENTS.md`) e pode divergir em silêncio. O
|
|
29
|
+
check as cruza e reprova quando não concordam. Pegou o `release-auditor` (sub-agent executável sem
|
|
30
|
+
rota) na 1ª execução — agora first-class no router e documentado (AGENTS.md §7).
|
|
31
|
+
|
|
32
|
+
### Corrigido / interno
|
|
33
|
+
- **`generators.test` migrado para `node:test`**: o harness custom legado não contava suas falhas no
|
|
34
|
+
tally do CI e vazava um `/tmp` por execução (588 diretórios acumulados). Agora é `node:test` com
|
|
35
|
+
cleanup — falha derruba o CI de verdade.
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
7
39
|
## [1.5.0] — 2026-07-19 — A memória como sistema fechado: medir → entregar → proteger → propagar
|
|
8
40
|
|
|
9
41
|
A economia de token do Forja sempre foi a memória persistente (ADR-0009), mas era uma promessa. Esta
|
package/README.en.md
CHANGED
|
@@ -88,11 +88,16 @@ process followed?", the answer is a file, not a promise.
|
|
|
88
88
|
- **Hierarchical memory** — global → domain → task → summary, with FTS5 search and *smart-context*
|
|
89
89
|
in 3 modes (ADR-0003).
|
|
90
90
|
- **SDD + GSD pipeline** — `spec → plan → tasks → check`, decisions recorded as ADRs.
|
|
91
|
-
- **
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
91
|
+
- **Self-verification (invariants that run)** — the framework proves itself: a family of gates guards
|
|
92
|
+
each frontier (core, tarball, doc coherence, agent topology, generated project), and `check:all`
|
|
93
|
+
runs the whole battery into a single verdict. Governance stops depending on discipline — it becomes
|
|
94
|
+
harness.
|
|
95
|
+
- **Token economy measured, not asserted** — memory (the `context.md` as a map) saves ~60% vs
|
|
96
|
+
exploring cold, and `token:economy` **proves** it across your domains. `code:context` delivers the
|
|
97
|
+
map ready to paste; `memory:audit` guarantees it doesn't lie about the code.
|
|
98
|
+
- **Project generation** — `project:new` scaffolds a full project (memory, agents, multi-AI
|
|
99
|
+
instructions, a NestJS backend as the default boilerplate) and registers the record; `project:upgrade`
|
|
100
|
+
brings new scaffold pieces to already-generated projects without touching the user's code.
|
|
96
101
|
- **3 integrated capabilities** (ADR-0016): **codegraph** (code analysis via MCP), **harness**
|
|
97
102
|
(agent-team design), **ai-engineering** (knowledge base).
|
|
98
103
|
|
|
@@ -117,7 +122,10 @@ forja spec:check my-feature
|
|
|
117
122
|
```
|
|
118
123
|
|
|
119
124
|
> Cloned the repo instead of installing? The same commands run as
|
|
120
|
-
> `node bin/forja.
|
|
125
|
+
> `node bin/forja.ts <command>` — the npm scripts are just thin aliases of the core.
|
|
126
|
+
> The source is TypeScript and runs natively: **dev needs Node ≥ 22.6** (type stripping). The
|
|
127
|
+
> *published* package ships `dist/*.js` and runs on **Node ≥ 20** — the `release-gate` proves it
|
|
128
|
+
> every release (SPEC-012).
|
|
121
129
|
|
|
122
130
|
Step by step on **create vs update** a project: [`docs/processo-projeto.md`](docs/processo-projeto.md).
|
|
123
131
|
|
|
@@ -160,7 +168,7 @@ Every process command goes through a single entry point (ADR-0020):
|
|
|
160
168
|
|
|
161
169
|
```bash
|
|
162
170
|
forja # help grouped by domain
|
|
163
|
-
forja <command> [args] # in a cloned repo: node bin/forja.
|
|
171
|
+
forja <command> [args] # in a cloned repo: node bin/forja.ts <command>
|
|
164
172
|
```
|
|
165
173
|
|
|
166
174
|
The core applies **gates** before running (e.g. product commands fail fast without a workspace) and
|
|
@@ -230,8 +238,8 @@ See ADR-0019 for the architectural decision.
|
|
|
230
238
|
## Repository structure (framework)
|
|
231
239
|
|
|
232
240
|
```
|
|
233
|
-
bin/ CLIs (init-project, create-memory-nest-kit)
|
|
234
|
-
lib/ Reusable modules (
|
|
241
|
+
bin/ CLIs (forja — the core; init-project, create-memory-nest-kit)
|
|
242
|
+
lib/ Reusable modules; lib/core/ is the invariant engine (registry, checks, health, release, doc-graph, gates)
|
|
235
243
|
scripts/ Automation (sprint-manager, agent-router, sync-universal-memory, …)
|
|
236
244
|
specs/ The framework's own SDD pipeline (spec → plan → tasks)
|
|
237
245
|
boilerplates/ Stack templates (api-rest, saas, ecommerce, microservices, monorepo)
|
|
@@ -279,30 +287,32 @@ output, code, and ADRs are readable regardless of language.
|
|
|
279
287
|
The throughline: **turn knowledge that lives as convention into an executable invariant.** Each item
|
|
280
288
|
below either closes a framework frontier with a gate, or carries that pattern into generated projects.
|
|
281
289
|
|
|
282
|
-
**
|
|
283
|
-
|
|
284
|
-
- [x] **
|
|
285
|
-
|
|
286
|
-
-
|
|
287
|
-
|
|
288
|
-
- [x] **
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
(
|
|
290
|
+
**Shipped** (through v1.6.0)
|
|
291
|
+
|
|
292
|
+
- [x] **Gate family** — every framework frontier is guarded by an invariant that runs: core
|
|
293
|
+
(`tools:doctor`, ADR-0023), tarball (`release:check`, ADR-0024), doc + ADR + agent-topology
|
|
294
|
+
coherence (ADR-0025, SPEC-019), generated project (`project:smoke`, ADR-0029). And `check:all`
|
|
295
|
+
runs the whole battery into one verdict (SPEC-020).
|
|
296
|
+
- [x] **TypeScript migration complete** — source 100% `.ts`, ships `dist/`, `noImplicitAny` ON. Found
|
|
297
|
+
latent bugs no test caught (SPEC-012).
|
|
298
|
+
- [x] **Memory economy as a system** — **measured** (`token:economy` proves ~60% vs cold),
|
|
299
|
+
**delivered** (`code:context`), **protected** (`memory:audit`, both directions), and **propagated**:
|
|
300
|
+
the generated project inherits the maps gate (ADR-0030).
|
|
301
|
+
- [x] **`project:upgrade`** — update an already-generated project without losing code: additive, never
|
|
302
|
+
overwrites (SPEC-018).
|
|
303
|
+
- [x] **Calibrated Clean Architecture** — layers where they pay off, lean where they don't; and the
|
|
304
|
+
token claim **measured and corrected** — the saving is memory's, not the layers' (ADR-0027).
|
|
293
305
|
|
|
294
306
|
**Next** (by dependency, not by wish)
|
|
295
307
|
|
|
296
|
-
- [ ] **
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
same feature in both architectures via `context:smart`. Prove it or recalibrate.
|
|
308
|
+
- [ ] **Generated backend `builds` under new toolchains** — `check:all --full` flags that
|
|
309
|
+
`better-sqlite3` won't compile on very new Node (no prebuild); pin the version or document the build
|
|
310
|
+
requirement.
|
|
300
311
|
- [ ] **`release-auditor` consumes the gate** — the third surface from ADR-0024: the agent runs
|
|
301
312
|
`release:check` instead of reimplementing the procedure in prose.
|
|
302
313
|
- [ ] **Boilerplates beyond NestJS** — the process is stack-agnostic; the templates will follow.
|
|
303
|
-
- [ ] **
|
|
304
|
-
|
|
305
|
-
lesson that froze the server-dashboard).
|
|
314
|
+
- [ ] **(vision) the orchestration engine** — the handoff chain that **runs**, not just is coherent
|
|
315
|
+
(SPEC-019 left it as future). The namesake executing: a 2.0 candidate.
|
|
306
316
|
|
|
307
317
|
Suggestions? Open an issue — a non-trivial feature here starts from a spec, yours included.
|
|
308
318
|
|
package/README.md
CHANGED
|
@@ -83,7 +83,9 @@ E cada comando acima ficou gravado em `.context/forja-runs.jsonl` — quando a g
|
|
|
83
83
|
- **Orquestração multiagente** — 6 papéis (orchestrator, context-engineer, sdd-architect, product, marketing, governance) com handoffs rastreados (7 campos, ADR-0005).
|
|
84
84
|
- **Memória hierárquica** — global → domínio → tarefa → resumo, com busca FTS5 e *smart-context* em 3 modos (ADR-0003).
|
|
85
85
|
- **Pipeline SDD + GSD** — `spec → plan → tasks → check`, decisões registradas como ADRs.
|
|
86
|
-
- **
|
|
86
|
+
- **Auto-verificação (invariantes que rodam)** — o framework prova a si mesmo: uma família de gates guarda cada fronteira (núcleo, tarball, coerência de doc, topologia de agentes, projeto gerado), e `check:all` roda a bateria inteira num veredito só. A governança deixa de depender de disciplina — vira harness.
|
|
87
|
+
- **Economia de token medida, não afirmada** — a memória (`context.md` como mapa) economiza ~60% vs explorar no frio, e `token:economy` **prova** isso nos seus domínios. `code:context` entrega o mapa pronto; `memory:audit` garante que ele não mente sobre o código.
|
|
88
|
+
- **Geração de projetos** — `project:new` cria scaffold completo no workspace (memória, agentes, instruções multi-IA, backend NestJS como boilerplate padrão) e registra a ficha; `project:upgrade` traz peças novas para projetos já gerados sem tocar no código do usuário.
|
|
87
89
|
- **3 capacidades integradas** (ADR-0016): **codegraph** (análise de código via MCP), **harness** (desenho de times de agentes), **ai-engineering** (base de conhecimento).
|
|
88
90
|
|
|
89
91
|
## ⚡ Quick start
|
|
@@ -107,7 +109,9 @@ forja spec:check minha-feature
|
|
|
107
109
|
```
|
|
108
110
|
|
|
109
111
|
> Clonou o repo em vez de instalar? Os mesmos comandos rodam como
|
|
110
|
-
> `node bin/forja.
|
|
112
|
+
> `node bin/forja.ts <comando>` — os scripts npm são apenas aliases finos do core.
|
|
113
|
+
> A fonte é TypeScript e roda nativa: **dev exige Node ≥ 22.6** (strip-types). O pacote *publicado*
|
|
114
|
+
> embarca `dist/*.js` e roda em **Node ≥ 20** — o `release-gate` prova isso a cada release (SPEC-012).
|
|
111
115
|
|
|
112
116
|
Passo a passo de **criar vs atualizar** projeto: [`docs/processo-projeto.md`](docs/processo-projeto.md).
|
|
113
117
|
|
|
@@ -150,7 +154,7 @@ Todos os comandos de processo passam por um único ponto de entrada (ADR-0020):
|
|
|
150
154
|
|
|
151
155
|
```bash
|
|
152
156
|
forja # help agrupado por domínio
|
|
153
|
-
forja <comando> [args] # no repo clonado: node bin/forja.
|
|
157
|
+
forja <comando> [args] # no repo clonado: node bin/forja.ts <comando>
|
|
154
158
|
```
|
|
155
159
|
|
|
156
160
|
O core aplica **gates** antes de executar (ex.: comandos de produto falham cedo sem
|
|
@@ -197,6 +201,7 @@ forja project:check # standards do framework (pre-commit)
|
|
|
197
201
|
forja tools:doctor # raio-x do núcleo; exit 1 se quebrou
|
|
198
202
|
forja release:check --publish # gate do tarball antes de publicar
|
|
199
203
|
forja project:smoke # gate do projeto gerado; --full instala e builda o backend
|
|
204
|
+
forja check:all # a bateria inteira de gates, um veredito; --full inclui os caros (SPEC-020)
|
|
200
205
|
forja project:dashboard # relatório estático de status
|
|
201
206
|
|
|
202
207
|
# Governança & auditoria
|
|
@@ -223,8 +228,8 @@ Veja ADR-0019 para a decisão arquitetural.
|
|
|
223
228
|
## Estrutura do repositório (framework)
|
|
224
229
|
|
|
225
230
|
```
|
|
226
|
-
bin/ CLIs (init-project, create-memory-nest-kit)
|
|
227
|
-
lib/ Módulos reutilizáveis (
|
|
231
|
+
bin/ CLIs (forja — o core; init-project, create-memory-nest-kit)
|
|
232
|
+
lib/ Módulos reutilizáveis; lib/core/ é o motor de invariantes (registry, checks, health, release, doc-graph, gates)
|
|
228
233
|
scripts/ Automação (sprint-manager, agent-router, sync-universal-memory, …)
|
|
229
234
|
specs/ Pipeline SDD do próprio framework (spec → plan → tasks)
|
|
230
235
|
boilerplates/ Templates de stack (api-rest, saas, ecommerce, microservices, monorepo)
|
|
@@ -270,32 +275,32 @@ O fio condutor: **converter conhecimento que vive em convenção em invariante e
|
|
|
270
275
|
item abaixo ou fecha uma fronteira do framework por um gate, ou leva esse padrão para os projetos
|
|
271
276
|
gerados.
|
|
272
277
|
|
|
273
|
-
**
|
|
274
|
-
|
|
275
|
-
- [x] **
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
- [x] **
|
|
280
|
-
|
|
281
|
-
- [x] **
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
278
|
+
**Entregue** (até v1.6.0)
|
|
279
|
+
|
|
280
|
+
- [x] **Família de gates** — cada fronteira do framework guarda por um invariante que roda: núcleo
|
|
281
|
+
(`tools:doctor`, ADR-0023), tarball (`release:check`, ADR-0024), coerência de doc + ADRs + topologia
|
|
282
|
+
de agentes (ADR-0025, SPEC-019), projeto gerado (`project:smoke`, ADR-0029). E `check:all` reúne a
|
|
283
|
+
bateria num veredito (SPEC-020).
|
|
284
|
+
- [x] **Migração TypeScript completa** — fonte 100% `.ts`, publica `dist/`, `noImplicitAny` ON. Achou
|
|
285
|
+
bugs latentes que nenhum teste pegava (SPEC-012).
|
|
286
|
+
- [x] **Economia de memória como sistema** — **medida** (`token:economy` prova ~60% vs frio),
|
|
287
|
+
**entregue** (`code:context`), **protegida** (`memory:audit`, nas duas direções) e **propagada**: o
|
|
288
|
+
projeto gerado herda o gate dos mapas (ADR-0030).
|
|
289
|
+
- [x] **`project:upgrade`** — atualizar um projeto já gerado sem perder código: aditivo, nunca
|
|
290
|
+
sobrescreve (SPEC-018).
|
|
291
|
+
- [x] **Clean Architecture calibrado** — camadas onde se pagam, enxuto onde não; e a claim de token
|
|
292
|
+
**medida e corrigida** — a economia é da memória, não das camadas (ADR-0027).
|
|
285
293
|
|
|
286
294
|
**Próximos passos** (por dependência, não por desejo)
|
|
287
295
|
|
|
288
|
-
- [
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
ADR-0027). Veredito honesto: para feature pequena o flat é mais barato; a economia do clean-arch é
|
|
292
|
-
função da escala, e a justificativa das camadas é **isolamento**, não token.
|
|
296
|
+
- [ ] **`builds` do backend gerado sob toolchain novo** — o `check:all --full` flagra que o
|
|
297
|
+
`better-sqlite3` não compila em Node muito novo (sem prebuild); fixar a versão ou documentar o
|
|
298
|
+
requisito de build.
|
|
293
299
|
- [ ] **`release-auditor` consome o gate** — a terceira superfície do ADR-0024: o agente roda
|
|
294
300
|
`release:check` em vez de reimplementar o procedimento em prosa.
|
|
295
301
|
- [ ] **Boilerplates além de NestJS** — o processo é agnóstico de stack; os templates vão atrás.
|
|
296
|
-
- [ ] **
|
|
297
|
-
|
|
298
|
-
do ADR-0022, que congelou o dashboard-servidor).
|
|
302
|
+
- [ ] **(visão) o motor de orquestração** — a cadeia de handoffs que **roda**, não só é coerente
|
|
303
|
+
(SPEC-019 deixou como futuro). O namesake executando: candidato ao 2.0.
|
|
299
304
|
|
|
300
305
|
Sugestões? Abra uma issue — feature não-trivial aqui começa por spec, inclusive as suas.
|
|
301
306
|
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* lib/agent-topology.ts — a topologia de orquestração é uma só, descrita em três lugares (SPEC-019).
|
|
3
|
+
*
|
|
4
|
+
* O nome do framework é orquestração multiagente, e quem-orquestra-quem vive em três fontes que podem
|
|
5
|
+
* divergir em silêncio:
|
|
6
|
+
*
|
|
7
|
+
* 1. `scripts/agent-router.ts` (`VALID_AGENTS`) — para quem um handoff pode ser roteado.
|
|
8
|
+
* 2. `.claude/agents/*.md` — os sub-agents executáveis (quem faz o trabalho).
|
|
9
|
+
* 3. `AGENTS.md` — a prosa que documenta os papéis.
|
|
10
|
+
*
|
|
11
|
+
* Este módulo extrai as três e aponta onde não concordam. É o `adr-refs` da orquestração.
|
|
12
|
+
*/
|
|
13
|
+
import fs from 'node:fs';
|
|
14
|
+
export interface TopologyEnv {
|
|
15
|
+
fs: typeof fs;
|
|
16
|
+
root: string;
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* Endpoints de handoff que NÃO são sub-agents especialistas e por isso não têm `.claude/agent`:
|
|
20
|
+
* - `user` — o humano.
|
|
21
|
+
* - `worker` — o agente implementador principal (o Claude que executa), não um especialista spawnado.
|
|
22
|
+
*/
|
|
23
|
+
export declare const ENDPOINTS: Set<string>;
|
|
24
|
+
/** Os agentes para os quais o router aceita rotear (`VALID_AGENTS` de agent-router.ts). */
|
|
25
|
+
export declare function routerAgents(env: TopologyEnv): string[];
|
|
26
|
+
/** Os sub-agents executáveis: os arquivos `.claude/agents/*.md` (menos README). */
|
|
27
|
+
export declare function subAgents(env: TopologyEnv): string[];
|
|
28
|
+
/** True se `name` é citado no AGENTS.md (documentado na prosa da topologia). */
|
|
29
|
+
export declare function documentedInAgentsMd(env: TopologyEnv, name: string): boolean;
|
|
30
|
+
export interface TopologyIssues {
|
|
31
|
+
/** Sub-agent executável que o router não conhece — implementação que a orquestração não alcança. */
|
|
32
|
+
unrouted: string[];
|
|
33
|
+
/** Papel roteável (não-endpoint) sem `.claude/agent` — o router promete um destino sem executor. */
|
|
34
|
+
missingExecutor: string[];
|
|
35
|
+
/** Sub-agent não citado no AGENTS.md — implementação sem documentação na topologia. */
|
|
36
|
+
undocumented: string[];
|
|
37
|
+
}
|
|
38
|
+
export declare function topologyIssues(env: TopologyEnv): TopologyIssues;
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* lib/agent-topology.ts — a topologia de orquestração é uma só, descrita em três lugares (SPEC-019).
|
|
3
|
+
*
|
|
4
|
+
* O nome do framework é orquestração multiagente, e quem-orquestra-quem vive em três fontes que podem
|
|
5
|
+
* divergir em silêncio:
|
|
6
|
+
*
|
|
7
|
+
* 1. `scripts/agent-router.ts` (`VALID_AGENTS`) — para quem um handoff pode ser roteado.
|
|
8
|
+
* 2. `.claude/agents/*.md` — os sub-agents executáveis (quem faz o trabalho).
|
|
9
|
+
* 3. `AGENTS.md` — a prosa que documenta os papéis.
|
|
10
|
+
*
|
|
11
|
+
* Este módulo extrai as três e aponta onde não concordam. É o `adr-refs` da orquestração.
|
|
12
|
+
*/
|
|
13
|
+
import path from 'node:path';
|
|
14
|
+
/**
|
|
15
|
+
* Endpoints de handoff que NÃO são sub-agents especialistas e por isso não têm `.claude/agent`:
|
|
16
|
+
* - `user` — o humano.
|
|
17
|
+
* - `worker` — o agente implementador principal (o Claude que executa), não um especialista spawnado.
|
|
18
|
+
*/
|
|
19
|
+
export const ENDPOINTS = new Set(['user', 'worker']);
|
|
20
|
+
/** Os agentes para os quais o router aceita rotear (`VALID_AGENTS` de agent-router.ts). */
|
|
21
|
+
export function routerAgents(env) {
|
|
22
|
+
try {
|
|
23
|
+
const src = env.fs.readFileSync(path.join(env.root, 'scripts', 'agent-router.ts'), 'utf8');
|
|
24
|
+
const m = src.match(/VALID_AGENTS\s*=\s*\[([^\]]*)\]/);
|
|
25
|
+
if (!m)
|
|
26
|
+
return [];
|
|
27
|
+
return [...m[1].matchAll(/'([^']+)'/g)].map((x) => x[1]);
|
|
28
|
+
}
|
|
29
|
+
catch {
|
|
30
|
+
return [];
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
/** Os sub-agents executáveis: os arquivos `.claude/agents/*.md` (menos README). */
|
|
34
|
+
export function subAgents(env) {
|
|
35
|
+
try {
|
|
36
|
+
return env.fs
|
|
37
|
+
.readdirSync(path.join(env.root, '.claude', 'agents'))
|
|
38
|
+
.filter((f) => f.endsWith('.md') && f.toLowerCase() !== 'readme.md')
|
|
39
|
+
.map((f) => f.replace(/\.md$/, ''))
|
|
40
|
+
.sort();
|
|
41
|
+
}
|
|
42
|
+
catch {
|
|
43
|
+
return [];
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
/** True se `name` é citado no AGENTS.md (documentado na prosa da topologia). */
|
|
47
|
+
export function documentedInAgentsMd(env, name) {
|
|
48
|
+
try {
|
|
49
|
+
const src = env.fs.readFileSync(path.join(env.root, 'AGENTS.md'), 'utf8').toLowerCase();
|
|
50
|
+
// Casa o nome exato como palavra (sdd-architect, context-engineer, release-auditor).
|
|
51
|
+
return new RegExp(`\\b${name.replace(/[-]/g, '[- ]')}\\b`).test(src);
|
|
52
|
+
}
|
|
53
|
+
catch {
|
|
54
|
+
return false;
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
export function topologyIssues(env) {
|
|
58
|
+
const router = new Set(routerAgents(env));
|
|
59
|
+
const agents = subAgents(env);
|
|
60
|
+
const agentSet = new Set(agents);
|
|
61
|
+
const unrouted = agents.filter((a) => !router.has(a) && !ENDPOINTS.has(a));
|
|
62
|
+
const missingExecutor = [...router].filter((r) => !ENDPOINTS.has(r) && !agentSet.has(r));
|
|
63
|
+
const undocumented = agents.filter((a) => !ENDPOINTS.has(a) && !documentedInAgentsMd(env, a));
|
|
64
|
+
return { unrouted, missingExecutor, undocumented };
|
|
65
|
+
}
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* lib/core/gates.ts — a bateria inteira, um veredito (SPEC-020).
|
|
3
|
+
*
|
|
4
|
+
* O framework acumulou uma família de gates — doctor (núcleo + coerência), release (tarball), smoke
|
|
5
|
+
* (projeto gerado). Cada um guarda uma fronteira, mas rodá-los todos era disciplina: a governança que
|
|
6
|
+
* existe para não depender de memória dependia da memória de quem lembra de invocar os gates.
|
|
7
|
+
*
|
|
8
|
+
* Este módulo **compõe** os runners que já existem — não reimplementa nenhum check. Uma máquina que
|
|
9
|
+
* chama as outras máquinas, e reduz tudo a um `worstStatus`.
|
|
10
|
+
*/
|
|
11
|
+
import { worstStatus } from './health.ts';
|
|
12
|
+
export interface GateGroup {
|
|
13
|
+
name: string;
|
|
14
|
+
results: any[];
|
|
15
|
+
}
|
|
16
|
+
/** Runners injetáveis — em produção, os catálogos reais; no teste, fakes com status conhecidos. */
|
|
17
|
+
export interface GatesDeps {
|
|
18
|
+
health?: () => Promise<any[]>;
|
|
19
|
+
smoke?: (opts: {
|
|
20
|
+
full: boolean;
|
|
21
|
+
}) => Promise<any[]>;
|
|
22
|
+
release?: () => Promise<any[]>;
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* Roda os gates aplicáveis ao framework e devolve os resultados agrupados por gate.
|
|
26
|
+
*
|
|
27
|
+
* Tier barato (default): coerência (doctor) + projeto gerado (smoke barato). `--full` adiciona os
|
|
28
|
+
* caros: o tarball (release) e o build do gerado (smoke --full).
|
|
29
|
+
*/
|
|
30
|
+
export declare function runGates({ full, deps }?: {
|
|
31
|
+
full?: boolean;
|
|
32
|
+
deps?: GatesDeps;
|
|
33
|
+
}): Promise<GateGroup[]>;
|
|
34
|
+
/** O pior status entre todos os gates — o veredito único. */
|
|
35
|
+
export declare function overallStatus(groups: GateGroup[]): string;
|
|
36
|
+
export { worstStatus };
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* lib/core/gates.ts — a bateria inteira, um veredito (SPEC-020).
|
|
3
|
+
*
|
|
4
|
+
* O framework acumulou uma família de gates — doctor (núcleo + coerência), release (tarball), smoke
|
|
5
|
+
* (projeto gerado). Cada um guarda uma fronteira, mas rodá-los todos era disciplina: a governança que
|
|
6
|
+
* existe para não depender de memória dependia da memória de quem lembra de invocar os gates.
|
|
7
|
+
*
|
|
8
|
+
* Este módulo **compõe** os runners que já existem — não reimplementa nenhum check. Uma máquina que
|
|
9
|
+
* chama as outras máquinas, e reduz tudo a um `worstStatus`.
|
|
10
|
+
*/
|
|
11
|
+
import { runChecks as runHealthChecks, worstStatus } from "./health.js";
|
|
12
|
+
import { runProjectSmoke } from "./project-smoke.js";
|
|
13
|
+
import { runReleaseChecks } from "./release.js";
|
|
14
|
+
/**
|
|
15
|
+
* Roda os gates aplicáveis ao framework e devolve os resultados agrupados por gate.
|
|
16
|
+
*
|
|
17
|
+
* Tier barato (default): coerência (doctor) + projeto gerado (smoke barato). `--full` adiciona os
|
|
18
|
+
* caros: o tarball (release) e o build do gerado (smoke --full).
|
|
19
|
+
*/
|
|
20
|
+
export async function runGates({ full = false, deps = {} } = {}) {
|
|
21
|
+
const health = deps.health ?? (() => runHealthChecks());
|
|
22
|
+
const smoke = deps.smoke ?? ((o) => runProjectSmoke(o));
|
|
23
|
+
const release = deps.release ?? (() => runReleaseChecks({}));
|
|
24
|
+
const groups = [];
|
|
25
|
+
groups.push({ name: 'núcleo & coerência', results: await health() });
|
|
26
|
+
groups.push({ name: 'projeto gerado', results: await smoke({ full }) });
|
|
27
|
+
if (full)
|
|
28
|
+
groups.push({ name: 'tarball (instalação limpa)', results: await release() });
|
|
29
|
+
return groups;
|
|
30
|
+
}
|
|
31
|
+
/** O pior status entre todos os gates — o veredito único. */
|
|
32
|
+
export function overallStatus(groups) {
|
|
33
|
+
return worstStatus(groups.flatMap((g) => g.results));
|
|
34
|
+
}
|
|
35
|
+
export { worstStatus };
|
package/dist/lib/core/health.js
CHANGED
|
@@ -39,6 +39,7 @@ import { getWorkspaceDbPath, getWorkspaceInfo } from "../workspace.js";
|
|
|
39
39
|
import { runChecks as run, worstStatus, stripTemplateLiterals, asErrno } from "./checks.js";
|
|
40
40
|
import { COMMANDS } from "./registry.js";
|
|
41
41
|
import { scanCommands, scanLinks, projectCommands, scanAdrRefs, adrNumbers } from "./doc-graph.js";
|
|
42
|
+
import { topologyIssues } from "../agent-topology.js";
|
|
42
43
|
/** @typedef {import('./checks.ts').Status} Status */
|
|
43
44
|
// O runner vive em checks.mjs e é compartilhado com o catálogo de release (SPEC-010). Re-exportado
|
|
44
45
|
// aqui para que `tools:doctor` e o hook SessionStart sigam importando de um lugar só.
|
|
@@ -522,6 +523,39 @@ const adrRefs = {
|
|
|
522
523
|
return { status: 'ok', detail: `toda referência a ADR resolve (${existing.size} ADRs)`, fix: null };
|
|
523
524
|
},
|
|
524
525
|
};
|
|
526
|
+
/**
|
|
527
|
+
* A topologia de orquestração é descrita em três lugares (router, `.claude/agents`, `AGENTS.md`) e
|
|
528
|
+
* pode divergir em silêncio (SPEC-019): um sub-agent que o router não roteia, um papel roteável sem
|
|
529
|
+
* executor, um agente não documentado. É a coerência da orquestração — o namesake do framework —
|
|
530
|
+
* feita invariante. `warn`: confunde a topologia, não trava o núcleo. Mesma família de `adr-refs`.
|
|
531
|
+
*/
|
|
532
|
+
const agentTopology = {
|
|
533
|
+
id: 'agent-topology',
|
|
534
|
+
title: 'a topologia de agentes concorda entre router, .claude/agents e AGENTS.md',
|
|
535
|
+
severity: 'warn',
|
|
536
|
+
scope: 'repo',
|
|
537
|
+
probe(env) {
|
|
538
|
+
if (!isFrameworkRepo(env)) {
|
|
539
|
+
return { status: 'ok', detail: 'fora do repo do framework — não se aplica', fix: null };
|
|
540
|
+
}
|
|
541
|
+
const { unrouted, missingExecutor, undocumented } = topologyIssues({ fs: env.fs, root: env.root });
|
|
542
|
+
const problemas = [];
|
|
543
|
+
if (unrouted.length)
|
|
544
|
+
problemas.push(`sem rota no router: ${unrouted.join(', ')}`);
|
|
545
|
+
if (missingExecutor.length)
|
|
546
|
+
problemas.push(`roteável sem .claude/agent: ${missingExecutor.join(', ')}`);
|
|
547
|
+
if (undocumented.length)
|
|
548
|
+
problemas.push(`não documentado no AGENTS.md: ${undocumented.join(', ')}`);
|
|
549
|
+
if (problemas.length) {
|
|
550
|
+
return {
|
|
551
|
+
status: 'warn',
|
|
552
|
+
detail: `topologia incoerente — ${problemas.join('; ')}`,
|
|
553
|
+
fix: 'alinhe VALID_AGENTS (agent-router.ts), .claude/agents/ e AGENTS.md',
|
|
554
|
+
};
|
|
555
|
+
}
|
|
556
|
+
return { status: 'ok', detail: 'router, .claude/agents e AGENTS.md concordam', fix: null };
|
|
557
|
+
},
|
|
558
|
+
};
|
|
525
559
|
/** @type {Check[]} */
|
|
526
560
|
export const CHECKS = [
|
|
527
561
|
nativeAbi,
|
|
@@ -535,6 +569,7 @@ export const CHECKS = [
|
|
|
535
569
|
commandsDocumented,
|
|
536
570
|
docsLinks,
|
|
537
571
|
adrRefs,
|
|
572
|
+
agentTopology,
|
|
538
573
|
];
|
|
539
574
|
/**
|
|
540
575
|
* Roda os checks do núcleo. Fachada sobre o runner de `checks.mjs`: existe só para injetar o
|
|
@@ -17,6 +17,7 @@ import os from 'node:os';
|
|
|
17
17
|
import path from 'node:path';
|
|
18
18
|
import { fileURLToPath } from 'node:url';
|
|
19
19
|
import { runChecks as run, worstStatus } from "./checks.js";
|
|
20
|
+
import { resolveScript } from "./registry.js";
|
|
20
21
|
// @ts-ignore — validador legado sem tipos exportados; usado só pela forma { isValid, errors }.
|
|
21
22
|
import { validateProjectStructure } from "../validators/structure-validator.js";
|
|
22
23
|
export { worstStatus };
|
|
@@ -32,7 +33,8 @@ export async function withGeneratedProject(fn, { root = repoRoot, spawn }) {
|
|
|
32
33
|
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'forja-smoke-'));
|
|
33
34
|
const projectDir = path.join(dir, 'smoke-proj');
|
|
34
35
|
try {
|
|
35
|
-
|
|
36
|
+
// resolveScript acha .ts em dev e .js no dist — cravar .ts quebrava no pacote publicado.
|
|
37
|
+
const gen = resolveScript(root, 'bin/create-memory-nest-kit');
|
|
36
38
|
const res = spawn(process.execPath, [gen, projectDir, '--force'], { cwd: dir });
|
|
37
39
|
if (res.code !== 0) {
|
|
38
40
|
throw new Error(`o gerador saiu com código ${res.code}:\n${(res.stderr || res.stdout).slice(0, 800)}`);
|
|
@@ -313,6 +313,11 @@ export const COMMANDS = {
|
|
|
313
313
|
desc: 'Gate do projeto gerado: gera isolado e prova que é coerente (SPEC-015). --full instala e builda o backend',
|
|
314
314
|
node: 'scripts/project-smoke.ts',
|
|
315
315
|
},
|
|
316
|
+
'check:all': {
|
|
317
|
+
domain: 'governanca',
|
|
318
|
+
desc: 'Roda a bateria inteira de gates e dá um veredito (SPEC-020). --full inclui tarball e build',
|
|
319
|
+
node: 'scripts/gates.ts',
|
|
320
|
+
},
|
|
316
321
|
'project:dashboard': {
|
|
317
322
|
domain: 'governanca',
|
|
318
323
|
desc: 'Gera dashboard estático de status',
|
|
@@ -39,7 +39,7 @@ const root = path.resolve(__dirname, '..');
|
|
|
39
39
|
ensureSchema({ silent: true });
|
|
40
40
|
const dbPath = getDbPath();
|
|
41
41
|
const REQUIRED = ['from', 'to', 'intent', 'context', 'acceptance', 'constraints', 'return'];
|
|
42
|
-
const VALID_AGENTS = ['orchestrator', 'context-engineer', 'sdd-architect', 'product', 'marketing', 'governance', 'worker', 'user'];
|
|
42
|
+
const VALID_AGENTS = ['orchestrator', 'context-engineer', 'sdd-architect', 'product', 'marketing', 'governance', 'release-auditor', 'worker', 'user'];
|
|
43
43
|
const VALID_INTENTS = ['implement', 'review', 'plan', 'research', 'spec', 'route'];
|
|
44
44
|
const BUSY_ATTEMPTS = 8;
|
|
45
45
|
const BUSY_DELAY_MS = 150;
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* check:all — a bateria inteira de gates do framework, um veredito (SPEC-020).
|
|
4
|
+
*
|
|
5
|
+
* forja check:all coerência (doctor) + projeto gerado (smoke barato)
|
|
6
|
+
* forja check:all --full + tarball (release:check) + build do gerado (smoke --full)
|
|
7
|
+
*
|
|
8
|
+
* Não substitui os gates focados — os agrega. "A casa está coerente?" num comando só.
|
|
9
|
+
*/
|
|
10
|
+
export {};
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* check:all — a bateria inteira de gates do framework, um veredito (SPEC-020).
|
|
4
|
+
*
|
|
5
|
+
* forja check:all coerência (doctor) + projeto gerado (smoke barato)
|
|
6
|
+
* forja check:all --full + tarball (release:check) + build do gerado (smoke --full)
|
|
7
|
+
*
|
|
8
|
+
* Não substitui os gates focados — os agrega. "A casa está coerente?" num comando só.
|
|
9
|
+
*/
|
|
10
|
+
import { runGates, overallStatus } from "../lib/core/gates.js";
|
|
11
|
+
const TAG = { ok: 'OK ', warn: 'AVISO', fail: 'FALHA', skipped: '— ' };
|
|
12
|
+
async function main() {
|
|
13
|
+
const full = process.argv.includes('--full');
|
|
14
|
+
console.log(`\nForja check:all${full ? ' (--full)' : ''} — a bateria inteira, um veredito\n`);
|
|
15
|
+
if (full)
|
|
16
|
+
console.log('Inclui os gates caros (empacota o tarball, builda o backend gerado) — leva minutos.\n');
|
|
17
|
+
const groups = await runGates({ full });
|
|
18
|
+
for (const g of groups) {
|
|
19
|
+
console.log(`▚ ${g.name}`);
|
|
20
|
+
for (const r of g.results) {
|
|
21
|
+
console.log(` ${TAG[r.status] ?? r.status} ${String(r.id).padEnd(18)} ${r.detail}`);
|
|
22
|
+
}
|
|
23
|
+
console.log('');
|
|
24
|
+
}
|
|
25
|
+
const verdict = overallStatus(groups);
|
|
26
|
+
if (verdict === 'fail') {
|
|
27
|
+
const criticos = groups.flatMap((g) => g.results).filter((r) => r.status === 'fail' && r.severity === 'critical');
|
|
28
|
+
console.log(`REPROVADO — ${criticos.length} gate(s) crítico(s) falharam:`);
|
|
29
|
+
for (const r of criticos)
|
|
30
|
+
console.log(` ${r.id}: ${r.fix || 'sem correção automática'}`);
|
|
31
|
+
process.exit(1);
|
|
32
|
+
}
|
|
33
|
+
if (verdict === 'warn') {
|
|
34
|
+
console.log('Aprovado com ressalvas. Nada crítico falhou.');
|
|
35
|
+
if (!full)
|
|
36
|
+
console.log('Para os gates caros (tarball, build do gerado), rode com --full.');
|
|
37
|
+
return;
|
|
38
|
+
}
|
|
39
|
+
console.log(full ? 'APROVADO — a bateria inteira passou.' : 'APROVADO. Para os gates caros, rode com --full.');
|
|
40
|
+
}
|
|
41
|
+
main().catch((err) => {
|
|
42
|
+
console.error(`\ncheck:all falhou: ${err.message}`);
|
|
43
|
+
process.exit(1);
|
|
44
|
+
});
|
|
@@ -14,6 +14,7 @@ import os from 'node:os';
|
|
|
14
14
|
import path from 'node:path';
|
|
15
15
|
import { fileURLToPath } from 'node:url';
|
|
16
16
|
import { planUpgrade, applyUpgrade } from "../lib/project-upgrade.js";
|
|
17
|
+
import { resolveScript } from "../lib/core/registry.js";
|
|
17
18
|
const __filename = fileURLToPath(import.meta.url);
|
|
18
19
|
const repoRoot = path.resolve(path.dirname(__filename), '..');
|
|
19
20
|
function main() {
|
|
@@ -34,7 +35,10 @@ function main() {
|
|
|
34
35
|
for (const k of Object.keys(env))
|
|
35
36
|
if (k.startsWith('npm_'))
|
|
36
37
|
delete env[k];
|
|
37
|
-
|
|
38
|
+
// resolveScript acha .ts em dev e dist/bin/create-memory-nest-kit.js no publicado — cravar .ts
|
|
39
|
+
// quebrava o comando instalado com module-not-found (o dist não tem .ts).
|
|
40
|
+
const generator = resolveScript(repoRoot, 'bin/create-memory-nest-kit');
|
|
41
|
+
execFileSync(process.execPath, [generator, fresh, '--force'], {
|
|
38
42
|
cwd: tmp,
|
|
39
43
|
env,
|
|
40
44
|
stdio: 'pipe',
|
|
@@ -37,6 +37,12 @@ Três checks novos no catálogo de `health.mjs` (`scope: repo`), sobre um scanne
|
|
|
37
37
|
ADR que existe. Fecha o último invariante que vivia por disciplina ("toda decisão vira ADR") pelo
|
|
38
38
|
lado verificável: referência a decisão inexistente é trilha que apodrece. Pegou o `ADR-0026`
|
|
39
39
|
pendurado (citado pela SPEC-012, nunca escrito) na primeira execução.
|
|
40
|
+
- **`agent-topology`** (warn, SPEC-019): a topologia de orquestração é descrita em três fontes
|
|
41
|
+
(`VALID_AGENTS` do router, `.claude/agents/*.md`, `AGENTS.md`) e pode divergir em silêncio — o
|
|
42
|
+
namesake do framework (orquestração multiagente) vivendo por disciplina. O check cruza as três:
|
|
43
|
+
sub-agent sem rota, papel roteável sem executor, agente não documentado. `user`/`worker` são
|
|
44
|
+
endpoints isentos. Pegou o `release-auditor` (executável, sem rota) na primeira execução. Mesma
|
|
45
|
+
classe dos checks acima, aplicada a quem-orquestra-quem.
|
|
40
46
|
|
|
41
47
|
Princípios:
|
|
42
48
|
|
package/package.json
CHANGED
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# Spec: gates
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-020
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **ADRs relacionadas**: ADR-0023 (doctor como gate), ADR-0024 (release gate), ADR-0029 (project:smoke), ADR-0020 (core/registry)
|
|
7
|
+
|
|
8
|
+
## 1. Problema
|
|
9
|
+
|
|
10
|
+
O framework acumulou uma família de gates — `tools:doctor` (núcleo + coerência de doc + topologia),
|
|
11
|
+
`release:check` (tarball), `project:smoke` (projeto gerado). Cada um guarda uma fronteira, mas estão
|
|
12
|
+
**espalhados**: ninguém lembra de rodar os três antes de um PR, e a governança do Forja — que existe
|
|
13
|
+
justamente para não depender de memória — depende da memória de quem publica para *invocar* os gates.
|
|
14
|
+
É a mesma ironia do ADR-0021, um nível acima: os gates existem, mas rodá-los ainda é disciplina.
|
|
15
|
+
|
|
16
|
+
## 2. Proposta de valor
|
|
17
|
+
|
|
18
|
+
Um comando roda **todos os gates aplicáveis ao framework** e dá **um veredito só**. "A casa está
|
|
19
|
+
coerente?" deixa de ser quatro comandos lembrados e vira um: `forja check:all`.
|
|
20
|
+
|
|
21
|
+
## 3. User stories
|
|
22
|
+
|
|
23
|
+
- **Como** mantenedor, **quero** um comando que rode a bateria inteira antes do PR, **para que** eu
|
|
24
|
+
não esqueça um gate e descubra a quebra no CI (ou depois).
|
|
25
|
+
- **Como** quem publica, **quero** `--full` que inclua os gates caros (tarball, build do gerado),
|
|
26
|
+
**para que** o pré-release seja um comando, não um checklist.
|
|
27
|
+
|
|
28
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
29
|
+
|
|
30
|
+
- [ ] AC-1: `forja check:all` roda os gates de coerência (o catálogo do `tools:doctor`) **+** o
|
|
31
|
+
`project:smoke` (tier barato) e reporta **um veredito** (exit ≠ 0 se qualquer crítico falhar).
|
|
32
|
+
- [ ] AC-2: `--full` adiciona os gates caros: `release:check` (tarball) e `project:smoke --full`
|
|
33
|
+
(instala + builda o backend gerado).
|
|
34
|
+
- [ ] AC-3: A saída **agrupa por gate** (núcleo & coerência / projeto gerado / tarball) e resume o
|
|
35
|
+
pior status ao final — legível, não um despejo.
|
|
36
|
+
- [ ] AC-4: **Compõe os runners existentes** (`health`, `project-smoke`, `release`) — uma máquina,
|
|
37
|
+
zero reimplementação de check. Reusa `worstStatus` de `checks.ts`.
|
|
38
|
+
- [ ] AC-5: Lógica de composição pura e testável (env/runners injetáveis; teste com fakes que
|
|
39
|
+
devolvem status conhecidos, sem gerar projeto de verdade).
|
|
40
|
+
|
|
41
|
+
## 5. Escopo
|
|
42
|
+
|
|
43
|
+
**Dentro**: compor os gates do framework num comando com veredito único e tiers.
|
|
44
|
+
|
|
45
|
+
**Fora** (explícito):
|
|
46
|
+
- `memory:audit` — é gate de **projeto gerado** (precisa de `memory/30-domains` de produto), não do
|
|
47
|
+
framework. Fica de fora do `check:all` do framework; roda no CI do projeto (ADR-0030).
|
|
48
|
+
- Reimplementar qualquer check — este comando só orquestra os catálogos que já existem.
|
|
49
|
+
- Substituir `tools:doctor`/`release:check`/`project:smoke` — eles seguem existindo, focados; o
|
|
50
|
+
`check:all` é o agregador, não o dono.
|
|
51
|
+
|
|
52
|
+
## 6. NFRs / restrições
|
|
53
|
+
|
|
54
|
+
- **Custo consciente**: o tier barato inclui a geração de um projeto (`project:smoke`) — segundos, sem
|
|
55
|
+
rede. O `--full` é minutos (empacota o tarball, `npm install` do backend). O tier certo para o
|
|
56
|
+
momento certo, como no `release:check`.
|
|
57
|
+
- **Compatibilidade**: comando novo; não muda os gates que agrega.
|
|
58
|
+
|
|
59
|
+
## 7. Métricas de sucesso
|
|
60
|
+
|
|
61
|
+
Um `forja check:all` antes do PR pega uma quebra que passaria (um gate esquecido) — a prova de que
|
|
62
|
+
reunir a bateria num comando valeu. A governança do framework deixa de depender de lembrar quais
|
|
63
|
+
gates rodar.
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
# Spec: orchestration-coherent
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-019
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **ADRs relacionadas**: ADR-0021 (invariante > disciplina), ADR-0025 (coerência da doc — a mesma classe), ADR-0005 (handoff 7 campos), ADR-0020 (core/registry)
|
|
7
|
+
|
|
8
|
+
## 1. Problema
|
|
9
|
+
|
|
10
|
+
O nome do repositório é **orquestração multiagente** — e é a parte **menos harnessed** do framework.
|
|
11
|
+
A topologia de quem-orquestra-quem é descrita em **três lugares independentes**, e nada garante que
|
|
12
|
+
concordem:
|
|
13
|
+
|
|
14
|
+
1. `AGENTS.md` — a prosa: os papéis e a topologia.
|
|
15
|
+
2. `scripts/agent-router.ts` (`VALID_AGENTS`) — o código: para quem um handoff pode ser roteado.
|
|
16
|
+
3. `.claude/agents/*.md` — os sub-agents executáveis: quem, de fato, faz o trabalho.
|
|
17
|
+
|
|
18
|
+
Três descrições da mesma coisa divergem em silêncio. **E já divergem hoje** (medido antes de escrever
|
|
19
|
+
esta spec — a mesma prova que o `adr-refs` deu):
|
|
20
|
+
|
|
21
|
+
- **`worker`** está no `VALID_AGENTS` e no `AGENTS.md`, mas **não tem** `.claude/agent`. Um papel que
|
|
22
|
+
recebe handoff sem definição executável — prosa que o código não implementa.
|
|
23
|
+
- **`release-auditor`** é um sub-agent executável, mas **não está** no `VALID_AGENTS`. Um agente para
|
|
24
|
+
o qual o router não consegue rotear — implementação que a orquestração não alcança.
|
|
25
|
+
- **`architect`** (AGENTS.md) vs **`sdd-architect`** (router/agents) — o mesmo papel com dois nomes.
|
|
26
|
+
|
|
27
|
+
Pelo critério do ADR-0021, isto não é orquestração: é sugestão. A topologia vive por disciplina, e
|
|
28
|
+
está silenciosamente incoerente **agora**. Não é conhecimento que falta — é execução.
|
|
29
|
+
|
|
30
|
+
## 2. Proposta de valor
|
|
31
|
+
|
|
32
|
+
A topologia de agentes deixa de poder divergir em silêncio: **as três fontes de verdade
|
|
33
|
+
(AGENTS.md ↔ router ↔ .claude/agents) são conferidas por um gate**. Um papel sem agente executável,
|
|
34
|
+
um agente sem rota, um nome divergente — tudo reprova. A orquestração descrita passa a ser a
|
|
35
|
+
orquestração implementada.
|
|
36
|
+
|
|
37
|
+
## 3. User stories
|
|
38
|
+
|
|
39
|
+
- **Como** mantenedor, **quero** que um papel citado na topologia sem sub-agent executável **reprove**,
|
|
40
|
+
**para que** a orquestração não prometa um agente que não existe.
|
|
41
|
+
- **Como** mantenedor, **quero** que um sub-agent para o qual o router não roteia seja apontado,
|
|
42
|
+
**para que** eu não tenha implementação órfã que a orquestração nunca aciona.
|
|
43
|
+
- **Como** governança, **quero** rodar isso no `tools:doctor`, **para que** a coerência da topologia
|
|
44
|
+
seja um artefato verificável, não uma afirmação no README.
|
|
45
|
+
|
|
46
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
47
|
+
|
|
48
|
+
- [ ] AC-1: Um check `agent-topology` (no catálogo do `tools:doctor`, via runner de `checks.ts`)
|
|
49
|
+
cruza as três fontes e **reprova** (ou avisa) quando divergem:
|
|
50
|
+
- papel roteável (`VALID_AGENTS`, menos `user`) **sem** `.claude/agents/<papel>.md` → o router
|
|
51
|
+
promete um destino que não tem executor;
|
|
52
|
+
- `.claude/agents/<x>.md` que **não** está em `VALID_AGENTS` → agente executável que ninguém roteia;
|
|
53
|
+
- papel citado no `AGENTS.md` que não bate com nenhuma das outras fontes → prosa órfã.
|
|
54
|
+
- [ ] AC-2: `user` é reconhecido como destino válido de handoff **sem** exigir um agent (é o humano —
|
|
55
|
+
não tem `.claude/agent`, e tudo bem).
|
|
56
|
+
- [ ] AC-3: O check roda no `tools:doctor` e reporta as divergências reais que já existem hoje
|
|
57
|
+
(`worker`, `release-auditor`, `architect`/`sdd-architect`) — a prova de que a fronteira estava
|
|
58
|
+
descoberta.
|
|
59
|
+
- [ ] AC-4: Fechada a incoerência: cada divergência resolvida (criar o agent, ajustar o router, ou
|
|
60
|
+
alinhar o nome) até o check ficar verde — decidido caso a caso, não no atacado.
|
|
61
|
+
- [ ] AC-5: Lógica pura e testável (extrai a topologia de fontes injetáveis; testes com fixtures).
|
|
62
|
+
|
|
63
|
+
## 5. Escopo
|
|
64
|
+
|
|
65
|
+
**Dentro**: conferir a **coerência estrutural** da topologia — os nomes de papéis/agentes batem entre
|
|
66
|
+
as três fontes.
|
|
67
|
+
|
|
68
|
+
**Fora** (explícito — a fronteira honesta):
|
|
69
|
+
- **Rodar os agentes de IA autonomamente.** O framework não executa um loop de IA; quem aciona os
|
|
70
|
+
sub-agents é o Claude Code, no uso. Este gate prova que a topologia é *coerente e acionável*, não
|
|
71
|
+
que a IA fez um bom trabalho. "Provar que a orquestração produz bom output" não é harness — é
|
|
72
|
+
julgamento, e fica fora.
|
|
73
|
+
- Validar o *conteúdo* de cada `.claude/agent` (o prompt está bom?) — é qualidade, não topologia.
|
|
74
|
+
- Um motor de execução de handoffs em cadeia (state machine que dirige o fluxo) — pode ser SPEC
|
|
75
|
+
futura; esta fecha a **coerência**, o pré-requisito de qualquer execução.
|
|
76
|
+
|
|
77
|
+
## 6. NFRs / restrições
|
|
78
|
+
|
|
79
|
+
- **Compatibilidade**: só lê as três fontes; não muda o comportamento do router nem dos agents.
|
|
80
|
+
- **Severidade honesta**: divergência que quebra a orquestração (papel roteável sem executor) =
|
|
81
|
+
provável `critical`/`warn` a decidir no plan; nome divergente = `warn`. A calibração fica para o
|
|
82
|
+
plan, à luz do que as divergências reais pedem.
|
|
83
|
+
|
|
84
|
+
## 7. Riscos e mitigação
|
|
85
|
+
|
|
86
|
+
| Risco | Prob. | Impacto | Mitigação |
|
|
87
|
+
|---|---|---|---|
|
|
88
|
+
| O check vira ruído (muitos avisos aceitáveis) | M | M | severidade calibrada no plan; `user` e casos legítimos isentos (AC-2) |
|
|
89
|
+
| Alinhar os nomes quebra referências em prosa | B | M | AC-4 resolve caso a caso, com o gate confirmando cada passo |
|
|
90
|
+
|
|
91
|
+
## 8. Métricas de sucesso
|
|
92
|
+
|
|
93
|
+
As três divergências de hoje (`worker`, `release-auditor`, `architect`/`sdd-architect`) resolvidas, o
|
|
94
|
+
`agent-topology` verde no `tools:doctor`, e uma futura divergência (um agent novo sem rota, um papel
|
|
95
|
+
renomeado) pega pelo gate antes do merge. A orquestração descrita = a orquestração implementada.
|