forjajs 1.6.1 → 1.7.0
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 +41 -0
- package/README.en.md +8 -5
- package/README.md +7 -5
- package/dist/bin/forja.js +7 -2
- 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 +40 -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/orchestrate.d.ts +12 -0
- package/dist/scripts/orchestrate.js +136 -0
- package/dist/scripts/spec-cli.d.ts +12 -0
- package/dist/scripts/spec-cli.js +30 -9
- 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,47 @@ Histórico consolidado das mudanças estruturais do framework. Para decisões ar
|
|
|
4
4
|
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
+
## [1.7.0] — 2026-07-22 — O motor de orquestração: o namesake executando
|
|
8
|
+
|
|
9
|
+
O nome do framework sempre foi orquestração multiagente; até aqui, a topologia era coerente
|
|
10
|
+
(SPEC-019) mas o fluxo vivia por disciplina. Esta release o faz **rodar**.
|
|
11
|
+
|
|
12
|
+
### Adicionado
|
|
13
|
+
- **`orchestrate` / `orchestrate:status` / `orchestrate:advance`** (SPEC-021, ADR-0031): a cadeia
|
|
14
|
+
SDD/GSD (spec→plan→tasks→implement→review) como **máquina de estados guardada por gates**. Cada
|
|
15
|
+
etapa abre com um handoff ADR-0005 para o dono do papel; `advance` só fecha a etapa se o artefato
|
|
16
|
+
SDD estiver aprovado **e** o gate da transição sair verde — pular etapa é bloqueado pela máquina,
|
|
17
|
+
não pela memória. O framework orquestra e guarda; o agente (IA ou humano) executa. Estado em
|
|
18
|
+
`<cwd>/.context/orchestrate-<slug>.json`; roda no framework e em projetos consumidores.
|
|
19
|
+
- `commands-documented` ganha fallback para comandos **sem dois-pontos** (grep literal de nome
|
|
20
|
+
conhecido) — `orchestrate` é o primeiro do registry.
|
|
21
|
+
|
|
22
|
+
### Corrigido
|
|
23
|
+
- **Backend gerado compila em Node 26**: o template pinava `better-sqlite3 ^11` (sem prebuild para
|
|
24
|
+
Node novo); alinhado ao do framework (`^12`). Fecha o caveat da v1.6.0 — `check:all --full` verde.
|
|
25
|
+
- **Roadmap defasado**: o `release-auditor` já consumia o gate (ADR-0024); refresh da tabela
|
|
26
|
+
(+ `consumer-spec-new`) e checkboxes marcados nos READMEs.
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## [1.6.2] — 2026-07-21 — Correção: `spec:new` em projetos consumidores
|
|
31
|
+
|
|
32
|
+
### Corrigido
|
|
33
|
+
- **`forja spec:new` num projeto consumidor escrevia a spec DENTRO de `node_modules/forjajs/dist`**
|
|
34
|
+
e falhava com "template ausente". Duas causas: o dispatcher spawnava os filhos com `cwd` = raiz do
|
|
35
|
+
pacote (agora usa o cwd de quem invocou — uma CLI opera onde é chamada), e o `spec-cli` resolvia
|
|
36
|
+
templates e destino por uma raiz só (agora separa `pkgRoot`, de onde vêm os templates, de
|
|
37
|
+
`targetRoot`, onde as specs nascem). Framework inalterado.
|
|
38
|
+
- Sem `.gitignore` ou sem bloco de allowlist: silêncio em vez de aviso — num consumidor esse é o
|
|
39
|
+
estado saudável (specs versionadas normalmente).
|
|
40
|
+
|
|
41
|
+
### Adicionado
|
|
42
|
+
- **Gate `consumer-spec-new`** no `release:check`: roda `spec:new` na instalação limpa e reprova se a
|
|
43
|
+
spec não nascer no projeto do consumidor ou vazar para dentro do pacote. O smoke pegava "não
|
|
44
|
+
carrega"; este pega "opera no mundo errado".
|
|
45
|
+
|
|
46
|
+
---
|
|
47
|
+
|
|
7
48
|
## [1.6.1] — 2026-07-20 — Correção: `project:upgrade` no pacote publicado
|
|
8
49
|
|
|
9
50
|
### 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.
|
package/dist/bin/forja.js
CHANGED
|
@@ -108,16 +108,21 @@ if (gateErrors.length) {
|
|
|
108
108
|
}
|
|
109
109
|
const started = Date.now();
|
|
110
110
|
let result;
|
|
111
|
+
// Os filhos rodam ONDE O USUÁRIO INVOCOU, não na raiz do pacote. `cwd: root` funcionava por
|
|
112
|
+
// coincidência no repo do framework (invoca-se da raiz), mas no pacote instalado `root` é
|
|
113
|
+
// `node_modules/forjajs/dist` — e comandos que operam no projeto do usuário (spec:new) escreviam
|
|
114
|
+
// DENTRO do pacote (bug da v1.6.1). Scripts do framework não dependem de cwd: resolvem seus paths
|
|
115
|
+
// por __dirname (repo) ou pelo workspace (absoluto).
|
|
111
116
|
if (cmd.node) {
|
|
112
117
|
const script = resolveScript(root, cmd.node);
|
|
113
118
|
result = spawnSync('node', [script, ...(cmd.args || []), ...rest], {
|
|
114
|
-
cwd:
|
|
119
|
+
cwd: process.cwd(),
|
|
115
120
|
stdio: 'inherit',
|
|
116
121
|
});
|
|
117
122
|
}
|
|
118
123
|
else {
|
|
119
124
|
result = spawnSync(cmd.bin, [...(cmd.args || []), ...rest], {
|
|
120
|
-
cwd:
|
|
125
|
+
cwd: process.cwd(),
|
|
121
126
|
stdio: 'inherit',
|
|
122
127
|
});
|
|
123
128
|
if (result.error && result.error.code === 'ENOENT') {
|
|
@@ -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
|
@@ -394,12 +394,52 @@ const smokeCommands = {
|
|
|
394
394
|
};
|
|
395
395
|
},
|
|
396
396
|
};
|
|
397
|
+
/**
|
|
398
|
+
* O bug da v1.6.1, generalizado: um comando pode CARREGAR limpo (o smoke passa) e ainda assim operar
|
|
399
|
+
* no mundo errado — `spec:new` escrevia dentro de `node_modules/forjajs/dist` e não achava os
|
|
400
|
+
* templates, porque resolvia tudo por `__dirname` e o dispatcher impunha `cwd` = raiz do pacote.
|
|
401
|
+
* Nenhuma assinatura de loader denuncia isso; só EXECUTAR o comando no mundo do consumidor e conferir
|
|
402
|
+
* ONDE o efeito aconteceu. É o smoke, um degrau acima: de "carrega" para "opera no lugar certo".
|
|
403
|
+
* O efeito colateral fica contido no installDir temporário, que é limpo sempre.
|
|
404
|
+
*/
|
|
405
|
+
const consumerSpecNew = {
|
|
406
|
+
id: 'consumer-spec-new',
|
|
407
|
+
title: 'spec:new opera no projeto do consumidor, não dentro do pacote',
|
|
408
|
+
severity: 'critical',
|
|
409
|
+
dependsOn: 'install',
|
|
410
|
+
probe(env) {
|
|
411
|
+
const pkg = JSON.parse(env.fs.readFileSync(path.join(env.pkgDir, 'package.json'), 'utf8'));
|
|
412
|
+
const binRel = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.forja;
|
|
413
|
+
const bin = path.join(env.pkgDir, binRel);
|
|
414
|
+
const res = env.spawn(process.execPath, [bin, 'spec:new', 'smoke-consumer-spec'], { cwd: env.installDir });
|
|
415
|
+
const noProjeto = env.fs.existsSync(path.join(env.installDir, 'specs', 'smoke-consumer-spec', 'spec.md'));
|
|
416
|
+
const dentroDoPacote = env.fs.existsSync(path.join(env.pkgDir, 'specs', 'smoke-consumer-spec'))
|
|
417
|
+
|| env.fs.existsSync(path.join(env.pkgDir, 'dist', 'specs', 'smoke-consumer-spec'));
|
|
418
|
+
if (dentroDoPacote) {
|
|
419
|
+
return {
|
|
420
|
+
status: 'fail',
|
|
421
|
+
detail: 'spec:new escreveu DENTRO de node_modules/forjajs — o comando opera no mundo errado',
|
|
422
|
+
fix: 'o dispatcher deve spawnar com o cwd do usuário e o spec-cli separar pkgRoot de targetRoot',
|
|
423
|
+
};
|
|
424
|
+
}
|
|
425
|
+
if (!noProjeto) {
|
|
426
|
+
const saida = `${res.stdout || ''}${res.stderr || ''}`.trim().split('\n')[0] || 'sem saída';
|
|
427
|
+
return {
|
|
428
|
+
status: 'fail',
|
|
429
|
+
detail: `spec:new não criou a spec no projeto do consumidor: ${saida}`,
|
|
430
|
+
fix: 'confira a resolução dos templates (pkgRoot) e do destino (cwd) no spec-cli',
|
|
431
|
+
};
|
|
432
|
+
}
|
|
433
|
+
return { status: 'ok', detail: 'spec criada no projeto do consumidor; templates do pacote resolvem', fix: null };
|
|
434
|
+
},
|
|
435
|
+
};
|
|
397
436
|
/** @type {import('./checks.ts').Check[]} */
|
|
398
437
|
export const RELEASE_CHECKS = [
|
|
399
438
|
treeClean,
|
|
400
439
|
install,
|
|
401
440
|
registryScripts,
|
|
402
441
|
smokeCommands,
|
|
442
|
+
consumerSpecNew,
|
|
403
443
|
importsResolve,
|
|
404
444
|
depsDeclared,
|
|
405
445
|
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
|
+
}
|
|
@@ -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();
|
|
@@ -12,6 +12,18 @@
|
|
|
12
12
|
* - feature-slug em kebab-case
|
|
13
13
|
* - status na frontmatter-like "- **Status**: ..." linha 3
|
|
14
14
|
*/
|
|
15
|
+
import fs from 'node:fs';
|
|
16
|
+
/**
|
|
17
|
+
* Duas raízes, de propósito (bug da v1.6.1: eram uma só, e no pacote instalado tudo apontava para
|
|
18
|
+
* `node_modules/forjajs/dist` — spec:new escrevia DENTRO do pacote e não achava os templates):
|
|
19
|
+
*
|
|
20
|
+
* - `pkgRoot` → de onde vêm os TEMPLATES. No dev é a raiz do repo (`scripts/..`); no publicado os
|
|
21
|
+
* templates viajam na raiz do pacote, um nível acima do `dist/` (`dist/scripts/../..`). O probe
|
|
22
|
+
* acha qual das duas tem `specs/_templates` de verdade.
|
|
23
|
+
* - `targetRoot` → onde as SPECS nascem: o projeto de quem invocou (`process.cwd()`, propagado pelo
|
|
24
|
+
* dispatcher). No repo do framework, cwd é a raiz do repo — comportamento inalterado.
|
|
25
|
+
*/
|
|
26
|
+
export declare function resolvePkgRoot(scriptDir: string, fsImpl?: typeof fs): string;
|
|
15
27
|
/**
|
|
16
28
|
* `.gitignore` ignora `/specs/*` e libera as specs do framework por allow-list. Uma spec nova
|
|
17
29
|
* nascia invisível ao git: criada, aprovada pelo check, e descartada em silêncio. A regra existia
|
package/dist/scripts/spec-cli.js
CHANGED
|
@@ -18,9 +18,27 @@ import process from 'node:process';
|
|
|
18
18
|
import { fileURLToPath } from 'node:url';
|
|
19
19
|
const __filename = fileURLToPath(import.meta.url);
|
|
20
20
|
const __dirname = path.dirname(__filename);
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
21
|
+
/**
|
|
22
|
+
* Duas raízes, de propósito (bug da v1.6.1: eram uma só, e no pacote instalado tudo apontava para
|
|
23
|
+
* `node_modules/forjajs/dist` — spec:new escrevia DENTRO do pacote e não achava os templates):
|
|
24
|
+
*
|
|
25
|
+
* - `pkgRoot` → de onde vêm os TEMPLATES. No dev é a raiz do repo (`scripts/..`); no publicado os
|
|
26
|
+
* templates viajam na raiz do pacote, um nível acima do `dist/` (`dist/scripts/../..`). O probe
|
|
27
|
+
* acha qual das duas tem `specs/_templates` de verdade.
|
|
28
|
+
* - `targetRoot` → onde as SPECS nascem: o projeto de quem invocou (`process.cwd()`, propagado pelo
|
|
29
|
+
* dispatcher). No repo do framework, cwd é a raiz do repo — comportamento inalterado.
|
|
30
|
+
*/
|
|
31
|
+
export function resolvePkgRoot(scriptDir, fsImpl = fs) {
|
|
32
|
+
for (const cand of [path.resolve(scriptDir, '..'), path.resolve(scriptDir, '..', '..')]) {
|
|
33
|
+
if (fsImpl.existsSync(path.join(cand, 'specs', '_templates')))
|
|
34
|
+
return cand;
|
|
35
|
+
}
|
|
36
|
+
return path.resolve(scriptDir, '..');
|
|
37
|
+
}
|
|
38
|
+
const pkgRoot = resolvePkgRoot(__dirname);
|
|
39
|
+
const targetRoot = process.cwd();
|
|
40
|
+
const specsDir = path.join(targetRoot, 'specs');
|
|
41
|
+
const templatesDir = path.join(pkgRoot, 'specs', '_templates');
|
|
24
42
|
const STAGES = ['spec', 'plan', 'tasks'];
|
|
25
43
|
const STATUS_RE = /-\s*\*\*Status\*\*:\s*([a-z]+)[^\n]*/i;
|
|
26
44
|
const VALID_STATUSES = ['draft', 'review', 'approved', 'implementing', 'done', 'abandoned'];
|
|
@@ -98,9 +116,14 @@ export function addSpecToAllowlist(content, slug) {
|
|
|
98
116
|
return { changed: true, content: lines.join('\n'), reason: 'added' };
|
|
99
117
|
}
|
|
100
118
|
function gitignorePath() {
|
|
101
|
-
return process.env.FORJA_GITIGNORE || path.join(
|
|
119
|
+
return process.env.FORJA_GITIGNORE || path.join(targetRoot, '.gitignore');
|
|
102
120
|
}
|
|
103
|
-
/**
|
|
121
|
+
/**
|
|
122
|
+
* Efeito colateral de `spec:new`. Nunca derruba a criação da spec — criar a spec é o trabalho.
|
|
123
|
+
* A allowlist `!/specs/<slug>` só existe no repo do FRAMEWORK (que ignora `/specs/*` por padrão).
|
|
124
|
+
* Num projeto consumidor não há bloco — e isso é o estado saudável: specs são versionadas
|
|
125
|
+
* normalmente. Por isso "sem .gitignore" e "sem bloco" são silêncio, não aviso.
|
|
126
|
+
*/
|
|
104
127
|
function ensureSpecVersioned(slug) {
|
|
105
128
|
const file = gitignorePath();
|
|
106
129
|
let raw;
|
|
@@ -108,13 +131,11 @@ function ensureSpecVersioned(slug) {
|
|
|
108
131
|
raw = fs.readFileSync(file, 'utf8');
|
|
109
132
|
}
|
|
110
133
|
catch {
|
|
111
|
-
|
|
112
|
-
return;
|
|
134
|
+
return; // sem .gitignore — nada a ajustar
|
|
113
135
|
}
|
|
114
136
|
const result = addSpecToAllowlist(raw, slug);
|
|
115
137
|
if (result.reason === 'no-block') {
|
|
116
|
-
|
|
117
|
-
return;
|
|
138
|
+
return; // sem bloco de allowlist — specs não são ignoradas; nada a fazer
|
|
118
139
|
}
|
|
119
140
|
if (!result.changed)
|
|
120
141
|
return;
|
|
@@ -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.
|