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.
@@ -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 testa os projetos *gerados* pelos boilerplates, não
49
- valida proveniência de pacote e não julga se a versão do `package.json` faz sentido para o que
50
- mudou. Se algo disso importa nesta release, diga.
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
- - [ ] **Generated backend `builds` under new toolchains** — `check:all --full` flags that
309
- `better-sqlite3` won't compile on very new Node (no prebuild); pin the version or document the build
310
- requirement.
311
- - [ ] **`release-auditor` consumes the gate** — the third surface from ADR-0024: the agent runs
312
- `release:check` instead of reimplementing the procedure in prose.
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
- - [ ] **`builds` do backend gerado sob toolchain novo** — o `check:all --full` flagra que o
297
- `better-sqlite3` não compila em Node muito novo (sem prebuild); fixar a versão ou documentar o
298
- requisito de build.
299
- - [ ] **`release-auditor` consome o gate** — a terceira superfície do ADR-0024: o agente roda
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;
@@ -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
- const orfaos = Object.keys(COMMANDS).filter((c) => !citados.has(c));
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;
@@ -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.8.1",
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
- const __filename = fileURLToPath(import.meta.url);
6
- const __dirname = path.dirname(__filename);
7
- const root = path.resolve(__dirname, '..');
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "forjajs",
3
- "version": "1.6.2",
3
+ "version": "1.7.1",
4
4
  "description": "Forja — framework CLI-first de orquestração multiagente, memória hierárquica e geração de projetos com IA",
5
5
  "type": "module",
6
6
  "main": "index.js",
@@ -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.