forjajs 4.0.1 → 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 (95) hide show
  1. package/CHANGELOG.md +111 -7
  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/publishing.md +0 -11
  64. package/docs/quick-reference.md +13 -0
  65. package/docs/roadmap-v4.1.md +199 -0
  66. package/memory/90-decisions/0082-contrato-saida-cli.md +95 -0
  67. package/memory/90-decisions/0083-mcp-cobertura-declarativa.md +103 -0
  68. package/memory/90-decisions/0084-drift-sentinel-fecha.md +79 -0
  69. package/memory/90-decisions/0085-adaptador-claude-paridade.md +85 -0
  70. package/package.json +4 -1
  71. package/specs/cli-intuitiva-v1/plan.md +169 -0
  72. package/specs/cli-intuitiva-v1/spec.md +163 -0
  73. package/specs/cli-intuitiva-v1/tasks.md +224 -0
  74. package/specs/contrato-saida-cli/plan.md +162 -0
  75. package/specs/contrato-saida-cli/spec.md +157 -0
  76. package/specs/contrato-saida-cli/tasks.md +153 -0
  77. package/specs/drift-sentinel/spec.md +17 -8
  78. package/specs/forja-status-caminho-feliz/plan.md +149 -0
  79. package/specs/forja-status-caminho-feliz/spec.md +158 -0
  80. package/specs/forja-status-caminho-feliz/tasks.md +175 -0
  81. package/specs/llm-adaptador-claude/plan.md +117 -0
  82. package/specs/llm-adaptador-claude/spec.md +144 -0
  83. package/specs/llm-adaptador-claude/tasks.md +100 -0
  84. package/specs/llm-benchmark-recomendacao/plan.md +121 -0
  85. package/specs/llm-benchmark-recomendacao/spec.md +141 -0
  86. package/specs/llm-benchmark-recomendacao/tasks.md +88 -0
  87. package/specs/llm-contexto-e-sessoes/plan.md +143 -0
  88. package/specs/llm-contexto-e-sessoes/spec.md +139 -0
  89. package/specs/llm-contexto-e-sessoes/tasks.md +127 -0
  90. package/specs/mcp-cobertura-nucleo/plan.md +158 -0
  91. package/specs/mcp-cobertura-nucleo/spec.md +161 -0
  92. package/specs/mcp-cobertura-nucleo/tasks.md +169 -0
  93. package/specs/projeto-gerado-confiavel/plan.md +148 -0
  94. package/specs/projeto-gerado-confiavel/spec.md +142 -0
  95. package/specs/projeto-gerado-confiavel/tasks.md +139 -0
package/CHANGELOG.md CHANGED
@@ -4,16 +4,120 @@ Histórico consolidado das mudanças estruturais do framework. Para decisões ar
4
4
 
5
5
  ---
6
6
 
7
- ## [4.0.1] — 2026-09-05 — Cache isolado no gate de release
7
+ ## [Unreleased]
8
8
 
9
- ### Corrigido
9
+ ## [4.1.0] — 2026-09-08 — Roadmap v4.1: menos erros, mais intuitivo, mais funcional com LLMs
10
10
 
