forjajs 1.6.2 → 1.7.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/.claude/agents/release-auditor.md +5 -3
- package/CHANGELOG.md +38 -0
- package/README.en.md +8 -5
- package/README.md +7 -5
- package/dist/lib/core/doc-graph.d.ts +6 -0
- package/dist/lib/core/doc-graph.js +14 -0
- package/dist/lib/core/health.js +3 -2
- package/dist/lib/core/registry.d.ts +18 -0
- package/dist/lib/core/registry.js +18 -0
- package/dist/lib/core/release.d.ts +18 -0
- package/dist/lib/core/release.js +34 -0
- package/dist/lib/generators/nest-generator.js +1 -1
- package/dist/lib/orchestrate.d.ts +91 -0
- package/dist/lib/orchestrate.js +137 -0
- package/dist/scripts/check-standards.js +5 -4
- package/dist/scripts/orchestrate.d.ts +12 -0
- package/dist/scripts/orchestrate.js +136 -0
- package/memory/90-decisions/0031-motor-de-orquestracao.md +55 -0
- package/package.json +1 -1
- package/specs/orchestrate/spec.md +108 -0
|
@@ -31,6 +31,7 @@ executa os comandos de verdade e reprova em qualquer um destes:
|
|
|
31
31
|
| `install` | O pacote instala do zero |
|
|
32
32
|
| `registry-scripts` | Todo comando anunciado tem script no tarball |
|
|
33
33
|
| `smoke-commands` | Os comandos **executam** — o help passa mesmo com tudo quebrado |
|
|
34
|
+
| `consumer-spec-new` | Os comandos operam no **projeto do consumidor**, não dentro do pacote (bug da v1.6.1) |
|
|
34
35
|
| `imports-resolve` | Todo import relativo resolve dentro do pacote |
|
|
35
36
|
| `deps-declared` | Nada importado ficou fora de `dependencies` |
|
|
36
37
|
| `deps-unused` | Nenhuma dependency é peso morto *(aviso)* |
|
|
@@ -45,9 +46,10 @@ O gate diz **o que** quebrou. Você diz **o que fazer com isso**:
|
|
|
45
46
|
runner já marca as consequências como `não verificado`, então persiga a raiz, não o eco.
|
|
46
47
|
- **Avisos não reprovam, mas informam.** `deps-unused` num release público é peso que todo usuário
|
|
47
48
|
baixa. Vale corrigir antes de publicar, mesmo sem travar.
|
|
48
|
-
- **Diga o que o gate não cobre.** Ele não
|
|
49
|
-
|
|
50
|
-
|
|
49
|
+
- **Diga o que o gate não cobre.** Ele não valida proveniência de pacote nem julga se a versão do
|
|
50
|
+
`package.json` faz sentido para o que mudou. O projeto *gerado* tem gate próprio — antes de uma
|
|
51
|
+
release que toca os generators, peça também `forja project:smoke --full` (ou `forja check:all
|
|
52
|
+
--full`, a bateria inteira). Se algo disso importa nesta release, diga.
|
|
51
53
|
- **Nunca aprove com base em leitura de código.** Se o gate não rodou, você não sabe — e a resposta
|
|
52
54
|
certa é dizer que não sabe.
|
|
53
55
|
|
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,44 @@ Histórico consolidado das mudanças estruturais do framework. Para decisões ar
|
|
|
4
4
|
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
+
## [1.7.1] — 2026-07-22 — Correção: `project:check` em projetos consumidores
|
|
8
|
+
|
|
9
|
+
### Corrigido
|
|
10
|
+
- **`forja project:check` num projeto consumidor auditava `node_modules/forjajs/dist/`** em vez do
|
|
11
|
+
projeto (raiz cravada em `__dirname/..`), reportando os arquivos obrigatórios como faltando (score
|
|
12
|
+
0%) — o que travava o gate `implement` do `orchestrate`. Agora audita `process.cwd()` (propagado
|
|
13
|
+
pelo dispatcher desde a 1.6.2). Mesma classe do `spec-cli` (v1.6.2); o `check-standards` ficou de
|
|
14
|
+
fora. O `check:all` **não** é afetado (agrega health/smoke/release, não `project:check`).
|
|
15
|
+
|
|
16
|
+
### Adicionado
|
|
17
|
+
- **Gate `consumer-project-check`** no `release:check`: planta um arquivo só no cwd e prova que
|
|
18
|
+
`project:check` audita o projeto do consumidor, não o pacote. Provado com dentes (reprova o bug).
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## [1.7.0] — 2026-07-22 — O motor de orquestração: o namesake executando
|
|
23
|
+
|
|
24
|
+
O nome do framework sempre foi orquestração multiagente; até aqui, a topologia era coerente
|
|
25
|
+
(SPEC-019) mas o fluxo vivia por disciplina. Esta release o faz **rodar**.
|
|
26
|
+
|
|
27
|
+
### Adicionado
|
|
28
|
+
- **`orchestrate` / `orchestrate:status` / `orchestrate:advance`** (SPEC-021, ADR-0031): a cadeia
|
|
29
|
+
SDD/GSD (spec→plan→tasks→implement→review) como **máquina de estados guardada por gates**. Cada
|
|
30
|
+
etapa abre com um handoff ADR-0005 para o dono do papel; `advance` só fecha a etapa se o artefato
|
|
31
|
+
SDD estiver aprovado **e** o gate da transição sair verde — pular etapa é bloqueado pela máquina,
|
|
32
|
+
não pela memória. O framework orquestra e guarda; o agente (IA ou humano) executa. Estado em
|
|
33
|
+
`<cwd>/.context/orchestrate-<slug>.json`; roda no framework e em projetos consumidores.
|
|
34
|
+
- `commands-documented` ganha fallback para comandos **sem dois-pontos** (grep literal de nome
|
|
35
|
+
conhecido) — `orchestrate` é o primeiro do registry.
|
|
36
|
+
|
|
37
|
+
### Corrigido
|
|
38
|
+
- **Backend gerado compila em Node 26**: o template pinava `better-sqlite3 ^11` (sem prebuild para
|
|
39
|
+
Node novo); alinhado ao do framework (`^12`). Fecha o caveat da v1.6.0 — `check:all --full` verde.
|
|
40
|
+
- **Roadmap defasado**: o `release-auditor` já consumia o gate (ADR-0024); refresh da tabela
|
|
41
|
+
(+ `consumer-spec-new`) e checkboxes marcados nos READMEs.
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
7
45
|
## [1.6.2] — 2026-07-21 — Correção: `spec:new` em projetos consumidores
|
|
8
46
|
|
|
9
47
|
### Corrigido
|
package/README.en.md
CHANGED
|
@@ -193,6 +193,9 @@ forja sprint:start # also: sprint:status · sprint:compl
|
|
|
193
193
|
forja gsd:plan <slug> # GSD runbook in .context/
|
|
194
194
|
forja gsd:handoff <intent> <slug> # role-to-role handoff (ADR-0005)
|
|
195
195
|
forja gsd:check <slug> # baseline runbook gates
|
|
196
|
+
forja orchestrate "<goal>" --slug <s> # open a run: the SDD/GSD chain as a gated state machine (SPEC-021)
|
|
197
|
+
forja orchestrate:status <slug> # the machine state: stages, gates, verdicts
|
|
198
|
+
forja orchestrate:advance <slug> # run the stage gate; green → next; red → blocked
|
|
196
199
|
|
|
197
200
|
# Code analysis (codegraph)
|
|
198
201
|
forja code:check # trustworthy index (worktree + freshness)
|
|
@@ -305,11 +308,11 @@ below either closes a framework frontier with a gate, or carries that pattern in
|
|
|
305
308
|
|
|
306
309
|
**Next** (by dependency, not by wish)
|
|
307
310
|
|
|
308
|
-
- [
|
|
309
|
-
`better-sqlite3`
|
|
310
|
-
|
|
311
|
-
- [
|
|
312
|
-
`
|
|
311
|
+
- [x] **Generated backend `builds` under new toolchains** — the template now matches the
|
|
312
|
+
framework's `better-sqlite3` (^12, with prebuilds); `check:all --full` compiles the generated
|
|
313
|
+
backend on Node 26.
|
|
314
|
+
- [x] **`release-auditor` consumes the gate** — the agent runs and judges `release:check --publish`
|
|
315
|
+
(ADR-0024), including `consumer-spec-new`; it doesn't reimplement the procedure.
|
|
313
316
|
- [ ] **Boilerplates beyond NestJS** — the process is stack-agnostic; the templates will follow.
|
|
314
317
|
- [ ] **(vision) the orchestration engine** — the handoff chain that **runs**, not just is coherent
|
|
315
318
|
(SPEC-019 left it as future). The namesake executing: a 2.0 candidate.
|
package/README.md
CHANGED
|
@@ -180,6 +180,9 @@ forja sprint:start # também: sprint:status · sprint:co
|
|
|
180
180
|
forja gsd:plan <slug> # runbook GSD em .context/
|
|
181
181
|
forja gsd:handoff <intent> <slug> # handoff entre papéis (ADR-0005)
|
|
182
182
|
forja gsd:check <slug> # gates básicos do runbook
|
|
183
|
+
forja orchestrate "<objetivo>" --slug <s> # abre a corrida: a cadeia SDD/GSD como máquina de estados (SPEC-021)
|
|
184
|
+
forja orchestrate:status <slug> # o estado da máquina: etapas, gates, vereditos
|
|
185
|
+
forja orchestrate:advance <slug> # roda o gate da etapa; verde → próxima; vermelho → trava
|
|
183
186
|
|
|
184
187
|
# Análise de código (codegraph)
|
|
185
188
|
forja code:check # índice confiável (worktree + freshness)
|
|
@@ -293,11 +296,10 @@ gerados.
|
|
|
293
296
|
|
|
294
297
|
**Próximos passos** (por dependência, não por desejo)
|
|
295
298
|
|
|
296
|
-
- [
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
-
|
|
300
|
-
`release:check` em vez de reimplementar o procedimento em prosa.
|
|
299
|
+
- [x] **`builds` do backend gerado sob toolchain novo** — o template alinhou o `better-sqlite3` ao
|
|
300
|
+
do framework (^12, com prebuilds); o `check:all --full` compila o backend gerado em Node 26.
|
|
301
|
+
- [x] **`release-auditor` consome o gate** — o agente executa e julga `release:check --publish`
|
|
302
|
+
(ADR-0024), incluindo o `consumer-spec-new`; não reimplementa o procedimento.
|
|
301
303
|
- [ ] **Boilerplates além de NestJS** — o processo é agnóstico de stack; os templates vão atrás.
|
|
302
304
|
- [ ] **(visão) o motor de orquestração** — a cadeia de handoffs que **roda**, não só é coerente
|
|
303
305
|
(SPEC-019 deixou como futuro). O namesake executando: candidato ao 2.0.
|
|
@@ -41,6 +41,12 @@ export declare function scanLinks(env: any): {
|
|
|
41
41
|
target: string;
|
|
42
42
|
resolved: string;
|
|
43
43
|
}[];
|
|
44
|
+
/**
|
|
45
|
+
* Um comando SEM dois-pontos (ex.: `orchestrate`) nunca casa com COMMAND_RE — o `:` é o
|
|
46
|
+
* discriminador que evita prosa virar falso positivo. Para um nome JÁ CONHECIDO do registry, porém,
|
|
47
|
+
* procurar `forja <cmd>` literal é preciso. É o fallback do `commands-documented` para esses casos.
|
|
48
|
+
*/
|
|
49
|
+
export declare function commandCited(env: any, cmd: string): boolean;
|
|
44
50
|
/** Números de ADR que existem de fato como arquivo (`NNNN-*.md`, sem `_template`). */
|
|
45
51
|
export declare function adrNumbers(env: any): Set<string>;
|
|
46
52
|
/**
|
|
@@ -138,6 +138,20 @@ export function scanLinks(env) {
|
|
|
138
138
|
}
|
|
139
139
|
return hits;
|
|
140
140
|
}
|
|
141
|
+
/**
|
|
142
|
+
* Um comando SEM dois-pontos (ex.: `orchestrate`) nunca casa com COMMAND_RE — o `:` é o
|
|
143
|
+
* discriminador que evita prosa virar falso positivo. Para um nome JÁ CONHECIDO do registry, porém,
|
|
144
|
+
* procurar `forja <cmd>` literal é preciso. É o fallback do `commands-documented` para esses casos.
|
|
145
|
+
*/
|
|
146
|
+
export function commandCited(env, cmd) {
|
|
147
|
+
const re = new RegExp(`(?:\\bforja\\s+|npm run\\s+)${cmd.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`);
|
|
148
|
+
for (const rel of docFiles(env)) {
|
|
149
|
+
const src = safeRead(env, path.join(env.root, rel));
|
|
150
|
+
if (src != null && re.test(src))
|
|
151
|
+
return true;
|
|
152
|
+
}
|
|
153
|
+
return false;
|
|
154
|
+
}
|
|
141
155
|
/** Superfícies onde um ADR pode ser citado: as de instrução + as specs + os próprios ADRs. */
|
|
142
156
|
const ADR_REF_SURFACES = [...DOC_SURFACES, 'specs', 'memory/90-decisions'];
|
|
143
157
|
const ADR_REF_RE = /ADR-(\d{4})/g;
|
package/dist/lib/core/health.js
CHANGED
|
@@ -38,7 +38,7 @@ import { fileURLToPath } from 'node:url';
|
|
|
38
38
|
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
|
-
import { scanCommands, scanLinks, projectCommands, scanAdrRefs, adrNumbers } from "./doc-graph.js";
|
|
41
|
+
import { scanCommands, scanLinks, projectCommands, scanAdrRefs, adrNumbers, commandCited } from "./doc-graph.js";
|
|
42
42
|
import { topologyIssues } from "../agent-topology.js";
|
|
43
43
|
/** @typedef {import('./checks.ts').Status} Status */
|
|
44
44
|
// O runner vive em checks.mjs e é compartilhado com o catálogo de release (SPEC-010). Re-exportado
|
|
@@ -463,7 +463,8 @@ const commandsDocumented = {
|
|
|
463
463
|
return { status: 'ok', detail: 'fora do repo do framework — não se aplica', fix: null };
|
|
464
464
|
}
|
|
465
465
|
const citados = new Set(scanCommands(env).map((c) => c.command));
|
|
466
|
-
|
|
466
|
+
// Comando sem `:` nunca casa com o scanner largo — para nomes conhecidos, o grep literal decide.
|
|
467
|
+
const orfaos = Object.keys(COMMANDS).filter((c) => !citados.has(c) && !commandCited(env, c));
|
|
467
468
|
if (orfaos.length) {
|
|
468
469
|
return {
|
|
469
470
|
status: 'warn',
|
|
@@ -108,6 +108,24 @@ export declare const COMMANDS: {
|
|
|
108
108
|
node: string;
|
|
109
109
|
args: string[];
|
|
110
110
|
};
|
|
111
|
+
orchestrate: {
|
|
112
|
+
domain: string;
|
|
113
|
+
desc: string;
|
|
114
|
+
node: string;
|
|
115
|
+
args: string[];
|
|
116
|
+
};
|
|
117
|
+
'orchestrate:status': {
|
|
118
|
+
domain: string;
|
|
119
|
+
desc: string;
|
|
120
|
+
node: string;
|
|
121
|
+
args: string[];
|
|
122
|
+
};
|
|
123
|
+
'orchestrate:advance': {
|
|
124
|
+
domain: string;
|
|
125
|
+
desc: string;
|
|
126
|
+
node: string;
|
|
127
|
+
args: string[];
|
|
128
|
+
};
|
|
111
129
|
'hermes:handoff': {
|
|
112
130
|
domain: string;
|
|
113
131
|
desc: string;
|
|
@@ -123,6 +123,24 @@ export const COMMANDS = {
|
|
|
123
123
|
node: 'scripts/agent-harness.ts',
|
|
124
124
|
args: ['gsd:check'],
|
|
125
125
|
},
|
|
126
|
+
orchestrate: {
|
|
127
|
+
domain: 'gsd',
|
|
128
|
+
desc: 'Abre uma corrida: a cadeia SDD/GSD como máquina de estados guardada por gates (SPEC-021). "<objetivo>" --slug <slug>',
|
|
129
|
+
node: 'scripts/orchestrate.ts',
|
|
130
|
+
args: ['start'],
|
|
131
|
+
},
|
|
132
|
+
'orchestrate:status': {
|
|
133
|
+
domain: 'gsd',
|
|
134
|
+
desc: 'O estado da corrida: etapas feitas, aberta, gates e vereditos',
|
|
135
|
+
node: 'scripts/orchestrate.ts',
|
|
136
|
+
args: ['status'],
|
|
137
|
+
},
|
|
138
|
+
'orchestrate:advance': {
|
|
139
|
+
domain: 'gsd',
|
|
140
|
+
desc: 'Roda o gate da etapa aberta; verde → abre a próxima; vermelho → trava com o parecer',
|
|
141
|
+
node: 'scripts/orchestrate.ts',
|
|
142
|
+
args: ['advance'],
|
|
143
|
+
},
|
|
126
144
|
'hermes:handoff': {
|
|
127
145
|
domain: 'gsd',
|
|
128
146
|
desc: 'Registra handoff ADR-0005 bruto via agent-router',
|
|
@@ -116,6 +116,24 @@ export declare function defaultEnv(overrides?: {}): {
|
|
|
116
116
|
node: string;
|
|
117
117
|
args: string[];
|
|
118
118
|
};
|
|
119
|
+
orchestrate: {
|
|
120
|
+
domain: string;
|
|
121
|
+
desc: string;
|
|
122
|
+
node: string;
|
|
123
|
+
args: string[];
|
|
124
|
+
};
|
|
125
|
+
'orchestrate:status': {
|
|
126
|
+
domain: string;
|
|
127
|
+
desc: string;
|
|
128
|
+
node: string;
|
|
129
|
+
args: string[];
|
|
130
|
+
};
|
|
131
|
+
'orchestrate:advance': {
|
|
132
|
+
domain: string;
|
|
133
|
+
desc: string;
|
|
134
|
+
node: string;
|
|
135
|
+
args: string[];
|
|
136
|
+
};
|
|
119
137
|
'hermes:handoff': {
|
|
120
138
|
domain: string;
|
|
121
139
|
desc: string;
|
package/dist/lib/core/release.js
CHANGED
|
@@ -433,6 +433,39 @@ const consumerSpecNew = {
|
|
|
433
433
|
return { status: 'ok', detail: 'spec criada no projeto do consumidor; templates do pacote resolvem', fix: null };
|
|
434
434
|
},
|
|
435
435
|
};
|
|
436
|
+
/**
|
|
437
|
+
* A mesma classe do `consumer-spec-new`, na AUDITORIA: `project:check` cravava a raiz em
|
|
438
|
+
* `__dirname/..` e auditava o PACOTE (`node_modules/forjajs/dist`) em vez do projeto do consumidor —
|
|
439
|
+
* reportava tudo faltando, score 0% (bug da v1.7.0, que travou uma corrida do `orchestrate`). O gate
|
|
440
|
+
* planta um arquivo que SÓ existe no cwd e confere que o comando o enxerga. Se ele auditasse o pacote,
|
|
441
|
+
* o arquivo do cwd não apareceria.
|
|
442
|
+
*/
|
|
443
|
+
const consumerProjectCheck = {
|
|
444
|
+
id: 'consumer-project-check',
|
|
445
|
+
title: 'project:check audita o projeto do consumidor (cwd), não o pacote',
|
|
446
|
+
severity: 'critical',
|
|
447
|
+
dependsOn: 'install',
|
|
448
|
+
probe(env) {
|
|
449
|
+
const pkg = JSON.parse(env.fs.readFileSync(path.join(env.pkgDir, 'package.json'), 'utf8'));
|
|
450
|
+
const binRel = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.forja;
|
|
451
|
+
const bin = path.join(env.pkgDir, binRel);
|
|
452
|
+
// Um AGENTS.md real, presente SÓ no cwd — a testemunha de qual raiz o comando auditou.
|
|
453
|
+
const marker = 'Marcador de auditoria do consumidor com mais de cem caracteres para não ser tratado como placeholder pelo check de padrões.\n';
|
|
454
|
+
env.fs.writeFileSync(path.join(env.installDir, 'AGENTS.md'), marker);
|
|
455
|
+
const res = env.spawn(process.execPath, [bin, 'project:check'], { cwd: env.installDir });
|
|
456
|
+
const saida = `${res.stdout || ''}${res.stderr || ''}`;
|
|
457
|
+
// A linha do AGENTS.md: "OK ... AGENTS.md" (achou no cwd) vs "Faltando" (auditou o pacote).
|
|
458
|
+
const linha = saida.split('\n').find((l) => /\bAGENTS\.md\b/.test(l)) || '';
|
|
459
|
+
if (/Faltando/i.test(linha) || linha === '') {
|
|
460
|
+
return {
|
|
461
|
+
status: 'fail',
|
|
462
|
+
detail: 'project:check não enxergou o AGENTS.md do cwd — está auditando o pacote, não o projeto',
|
|
463
|
+
fix: 'a raiz auditada deve ser process.cwd(), não path.resolve(__dirname, ..) — ver check-standards',
|
|
464
|
+
};
|
|
465
|
+
}
|
|
466
|
+
return { status: 'ok', detail: 'project:check audita o cwd (o AGENTS.md do consumidor foi visto)', fix: null };
|
|
467
|
+
},
|
|
468
|
+
};
|
|
436
469
|
/** @type {import('./checks.ts').Check[]} */
|
|
437
470
|
export const RELEASE_CHECKS = [
|
|
438
471
|
treeClean,
|
|
@@ -440,6 +473,7 @@ export const RELEASE_CHECKS = [
|
|
|
440
473
|
registryScripts,
|
|
441
474
|
smokeCommands,
|
|
442
475
|
consumerSpecNew,
|
|
476
|
+
consumerProjectCheck,
|
|
443
477
|
importsResolve,
|
|
444
478
|
depsDeclared,
|
|
445
479
|
depsUnused,
|
|
@@ -44,7 +44,7 @@ function createNestTemplates(projectName) {
|
|
|
44
44
|
"@nestjs/common": "^11.0.0",
|
|
45
45
|
"@nestjs/core": "^11.0.0",
|
|
46
46
|
"@nestjs/platform-express": "^11.0.0",
|
|
47
|
-
"better-sqlite3": "^11.
|
|
47
|
+
"better-sqlite3": "^12.11.1",
|
|
48
48
|
"reflect-metadata": "^0.2.2",
|
|
49
49
|
"rxjs": "^7.8.1"
|
|
50
50
|
},
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* lib/orchestrate.ts — o motor de orquestração: a cadeia de handoffs como máquina de estados
|
|
3
|
+
* (SPEC-021, ADR-0031).
|
|
4
|
+
*
|
|
5
|
+
* O framework NÃO executa o trabalho de cada etapa — quem faz é o agente (IA ou humano) que pega o
|
|
6
|
+
* handoff aberto. O que o motor faz, e nada mais: decompõe o objetivo na cadeia SDD/GSD, abre a
|
|
7
|
+
* etapa certa, e **só avança quando o gate da etapa passa**. A etapa que tenta pular fica bloqueada
|
|
8
|
+
* pela máquina, não pela memória de alguém. O framework orquestra e guarda; o agente executa.
|
|
9
|
+
*
|
|
10
|
+
* Estado em `<cwd>/.context/orchestrate-<slug>.json` — ao lado dos runbooks GSD, versionável se o
|
|
11
|
+
* projeto quiser. Cada transição também vira handoff ADR-0005 (via agent-router) e linha de
|
|
12
|
+
* auditoria (via o dispatcher). A corrida inteira é reconstruível.
|
|
13
|
+
*/
|
|
14
|
+
import fs from 'node:fs';
|
|
15
|
+
export interface OrchestrateEnv {
|
|
16
|
+
fs: typeof fs;
|
|
17
|
+
}
|
|
18
|
+
export interface Stage {
|
|
19
|
+
id: string;
|
|
20
|
+
owner: string;
|
|
21
|
+
/** O que o dono faz nesta etapa (vai no handoff). */
|
|
22
|
+
work: string;
|
|
23
|
+
/** intent do handoff (ADR-0005): implement | review | plan | research. */
|
|
24
|
+
intent: 'implement' | 'review' | 'plan' | 'research';
|
|
25
|
+
/** argv do `forja` que guarda a transição — a etapa só fecha se este comando sair 0. */
|
|
26
|
+
gate: string[];
|
|
27
|
+
/**
|
|
28
|
+
* Artefato SDD que a etapa produz (`specs/<slug>/<artifact>.md`), exigido aprovado além do gate.
|
|
29
|
+
* Sem isto, `spec:check` deixaria a etapa `plan` avançar SEM plan.md — ausência não é incoerência
|
|
30
|
+
* para o check, mas é trabalho não feito para a máquina (furo achado no test-drive da SPEC-021).
|
|
31
|
+
*/
|
|
32
|
+
artifact?: 'spec' | 'plan' | 'tasks';
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* A cadeia v1: o pipeline SDD/GSD, determinística de propósito (decisão 3 da SPEC-021). Cada
|
|
36
|
+
* transição tem dono e gate; a topologia dos donos é a que o `agent-topology` mantém coerente.
|
|
37
|
+
*/
|
|
38
|
+
export declare function chainFor(slug: string): Stage[];
|
|
39
|
+
export interface StageState {
|
|
40
|
+
id: string;
|
|
41
|
+
owner: string;
|
|
42
|
+
gate: string;
|
|
43
|
+
status: 'pending' | 'open' | 'done';
|
|
44
|
+
verdict?: string;
|
|
45
|
+
closedAt?: string;
|
|
46
|
+
}
|
|
47
|
+
export interface RunState {
|
|
48
|
+
slug: string;
|
|
49
|
+
goal: string;
|
|
50
|
+
createdAt: string;
|
|
51
|
+
/** Índice da etapa aberta; === stages.length quando a corrida terminou. */
|
|
52
|
+
current: number;
|
|
53
|
+
stages: StageState[];
|
|
54
|
+
}
|
|
55
|
+
export declare function statePath(root: string, slug: string): string;
|
|
56
|
+
export declare function loadState(root: string, slug: string, env?: OrchestrateEnv): RunState | null;
|
|
57
|
+
/** Abre uma corrida: a cadeia inteira `pending`, a primeira etapa `open`. Recusa sobrescrever. */
|
|
58
|
+
export declare function startRun({ root, slug, goal }: {
|
|
59
|
+
root: string;
|
|
60
|
+
slug: string;
|
|
61
|
+
goal: string;
|
|
62
|
+
}, env?: OrchestrateEnv): RunState;
|
|
63
|
+
/** O artefato existe e está aprovado? A máquina exige o trabalho, não só a coerência. */
|
|
64
|
+
export declare function artifactReady(root: string, slug: string, artifact: string, env?: OrchestrateEnv): {
|
|
65
|
+
ok: boolean;
|
|
66
|
+
reason: string;
|
|
67
|
+
};
|
|
68
|
+
export interface AdvanceResult {
|
|
69
|
+
advanced: boolean;
|
|
70
|
+
/** A etapa que o gate avaliou. */
|
|
71
|
+
stage: StageState;
|
|
72
|
+
/** A próxima etapa aberta (null quando a corrida terminou ou o gate reprovou). */
|
|
73
|
+
next: StageState | null;
|
|
74
|
+
finished: boolean;
|
|
75
|
+
gateOutput: string;
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* O coração do motor: roda o gate da etapa aberta. Verde → fecha a etapa e abre a próxima.
|
|
79
|
+
* Vermelho → a corrida fica onde está, com o parecer gravado. `runGate` é injetado — o motor não
|
|
80
|
+
* sabe COMO o gate roda, só que devolve exit code e saída (testável sem spawnar nada).
|
|
81
|
+
*/
|
|
82
|
+
export declare function advance({ root, slug, runGate, }: {
|
|
83
|
+
root: string;
|
|
84
|
+
slug: string;
|
|
85
|
+
runGate: (gateArgv: string[]) => {
|
|
86
|
+
code: number;
|
|
87
|
+
output: string;
|
|
88
|
+
};
|
|
89
|
+
}, env?: OrchestrateEnv): AdvanceResult;
|
|
90
|
+
/** O handoff ADR-0005 da etapa — quem abre a etapa entrega este payload ao agent-router. */
|
|
91
|
+
export declare function handoffFor(slug: string, goal: string, stageIndex: number): Record<string, string>;
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* lib/orchestrate.ts — o motor de orquestração: a cadeia de handoffs como máquina de estados
|
|
3
|
+
* (SPEC-021, ADR-0031).
|
|
4
|
+
*
|
|
5
|
+
* O framework NÃO executa o trabalho de cada etapa — quem faz é o agente (IA ou humano) que pega o
|
|
6
|
+
* handoff aberto. O que o motor faz, e nada mais: decompõe o objetivo na cadeia SDD/GSD, abre a
|
|
7
|
+
* etapa certa, e **só avança quando o gate da etapa passa**. A etapa que tenta pular fica bloqueada
|
|
8
|
+
* pela máquina, não pela memória de alguém. O framework orquestra e guarda; o agente executa.
|
|
9
|
+
*
|
|
10
|
+
* Estado em `<cwd>/.context/orchestrate-<slug>.json` — ao lado dos runbooks GSD, versionável se o
|
|
11
|
+
* projeto quiser. Cada transição também vira handoff ADR-0005 (via agent-router) e linha de
|
|
12
|
+
* auditoria (via o dispatcher). A corrida inteira é reconstruível.
|
|
13
|
+
*/
|
|
14
|
+
import fs from 'node:fs';
|
|
15
|
+
import path from 'node:path';
|
|
16
|
+
const defaultEnv = { fs };
|
|
17
|
+
/**
|
|
18
|
+
* A cadeia v1: o pipeline SDD/GSD, determinística de propósito (decisão 3 da SPEC-021). Cada
|
|
19
|
+
* transição tem dono e gate; a topologia dos donos é a que o `agent-topology` mantém coerente.
|
|
20
|
+
*/
|
|
21
|
+
export function chainFor(slug) {
|
|
22
|
+
return [
|
|
23
|
+
{ id: 'spec', owner: 'product', intent: 'plan', work: `escrever/aprovar specs/${slug}/spec.md`, gate: ['spec:check', slug], artifact: 'spec' },
|
|
24
|
+
{ id: 'plan', owner: 'sdd-architect', intent: 'plan', work: `escrever/aprovar specs/${slug}/plan.md`, gate: ['spec:check', slug], artifact: 'plan' },
|
|
25
|
+
{ id: 'tasks', owner: 'sdd-architect', intent: 'plan', work: `decompor specs/${slug}/tasks.md`, gate: ['spec:check', slug], artifact: 'tasks' },
|
|
26
|
+
{ id: 'implement', owner: 'worker', intent: 'implement', work: 'implementar as tasks com verde contínuo', gate: ['project:check'] },
|
|
27
|
+
{ id: 'review', owner: 'governance', intent: 'review', work: 'revisar a entrega contra os ACs', gate: ['check:all'] },
|
|
28
|
+
];
|
|
29
|
+
}
|
|
30
|
+
export function statePath(root, slug) {
|
|
31
|
+
return path.join(root, '.context', `orchestrate-${slug}.json`);
|
|
32
|
+
}
|
|
33
|
+
export function loadState(root, slug, env = defaultEnv) {
|
|
34
|
+
try {
|
|
35
|
+
return JSON.parse(env.fs.readFileSync(statePath(root, slug), 'utf8'));
|
|
36
|
+
}
|
|
37
|
+
catch {
|
|
38
|
+
return null;
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
function saveState(root, state, env) {
|
|
42
|
+
const file = statePath(root, state.slug);
|
|
43
|
+
env.fs.mkdirSync(path.dirname(file), { recursive: true });
|
|
44
|
+
env.fs.writeFileSync(file, JSON.stringify(state, null, 2) + '\n');
|
|
45
|
+
}
|
|
46
|
+
/** Abre uma corrida: a cadeia inteira `pending`, a primeira etapa `open`. Recusa sobrescrever. */
|
|
47
|
+
export function startRun({ root, slug, goal }, env = defaultEnv) {
|
|
48
|
+
if (loadState(root, slug, env)) {
|
|
49
|
+
throw new Error(`já existe uma corrida para "${slug}" — veja orchestrate:status ${slug}`);
|
|
50
|
+
}
|
|
51
|
+
const stages = chainFor(slug).map((s, i) => ({
|
|
52
|
+
id: s.id,
|
|
53
|
+
owner: s.owner,
|
|
54
|
+
gate: s.gate.join(' '),
|
|
55
|
+
status: i === 0 ? 'open' : 'pending',
|
|
56
|
+
}));
|
|
57
|
+
const state = { slug, goal, createdAt: new Date().toISOString(), current: 0, stages };
|
|
58
|
+
saveState(root, state, env);
|
|
59
|
+
return state;
|
|
60
|
+
}
|
|
61
|
+
const STATUS_RE = /-\s*\*\*Status\*\*:\s*([a-z]+)/i;
|
|
62
|
+
const READY_STATUSES = new Set(['approved', 'implementing', 'done']);
|
|
63
|
+
/** O artefato existe e está aprovado? A máquina exige o trabalho, não só a coerência. */
|
|
64
|
+
export function artifactReady(root, slug, artifact, env = defaultEnv) {
|
|
65
|
+
const file = path.join(root, 'specs', slug, `${artifact}.md`);
|
|
66
|
+
let src;
|
|
67
|
+
try {
|
|
68
|
+
src = env.fs.readFileSync(file, 'utf8');
|
|
69
|
+
}
|
|
70
|
+
catch {
|
|
71
|
+
return { ok: false, reason: `specs/${slug}/${artifact}.md não existe — a etapa não foi feita` };
|
|
72
|
+
}
|
|
73
|
+
const m = src.match(STATUS_RE);
|
|
74
|
+
const status = m ? m[1].toLowerCase() : 'unknown';
|
|
75
|
+
if (!READY_STATUSES.has(status)) {
|
|
76
|
+
return { ok: false, reason: `specs/${slug}/${artifact}.md está "${status}" — precisa de approved` };
|
|
77
|
+
}
|
|
78
|
+
return { ok: true, reason: `${artifact}.md ${status}` };
|
|
79
|
+
}
|
|
80
|
+
/**
|
|
81
|
+
* O coração do motor: roda o gate da etapa aberta. Verde → fecha a etapa e abre a próxima.
|
|
82
|
+
* Vermelho → a corrida fica onde está, com o parecer gravado. `runGate` é injetado — o motor não
|
|
83
|
+
* sabe COMO o gate roda, só que devolve exit code e saída (testável sem spawnar nada).
|
|
84
|
+
*/
|
|
85
|
+
export function advance({ root, slug, runGate, }, env = defaultEnv) {
|
|
86
|
+
const state = loadState(root, slug, env);
|
|
87
|
+
if (!state)
|
|
88
|
+
throw new Error(`nenhuma corrida para "${slug}" — comece com: forja orchestrate "<objetivo>" --slug ${slug}`);
|
|
89
|
+
if (state.current >= state.stages.length) {
|
|
90
|
+
return { advanced: false, stage: state.stages[state.stages.length - 1], next: null, finished: true, gateOutput: '' };
|
|
91
|
+
}
|
|
92
|
+
const chain = chainFor(slug);
|
|
93
|
+
const stage = state.stages[state.current];
|
|
94
|
+
const def = chain[state.current];
|
|
95
|
+
// O artefato da etapa vem ANTES do gate: sem specs/<slug>/<artifact>.md aprovado, o trabalho não
|
|
96
|
+
// foi feito — não importa o que o check de coerência diga.
|
|
97
|
+
if (def.artifact) {
|
|
98
|
+
const ready = artifactReady(root, slug, def.artifact, env);
|
|
99
|
+
if (!ready.ok) {
|
|
100
|
+
stage.verdict = ready.reason;
|
|
101
|
+
saveState(root, state, env);
|
|
102
|
+
return { advanced: false, stage, next: null, finished: false, gateOutput: ready.reason };
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
const res = runGate(def.gate);
|
|
106
|
+
if (res.code !== 0) {
|
|
107
|
+
stage.verdict = `gate reprovou (exit ${res.code})`;
|
|
108
|
+
saveState(root, state, env);
|
|
109
|
+
return { advanced: false, stage, next: null, finished: false, gateOutput: res.output };
|
|
110
|
+
}
|
|
111
|
+
stage.status = 'done';
|
|
112
|
+
stage.verdict = 'gate verde';
|
|
113
|
+
stage.closedAt = new Date().toISOString();
|
|
114
|
+
state.current += 1;
|
|
115
|
+
let next = null;
|
|
116
|
+
if (state.current < state.stages.length) {
|
|
117
|
+
next = state.stages[state.current];
|
|
118
|
+
next.status = 'open';
|
|
119
|
+
}
|
|
120
|
+
saveState(root, state, env);
|
|
121
|
+
return { advanced: true, stage, next, finished: next == null, gateOutput: res.output };
|
|
122
|
+
}
|
|
123
|
+
/** O handoff ADR-0005 da etapa — quem abre a etapa entrega este payload ao agent-router. */
|
|
124
|
+
export function handoffFor(slug, goal, stageIndex) {
|
|
125
|
+
const chain = chainFor(slug);
|
|
126
|
+
const s = chain[stageIndex];
|
|
127
|
+
return {
|
|
128
|
+
from: 'orchestrator',
|
|
129
|
+
to: s.owner,
|
|
130
|
+
intent: s.intent,
|
|
131
|
+
context: `orchestrate ${slug} — objetivo: ${goal}. Etapa ${s.id}: specs/${slug}/, .context/orchestrate-${slug}.json`,
|
|
132
|
+
acceptance: `gate da etapa verde: forja ${s.gate.join(' ')}`,
|
|
133
|
+
constraints: `só a etapa ${s.id}; a máquina não avança sem o gate (SPEC-021)`,
|
|
134
|
+
return: `feito o trabalho, rode: forja orchestrate:advance ${slug}`,
|
|
135
|
+
spec_slug: slug,
|
|
136
|
+
};
|
|
137
|
+
}
|
|
@@ -1,10 +1,11 @@
|
|
|
1
1
|
import fs from 'node:fs';
|
|
2
2
|
import path from 'node:path';
|
|
3
|
-
import { fileURLToPath } from 'node:url';
|
|
4
3
|
import { resolveProject, getWorkspaceInfo, initWorkspace } from "../lib/workspace.js";
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
4
|
+
// O projeto a auditar é ONDE O USUÁRIO INVOCOU — `process.cwd()`, propagado pelo dispatcher desde a
|
|
5
|
+
// v1.6.2. Cravar `__dirname/..` auditava a raiz do PACOTE (`node_modules/forjajs/dist`) no consumidor
|
|
6
|
+
// e reportava tudo como faltando (bug da v1.7.0, mesma classe do spec-cli). No repo do framework,
|
|
7
|
+
// invoca-se da raiz, então cwd = a raiz do framework — comportamento inalterado.
|
|
8
|
+
const root = process.cwd();
|
|
8
9
|
const [projectArg] = process.argv.slice(2);
|
|
9
10
|
const project = projectArg || 'framework-root';
|
|
10
11
|
let projectDir;
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* orchestrate — a cadeia SDD/GSD como máquina de estados guardada por gates (SPEC-021, ADR-0031).
|
|
4
|
+
*
|
|
5
|
+
* forja orchestrate "<objetivo>" --slug <slug> decompõe e abre a 1ª etapa (handoff ADR-0005)
|
|
6
|
+
* forja orchestrate:status <slug> o estado da máquina
|
|
7
|
+
* forja orchestrate:advance <slug> roda o gate da etapa; verde → próxima; vermelho → trava
|
|
8
|
+
*
|
|
9
|
+
* O motor orquestra e guarda; o agente (IA ou humano) que pega o handoff executa. Roda onde você
|
|
10
|
+
* invocar: no framework (dogfood) ou num projeto gerado — o estado vive em `<cwd>/.context/`.
|
|
11
|
+
*/
|
|
12
|
+
export {};
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* orchestrate — a cadeia SDD/GSD como máquina de estados guardada por gates (SPEC-021, ADR-0031).
|
|
4
|
+
*
|
|
5
|
+
* forja orchestrate "<objetivo>" --slug <slug> decompõe e abre a 1ª etapa (handoff ADR-0005)
|
|
6
|
+
* forja orchestrate:status <slug> o estado da máquina
|
|
7
|
+
* forja orchestrate:advance <slug> roda o gate da etapa; verde → próxima; vermelho → trava
|
|
8
|
+
*
|
|
9
|
+
* O motor orquestra e guarda; o agente (IA ou humano) que pega o handoff executa. Roda onde você
|
|
10
|
+
* invocar: no framework (dogfood) ou num projeto gerado — o estado vive em `<cwd>/.context/`.
|
|
11
|
+
*/
|
|
12
|
+
import { spawnSync } from 'node:child_process';
|
|
13
|
+
import path from 'node:path';
|
|
14
|
+
import { fileURLToPath } from 'node:url';
|
|
15
|
+
import { startRun, advance, loadState, chainFor, handoffFor } from "../lib/orchestrate.js";
|
|
16
|
+
import { resolveScript } from "../lib/core/registry.js";
|
|
17
|
+
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
|
18
|
+
const pkgRoot = path.resolve(__dirname, '..');
|
|
19
|
+
const targetRoot = process.cwd();
|
|
20
|
+
function forjaBin() {
|
|
21
|
+
return resolveScript(pkgRoot, 'bin/forja');
|
|
22
|
+
}
|
|
23
|
+
/** Registra o handoff da etapa via agent-router. Falha de workspace não derruba a corrida. */
|
|
24
|
+
function registerHandoff(slug, goal, stageIndex) {
|
|
25
|
+
const payload = handoffFor(slug, goal, stageIndex);
|
|
26
|
+
const router = resolveScript(pkgRoot, 'scripts/agent-router');
|
|
27
|
+
const res = spawnSync(process.execPath, [router, 'append', JSON.stringify(payload)], {
|
|
28
|
+
cwd: targetRoot,
|
|
29
|
+
encoding: 'utf8',
|
|
30
|
+
});
|
|
31
|
+
if (res.status !== 0) {
|
|
32
|
+
console.log(` (handoff não registrado: ${String(res.stderr || '').trim().split('\n')[0] || 'workspace indisponível'} — a corrida segue)`);
|
|
33
|
+
}
|
|
34
|
+
else {
|
|
35
|
+
console.log(` handoff → ${payload.to} (${payload.intent}) registrado`);
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
function printStatus(slug) {
|
|
39
|
+
const state = loadState(targetRoot, slug);
|
|
40
|
+
if (!state) {
|
|
41
|
+
console.error(`Nenhuma corrida para "${slug}". Comece com: forja orchestrate "<objetivo>" --slug ${slug}`);
|
|
42
|
+
process.exit(1);
|
|
43
|
+
}
|
|
44
|
+
const ICON = { done: '✓', open: '▶', pending: '·' };
|
|
45
|
+
console.log(`\nCorrida: ${state.slug} — ${state.goal}\n`);
|
|
46
|
+
for (const s of state.stages) {
|
|
47
|
+
const marca = ICON[s.status] ?? '?';
|
|
48
|
+
const veredito = s.verdict ? ` [${s.verdict}]` : '';
|
|
49
|
+
console.log(` ${marca} ${s.id.padEnd(10)} ${s.owner.padEnd(14)} gate: forja ${s.gate}${veredito}`);
|
|
50
|
+
}
|
|
51
|
+
if (state.current >= state.stages.length) {
|
|
52
|
+
console.log('\nCorrida CONCLUÍDA — todas as transições passaram pelos gates.');
|
|
53
|
+
}
|
|
54
|
+
else {
|
|
55
|
+
const aberta = state.stages[state.current];
|
|
56
|
+
console.log(`\nEtapa aberta: ${aberta.id} (dono: ${aberta.owner}). Feito o trabalho: forja orchestrate:advance ${slug}`);
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
function main() {
|
|
60
|
+
const [mode, ...argv] = process.argv.slice(2);
|
|
61
|
+
if (mode === 'status') {
|
|
62
|
+
const slug = argv[0];
|
|
63
|
+
if (!slug) {
|
|
64
|
+
console.error('Uso: forja orchestrate:status <slug>');
|
|
65
|
+
process.exit(1);
|
|
66
|
+
}
|
|
67
|
+
printStatus(slug);
|
|
68
|
+
return;
|
|
69
|
+
}
|
|
70
|
+
if (mode === 'advance') {
|
|
71
|
+
const slug = argv[0];
|
|
72
|
+
if (!slug) {
|
|
73
|
+
console.error('Uso: forja orchestrate:advance <slug>');
|
|
74
|
+
process.exit(1);
|
|
75
|
+
}
|
|
76
|
+
const state = loadState(targetRoot, slug);
|
|
77
|
+
if (!state) {
|
|
78
|
+
console.error(`Nenhuma corrida para "${slug}".`);
|
|
79
|
+
process.exit(1);
|
|
80
|
+
}
|
|
81
|
+
const result = advance({
|
|
82
|
+
root: targetRoot,
|
|
83
|
+
slug,
|
|
84
|
+
runGate: (gateArgv) => {
|
|
85
|
+
console.log(`Rodando o gate da etapa: forja ${gateArgv.join(' ')}\n`);
|
|
86
|
+
const res = spawnSync(process.execPath, [forjaBin(), ...gateArgv], { cwd: targetRoot, encoding: 'utf8' });
|
|
87
|
+
const output = `${res.stdout || ''}${res.stderr || ''}`;
|
|
88
|
+
process.stdout.write(output);
|
|
89
|
+
return { code: res.status ?? 1, output };
|
|
90
|
+
},
|
|
91
|
+
});
|
|
92
|
+
if (!result.advanced && result.finished) {
|
|
93
|
+
console.log('\nA corrida já estava concluída.');
|
|
94
|
+
return;
|
|
95
|
+
}
|
|
96
|
+
if (!result.advanced) {
|
|
97
|
+
console.log(`\nBLOQUEADO — a etapa "${result.stage.id}" não avança: ${result.stage.verdict}.`);
|
|
98
|
+
console.log('A máquina não pula etapa. Corrija o que o gate apontou e rode advance de novo.');
|
|
99
|
+
process.exit(1);
|
|
100
|
+
}
|
|
101
|
+
console.log(`\n✓ etapa "${result.stage.id}" fechada (gate verde).`);
|
|
102
|
+
if (result.finished) {
|
|
103
|
+
console.log('Corrida CONCLUÍDA — todas as transições passaram pelos gates.');
|
|
104
|
+
return;
|
|
105
|
+
}
|
|
106
|
+
console.log(`▶ etapa aberta: "${result.next.id}" (dono: ${result.next.owner}).`);
|
|
107
|
+
registerHandoff(slug, state.goal, chainFor(slug).findIndex((s) => s.id === result.next.id));
|
|
108
|
+
return;
|
|
109
|
+
}
|
|
110
|
+
// start: forja orchestrate "<objetivo>" --slug <slug> (o dispatcher injeta o modo 'start').
|
|
111
|
+
// Parse POSICIONAL: `--slug` consome o próximo token; o resto é o objetivo. Filtrar por valor
|
|
112
|
+
// corromperia objetivos que contêm a palavra do slug (objetivo "pix" + --slug pix → vazio).
|
|
113
|
+
const tokens = mode === 'start' ? argv : [mode, ...argv];
|
|
114
|
+
let slug = null;
|
|
115
|
+
const goalWords = [];
|
|
116
|
+
for (let i = 0; i < tokens.length; i += 1) {
|
|
117
|
+
if (tokens[i] === '--slug') {
|
|
118
|
+
slug = tokens[i + 1] ?? null;
|
|
119
|
+
i += 1;
|
|
120
|
+
continue;
|
|
121
|
+
}
|
|
122
|
+
goalWords.push(tokens[i]);
|
|
123
|
+
}
|
|
124
|
+
const goal = goalWords.join(' ').trim();
|
|
125
|
+
if (!slug || !goal) {
|
|
126
|
+
console.error('Uso: forja orchestrate "<objetivo>" --slug <slug>');
|
|
127
|
+
process.exit(1);
|
|
128
|
+
}
|
|
129
|
+
const state = startRun({ root: targetRoot, slug, goal });
|
|
130
|
+
console.log(`Corrida aberta: ${slug} — ${goal}`);
|
|
131
|
+
console.log(`Cadeia: ${state.stages.map((s) => s.id).join(' → ')} (cada transição guardada por gate)\n`);
|
|
132
|
+
console.log(`▶ etapa aberta: "${state.stages[0].id}" (dono: ${state.stages[0].owner}).`);
|
|
133
|
+
registerHandoff(slug, goal, 0);
|
|
134
|
+
console.log(`\nEstado: .context/orchestrate-${slug}.json · status: forja orchestrate:status ${slug}`);
|
|
135
|
+
}
|
|
136
|
+
main();
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# ADR-0031: O motor de orquestração — a cadeia como máquina de estados guardada por gates
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-22
|
|
5
|
+
- **Autor(es)**: apk
|
|
6
|
+
- **Tags**: orchestration, gates, sdd, gsd
|
|
7
|
+
|
|
8
|
+
## Contexto
|
|
9
|
+
|
|
10
|
+
O nome do framework é orquestração multiagente. A SPEC-019 tornou a topologia *coerente*
|
|
11
|
+
(`agent-topology`), mas coerência não é execução: um fluxo multi-papel vivia em handoffs avulsos e
|
|
12
|
+
na disciplina de quem lembra de rodar os checks entre etapas. Não existia uma cadeia que **roda**,
|
|
13
|
+
gate a gate — o namesake era a última grande superfície por disciplina.
|
|
14
|
+
|
|
15
|
+
A tensão central: **o framework não executa IA autonomamente.** Quem faz o trabalho de cada etapa é
|
|
16
|
+
um agente (sub-agent do Claude Code, outra IA, ou um humano) que pega o handoff.
|
|
17
|
+
|
|
18
|
+
## Decisão
|
|
19
|
+
|
|
20
|
+
O motor é a **máquina de estados da cadeia de handoffs, com transições guardadas por gates** — e
|
|
21
|
+
nada mais (SPEC-021):
|
|
22
|
+
|
|
23
|
+
- `forja orchestrate "<objetivo>" --slug <s>` decompõe na cadeia SDD/GSD determinística
|
|
24
|
+
(spec→plan→tasks→implement→review), abre a 1ª etapa e registra o handoff ADR-0005 do dono.
|
|
25
|
+
- `forja orchestrate:advance <s>` fecha a etapa **só se** (1) o artefato SDD da etapa existe e está
|
|
26
|
+
aprovado e (2) o gate da transição sai verde (`spec:check` / `project:check` / `check:all`).
|
|
27
|
+
Vermelho → a corrida trava com o parecer. Verde → abre a próxima e registra o handoff.
|
|
28
|
+
- Estado em `<cwd>/.context/orchestrate-<slug>.json`; roda onde for invocado (framework como
|
|
29
|
+
dogfood; projetos consumidores por construção, graças ao cwd propagado da v1.6.2).
|
|
30
|
+
|
|
31
|
+
**O framework orquestra e guarda; o agente executa.** Honesto (não finge autonomia de IA) e ainda
|
|
32
|
+
assim um motor real: a cadeia progride por veredito de gate, não por memória.
|
|
33
|
+
|
|
34
|
+
## Alternativas consideradas
|
|
35
|
+
|
|
36
|
+
- **Acionar o sub-agent automaticamente no advance** — adiada: mais mágica, mais acoplamento ao
|
|
37
|
+
Claude Code (fere a promessa multi-IA); será decidida com os dados do uso manual (candidata a 2.0).
|
|
38
|
+
- **Decomposição por LLM (cadeia sob medida)** — adiada: v1 é determinística, provável e auditável.
|
|
39
|
+
- **Só documentar o fluxo (status quo)** — rejeitada: é a "regra que depende de memória" (ADR-0021).
|
|
40
|
+
|
|
41
|
+
## Consequências
|
|
42
|
+
|
|
43
|
+
**Positivas**:
|
|
44
|
+
- Pular etapa é **bloqueado pela máquina** (provado: sem artefato o gate nem roda; draft não passa).
|
|
45
|
+
- Compõe o que existe: spec-cli, agent-router (7 campos), os gates, a auditoria — zero reimplementação.
|
|
46
|
+
- A corrida inteira é reconstruível: estado + handoffs + `forja-runs.jsonl`.
|
|
47
|
+
|
|
48
|
+
**Negativas / Trade-offs**:
|
|
49
|
+
- `advance` manual: o motor não empurra ninguém — cobra quando alguém tenta avançar. É o v1 honesto.
|
|
50
|
+
- Cadeia fixa: features fora do formato SDD (hotfix, chore) não precisam do motor — e não devem usá-lo.
|
|
51
|
+
|
|
52
|
+
## Rastreamento
|
|
53
|
+
- Implementação: `lib/orchestrate.ts`, `scripts/orchestrate.ts`, `test/orchestrate.test.js`
|
|
54
|
+
- Spec: `specs/orchestrate/spec.md` (SPEC-021)
|
|
55
|
+
- ADRs relacionadas: ADR-0005 (handoffs), ADR-0020 (registry), ADR-0021 (invariante > disciplina), SPEC-019 (topologia)
|
package/package.json
CHANGED
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
# Spec: orchestrate — o motor de orquestração (exploratória, 2.0)
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-021
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **ADRs relacionadas**: ADR-0005 (handoff 7 campos), ADR-0019 (workspace), ADR-0020 (core/registry), SPEC-019 (topologia coerente), ADR-0023/0024/0029 (os gates), ADR-0009 (memória)
|
|
7
|
+
|
|
8
|
+
> **Exploratória.** O objetivo desta spec não é fechar o escopo — é tornar o conceito concreto o
|
|
9
|
+
> bastante para decidir o formato, e expor as decisões duras antes de virar plano. As perguntas
|
|
10
|
+
> abertas da §8 são o coração; as respostas remodelam o resto.
|
|
11
|
+
|
|
12
|
+
## 1. Problema
|
|
13
|
+
|
|
14
|
+
O nome do framework é **orquestração multiagente**. A SPEC-019 provou que a topologia é *coerente* —
|
|
15
|
+
mas orquestração coerente não é orquestração que **acontece**. Hoje um fluxo multi-papel (product →
|
|
16
|
+
architect → worker → governance) vive em três lugares soltos: a prosa do `AGENTS.md`, os handoffs
|
|
17
|
+
avulsos do `agent-router` (cada um independente, sem noção de cadeia), e a disciplina de quem lembra
|
|
18
|
+
de rodar `spec:check` entre uma etapa e outra. **Não existe uma cadeia que roda, gate a gate.** O
|
|
19
|
+
namesake é a última grande superfície que ainda vive por disciplina.
|
|
20
|
+
|
|
21
|
+
## 2. A tensão central (a decisão que organiza tudo)
|
|
22
|
+
|
|
23
|
+
**O framework não roda IA autonomamente.** Ele não pode "chamar o Claude e mandar implementar". Quem
|
|
24
|
+
executa o *trabalho* de cada papel é um agente de IA (sub-agent do Claude Code) ou um humano.
|
|
25
|
+
|
|
26
|
+
Então "orquestração que executa" **não** pode significar "o framework faz o trabalho". Significa:
|
|
27
|
+
|
|
28
|
+
> O framework é a **máquina de estados da cadeia de handoffs**, com **transições guardadas por
|
|
29
|
+
> gates**. Ele decompõe o objetivo, abre o handoff certo, roda o gate quando a etapa fecha, e — se o
|
|
30
|
+
> gate passa — abre a próxima; se falha, trava com o parecer. O *trabalho* dentro de cada etapa é de
|
|
31
|
+
> quem pega o handoff. **O framework orquestra e guarda; o agente executa.**
|
|
32
|
+
|
|
33
|
+
Isto é honesto (não finge autonomia de IA) e ainda assim é um motor de execução real: a cadeia
|
|
34
|
+
progride dirigida por **veredito de gate**, não por memória. É o pipeline SDD/GSD virado máquina.
|
|
35
|
+
|
|
36
|
+
## 3. Proposta de valor
|
|
37
|
+
|
|
38
|
+
Um objetivo vira uma **cadeia auditável e guardada**: cada etapa só abre quando a anterior passou no
|
|
39
|
+
seu gate. A pergunta "o processo foi seguido?" deixa de ser uma promessa e vira o estado de uma
|
|
40
|
+
máquina — e a governança do Forja chega ao próprio ato de orquestrar.
|
|
41
|
+
|
|
42
|
+
## 4. Formato proposto (v1 — a discutir)
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
forja orchestrate "adicionar pagamento pix" --slug pagamentos-pix
|
|
46
|
+
# → decompõe numa cadeia de handoffs (o runbook), abre a 1ª etapa
|
|
47
|
+
|
|
48
|
+
forja orchestrate:status pagamentos-pix
|
|
49
|
+
# → o estado da máquina: etapa aberta, feitas, bloqueadas, último veredito de gate
|
|
50
|
+
|
|
51
|
+
forja orchestrate:advance pagamentos-pix
|
|
52
|
+
# → o dono da etapa atual fez o trabalho; roda o GATE da etapa;
|
|
53
|
+
# verde → fecha o handoff + abre o próximo; vermelho → trava com o parecer
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
**A cadeia (v1, determinística — o pipeline SDD/GSD):**
|
|
57
|
+
|
|
58
|
+
| # | Papel | Etapa | Gate da transição |
|
|
59
|
+
|---|---|---|---|
|
|
60
|
+
| 1 | product | `spec` | `spec:check` (spec aprovada) |
|
|
61
|
+
| 2 | sdd-architect | `plan` | `spec:check` (plan aprovado) |
|
|
62
|
+
| 3 | sdd-architect | `tasks` | `spec:check` (tasks aprovado) |
|
|
63
|
+
| 4 | worker | `implement` | `project:check` / `code:check` |
|
|
64
|
+
| 5 | governance | `review` | `check:all` |
|
|
65
|
+
|
|
66
|
+
Cada transição é um handoff ADR-0005 (7 campos) gravado pelo `agent-router`, e cada `advance` é uma
|
|
67
|
+
linha na trilha de auditoria. A topologia coerente da SPEC-019 é o grafo que a máquina percorre.
|
|
68
|
+
|
|
69
|
+
## 5. Escopo
|
|
70
|
+
|
|
71
|
+
**Dentro (v1)**:
|
|
72
|
+
- A máquina de estados da cadeia (decompor → abrir → gate → avançar/travar), sobre o `agent-router`.
|
|
73
|
+
- Gates como transições: a etapa não avança sem o gate verde.
|
|
74
|
+
- `orchestrate` / `orchestrate:status` / `orchestrate:advance` no registry; tudo auditado.
|
|
75
|
+
|
|
76
|
+
**Fora (explícito — a fronteira honesta)**:
|
|
77
|
+
- **Rodar a IA que faz o trabalho de cada etapa.** Isso é o Claude Code (ou o humano) que pega o
|
|
78
|
+
handoff aberto. O framework abre a etapa e a guarda; não a executa.
|
|
79
|
+
- **Decomposição por LLM.** v1 usa a cadeia determinística do SDD/GSD — provável e auditável. Um
|
|
80
|
+
planejador de IA que monta cadeias sob medida é evolução, não a base.
|
|
81
|
+
- Paralelismo / cadeias ramificadas — v1 é linear. Ramos e fan-out ficam para depois.
|
|
82
|
+
|
|
83
|
+
## 6. Riscos
|
|
84
|
+
|
|
85
|
+
| Risco | Prob. | Impacto | Mitigação |
|
|
86
|
+
|---|---|---|---|
|
|
87
|
+
| Virar "só um wrapper do agent-router + gates" (pouco valor) | M | A | o valor é a **transição guardada** — a etapa que não avança sem o gate; isso não existe hoje |
|
|
88
|
+
| Acoplar ao Claude Code e ferir a promessa multi-IA | M | M | o motor é agnóstico: abre handoffs; *quem* os pega (Claude/humano/outra IA) é externo |
|
|
89
|
+
| Reimplementar o que o SDD já faz | B | M | compõe `spec:check`/`project:check`/`check:all` — não reimplementa gate nenhum |
|
|
90
|
+
|
|
91
|
+
## 7. Métricas de sucesso
|
|
92
|
+
|
|
93
|
+
Um objetivo levado do `orchestrate` até o `review` com **cada transição guardada por um gate verde**,
|
|
94
|
+
a corrida inteira reconstruível a partir do `forja-runs.jsonl` — e uma tentativa de pular etapa
|
|
95
|
+
(avançar com o gate vermelho) **bloqueada** pela máquina. A orquestração deixa de ser prosa.
|
|
96
|
+
|
|
97
|
+
## 8. Decisões (aprovadas)
|
|
98
|
+
|
|
99
|
+
1. **`advance` manual.** O dono da etapa roda `orchestrate:advance` quando terminou; o motor roda o
|
|
100
|
+
gate e decide. Acionar o sub-agent automaticamente fica para uma iteração futura — decidida com os
|
|
101
|
+
dados do uso manual.
|
|
102
|
+
2. **Roda onde é invocado (`cwd`).** Framework primeiro como dogfood; por construção da 1.6.2 (o
|
|
103
|
+
dispatcher propaga o cwd), o mesmo motor funciona num projeto consumidor sem código extra. O
|
|
104
|
+
estado vive em `<cwd>/.context/orchestrate-<slug>.json`, ao lado dos runbooks GSD.
|
|
105
|
+
3. **Cadeia determinística SDD/GSD no v1.** Auditável e provável. Planejador de IA é evolução.
|
|
106
|
+
4. **O motor é a v1.7.0** (aditivo, não quebra nada). O 2.0 fica para a limpeza breaking
|
|
107
|
+
(`dashboard/`, `projects/`, Node ≥22.6 formal) + o salto de identidade escolhido com os dados do
|
|
108
|
+
motor em uso.
|