forjajs 4.0.0 → 4.1.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.
Files changed (94) hide show
  1. package/CHANGELOG.md +115 -0
  2. package/DOC-MAP.md +1 -0
  3. package/README.md +7 -2
  4. package/dist/apps/cli/src/index.d.ts +18 -1
  5. package/dist/apps/cli/src/index.js +161 -26
  6. package/dist/apps/cli/src/params.d.ts +44 -0
  7. package/dist/apps/cli/src/params.js +123 -0
  8. package/dist/bin/forja.js +234 -13
  9. package/dist/bin/init-project.js +11 -62
  10. package/dist/lib/cli-output.d.ts +29 -0
  11. package/dist/lib/cli-output.js +39 -0
  12. package/dist/lib/core/checks.d.ts +1 -1
  13. package/dist/lib/core/health.d.ts +9 -0
  14. package/dist/lib/core/health.js +9 -0
  15. package/dist/lib/core/project-smoke.d.ts +6 -2
  16. package/dist/lib/core/project-smoke.js +83 -7
  17. package/dist/lib/core/registry.d.ts +38 -571
  18. package/dist/lib/core/registry.js +174 -25
  19. package/dist/lib/core/release.d.ts +1 -571
  20. package/dist/lib/core/release.js +0 -3
  21. package/dist/lib/handoffs-index.d.ts +16 -0
  22. package/dist/lib/handoffs-index.js +29 -0
  23. package/dist/lib/llm/claude-output.d.ts +8 -0
  24. package/dist/lib/llm/claude-output.js +54 -0
  25. package/dist/lib/llm/context.d.ts +22 -0
  26. package/dist/lib/llm/context.js +39 -0
  27. package/dist/lib/llm/session.d.ts +6 -1
  28. package/dist/lib/llm/session.js +12 -2
  29. package/dist/lib/multi-ai-instructions.d.ts +28 -0
  30. package/dist/lib/multi-ai-instructions.js +83 -0
  31. package/dist/lib/orchestrate.d.ts +5 -0
  32. package/dist/lib/orchestrate.js +18 -0
  33. package/dist/lib/specs-index.d.ts +20 -0
  34. package/dist/lib/specs-index.js +51 -0
  35. package/dist/lib/sprint-index.d.ts +15 -0
  36. package/dist/lib/sprint-index.js +34 -0
  37. package/dist/lib/status-model.d.ts +64 -0
  38. package/dist/lib/status-model.js +180 -0
  39. package/dist/packages/evals/src/index.d.ts +2 -0
  40. package/dist/packages/evals/src/index.js +21 -0
  41. package/dist/packages/llm/src/index.d.ts +24 -3
  42. package/dist/packages/llm/src/index.js +51 -5
  43. package/dist/scripts/cost-economy.js +12 -10
  44. package/dist/scripts/drift-check.d.ts +2 -0
  45. package/dist/scripts/drift-check.js +57 -1
  46. package/dist/scripts/engineer.js +7 -4
  47. package/dist/scripts/forja-setup.d.ts +14 -0
  48. package/dist/scripts/forja-setup.js +58 -0
  49. package/dist/scripts/forja-status.d.ts +11 -0
  50. package/dist/scripts/forja-status.js +70 -0
  51. package/dist/scripts/hook-session-start.js +20 -46
  52. package/dist/scripts/llm-fit.js +113 -8
  53. package/dist/scripts/project-smoke.js +13 -3
  54. package/dist/scripts/simulate.js +18 -6
  55. package/dist/scripts/token-economy.js +34 -28
  56. package/dist/scripts/tools-doctor.js +14 -6
  57. package/docs/2x/CLI-CAPABILITIES.md +34 -10
  58. package/docs/agent-operating-contract.md +1 -1
  59. package/docs/cli-first-operacao.md +17 -0
  60. package/docs/contrato-saida-cli.md +79 -0
  61. package/docs/llm-evolution.md +2 -1
  62. package/docs/llm-fit-loop.md +74 -2
  63. package/docs/quick-reference.md +13 -0
  64. package/docs/roadmap-v4.1.md +199 -0
  65. package/memory/90-decisions/0082-contrato-saida-cli.md +95 -0
  66. package/memory/90-decisions/0083-mcp-cobertura-declarativa.md +103 -0
  67. package/memory/90-decisions/0084-drift-sentinel-fecha.md +79 -0
  68. package/memory/90-decisions/0085-adaptador-claude-paridade.md +85 -0
  69. package/package.json +4 -1
  70. package/specs/cli-intuitiva-v1/plan.md +169 -0
  71. package/specs/cli-intuitiva-v1/spec.md +163 -0
  72. package/specs/cli-intuitiva-v1/tasks.md +224 -0
  73. package/specs/contrato-saida-cli/plan.md +162 -0
  74. package/specs/contrato-saida-cli/spec.md +157 -0
  75. package/specs/contrato-saida-cli/tasks.md +153 -0
  76. package/specs/drift-sentinel/spec.md +17 -8
  77. package/specs/forja-status-caminho-feliz/plan.md +149 -0
  78. package/specs/forja-status-caminho-feliz/spec.md +158 -0
  79. package/specs/forja-status-caminho-feliz/tasks.md +175 -0
  80. package/specs/llm-adaptador-claude/plan.md +117 -0
  81. package/specs/llm-adaptador-claude/spec.md +144 -0
  82. package/specs/llm-adaptador-claude/tasks.md +100 -0
  83. package/specs/llm-benchmark-recomendacao/plan.md +121 -0
  84. package/specs/llm-benchmark-recomendacao/spec.md +141 -0
  85. package/specs/llm-benchmark-recomendacao/tasks.md +88 -0
  86. package/specs/llm-contexto-e-sessoes/plan.md +143 -0
  87. package/specs/llm-contexto-e-sessoes/spec.md +139 -0
  88. package/specs/llm-contexto-e-sessoes/tasks.md +127 -0
  89. package/specs/mcp-cobertura-nucleo/plan.md +158 -0
  90. package/specs/mcp-cobertura-nucleo/spec.md +161 -0
  91. package/specs/mcp-cobertura-nucleo/tasks.md +169 -0
  92. package/specs/projeto-gerado-confiavel/plan.md +148 -0
  93. package/specs/projeto-gerado-confiavel/spec.md +142 -0
  94. package/specs/projeto-gerado-confiavel/tasks.md +139 -0