11
- - `release:check` usa cache npm temporário próprio na instalação isolada, sem depender do
12
- estado ou das permissões do cache global; o cache é removido ao final do gate.
13
- - Guia de publicação documenta o cache isolado, o acesso ao registry e a instalação das
14
- dependências do checkout antes dos gates.
11
+ **Roadmap v4.1 concluído** ([`docs/roadmap-v4.1.md`](docs/roadmap-v4.1.md)): as 12 workstreams
12
+ (W1–W12) — menos erros, operação mais intuitiva, mais funcional com LLMs — foram implementadas
13
+ pelo pipeline SDD do próprio Forja e merjadas em `main` (PRs #61–#69). Specs SPEC-043 a SPEC-050
14
+ em `done`; `drift-sentinel` (SPEC-030) segue `implementing` por desenho (ADR-0084, janela de
15
+ observação até 2026-10-08). ADRs estruturais: 0082 (contrato de saída CLI), 0083 (cobertura MCP
16
+ declarativa), 0084 (fecho do drift-sentinel), 0085 (adaptador Claude). Detalhe de cada frente
17
+ nas entradas abaixo.
15
18
 
16
- ---
19
+ ### Adicionado
20
+
21
+ - `forja llm:run --engineer "<objetivo>"` — monta o contexto pelo façade `engineer` (ADRs, risco,
22
+ fluxo, …) e o embute no prompt. O hash cobre o prompt transmitido; em `contextRefs` fica só a
23
+ referência `engineer:<objetivo>`, nunca o conteúdo. Falha do façade → `errorCode:
24
+ "ENGINEER_FAILED"` antes de chamar o provedor. (SPEC-048)
25
+ - `forja llm:sessions list|show` — leitura das sessões LLM registradas (`llm_session`) para
26
+ recuperar o `SESSION_ID` que `llm:run --resume` exige. Somente leitura. (SPEC-048)
27
+ - `forja llm:eval` reporta `durationMsP50`/`durationMsP95` e `costPerAcceptedTask`
28
+ (`totalCost / tarefas aceitas`; 0 quando nenhuma). As métricas anteriores não mudam. (SPEC-049)
29
+ - `forja llm:recommend` pondera **latência e custo** além do fit declarado e do sucesso local
30
+ (bônus limitado — nunca inverte um fit) e devolve `evidence` por candidato
31
+ (`samples`, `medianDurationMs`, `meanCostUsd`, `successRate`) + `reasons` com `latency:p50=…` /
32
+ `cost:$…/run`. Nenhum percentual de ganho é afirmado antes de um baseline de 30 dias. (SPEC-049)
33
+ - Adaptador **Claude** com paridade de retomada e formato: `llm:run --profile claude` invoca
34
+ `claude -p "<prompt>" --output-format json [--resume <id>]` (`shell:false`, sem ler API keys),
35
+ normaliza o objeto JSON único do provedor (`result`/`session_id`/`usage`) e trata
36
+ `is_error`/`subtype` como erro visível. `RESUME_PROVIDERS = { codex, claude }` — `--resume` e
37
+ `llm:sessions` passam a valer para Claude. `--output-schema` com o perfil `claude` é validação
38
+ **local (Ajv)**, não geração garantida pelo provedor; `llm:probe claude` reporta
39
+ `features.resume: true` / `features.outputSchema: false`. (SPEC-050, ADR-0085)
40
+ - `forja help <comando>` — uso, argumentos posicionais, exemplos e próximos passos de cada
41
+ comando, a partir de campos novos e opcionais do registry (`usage`, `cliArgs`, `examples`,
42
+ `next`, `spec`, `tier`). `forja <comando> --help` faz o mesmo inline. (SPEC-043)
43
+ - `forja setup` — rotina de primeiro uso (`workspace:init` + `sync:universal`) atrás de
44
+ confirmação; `--yes` para uso não-interativo; aborta sem efeito quando não há TTY. (SPEC-043)
45
+ - `forja status` — retrato único do estado: workspace, sprint, corrida orchestrate aberta,
46
+ specs por status, últimos runs, handoffs em aberto. `--json` estável; cada seção degrada com
47
+ `indisponível: <motivo>`. (SPEC-044)
48
+ - `forja next` — a próxima ação recomendada e o comando exato, por prioridade determinística
49
+ (workspace ausente → `setup`; memória crua → `sync:universal`; corrida travada → parecer +
50
+ `orchestrate:advance`; spec `approved` sem plan → `spec:plan`; …). `--json` →
51
+ `{ action, command, reason }`. (SPEC-044)
52
+ - `suggest()` passou a casar por substring **e** distância de edição sobre o nome completo:
53
+ `forja plan` sugere `spec:plan`. Toda mensagem de comando desconhecido termina com
54
+ `forja help <palpite>`. (SPEC-043)
55
+ - Argumento posicional obrigatório em falta falha **antes** de invocar o script-filho, imprimindo
56
+ o `Uso:` do comando — sem stack trace. (SPEC-043)
57
+ - **Contrato de saída da CLI** ([ADR-0082](memory/90-decisions/0082-contrato-saida-cli.md),
58
+ [`docs/contrato-saida-cli.md`](docs/contrato-saida-cli.md)): `--json` emite um único objeto com
59
+ chave `status` (`ok`|`error`|`rejected`); exit codes 0/1/2/127. `lib/cli-output.ts`
60
+ (`emitOk`/`emitError`/`emitRejected`) impõe o formato; `test/cli-output-contract.test.js` itera
61
+ o registry e reprova qualquer `json: true` que desvie. Conjunto conformado: `status`, `next`,
62
+ `engineer`, `simulate`, `cost:economy`, `token:economy`. (SPEC-045)
63
+ - **Cobertura MCP de 6 → 18 comandos** ([ADR-0083](memory/90-decisions/0083-mcp-cobertura-declarativa.md)):
64
+ `spec:new`, `spec:plan`, `spec:tasks`, `query:universal`, `engineer`, `risk:assess`,
65
+ `orchestrate:status`, `orchestrate:advance`, `drift:check`, `code:context`, `status`, `next`
66
+ viram capabilities tipadas — `forja mcp:start` → `tools/list` passa a expô-las e o fluxo SDD
67
+ roda por `tools/call`. Mapeamento argv↔payload declarativo (`apps/cli/src/params.ts`,
68
+ `parseArgv`/`argvFor` inversos com round-trip test); o `if/else` por comando some. `spec:check`
69
+ e `tools:doctor` fecham o débito D7 de SPEC-045 (agora `json: true`). (SPEC-046)
70
+ - `forja project:smoke --ai <lista>` — o gate do projeto gerado passa a exercitar o caminho real
71
+ do `--ai` (memória + instruções nativas por IA), gerado só-memória e sem rede. (SPEC-047)
72
+ - Check `ai-instructions` no `project:smoke`: quando `--ai` é pedido, prova que cada
73
+ `.ia-instructions/<ai>.md` deriva da mesma fonte (corpo byte-idêntico entre IAs, só o cabeçalho
74
+ muda) e que `models.json` bate com a lista. É o análogo do `agent-topology`, na saída do gerador. (SPEC-047)
75
+ - `.github/workflows/ci.yml` — job `project-smoke-ai` em matriz (`claude` · `copilot` ·
76
+ `claude,copilot,gemini,codex`), tier barato, a cada PR e push. (SPEC-047)
77
+ - `lib/multi-ai-instructions.ts` — a escrita das instruções nativas por IA vira função `lib/`
78
+ testada, compartilhada por `bin/init-project.ts` e pelo smoke. (SPEC-047)
79
+ - `forja drift:check --all` — roda o sentinela de drift uma vez por projeto do workspace, cada um
80
+ num grafo isolado e persistente (`<projeto>/.context/drift-graph.db`). É o modo lote que a
81
+ SPEC-030 §3 previa: rodar antes de retomar um projeto parado há meses. (SPEC-030, ADR-0084)
82
+
83
+ ### Alterado
84
+
85
+ - **SPEC-030 (Drift Sentinel) fecha** ([ADR-0084](memory/90-decisions/0084-drift-sentinel-fecha.md)):
86
+ a métrica de sucesso do §8 (drift real encontrado no mundo) era infalsificável como bloqueio de
87
+ `done` — foi reformulada para um aceite verificável agora (determinismo, zero falso positivo no
88
+ monorepo, `--all` completa), e "drift real no mundo" virou janela de observação até 2026-10-08.
89
+ `drift:check` segue como gate opt-in (`check:all --with-drift`), inalterado. Status → `done`.
90
+ - **`--json` de comando-capability** (`spec:check`, `tools:doctor`, `code:impact`, `spec:new`, …)
91
+ deixa de emitir o `ExecutionResult` cru e passa a seguir o contrato de saída (`{ status, … }`)
92
+ via o adaptador `toContract` em `bin/forja.ts`. O consumo por MCP (`tools/call`) não muda.
93
+ (SPEC-046, ADR-0083)
94
+ - **`token:economy --json`** deixa de emitir um array cru — passa a `{ "status": "ok",
95
+ "rows": [...] }`. Quebra do JSON desse comando (ADR-0082). (SPEC-045)
96
+ - **`simulate`** com recomendação `discard`: exit code passa de `0` para **`2`** e, com `--json`,
97
+ `status: "rejected"` — é um gate negativo, não sucesso (ADR-0082). (SPEC-045)
98
+ - **`cost:economy --json`** deixava de ser parseável (avisos de texto iam no stdout); agora o
99
+ stdout é só o objeto, avisos vão para o stderr. (SPEC-045)
100
+
101
+ - `forja help` (sem argumentos) lista só os comandos do núcleo (`tier: 'core'`), agrupados por
102
+ domínio, com rodapé para `forja help --all`. `forja help --all` preserva a saída completa
103
+ anterior; os sufixos `(SPEC-0XX)` saíram das descrições do núcleo para o detalhe de `help <cmd>`. (SPEC-043)
104
+ - `orchestrate` e os comandos de estado (`status`, `next`) abrem o bloco GSD no `forja help` —
105
+ o caminho feliz em primeiro lugar. (SPEC-044)
106
+ - `tools:doctor` e o bloco `<framework-status>` do SessionStart agrupam os checks em três blocos
107
+ rotulados — **Bloqueia o fluxo**, **Rotina de primeiro uso**, **Opcional (ferramentas)**. O
108
+ exit code do gate é inalterado. Mudança aditiva. (SPEC-043)
109
+ - `listSpecs` e `openHandoffs` saíram de `scripts/hook-session-start.ts` para
110
+ `lib/specs-index.ts` / `lib/handoffs-index.ts`, compartilhados com `forja status`. `listRuns`
111
+ novo em `lib/orchestrate.ts`. (SPEC-044)
112
+
113
+ ### Notas de contrato
114
+
115
+ - Decidido no plan (`specs/cli-intuitiva-v1/`): o `--fix` da spec original virou o comando
116
+ dedicado `forja setup` — `tools:doctor` continua só diagnóstico, por desenho. O campo de args
117
+ posicionais no registry chama-se `cliArgs` (não `args`, que é o prefixo fixo do spawn).
118
+ - `spec:check` e `tools:doctor` entraram no contrato de saída via SPEC-046: o envelope da
119
+ capability MCP é convertido pelo adaptador `toContract` em `bin/forja.ts` (fecha o débito D7
120
+ de SPEC-045).
17
121
 
18
122
  ## [4.0.0] — 2026-09-05 — Integrações LLM, sessões e validação
19
123
 
package/DOC-MAP.md CHANGED
@@ -55,6 +55,7 @@ Ponto de entrada por papel. Para histórico de fases ver `CHANGELOG.md`; para de
55
55
  | Manual operacional CLI-first | `docs/manual-operacional-cli-sdd-gsd.md` |
56
56
  | Modos embedded e studio | `docs/modos-de-operacao.md` |
57
57
  | Guia curto CLI-first | `docs/cli-first-operacao.md` |
58
+ | Contrato de saída da CLI (`--json` + exit codes) | `docs/contrato-saida-cli.md` |
58
59
  | Mudanças recentes | `CHANGELOG.md` |
59
60
  | Decisões arquiteturais | `memory/90-decisions/` |
60
61
  | Glossário | `docs/glossary.md` |
package/README.md CHANGED
@@ -220,6 +220,11 @@ scripts are thin aliases that route through the core.
220
220
  ## Essential commands
221
221
 
222
222
  ```bash
223
+ # Orientation — the happy path
224
+ forja status # where am I: workspace, sprint, run, specs, runs, handoffs
225
+ forja next # what now: one line — the next action + the exact command
226
+ forja help [<command>|--all] # the core, or one command's usage/args/examples/next steps
227
+
223
228
  # Workspace & projects
224
229
  forja workspace:init # create ~/forja-workspace
225
230
  forja project:new <name> --ai claude,copilot # create a project in the workspace
@@ -234,7 +239,7 @@ forja sprint:start # also: sprint:status · sprint:compl
234
239
  forja gsd:plan <slug> # GSD runbook in .context/
235
240
  forja gsd:handoff <intent> <slug> # role-to-role handoff (ADR-0005)
236
241
  forja gsd:check <slug> # baseline runbook gates
237
- forja orchestrate "<goal>" --slug <s> # open a run: the SDD/GSD chain as a gated state machine (SPEC-021)
242
+ forja orchestrate "<goal>" --slug <s> # the default path: the whole SDD/GSD chain as a gated state machine (SPEC-021)
238
243
  forja orchestrate:status <slug> # the machine state: stages, gates, verdicts
239
244
  forja orchestrate:advance <slug> # run the stage gate; green → next; red → blocked
240
245
 
@@ -290,7 +295,7 @@ forja cost:economy # real $ cost per model, from the obs
290
295
  forja project:check # framework standards (pre-commit)
291
296
  forja tools:doctor # core X-ray; tells permission/lock from corruption; exit 1 if broken
292
297
  forja release:check --publish # tarball gate before publishing
293
- forja project:smoke # generated-project gate; --full installs and builds the backend
298
+ forja project:smoke # generated-project gate; --full installs+builds; --ai <list> checks native instructions
294
299
  forja project:dashboard # static status report
295
300
 
296
301
  # Governance & audit
@@ -1,7 +1,8 @@
1
1
  import { type AgentIdentity, type CapabilityId, type ExecutionResult } from '../../../packages/contracts/src/index.ts';
2
2
  import { CapabilityRegistry } from '../../../packages/core/src/index.ts';
3
- import { PolicyEngine } from '../../../packages/policy/src/index.ts';
3
+ import { PolicyEngine, type PolicyCategory } from '../../../packages/policy/src/index.ts';
4
4
  import { GraphLoop, type GraphDocumentSource } from '../../../packages/graph/src/index.ts';
5
+ import { type CapabilityParam } from './params.ts';
5
6
  export interface LegacyCliResult {
6
7
  readonly exitCode: number;
7
8
  readonly stdout: string;
@@ -28,6 +29,22 @@ export declare function createLegacyCliRunner(root: string, cwd?: string): Legac
28
29
  interface InputRecord {
29
30
  readonly [key: string]: unknown;
30
31
  }
32
+ interface CliCapabilitySpec<Input extends InputRecord> {
33
+ readonly id: CapabilityId;
34
+ readonly command: string;
35
+ readonly description: string;
36
+ readonly categories: readonly PolicyCategory[];
37
+ readonly permissions: readonly string[];
38
+ readonly risk: 'low' | 'medium' | 'high' | 'critical';
39
+ readonly sideEffects: readonly string[];
40
+ /** argv↔payload declarativo (SPEC-046). `toArgs` e o parse de argv derivam daqui. */
41
+ readonly params: readonly CapabilityParam[];
42
+ /** Opcional: só quando há checagem além de "required + tipo" (range, enum). Default: `makeValidator(params)`. */
43
+ readonly validateInput?: (value: unknown) => Input;
44
+ /** Opcional: `timeoutMs` do registry quando o default de 30s é curto. */
45
+ readonly timeoutMs?: number;
46
+ }
47
+ export declare const CLI_CAPABILITY_SPECS: readonly CliCapabilitySpec<InputRecord>[];
31
48
  export declare const CLI_COMMAND_TO_CAPABILITY: Readonly<Record<string, CapabilityId>>;
32
49
  /** Interface commands for discovering/executing capabilities; handlers remain in the registry. */
33
50
  export declare const CLI_INTERFACE_COMMANDS: readonly ["capabilities:list", "capabilities:describe", "capability:execute", "mcp:start"];
@@ -5,6 +5,7 @@ import { CapabilityRegistry, } from "../../../packages/core/src/index.js";
5
5
  import { PolicyEngine } from "../../../packages/policy/src/index.js";
6
6
  import { COMMANDS, resolveScript } from "../../../lib/core/registry.js";
7
7
  import { GraphIndexer } from "../../../packages/graph/src/index.js";
8
+ import { parseArgv, argvFor, makeValidator } from "./params.js";
8
9
  export function createLegacyCliRunner(root, cwd = process.cwd()) {
9
10
  return (command, args) => {
10
11
  const definition = COMMANDS[command];
@@ -17,7 +18,8 @@ export function createLegacyCliRunner(root, cwd = process.cwd()) {
17
18
  return { exitCode: result.status ?? 1, stdout: result.stdout ?? '', stderr: [result.stderr ?? '', result.error?.message ?? ''].filter(Boolean).join('\n') };
18
19
  };
19
20
  }
20
- const CLI_CAPABILITY_SPECS = [
21
+ export const CLI_CAPABILITY_SPECS = [
22
+ // --- Os 6 originais: mesma assinatura, `params` no lugar do `toArgs` manual (SPEC-046) ---
21
23
  {
22
24
  id: 'system.doctor',
23
25
  command: 'tools:doctor',
@@ -26,8 +28,8 @@ const CLI_CAPABILITY_SPECS = [
26
28
  permissions: ['read'],
27
29
  risk: 'low',
28
30
  sideEffects: [],
31
+ params: [],
29
32
  validateInput: emptyInput,
30
- toArgs: () => [],
31
33
  },
32
34
  {
33
35
  id: 'code.impact',
@@ -37,8 +39,11 @@ const CLI_CAPABILITY_SPECS = [
37
39
  permissions: ['read'],
38
40
  risk: 'low',
39
41
  sideEffects: [],
42
+ params: [
43
+ { name: 'symbol', kind: 'positional', required: true },
44
+ { name: 'depth', kind: 'positional', parse: 'int' },
45
+ ],
40
46
  validateInput: validateCodeImpactInput,
41
- toArgs: (input) => input.depth === undefined ? [input.symbol] : [input.symbol, String(input.depth)],
42
47
  },
43
48
  {
44
49
  id: 'context.budget',
@@ -48,8 +53,11 @@ const CLI_CAPABILITY_SPECS = [
48
53
  permissions: ['read'],
49
54
  risk: 'low',
50
55
  sideEffects: ['context_run_record'],
56
+ params: [
57
+ { name: 'target', kind: 'positional', required: true },
58
+ { name: 'limitTokens', kind: 'positional', parse: 'int' },
59
+ ],
51
60
  validateInput: validateContextBudgetInput,
52
- toArgs: (input) => input.limitTokens === undefined ? [input.target] : [input.target, String(input.limitTokens)],
53
61
  },
54
62
  {
55
63
  id: 'spec.validate',
@@ -59,8 +67,8 @@ const CLI_CAPABILITY_SPECS = [
59
67
  permissions: ['read'],
60
68
  risk: 'low',
61
69
  sideEffects: [],
70
+ params: [{ name: 'feature', kind: 'positional' }],
62
71
  validateInput: validateSpecCheckInput,
63
- toArgs: (input) => input.feature === undefined ? [] : [input.feature],
64
72
  },
65
73
  {
66
74
  id: 'sprint.status',
@@ -70,8 +78,8 @@ const CLI_CAPABILITY_SPECS = [
70
78
  permissions: ['read'],
71
79
  risk: 'low',
72
80
  sideEffects: [],
81
+ params: [{ name: 'project', kind: 'positional' }],
73
82
  validateInput: validateSprintStatusInput,
74
- toArgs: (input) => input.project === undefined ? [] : [input.project],
75
83
  },
76
84
  {
77
85
  id: 'handoff.create',
@@ -81,8 +89,146 @@ const CLI_CAPABILITY_SPECS = [
81
89
  permissions: ['write'],
82
90
  risk: 'low',
83
91
  sideEffects: ['handoff_record'],
92
+ params: [
93
+ { name: 'phase', kind: 'positional', required: true },
94
+ { name: 'slug', kind: 'positional', required: true },
95
+ { name: 'context', kind: 'rest' },
96
+ ],
84
97
  validateInput: validateHandoffInput,
85
- toArgs: (input) => [input.phase, input.slug, ...(input.context === undefined ? [] : [input.context])],
98
+ },
99
+ // --- SPEC-046 / ADR-0083: o núcleo do fluxo operável por MCP ---
100
+ {
101
+ id: 'spec.create',
102
+ command: 'spec:new',
103
+ description: 'Cria specs/<slug>/spec.md a partir do template.',
104
+ categories: ['write'],
105
+ permissions: ['write'],
106
+ risk: 'low',
107
+ sideEffects: ['spec_file'],
108
+ params: [{ name: 'slug', kind: 'positional', required: true }],
109
+ },
110
+ {
111
+ id: 'spec.plan',
112
+ command: 'spec:plan',
113
+ description: 'Deriva plan.md de uma spec aprovada.',
114
+ categories: ['write'],
115
+ permissions: ['write'],
116
+ risk: 'low',
117
+ sideEffects: ['spec_file'],
118
+ params: [{ name: 'slug', kind: 'positional', required: true }],
119
+ },
120
+ {
121
+ id: 'spec.tasks',
122
+ command: 'spec:tasks',
123
+ description: 'Decompõe plan.md em tasks.md.',
124
+ categories: ['write'],
125
+ permissions: ['write'],
126
+ risk: 'low',
127
+ sideEffects: ['spec_file'],
128
+ params: [{ name: 'slug', kind: 'positional', required: true }],
129
+ },
130
+ {
131
+ id: 'code.context',
132
+ command: 'code:context',
133
+ description: 'Pacote de contexto mínimo de um domínio (o mapa; + código com --code).',
134
+ categories: ['read'],
135
+ permissions: ['read'],
136
+ risk: 'low',
137
+ sideEffects: [],
138
+ params: [
139
+ { name: 'domain', kind: 'positional' },
140
+ { name: 'code', kind: 'flag' },
141
+ ],
142
+ },
143
+ {
144
+ id: 'memory.query',
145
+ command: 'query:universal',
146
+ description: 'Busca FTS5 na memória universal.',
147
+ categories: ['read', 'database'],
148
+ permissions: ['read'],
149
+ risk: 'low',
150
+ sideEffects: [],
151
+ params: [{ name: 'query', kind: 'positional', required: true }],
152
+ },
153
+ {
154
+ id: 'engineering.facade',
155
+ command: 'engineer',
156
+ description: 'Façade: contexto + ADRs relevantes + architecture:check + risco + fluxo recomendado.',
157
+ categories: ['read', 'database', 'execution'],
158
+ permissions: ['read'],
159
+ risk: 'medium',
160
+ sideEffects: [],
161
+ params: [
162
+ { name: 'objective', kind: 'positional', required: true },
163
+ { name: 'ref', kind: 'flag-value', flag: '--ref' },
164
+ { name: 'role', kind: 'flag-value', flag: '--role' },
165
+ ],
166
+ timeoutMs: 120_000,
167
+ },
168
+ {
169
+ id: 'risk.assess',
170
+ command: 'risk:assess',
171
+ description: 'Score de risco 0-100 (7 fatores) sobre o diff de um ref.',
172
+ categories: ['read', 'database'],
173
+ permissions: ['read'],
174
+ risk: 'low',
175
+ sideEffects: ['risk_assessment'],
176
+ params: [{ name: 'ref', kind: 'positional' }],
177
+ },
178
+ {
179
+ id: 'orchestrate.status',
180
+ command: 'orchestrate:status',
181
+ description: 'O estado de uma corrida orchestrate: etapas, gates, vereditos.',
182
+ categories: ['read'],
183
+ permissions: ['read'],
184
+ risk: 'low',
185
+ sideEffects: [],
186
+ params: [{ name: 'slug', kind: 'positional', required: true }],
187
+ },
188
+ {
189
+ id: 'orchestrate.advance',
190
+ command: 'orchestrate:advance',
191
+ description: 'Roda o gate da etapa aberta; verde abre a próxima, vermelho trava com o parecer.',
192
+ categories: ['write', 'execution', 'database'],
193
+ permissions: ['write'],
194
+ risk: 'medium',
195
+ sideEffects: ['orchestrate_state'],
196
+ params: [{ name: 'slug', kind: 'positional', required: true }],
197
+ timeoutMs: 300_000,
198
+ },
199
+ {
200
+ id: 'drift.check',
201
+ command: 'drift:check',
202
+ description: 'Reindexa e sinaliza relações verified que a extração atual não reproduz mais.',
203
+ categories: ['read', 'database', 'execution'],
204
+ permissions: ['read'],
205
+ risk: 'medium',
206
+ sideEffects: ['graph_write'],
207
+ params: [
208
+ { name: 'domain', kind: 'flag-value', flag: '--domain' },
209
+ { name: 'all', kind: 'flag' }, // SPEC-030 §3 / ADR-0084: modo lote por projeto do workspace
210
+ ],
211
+ timeoutMs: 120_000,
212
+ },
213
+ {
214
+ id: 'forja.status',
215
+ command: 'status',
216
+ description: 'Retrato único do estado: workspace, sprint, corrida, specs, runs, handoffs.',
217
+ categories: ['read'],
218
+ permissions: ['read'],
219
+ risk: 'low',
220
+ sideEffects: [],
221
+ params: [],
222
+ },
223
+ {
224
+ id: 'forja.next',
225
+ command: 'next',
226
+ description: 'A próxima ação recomendada e o comando exato para executá-la.',
227
+ categories: ['read'],
228
+ permissions: ['read'],
229
+ risk: 'low',
230
+ sideEffects: [],
231
+ params: [],
86
232
  },
87
233
  ];
88
234
  export const CLI_COMMAND_TO_CAPABILITY = Object.freeze(Object.fromEntries(CLI_CAPABILITY_SPECS.map((spec) => [spec.command, spec.id])));
@@ -138,27 +284,16 @@ export function capabilityIdForCommand(command) {
138
284
  return command === 'graph:sync' ? 'graph.sync' : CLI_COMMAND_TO_CAPABILITY[command];
139
285
  }
140
286
  export function parseLegacyCommandInput(command, args) {
287
+ // `graph:sync` é o único sem comando CLI / sem params — os demais derivam de `spec.params` (SPEC-046).
141
288
  if (command === 'graph:sync')
142
289
  return { capabilityId: 'graph.sync', payload: {} };
143
290
  const capabilityId = capabilityIdForCommand(command);
144
291
  if (capabilityId === undefined)
145
292
  throw new Error(`Command is not migrated to a capability: ${command}`);
146
- if (command === 'tools:doctor')
147
- return { capabilityId, payload: {} };
148
- if (command === 'code:impact') {
149
- const [symbol, depth] = args;
150
- return { capabilityId, payload: { symbol, ...(depth === undefined ? {} : { depth: Number(depth) }) } };
151
- }
152
- if (command === 'context:budget') {
153
- const [target, limitTokens] = args;
154
- return { capabilityId, payload: { target, ...(limitTokens === undefined ? {} : { limitTokens: Number(limitTokens) }) } };
155
- }
156
- if (command === 'spec:check')
157
- return { capabilityId, payload: args[0] === undefined ? {} : { feature: args[0] } };
158
- if (command === 'sprint:status')
159
- return { capabilityId, payload: args[0] === undefined ? {} : { project: args[0] } };
160
- const [phase, slug, ...contextParts] = args;
161
- return { capabilityId, payload: { phase, slug, ...(contextParts.length === 0 ? {} : { context: contextParts.join(' ') }) } };
293
+ const spec = CLI_CAPABILITY_SPECS.find((s) => s.command === command);
294
+ if (spec === undefined)
295
+ throw new Error(`No capability spec for command: ${command}`);
296
+ return { capabilityId, payload: parseArgv(spec.params, args) };
162
297
  }
163
298
  export async function executeCliCapability(runtime, capabilityId, payload, correlationId) {
164
299
  const definition = runtime.registry.describe(capabilityId);
@@ -206,16 +341,16 @@ function registerCliCapability(registry, runner, spec) {
206
341
  requirements: [],
207
342
  supportsAutonomy: true,
208
343
  idempotent: true,
209
- timeoutMs: 30_000,
344
+ timeoutMs: spec.timeoutMs ?? 30_000,
210
345
  retry: { maxAttempts: 1, backoffMs: 0 },
211
346
  aliases: [spec.command],
212
347
  };
213
348
  const registration = {
214
349
  definition,
215
- validateInput: spec.validateInput,
350
+ validateInput: spec.validateInput ?? makeValidator(spec.params),
216
351
  validateOutput: validateCliPayload,
217
352
  handler: async (input) => {
218
- const args = spec.toArgs(input);
353
+ const args = argvFor(spec.params, input);
219
354
  const result = await runner(spec.command, args);
220
355
  const capturedAt = new Date().toISOString();
221
356
  const evidence = {
@@ -0,0 +1,44 @@
1
+ /**
2
+ * apps/cli/src/params.ts — mapeamento declarativo argv↔payload de um comando-capability
3
+ * (SPEC-046, ADR-0083).
4
+ *
5
+ * `parseArgv` e `argvFor` são inversas. Um teste de round-trip
6
+ * (`argvFor(params, parseArgv(params, argv)) === argv`) para todo spec é o contrato que impede
7
+ * as duas de divergirem — o `if/else` por comando que existia antes não tinha esse contrato.
8
+ *
9
+ * Convenção de ordem em `argvFor`: os params são emitidos na ordem em que aparecem em `params`.
10
+ * Um `positional` opcional só é seguro antes de outro `positional` se o anterior estiver sempre
11
+ * presente — na prática, opcionais ficam por último.
12
+ */
13
+ export interface InputRecord {
14
+ readonly [key: string]: unknown;
15
+ }
16
+ export type CapabilityParam = {
17
+ readonly name: string;
18
+ readonly kind: 'positional';
19
+ readonly required?: boolean;
20
+ readonly parse?: 'string' | 'int';
21
+ } | {
22
+ readonly name: string;
23
+ readonly kind: 'flag';
24
+ } | {
25
+ readonly name: string;
26
+ readonly kind: 'flag-value';
27
+ readonly flag: string;
28
+ readonly required?: boolean;
29
+ readonly parse?: 'string' | 'int';
30
+ } | {
31
+ readonly name: string;
32
+ readonly kind: 'rest';
33
+ readonly required?: boolean;
34
+ };
35
+ /** argv → `{ [param.name]: value }`. Flags desconhecidas são ignoradas. */
36
+ export declare function parseArgv(params: readonly CapabilityParam[], argv: readonly string[]): InputRecord;
37
+ /** `{ [param.name]: value }` → argv, na ordem de `params`. */
38
+ export declare function argvFor(params: readonly CapabilityParam[], input: InputRecord): string[];
39
+ /**
40
+ * Validador base a partir de `params`: exige os `required` presentes e o tipo certo
41
+ * (`int` → número finito; resto → string). Specs com limite adicional (range, enum) embrulham
42
+ * esta função.
43
+ */
44
+ export declare function makeValidator(params: readonly CapabilityParam[]): (value: unknown) => InputRecord;
@@ -0,0 +1,123 @@
1
+ /**
2
+ * apps/cli/src/params.ts — mapeamento declarativo argv↔payload de um comando-capability
3
+ * (SPEC-046, ADR-0083).
4
+ *
5
+ * `parseArgv` e `argvFor` são inversas. Um teste de round-trip
6
+ * (`argvFor(params, parseArgv(params, argv)) === argv`) para todo spec é o contrato que impede
7
+ * as duas de divergirem — o `if/else` por comando que existia antes não tinha esse contrato.
8
+ *
9
+ * Convenção de ordem em `argvFor`: os params são emitidos na ordem em que aparecem em `params`.
10
+ * Um `positional` opcional só é seguro antes de outro `positional` se o anterior estiver sempre
11
+ * presente — na prática, opcionais ficam por último.
12
+ */
13
+ function coerce(value, parse) {
14
+ return parse === 'int' ? Number(value) : value;
15
+ }
16
+ /** argv → `{ [param.name]: value }`. Flags desconhecidas são ignoradas. */
17
+ export function parseArgv(params, argv) {
18
+ const positionals = params.filter((p) => p.kind === 'positional');
19
+ const rest = params.find((p) => p.kind === 'rest');
20
+ const flagValues = new Map(params
21
+ .filter((p) => p.kind === 'flag-value')
22
+ .map((p) => [p.flag, p]));
23
+ const flags = new Map(params
24
+ .filter((p) => p.kind === 'flag')
25
+ .map((p) => [`--${p.name}`, p]));
26
+ const out = {};
27
+ const restParts = [];
28
+ let posIdx = 0;
29
+ for (let i = 0; i < argv.length; i += 1) {
30
+ const tok = argv[i];
31
+ if (tok.startsWith('--')) {
32
+ const fv = flagValues.get(tok);
33
+ if (fv !== undefined) {
34
+ const raw = argv[i + 1];
35
+ if (raw !== undefined) {
36
+ out[fv.name] = coerce(raw, fv.parse);
37
+ i += 1;
38
+ }
39
+ continue;
40
+ }
41
+ const fl = flags.get(tok);
42
+ if (fl !== undefined) {
43
+ out[fl.name] = true;
44
+ continue;
45
+ }
46
+ continue; // flag desconhecida — ignora
47
+ }
48
+ if (posIdx < positionals.length) {
49
+ const p = positionals[posIdx];
50
+ posIdx += 1;
51
+ out[p.name] = coerce(tok, p.parse);
52
+ }
53
+ else if (rest !== undefined) {
54
+ restParts.push(tok);
55
+ }
56
+ }
57
+ if (rest !== undefined && restParts.length > 0)
58
+ out[rest.name] = restParts.join(' ');
59
+ return out;
60
+ }
61
+ /** `{ [param.name]: value }` → argv, na ordem de `params`. */
62
+ export function argvFor(params, input) {
63
+ const argv = [];
64
+ for (const p of params) {
65
+ const value = input[p.name];
66
+ if (p.kind === 'positional') {
67
+ if (value !== undefined)
68
+ argv.push(String(value));
69
+ }
70
+ else if (p.kind === 'flag-value') {
71
+ if (value !== undefined)
72
+ argv.push(p.flag, String(value));
73
+ }
74
+ else if (p.kind === 'flag') {
75
+ if (value === true)
76
+ argv.push(`--${p.name}`);
77
+ }
78
+ else {
79
+ // rest
80
+ const text = value === undefined ? '' : String(value);
81
+ if (text.length > 0)
82
+ argv.push(...text.split(' '));
83
+ }
84
+ }
85
+ return argv;
86
+ }
87
+ /**
88
+ * Validador base a partir de `params`: exige os `required` presentes e o tipo certo
89
+ * (`int` → número finito; resto → string). Specs com limite adicional (range, enum) embrulham
90
+ * esta função.
91
+ */
92
+ export function makeValidator(params) {
93
+ return (value) => {
94
+ if (value === undefined || value === null)
95
+ value = {};
96
+ if (typeof value !== 'object' || Array.isArray(value))
97
+ throw new Error('input deve ser um objeto');
98
+ const input = value;
99
+ const out = {};
100
+ for (const p of params) {
101
+ const v = input[p.name];
102
+ if (v === undefined) {
103
+ if ('required' in p && p.required)
104
+ throw new Error(`campo obrigatório ausente: ${p.name}`);
105
+ continue;
106
+ }
107
+ const wantsInt = (p.kind === 'positional' || p.kind === 'flag-value') && p.parse === 'int';
108
+ if (wantsInt) {
109
+ if (typeof v !== 'number' || !Number.isFinite(v))
110
+ throw new Error(`${p.name} deve ser um número`);
111
+ }
112
+ else if (p.kind === 'flag') {
113
+ if (typeof v !== 'boolean')
114
+ throw new Error(`${p.name} deve ser booleano`);
115
+ }
116
+ else if (typeof v !== 'string' || v.trim().length === 0) {
117
+ throw new Error(`${p.name} deve ser uma string não-vazia`);
118
+ }
119
+ out[p.name] = v;
120
+ }
121
+ return out;
122
+ };
123
+ }