@@ -0,0 +1,158 @@
1
+ # Plan: mcp-cobertura-nucleo
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Status**: approved
5
+ - **Criado em**: 2026-09-08
6
+
7
+ > Como vamos construir o que a spec define. Sem código aqui — só estrutura e decisões.
8
+
9
+ ## 1. Abordagem técnica
10
+
11
+ **Uma fonte para o mapeamento argv↔payload, e um adaptador do envelope para o contrato.**
12
+ `apps/cli/src/params.ts` (novo) define `CapabilityParam` e duas funções puras inversas —
13
+ `parseArgv(params, argv)` e `argvFor(params, input)`. `CliCapabilitySpec` ganha `params`; o
14
+ `toArgs` de cada spec vira `argvFor(spec.params)`, e o `if/else` de `parseLegacyCommandInput`
15
+ vira `parseArgv(spec.params, argv)`. Um round-trip fixture por spec força os dois a fecharem.
16
+ Em `bin/forja.ts`, `toContract(executionResult)` traduz `{status:'succeeded'|'failed', output}`
17
+ no objeto do contrato de saída (ADR-0082) quando `--json`. Adicionar comando à cobertura passa a
18
+ ser uma entrada em `CLI_CAPABILITY_SPECS`.
19
+
20
+ ## 2. Módulos afetados
21
+
22
+ | Caminho | Mudança | Risco |
23
+ |---|---|---|
24
+ | `memory/90-decisions/0083-mcp-cobertura-declarativa.md` | **criar** — arg mapping declarativo, critério de capability, mapa envelope→contrato | B |
25
+ | `apps/cli/src/params.ts` | **criar** — `CapabilityParam`, `parseArgv`, `argvFor`, `makeValidator` (validador base a partir de `params`) | M |
26
+ | `apps/cli/src/index.ts` | editar — `CliCapabilitySpec.params`; `toArgs` = `argvFor`; `parseLegacyCommandInput` → `parseArgv` genérico; **+13 specs**; validators viram `makeValidator(params)` + checagem extra explícita onde há range | A |
27
+ | `bin/forja.ts` | editar — `toContract()`; `printExecutionResult` no modo `--json` emite o contrato; `runCapabilityCommand` sai com o exit code derivado (0/1/2) | M |
28
+ | `lib/core/registry.ts` | editar — `json: true` em `spec:check` e `tools:doctor` (D7 fechado) | B |
29
+ | `packages/mcp/src/index.ts` | editar **só se necessário** — `capabilityTool` hoje emite `payload: {type:'object'}` genérico; enriquecer com schema derivado de `params` é **stretch**, não requisito | B |
30
+ | `test/cli-params.test.js` | **criar** — round-trip `argvFor(parseArgv(argv)) === argv` para todo spec | B |
31
+ | `test/mcp-coverage.test.js` | **criar** — contagem ≥ 18; e2e `tools/call` do fluxo SDD num workspace temporário | M |
32
+ | `test/cli-output-contract.test.js` | editar — deixa de excluir `spec:check`/`tools:doctor` (passam a conformar via `toContract`) | B |
33
+ | `docs/capacidades-externas.md`, `docs/contrato-saida-cli.md`, `CHANGELOG.md` | editar — cobertura maior + envelope alinhado | B |
34
+
35
+ ## 3. Diagrama de fluxo
36
+
37
+ ```
38
+ CLI: forja <cmd> [args] [--json]
39
+ │ bin/forja.ts: capabilityIdForCommand(cmd) ≠ undefined
40
+ ├─ withoutFlag(args,'--json')
41
+ ├─ parseLegacyCommandInput(cmd, args) ── parseArgv(spec.params, args) ─► {capabilityId, payload}
42
+ ├─ executeCliCapability(runtime, id, payload) (validateInput → spawn `node bin/forja.ts <cmd>` captured)
43
+ └─ printExecutionResult(result, json)
44
+ json=false → stdout/stderr do filho, como hoje
45
+ json=true → toContract(result):
46
+ succeeded & exit 0 → {status:'ok', ...merge(stdout)} exit 0
47
+ succeeded & exit 2 → {status:'rejected', ...merge(stdout)} exit 2
48
+ failed / exit 1 → {status:'error', error:{message,code}, ...merge(stdout)} exit 1
49
+ merge(stdout): JSON objeto → espalha (colisão com `status` → vai p/ `raw`); senão `raw: "<texto>"`
50
+
51
+ MCP: tools/call <capabilityTool> → registry.execute(payload) → mesmo handler (spawn captured) → ExecutionResult
52
+ (não passa por toContract; o MCP consome o ExecutionResult, contrato próprio do protocolo)
53
+ ```
54
+
55
+ ## 4. Contratos (API/CLI/Schema)
56
+
57
+ ```ts
58
+ // apps/cli/src/params.ts
59
+ export type CapabilityParam =
60
+ | { name: string; kind: 'positional'; required?: boolean; parse?: 'string' | 'int' }
61
+ | { name: string; kind: 'flag' } // boolean: --code
62
+ | { name: string; kind: 'flag-value'; flag: string; required?: boolean; parse?: 'string' | 'int' } // --mode <v>
63
+ | { name: string; kind: 'rest' }; // resto → string (join ' ')
64
+
65
+ export function parseArgv(params: readonly CapabilityParam[], argv: readonly string[]): InputRecord;
66
+ export function argvFor(params: readonly CapabilityParam[], input: InputRecord): string[];
67
+ export function makeValidator(params: readonly CapabilityParam[]): (v: unknown) => InputRecord; // required + tipo
68
+ ```
69
+
70
+ **`CliCapabilitySpec`** ganha `readonly params: readonly CapabilityParam[]`. `toArgs` deixa de
71
+ ser campo (derivado); `validateInput` continua campo (pode ser `makeValidator(params)` ou um
72
+ wrapper que chama a base e adiciona checagem).
73
+
74
+ **`toContract(result: ExecutionResult): { json: Record<string, unknown>; exitCode: 0 | 1 | 2 }`**
75
+ em `bin/forja.ts`. Único ponto que conhece o mapa envelope→contrato (ADR-0083).
76
+
77
+ ## 5. Decisões e alternativas
78
+
79
+ **D1 — `params` declarativo, `parseArgv`/`argvFor` puros e inversos.** Rejeitado: manter `toArgs`
80
+ manual + if-chain (a causa do problema); gerar um só sentido e inferir o outro (frágil para
81
+ flags). O round-trip test é o contrato que força a consistência.
82
+
83
+ **D2 — `validateInput` continua explícito, com base gerada.** `makeValidator(params)` cobre
84
+ "required presente + tipo certo"; specs com range (`code:impact` depth 1..10) embrulham a base.
85
+ Rejeitado: derivar validação 100% de `params` — perderia os limites que já existem e são certos.
86
+
87
+ **D3 — `toContract` mora em `bin/forja.ts`, não em `apps/cli`.** É a fronteira CLI; o MCP
88
+ consome o `ExecutionResult` direto (contrato do próprio protocolo). Rejeitado: mudar
89
+ `normalizeCliResult`/`executeCliCapability` — quebraria o consumo MCP.
90
+
91
+ **D4 — `merge(stdout)` com fallback `raw`.** Se o `stdout` do filho é um objeto JSON, espalha no
92
+ resultado (o filho já pode ser `json:true` e emitir `{status:'ok',...}` — nesse caso o `status`
93
+ do filho e o do contrato coincidem). Colisão real (filho emite `status` diferente) → o `stdout`
94
+ inteiro vai para `raw` e o `status` do contrato manda. Rejeitado: sempre aninhar em `output`
95
+ (menos flat, contraria o ADR-0082).
96
+
97
+ **D5 — Conjunto fechado: 13 novos.** `spec:new/plan/tasks` (write SDD), `context:smart`,
98
+ `code:context`, `query:universal`, `engineer`, `risk:assess`, `orchestrate:status`,
99
+ `orchestrate:advance` (write+execution, `risk:'medium'`), `drift:check` (`risk:'medium'`,
100
+ timeout maior), `status`, `next`. **Fora**, com razão no ADR-0083: `orchestrate` (start — abre
101
+ corrida, efeito grande), `llm:*` (ADR-0081), `project:new`/`sprint:*`/`setup`/`workspace:init`
102
+ (mutação fora do SDD), `memory:*` de escrita, `architecture:approve` (governança).
103
+
104
+ **D6 — Ids `<domínio>.<verbo>`** seguindo os 6 atuais (`spec.validate`, `handoff.create`):
105
+ `spec.create`, `spec.plan`, `spec.tasks`, `context.smart`, `code.context`, `memory.query`,
106
+ `engineering.facade`, `risk.assess`, `orchestrate.status`, `orchestrate.advance`, `drift.check`,
107
+ `forja.status`, `forja.next`.
108
+
109
+ **D7 — `gsd:handoff` usa `kind: 'rest'`** para o `...contextParts` variádico — some do if-chain
110
+ como os outros, não fica special-case.
111
+
112
+ ADR-0083 é necessária (contrato de superfície + mudança de forma do `--json`).
113
+
114
+ ## 6. Dependências
115
+
116
+ - **SPEC-043** (`json`/`tier` no registry), **SPEC-045** (ADR-0082, contrato de saída). Branch
117
+ empilhada sobre `feat/contrato-saida-cli` (#63) → `feat/forja-status` (#62) → `feat/cli-intuitiva-v1` (#61).
118
+ - **Pacotes npm**: nenhum.
119
+ - **Migrações**: nenhuma.
120
+
121
+ ## 7. Rollout
122
+
123
+ - [ ] Feature flag: não. Aditivo (mais capabilities); o único comportamento que muda é a **forma
124
+ do `--json` de comandos-capability** — ADR-0083 + CHANGELOG.
125
+ - [ ] Migração de dados: não.
126
+ - [ ] Doc/persona: `docs/capacidades-externas.md` (cobertura), `docs/contrato-saida-cli.md`
127
+ (comandos-capability agora conformam).
128
+ - [ ] `CHANGELOG.md` `[Unreleased]`: Adicionado (13 capabilities, `params` declarativo);
129
+ Alterado/breaking (`--json` de comando-capability: envelope → contrato).
130
+
131
+ ## 8. Sinais de fracasso (kill criteria)
132
+
133
+ - Um dos 6 atuais não se expressa em `params` sem perder informação (fora `gsd:handoff`, já
134
+ previsto) → manter esse um special-case **nomeado** e declarativo para o resto; não bloquear.
135
+ - `merge(stdout)` gera colisões demais na prática → abandonar o flat, emitir
136
+ `{status, exitCode, stdout, stderr}` (ainda contrato-shaped, menos ergonômico) e seguir.
137
+ - e2e MCP do fluxo SDD fica flaky → `concurrency:false`, `FORJA_WORKSPACE` temp fixo, fixtures
138
+ mínimas; se ainda assim, reduzir o e2e a `spec.create → spec.validate` só.
139
+ - Enriquecer `capabilityTool` com schema de `params` puxa refactor no `McpServer` → é stretch,
140
+ cortar sem dó (o `validateInput` já protege).
141
+
142
+ ## Evidências e estado real
143
+
144
+ | AC | Task | Verificação |
145
+ |---|---|---|
146
+ | AC-1 | T1 | ADR-0083; `adr-refs` verde |
147
+ | AC-2 | T2, T3 | `params.ts` + `index.ts` sem `if/else` por comando |
148
+ | AC-3 | T2, T6 | `test/cli-params.test.js` round-trip para todo spec |
149
+ | AC-4 | T4 | `CLI_CAPABILITY_SPECS.length ≥ 18`; `capabilities:list` |
150
+ | AC-5 | T5 | `toContract` + `printExecutionResult`; contrato no `--json` de capability |
151
+ | AC-6 | T5, T7 | `spec:check`/`tools:doctor` `json:true`; `cli-output-contract` cobre-os |
152
+ | AC-7 | T4 | cada spec nova com `permissions`/`risk`/`categories`; `validateInput` antes do spawn |
153
+ | AC-8 | T6 | `test/mcp-coverage.test.js` — `tools/list` + `tools/call` do fluxo |
154
+ | AC-9 | T8 | bateria completa; round-trip dos 6 atuais + testes MCP existentes verdes |
155
+
156
+ - **Mudança de contrato**: `--json` de comando-capability passa do `ExecutionResult` cru para o
157
+ objeto do contrato de saída (ADR-0082/0083).
158
+ - **Hipótese, não medição**: adoção via MCP depende de agentes configurarem `mcp:start`.
@@ -0,0 +1,161 @@
1
+ # Spec: mcp-cobertura-nucleo — o núcleo do fluxo operável por MCP
2
+
3
+ - **ID**: SPEC-046
4
+ - **Status**: done
5
+ - **Owner**: apk
6
+ - **Criado em**: 2026-09-08
7
+ - **Sprint alvo**: <a definir>
8
+ - **ADRs relacionadas**: **ADR-0083** (nova — arg mapping declarativo + critério de capability +
9
+ alinhamento do envelope ao contrato de saída).
10
+ - **Origem**: `docs/roadmap-v4.1.md`, Onda 2 (W6). Fecha o débito D7 de SPEC-045.
11
+ - **Depende de**: `cli-intuitiva-v1` (SPEC-043, `json`/`tier` no registry),
12
+ `contrato-saida-cli` (SPEC-045, ADR-0082). Branch empilhada sobre `feat/contrato-saida-cli`.
13
+
14
+ ## 1. Problema
15
+
16
+ Um agente que fala com o Forja por MCP (`forja mcp:start`) enxerga **6 comandos** de ~75:
17
+ `tools:doctor`, `code:impact`, `context:budget`, `spec:check`, `sprint:status`, `gsd:handoff`
18
+ (+ `graph.sync`). Ele **não consegue** rodar o fluxo SDD (`spec:new/plan/tasks`), nem
19
+ `context:smart`, `query:universal`, `engineer`, `risk:assess`, `orchestrate:status/advance`,
20
+ `drift:check`, `status`, `next` — cai em adivinhar invocação de CLI, que é o atrito que o resto
21
+ do roadmap v4.1 ataca.
22
+
23
+ Dois obstáculos estruturais no caminho de adicionar comandos:
24
+
25
+ - **`apps/cli/src/index.ts`** traduz argv↔payload num `if/else` por comando dentro de
26
+ `parseLegacyCommandInput`, e cada spec tem um `toArgs` que é o inverso manual disso. Adicionar
27
+ um comando exige mexer nos dois, em sincronia, sem contrato que force a coerência.
28
+ - **O `--json` de um comando-capability não segue o contrato de saída (ADR-0082)**. Ele despeja o
29
+ `ExecutionResult` cru (`{ status: "succeeded" | "failed", output: { payload: { stdout, … } } }`).
30
+ É o débito **D7** da SPEC-045: `spec:check` e `tools:doctor` ficaram fora do contrato por isso.
31
+
32
+ **Como medimos hoje**: `CLI_CAPABILITY_SPECS.length === 6`. `forja mcp:start` + `tools/list` → 6.
33
+
34
+ ## 2. Proposta de valor
35
+
36
+ O núcleo do fluxo (~18 comandos) fica operável por MCP com input tipado, e o `--json` de qualquer
37
+ comando-capability passa a seguir o contrato de saída. Adicionar um comando novo à cobertura vira
38
+ **uma entrada declarativa**, não um `if` a mais em dois lugares.
39
+
40
+ ## 3. User stories
41
+
42
+ - **Como** agente LLM plugado via MCP, **quero** `spec:new`, `spec:plan`, `context:smart`,
43
+ `query:universal`, `engineer`, `risk:assess`, `orchestrate:status/advance`, `status`, `next`
44
+ como tools tipadas, **para que** eu rode o fluxo sem montar linha de comando.
45
+ - **Como** consumidor de `spec:check --json` / `tools:doctor --json`, **quero** o formato do
46
+ contrato (`{status: "ok"|"error"|"rejected", …}`), **para que** eu não trate dois envelopes.
47
+ - **Como** mantenedor, **quero** adicionar um comando à cobertura numa entrada declarativa com um
48
+ teste que força argv↔payload a fecharem, **para que** não haja `if/else` a sincronizar.
49
+
50
+ ## 4. Critérios de aceite (Definition of Done)
51
+
52
+ - [ ] **AC-1**: **ADR-0083** registra: (a) o arg mapping declarativo; (b) o critério do que vira
53
+ capability nesta rodada (somente leitura + writes SDD de baixo risco; sem `llm:*`, sem
54
+ writes de sprint/projeto, sem `orchestrate` start); (c) o mapa envelope→contrato:
55
+ `succeeded`→`ok`, `failed`→`error`, `exitCode === 2` do comando→`rejected`.
56
+ - [ ] **AC-2**: `CliCapabilitySpec` ganha `params: { name, kind: 'positional' | 'flag' | 'flag-value', required?: boolean }[]`. `toArgs` e o parse de argv passam a ser **derivados de `params`** por um só helper; o `if/else` por comando em `parseLegacyCommandInput` **é removido** (os casos especiais restantes, se houver, ficam explicitamente nomeados).
57
+ - [ ] **AC-3**: round-trip testado — para todo spec, `toArgs(parseArgs(spec, argvFixture))` reproduz `argvFixture` (ordem, flags, valores).
58
+ - [ ] **AC-4**: `CLI_CAPABILITY_SPECS` cobre, além dos 6 atuais: `spec:new`, `spec:plan`,
59
+ `spec:tasks`, `context:smart`, `code:context`, `query:universal`, `engineer`,
60
+ `risk:assess`, `orchestrate:status`, `orchestrate:advance`, `drift:check`, `status`,
61
+ `next`. (Lista final fechada no `plan`.) `forja capabilities:list` e o `tools/list` do MCP
62
+ mostram o conjunto.
63
+ - [ ] **AC-5**: `bin/forja.ts` — no modo `--json`, um comando-capability emite **o contrato**
64
+ (`{status, …}` conforme ADR-0082) derivado do `ExecutionResult`, não o envelope cru.
65
+ `stdout` do comando-filho, se for JSON válido, é **fundido** no objeto (flat); senão vai
66
+ como string em `raw`. `stderr` → stderr. Exit code segue o contrato (0/1/2).
67
+ - [ ] **AC-6**: `spec:check` e `tools:doctor` marcados `json: true` no registry (D7 fechado);
68
+ `test/cli-output-contract.test.js` passa a cobri-los sem alteração no teste.
69
+ - [ ] **AC-7**: cada capability nova declara `permissions`/`risk`/`categories`/`sideEffects`
70
+ coerentes (as de escrita SDD como `write`+`database` quando gravam; as de leitura como
71
+ `read`). `validateInput` rejeita input fora do schema **antes** de spawnar.
72
+ - [ ] **AC-8**: e2e — `forja mcp:start` responde `tools/list` com o núcleo; `tools/call` de
73
+ `spec.create` → `spec.validate` roda o fluxo por MCP num workspace temporário.
74
+ - [ ] **AC-9**: `tsc --noEmit`, `node --test test/*.test.js`, `forja spec:check`,
75
+ `forja project:check` verdes. Nenhum dos 6 comandos-capability atuais muda de assinatura,
76
+ payload MCP ou exit code (round-trip + testes MCP existentes verdes).
77
+
78
+ ## 5. Escopo
79
+
80
+ **Dentro**:
81
+ - ADR-0083.
82
+ - `apps/cli/src/index.ts` — `params` declarativo, helper de parse/serialização, remoção do
83
+ `if/else`; +13 specs.
84
+ - `bin/forja.ts` — `printExecutionResult` no modo `--json` emite o contrato de saída.
85
+ - `lib/core/registry.ts` — `json: true` em `spec:check`, `tools:doctor` (e nos novos que ganham
86
+ `--json` de fato via capability, se aplicável).
87
+ - Testes: round-trip de args, contagem/lista de capabilities, e2e MCP do fluxo SDD, contrato de
88
+ saída dos capability commands.
89
+ - `docs/capacidades-externas.md` e `docs/contrato-saida-cli.md` — nota sobre o envelope alinhado.
90
+
91
+ **Fora** (evita scope creep):
92
+ - `llm:*` como capability — tem contrato de privacidade próprio (ADR-0081); rodada separada.
93
+ - Writes de mutação fora do SDD: `project:new`, `sprint:start/complete`, `workspace:init`,
94
+ `setup`, `orchestrate` (start).
95
+ - MCP **resources** (só tools nesta rodada).
96
+ - Mudança em `PolicyEngine`, autonomy bands, ou no `McpServer` além do que a lista maior exige.
97
+ - Retrofit de `--json` em comandos que não são capability e não têm (isso é incremental por W5).
98
+
99
+ ## 6. NFRs / restrições
100
+
101
+ - **Compatibilidade**: os 6 capability commands atuais — payload MCP, `toArgs`, exit code —
102
+ **idênticos** (AC-9). O `--json` **de capability commands muda de forma** (envelope →
103
+ contrato): documentado no ADR-0083 e no CHANGELOG; alinha, não regride (o envelope não tinha
104
+ consumidor externo além do MCP, que usa `tools/call`, não `--json`).
105
+ - **Segurança**: `validateInput` roda antes do spawn; capability de escrita declara `write` e o
106
+ `PolicyEngine` já cobre `roles: ['cli']` com todas as categorias — sem ampliar autonomia.
107
+ - **Performance**: parse declarativo é O(argv); irrelevante.
108
+ - **Observabilidade**: auditoria de `runCapabilityCommand` inalterada (`forja-runs.jsonl`).
109
+
110
+ ## 7. Riscos e mitigação
111
+
112
+ | Risco | Probabilidade | Impacto | Mitigação |
113
+ |---|---|---|---|
114
+ | Remover o `if/else` quebra o parse de um dos 6 atuais | M | A | AC-3 round-trip cobre os 6 antes de tocar qualquer coisa; testes MCP existentes são gate |
115
+ | Fundir `stdout` JSON do filho no objeto colide com `status` | M | M | Ordem de merge: contrato primeiro, `stdout` depois só para chaves livres; conflito de `status` → `stdout` vai para `raw` |
116
+ | `context:smart`/`engineer` como capability puxam dependências pesadas (graph, sqlite) para todo `mcp:start` | M | M | O handler continua spawnando `node bin/forja.ts <cmd>` (subprocess), não importando o módulo — o custo é o mesmo de hoje |
117
+ | Lista de 18 vira 30 por pressão de "só mais esse" | M | B | Critério no ADR-0083; fora dele = nova spec |
118
+ | `drift:check` como capability expõe reindexação cara sem rate limit | B | M | `risk: 'medium'`, `idempotent: true`, `timeoutMs` maior; é read-mostly (não promove nada) |
119
+
120
+ ## 8. Métricas de sucesso
121
+
122
+ 30 dias, baseline antes (`CLI_CAPABILITY_SPECS.length === 6`, `tools/list` = 6):
123
+
124
+ - `tools/list` do MCP passa a listar ≥ 18; um agente completa `spec:new → spec:check` só por
125
+ `tools/call`, sem CLI.
126
+ - Zero regressões nos 6 capability commands atuais.
127
+ - `spec:check --json` / `tools:doctor --json` passam no `cli-output-contract` sem exceção.
128
+ - Adicionar o 19º comando à cobertura é 1 entrada declarativa + 1 fixture de round-trip (medido
129
+ no primeiro PR que o fizer).
130
+
131
+ ## Evidências e estado real
132
+
133
+ **Implementado em 2026-09-08** na branch `feat/mcp-cobertura` (sobre `feat/contrato-saida-cli`).
134
+ Bateria: `tsc --noEmit` limpo; `node --test test/*.test.js` **531/531** (+28: `cli-params`,
135
+ `mcp-coverage`, e o ajuste em `cli-capability-adapter`); `forja spec:check` e `forja project:check`
136
+ (100%) verdes; `adr-refs` 79 ADRs.
137
+
138
+ | AC | Onde | Verificado |
139
+ |---|---|---|
140
+ | AC-1 | `memory/90-decisions/0083-mcp-cobertura-declarativa.md` | `adr-refs` verde |
141
+ | AC-2 | `apps/cli/src/params.ts`, `apps/cli/src/index.ts` | `parseLegacyCommandInput` = `parseArgv(spec.params, argv)`; único special-case restante é `graph:sync` |
142
+ | AC-3 | `test/cli-params.test.js` | round-trip `argvFor(parseArgv(argv)) === argv` para os **18** specs |
143
+ | AC-4 | `apps/cli/src/index.ts` | `CLI_CAPABILITY_SPECS.length === 18` (+`graph.sync` = 19 no `capabilities:list`); `test/mcp-coverage.test.js` |
144
+ | AC-5 | `bin/forja.ts` `toContract()` | `--json` de comando-capability → `{status:'ok'\|'error'\|'rejected', ...merge(stdout)}`; `stderr`→stderr; exit 0/1/2 |
145
+ | AC-6 | `lib/core/registry.ts` | `spec:check`/`tools:doctor` `json: true`; `test/cli-output-contract.test.js` cobre-os (via `toContract` → `{status:'ok', raw}`) |
146
+ | AC-7 | `apps/cli/src/index.ts` | cada spec com `permissions`/`risk`/`categories`/`sideEffects`; `validateInput` = `makeValidator(params)` (default) + os 3 custom com range/enum |
147
+ | AC-8 | `test/mcp-coverage.test.js` | `tools/list` expõe o núcleo; `tools/call` `spec.create` → `spec.validate` roda num workspace temp |
148
+ | AC-9 | — | round-trip dos 6 originais verde; testes MCP existentes verdes (`cli-capability-adapter` ajustado para "os 6 ⊆ lista, ≥18") |
149
+
150
+ - **Desvio vs. o plan**: `context:smart` **saiu** da lista (o script tem shape posicional ambíguo
151
+ `[project, keyword]`, não `--mode`/`--domain`) — 12 novos, não 13; total 18. `status`/`next`/
152
+ `engineer` são capability (para o MCP) mas rodam **direto** no CLI (têm `--json` nativo de W4/W5);
153
+ `bin/forja.ts` desvia esses 3 da camada de capability (`NATIVE_JSON_CAPABILITIES`).
154
+ - **Mudança de contrato**: o `--json` de comando-capability (`spec:check`, `code:impact`,
155
+ `spec:new`, …) passa do `ExecutionResult` cru para o contrato de saída. O `tools/call` do MCP
156
+ não muda. No ADR-0083 e no CHANGELOG.
157
+ - **Fecha D7 da SPEC-045**. Nota: `spec:check`/`tools:doctor --json` hoje devolvem
158
+ `{status:'ok', raw:'<texto>'}` — o filho roda em texto e o texto vai em `raw`; estruturar a
159
+ saída deles é follow-up (não bloqueia o contrato).
160
+ - **Hipótese, não medição**: adoção via MCP depende de agentes configurarem `mcp:start`.
161
+ - **Pendências**: revisão de Governança; handoff `review` registrado; depende do merge de #63→#62→#61.
@@ -0,0 +1,169 @@
1
+ # Tasks: mcp-cobertura-nucleo
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Plan**: ./plan.md
5
+ - **Status**: approved
6
+ - **Criado em**: 2026-09-08
7
+
8
+ > Decomposição executável. Cada task tem dono, critério de done e paths.
9
+
10
+ Grafo de dependência:
11
+
12
+ ```
13
+ T1 ─┐
14
+ T2 ─ T3 ─ T4 ─┬─ T6 ─┐
15
+ └── T5 ──┬───┤
16
+ ├─ T7
17
+ └─ T8
18
+ todas ────────────────► T9
19
+ ```
20
+
21
+ Ordem: T2 → T3 (refatora os 6, sem novos) → T4 (adiciona 13) e T5 (contrato de saída) em
22
+ paralelo → T6/T7/T8 → T9.
23
+
24
+ ---
25
+
26
+ ## T1 — ADR-0083
27
+ - **Owner**: SDD Architect · **Est**: P · **Depende de**: —
28
+ - **Paths**: `memory/90-decisions/0083-mcp-cobertura-declarativa.md`
29
+ - **Escopo**: registrar (a) o arg mapping declarativo (`params`, `parseArgv`/`argvFor` inversos,
30
+ round-trip como contrato); (b) o **critério** do que vira capability nesta rodada e a lista de
31
+ fora com a razão (plan §D5); (c) o mapa **envelope→contrato de saída**: `succeeded`+exit0→`ok`,
32
+ `succeeded`+exit2→`rejected`, `failed`/exit1→`error`; regra do `merge(stdout)`/`raw`.
33
+ - **Done**:
34
+ - [ ] ADR existe; `forja tools:doctor` → `adr-refs` verde (79 ADRs)
35
+
36
+ ## T2 — `apps/cli/src/params.ts`
37
+ - **Owner**: Worker · **Est**: M · **Depende de**: —
38
+ - **Paths**: `apps/cli/src/params.ts` (novo), `test/cli-params.test.js` (novo, parte)
39
+ - **Escopo**: `CapabilityParam` (kinds `positional` | `flag` | `flag-value` | `rest`),
40
+ `parseArgv(params, argv): InputRecord`, `argvFor(params, input): string[]` (inversos),
41
+ `makeValidator(params)` (required presente + tipo `string`/`int`). Puros, sem I/O.
42
+ - **Done**:
43
+ - [ ] `tsc --noEmit` verde
44
+ - [ ] testes unitários: `argvFor(params, parseArgv(params, argv))` reproduz `argv` para cada kind
45
+ (positional obrigatório/opcional, flag booleana, flag-value, rest); `makeValidator` rejeita
46
+ required ausente e tipo errado
47
+
48
+ ## T3 — Refatorar os 6 capability specs atuais para `params`
49
+ - **Owner**: Worker · **Est**: M · **Depende de**: T2
50
+ - **Paths**: `apps/cli/src/index.ts`
51
+ - **Escopo**: `CliCapabilitySpec` ganha `params`. Adicionar `params` aos 6
52
+ (`tools:doctor` → `[]`; `code:impact` → `[positional symbol req, flag-value --depth int]`;
53
+ `context:budget` → `[positional target req, flag-value --limit-tokens int]`;
54
+ `spec:check` → `[positional feature]`; `sprint:status` → `[positional project]`;
55
+ `gsd:handoff` → `[positional phase req, positional slug req, rest context]`).
56
+ `toArgs` = `argvFor(spec.params)`. `parseLegacyCommandInput` → `parseArgv(spec.params, argv)`
57
+ (o if/else por comando some; `graph:sync` continua o único special-case, sem `command`).
58
+ `validateInput` de cada um passa a chamar `makeValidator(params)` e manter só a checagem extra
59
+ (range de `depth`, `limitTokens`, enum de `phase`).
60
+ - **Done**:
61
+ - [ ] `parseLegacyCommandInput` sem nenhum `if (command === …)` além de `graph:sync`
62
+ - [ ] round-trip verde para os 6 (T6 formaliza; aqui, checagem manual)
63
+ - [ ] `node --test test/*.test.js` — testes MCP/capability existentes **verdes sem alteração** (AC-9)
64
+
65
+ ## T4 — Adicionar os 13 capability specs novos
66
+ - **Owner**: Worker · **Est**: G · **Depende de**: T3
67
+ - **Paths**: `apps/cli/src/index.ts`
68
+ - **Escopo**: adicionar a `CLI_CAPABILITY_SPECS` (ids e params no plan §D5/§D6):
69
+ `spec.create` (`spec:new`, `[positional slug req]`, `write`), `spec.plan`, `spec.tasks`
70
+ (idem), `context.smart` (`[flag-value --mode, flag-value --domain]`, `read,database`),
71
+ `code.context` (`[positional domain, flag --code]`, `read`), `memory.query` (`query:universal`,
72
+ `[positional query req]`, `read,database`), `engineering.facade` (`engineer`,
73
+ `[positional objective req, flag-value --ref, flag-value --role]`, `read,database,execution`),
74
+ `risk.assess` (`[positional ref]`, `read,database`), `orchestrate.status` (`[positional slug]`,
75
+ `read`), `orchestrate.advance` (`[positional slug req]`, `write,execution`, `risk:'medium'`),
76
+ `drift.check` (`[flag-value --domain]`, `read,database,execution`, `risk:'medium'`,
77
+ `timeoutMs` maior), `forja.status` (`status`, `[]`, `read`), `forja.next` (`next`, `[]`, `read`).
78
+ Cada um: `description`, `permissions`, `sideEffects` coerentes; `validateInput` = `makeValidator`.
79
+ - **Done**:
80
+ - [ ] `CLI_CAPABILITY_SPECS.length >= 18`
81
+ - [ ] `forja capabilities:list` lista o conjunto; `forja capabilities:describe <id>` funciona
82
+ - [ ] `tsc --noEmit` verde
83
+
84
+ ## T5 — Contrato de saída no `--json` de comando-capability
85
+ - **Owner**: Worker · **Est**: M · **Depende de**: T2, T3
86
+ - **Paths**: `bin/forja.ts`
87
+ - **Escopo**: `toContract(result): { json, exitCode }` — único ponto do mapa envelope→contrato
88
+ (ADR-0083). `printExecutionResult(result, json)`: `json=true` → `console.log(JSON.stringify(
89
+ toContract(result).json))` + `process.stderr.write(stderr)`; `json=false` inalterado.
90
+ `runCapabilityCommand` retorna `toContract(...).exitCode` no modo `--json`. `merge(stdout)`:
91
+ objeto JSON → espalha (colisão de `status` → `raw`); senão `raw: <texto>`. `graph:sync`
92
+ (payload sem `exitCode`) → `status:'ok'` + payload espalhado.
93
+ - **Done**:
94
+ - [ ] `forja tools:doctor --json` → `{status:'ok'|'error', ...}`; `forja spec:check <x> --json`
95
+ → `{status:'ok'|'rejected', ...}`
96
+ - [ ] `forja tools:doctor` (sem `--json`) e o consumo MCP (`tools/call`) inalterados
97
+ - [ ] exit code do `--json` casa com `status` (0/1/2)
98
+
99
+ ## T6 — Testes: round-trip + cobertura MCP e2e
100
+ - **Owner**: Worker · **Est**: M · **Depende de**: T4, T5
101
+ - **Paths**: `test/cli-params.test.js`, `test/mcp-coverage.test.js` (novos)
102
+ - **Escopo**:
103
+ - `cli-params`: para **todo** spec em `CLI_CAPABILITY_SPECS`, uma fixture de argv válido →
104
+ `argvFor(params, parseArgv(params, argv))` === argv.
105
+ - `mcp-coverage`: `createCliCapabilityRuntime` + `McpServer` → `tools/list` contém o núcleo
106
+ (`spec.create`, `spec.plan`, `memory.query`, `engineering.facade`, …); `tools/call`
107
+ `spec.create` depois `spec.validate` num `FORJA_WORKSPACE` temp roda o fluxo. `concurrency:false`.
108
+ - **Done**:
109
+ - [ ] `node --test test/cli-params.test.js test/mcp-coverage.test.js` verde
110
+
111
+ ## T7 — `json: true` em `spec:check` e `tools:doctor` (fecha D7)
112
+ - **Owner**: Worker · **Est**: P · **Depende de**: T5
113
+ - **Paths**: `lib/core/registry.ts`, `test/cli-output-contract.test.js`
114
+ - **Escopo**: `json: true` + `--json` no `usage`/`examples` das duas entradas. O
115
+ `cli-output-contract` itera o registry — passa a cobri-las automaticamente; ajustar só se a
116
+ fixture de args precisar (ex.: `tools:doctor` sem args).
117
+ - **Done**:
118
+ - [ ] `node --test test/cli-output-contract.test.js` verde com `spec:check` e `tools:doctor` incluídos
119
+ - [ ] `forja help tools:doctor` mostra `--json`
120
+
121
+ ## T8 — Documentação + CHANGELOG
122
+ - **Owner**: Worker · **Est**: P · **Depende de**: T4, T5
123
+ - **Paths**: `docs/capacidades-externas.md`, `docs/contrato-saida-cli.md`, `CHANGELOG.md`
124
+ - **Escopo**: `capacidades-externas.md` — cobertura MCP passou de 6 para ~18, com o critério.
125
+ `contrato-saida-cli.md` — remover a ressalva de `spec:check`/`tools:doctor`; anotar que
126
+ comandos-capability conformam via `toContract`. CHANGELOG `[Unreleased]`: Adicionado (13
127
+ capabilities, `params` declarativo); Alterado/breaking (`--json` de comando-capability:
128
+ envelope → contrato de saída).
129
+ - **Done**:
130
+ - [ ] `forja tools:doctor` → `docs-commands`, `commands-documented`, `docs-links` verdes
131
+
132
+ ## T9 — Validação final + fecho
133
+ - **Owner**: Worker → Governance · **Est**: P · **Depende de**: T1–T8
134
+ - **Paths**: `specs/mcp-cobertura-nucleo/spec.md`
135
+ - **Escopo**: bateria; `spec.md` §Evidências (resultado, data, desvios); mover status; handoff `review`.
136
+ - **Done**:
137
+ - [ ] `tsc --noEmit`, `node --test test/*.test.js`, `forja spec:check`, `forja project:check` verdes — AC-9
138
+ - [ ] `spec:set-status mcp-cobertura-nucleo spec implementing` no início; handoff `worker →
139
+ governance (review)` ao fim
140
+
141
+ ---
142
+
143
+ ## Mapa AC → task
144
+
145
+ | AC | Tasks | Verificação-chave |
146
+ |---|---|---|
147
+ | AC-1 | T1 | ADR-0083; `adr-refs` verde |
148
+ | AC-2 | T2, T3 | `parseLegacyCommandInput` sem if/else por comando |
149
+ | AC-3 | T2, T6 | `test/cli-params.test.js` round-trip para todo spec |
150
+ | AC-4 | T4 | `CLI_CAPABILITY_SPECS.length ≥ 18`; `capabilities:list` |
151
+ | AC-5 | T5 | `--json` de capability emite o contrato |
152
+ | AC-6 | T7 | `spec:check`/`tools:doctor` no `cli-output-contract` |
153
+ | AC-7 | T4 | `permissions`/`risk`/`categories` por spec; `validateInput` antes do spawn |
154
+ | AC-8 | T6 | `test/mcp-coverage.test.js` — `tools/list` + `tools/call` do fluxo |
155
+ | AC-9 | T9 | bateria; 6 atuais inalterados |
156
+
157
+ ## Handoffs entre agentes
158
+
159
+ SDD Architect (spec+plan+tasks + ADR-0083 na T1) → **Worker** (T2–T8) → **Governance** (T9 +
160
+ `project:check`). Registrar via Hermes no início da implementação.
161
+
162
+ ## Evidências e estado real
163
+
164
+ - Nada executado — caixas `[ ]` abertas.
165
+ - **Dependência viva**: `feat/contrato-saida-cli` (#63) → `feat/forja-status` (#62) →
166
+ `feat/cli-intuitiva-v1` (#61).
167
+ - **Mudança de contrato**: `--json` de comando-capability (envelope → contrato de saída).
168
+ - **A maior das ondas** — AC-9 (6 capability commands byte-idênticos) é o gate; round-trip dos 6
169
+ antes de tocar qualquer coisa (T3).
@@ -0,0 +1,148 @@
1
+ # Plan: projeto-gerado-confiavel
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Status**: approved
5
+ - **Criado em**: 2026-09-08
6
+
7
+ > Como vamos construir o que a spec define. Sem código aqui — só estrutura e decisões.
8
+
9
+ ## 1. Abordagem técnica
10
+
11
+ `lib/core/project-smoke.ts` já é o gate certo e já usa o runner de `checks.ts`. Estende-se:
12
+ `SmokeEnv` ganha `ai?: string[]`; quando presente, `withGeneratedProject` gera via
13
+ `bin/init-project.ts <dir> --ai <lista> --skip-backend --force` (memória + instruções, **sem
14
+ rede**) em vez de `create-memory-nest-kit` direto. O `structure` check passa a rodar
15
+ `includeNest: false` nesse modo (não há `backend/`). Um check novo `aiInstructionsCoherent`
16
+ (condicionado a `env.ai`) prova que `.ia-instructions/<ai>.md` de cada IA da lista tem o mesmo
17
+ corpo e que `models.json` bate com a lista. `scripts/project-smoke.ts` ganha `--ai`. O CI roda
18
+ uma matriz de 3 combinações no tier barato. `project:smoke` sem `--ai` fica idêntico.
19
+
20
+ ## 2. Módulos afetados
21
+
22
+ | Caminho | Mudança | Risco |
23
+ |---|---|---|
24
+ | `lib/core/project-smoke.ts` | editar — `SmokeEnv.ai?`; `withGeneratedProject` decide o gerador por `ai`; `HOME` isolado no `spawn` quando `ai`; `structure` usa `includeNest: !ai`; `SMOKE_CHECKS` ganha `aiInstructionsCoherent`; `runProjectSmoke({ ai? })` | M |
25
+ | `scripts/project-smoke.ts` | editar — flag `--ai <lista>` → `runProjectSmoke({ full, ai })` | B |
26
+ | `lib/core/registry.ts` | editar — `--ai` no `usage`/`examples` de `project:smoke` | B |
27
+ | `.github/workflows/ci.yml` | editar — job (ou step em job novo) `project-smoke-ai` com `strategy.matrix.ai: ['claude', 'copilot', 'claude,copilot,gemini,codex']`, `fail-fast: false`, rodando `node bin/forja.ts project:smoke --ai ${{ matrix.ai }}` | B |
28
+ | `test/project-smoke.test.js` | editar/criar — `runProjectSmoke({ ai })` verde; divergência injetada reprova `aiInstructionsCoherent` | M |
29
+ | `docs/quick-reference.md` ou `docs/dev-workflow.md`, `CHANGELOG.md` | editar — `project:smoke --ai` | B |
30
+
31
+ ## 3. Diagrama de fluxo
32
+
33
+ ```
34
+ forja project:smoke [--ai a,b,c] [--full]
35
+ │
36
+ └── runProjectSmoke({ full, ai })
37
+ └── withGeneratedProject(fn, { root, spawn, ai })
38
+ ai ausente → spawn(create-memory-nest-kit, [dir, --force]) (projeto completo, como hoje)
39
+ ai presente → spawn(init-project.ts, [dir, --ai a,b,c, --skip-backend, --force], { HOME: tmp })
40
+ └── run({ checks: SMOKE_CHECKS, env: { ...base, projectDir, ai } })
41
+ generated · no-placeholders · json-valid
42
+ structure → includeNest: !env.ai
43
+ gate-inherited
44
+ ai-instructions → SÓ quando env.ai: <ai>.md existem, corpos idênticos, models.json bate
45
+ builds (--full) → skipped quando env.ai (sem backend)
46
+
47
+ CI: job project-smoke-ai (matrix.ai = claude | copilot | claude,copilot,gemini,codex, fail-fast:false)
48
+ node bin/forja.ts project:smoke --ai ${{ matrix.ai }}
49
+ ```
50
+
51
+ ## 4. Contratos (API/CLI/Schema)
52
+
53
+ ```ts
54
+ // lib/core/project-smoke.ts
55
+ interface SmokeEnv {
56
+ root: string; fs: typeof fs; projectDir?: string; full: boolean;
57
+ ai?: readonly string[]; // novo: lista de IAs; presente ⇒ gera via init-project.ts
58
+ spawn: (cmd, args, opts?) => { stdout: string; stderr: string; code: number };
59
+ }
60
+ export function runProjectSmoke(opts?: { full?: boolean; ai?: string[]; env?: Partial<SmokeEnv> }): Promise<Result[]>;
61
+ ```
62
+
63
+ **`aiInstructionsCoherent`** (`severity: 'critical'`, `dependsOn: 'generated'`): quando `env.ai`
64
+ está setado —
65
+ 1. cada `<ai>` da lista tem `.ia-instructions/<ai>.md`;
66
+ 2. removendo as linhas que casam os 2 regexes de `step02CopyInstructions` (`^# Instruções para .+ — Forja$`
67
+ e `^> Guia para .+ multi-IA por design\.$`, e a versão já reescrita), o corpo dos `<ai>.md` é
68
+ **idêntico** byte a byte entre todos;
69
+ 3. `.ia-instructions/models.json` parseia, `fallback_chain` deep-equal a `env.ai`, `engines` tem
70
+ uma chave por IA com `instruction_file` = `.ia-instructions/<ai>.md`.
71
+ Sem `env.ai` → `status: 'skipped'`.
72
+
73
+ **CLI**: `--ai claude,copilot` → `ai = 'claude,copilot'.split(',').map(s => s.trim()).filter(Boolean)`.
74
+
75
+ ## 5. Decisões e alternativas
76
+
77
+ **D1 — REVISADO na implementação: `create-memory-nest-kit --only-memory` + `writeAiInstructions()`
78
+ extraído para `lib/`.** `init-project.ts` **não roda em dev** (hardcoda `bin/create-memory-nest-kit.js`
79
+ e `.mjs` em vários pontos; só funciona do pacote publicado) e trata o path como nome de projeto de
80
+ workspace (escreve `~/forja-workspace/projects/<slug>`). Consertar tudo isso seria refator grande
81
+ (kill-criterion). Em vez disso: a lógica de `step02CopyInstructions` vira
82
+ `lib/multi-ai-instructions.ts` `writeAiInstructions(projectDir, aiList, { kitRoot })` (+
83
+ `stripInstructionHeader` para o check); `init-project.ts step02` passa a **delegar** para ela; o
84
+ smoke gera memória com `create-memory-nest-kit --only-memory` (funciona em dev, sem rede, sem tocar
85
+ `~`) e chama `writeAiInstructions`. Ganho colateral: a escrita multi-IA vira função `lib/` testada,
86
+ compartilhada por gerador e smoke — que é o coração de W8.
87
+ Rejeitado: consertar os hardcodes `.js`/`.mjs` de `init-project.ts` (fora do escopo);
88
+ gerar com backend (step04 = `npm install`).
89
+
90
+ **D2 — `structure` adapta com `includeNest: !env.ai`, não um check separado.** O modo `--ai` é
91
+ memória-only; validar estrutura NestJS ali seria um falso negativo. Rejeitado: duplicar o check.
92
+
93
+ **D3 — `aiInstructionsCoherent` normaliza removendo linhas por regex, não por contagem fixa.**
94
+ `step02` reescreve 2 linhas específicas; o check remove qualquer linha que case os padrões
95
+ originais **ou** os reescritos, e compara o resto. Rejeitado: `slice(2)` (frágil se o cabeçalho
96
+ crescer).
97
+
98
+ **D4 — Matriz de 3 combinações, `fail-fast: false`.** `claude` (1 IA), `copilot` (outra 1, pega
99
+ divergência de header por IA), e as 4 juntas (o caso completo). Rejeitado: só as 4 juntas (não
100
+ isola qual IA quebrou); rejeitado: todas as permutações (custo sem retorno).
101
+
102
+ **D5 — Sem ADR.** `project:smoke` já existe (SPEC-015); a geração multi-IA já é fonte única.
103
+ Isto é extensão + wiring + um check. Se o `plan` revelar que `init-project.ts` precisa de
104
+ refactor para ser testável, aí sim abre-se ADR.
105
+
106
+ ## 6. Dependências
107
+
108
+ - Independente das Ondas 1–2. Branch a partir de `main`.
109
+ - **Pacotes npm**: nenhum.
110
+ - **Migrações**: nenhuma.
111
+ - Assume `init-project.ts --skip-backend` sem rede (validar na T1) e que ele copia
112
+ `scripts/check-memory-maps.mjs` (o `gate-inherited` check depende disso — validar na T2).
113
+
114
+ ## 7. Rollout
115
+
116
+ - [ ] Feature flag: não.
117
+ - [ ] Migração de dados: não.
118
+ - [ ] Doc/persona: `docs/quick-reference.md` / `docs/dev-workflow.md` (`project:smoke --ai`),
119
+ `docs/personas/qa/README.md` se mencionar smoke.
120
+ - [ ] `CHANGELOG.md` `[Unreleased]`: Adicionado (`project:smoke --ai`, check `aiInstructionsCoherent`,
121
+ matriz de CI). Sem quebras.
122
+
123
+ ## 8. Sinais de fracasso (kill criteria)
124
+
125
+ - `init-project.ts --skip-backend` puxa rede ou escreve em `~` sem isolamento viável → gerar
126
+ só a memória (`create-memory-nest-kit --only-memory`) e chamar a lógica de instruções por um
127
+ export novo e mínimo de `init-project.ts`; se isso for refactor grande, W8 vira spec própria.
128
+ - `gate-inherited` não vale no modo memória-only (o script não viaja com `--skip-backend`) →
129
+ condicionar `gate-inherited` a `!env.ai` e cobrir a herança do gate só no smoke completo.
130
+ - A matriz de 3 células passa de ~1 min → cortar para 2 combinações (`copilot` e as 4 juntas).
131
+
132
+ ## Evidências e estado real
133
+
134
+ | AC | Task | Verificação |
135
+ |---|---|---|
136
+ | AC-1 | T1 | `runProjectSmoke({ ai })` gera via `init-project.ts`; sem `ai` inalterado |
137
+ | AC-2 | T4 | `forja project:smoke --ai claude,copilot` — mesmo veredito/exit |
138
+ | AC-3 | T3 | check `aiInstructionsCoherent` (arquivos, corpos idênticos, `models.json`) |
139
+ | AC-4 | T2 | checks existentes rodam sobre a saída do `init-project.ts` (`structure` com `includeNest:false`) |
140
+ | AC-5 | T6 | `ci.yml` matriz `ai` no tier barato, PR + push |
141
+ | AC-6 | T7 | teste verde + teste de divergência injetada reprova |
142
+ | AC-7 | T4 | `forja project:smoke --ai claude,copilot,gemini,codex` local passa |
143
+ | AC-8 | T9 | bateria completa verde; `ci.yml` revisado |
144
+
145
+ - **Descoberta**: `--ai` é do `init-project.ts`, não do `create-memory-nest-kit`; as instruções
146
+ já derivam de `.gemini-instructions.md` (fonte única).
147
+ - **Hipótese, não medição**: métrica de §8 depende de um PR real quebrar o gerador; até lá, o
148
+ teste de regressão (T7) é a evidência.