forjajs 5.1.0 → 5.3.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.
Files changed (119) hide show
  1. package/CHANGELOG.md +108 -0
  2. package/README.md +52 -4
  3. package/README.pt-BR.md +54 -4
  4. package/dist/apps/cli/src/index.d.ts +0 -1
  5. package/dist/apps/cli/src/index.js +43 -32
  6. package/dist/apps/dashboard/app/api/forja/[...path]/route.js +34 -1
  7. package/dist/apps/dashboard/app/api/forja/capabilities.d.ts +26 -0
  8. package/dist/apps/dashboard/app/api/forja/capabilities.js +39 -0
  9. package/dist/apps/dashboard/app/dashboard-client.jsx +607 -42
  10. package/dist/apps/server/src/forja-nest.module.d.ts +6 -0
  11. package/dist/apps/server/src/forja-nest.module.js +55 -0
  12. package/dist/apps/server/src/main.d.ts +21 -4
  13. package/dist/apps/server/src/main.js +79 -57
  14. package/dist/apps/server/src/task-planning-service.d.ts +29 -0
  15. package/dist/apps/server/src/task-planning-service.js +195 -0
  16. package/dist/apps/server/src/task-runtime-coordinator.d.ts +57 -0
  17. package/dist/apps/server/src/task-runtime-coordinator.js +229 -0
  18. package/dist/bin/forja.js +3 -2
  19. package/dist/lib/agent-evals.d.ts +138 -0
  20. package/dist/lib/agent-evals.js +365 -0
  21. package/dist/lib/cli-output.js +14 -2
  22. package/dist/lib/code-context.d.ts +33 -5
  23. package/dist/lib/code-context.js +70 -5
  24. package/dist/lib/context-builder.d.ts +49 -4
  25. package/dist/lib/context-builder.js +114 -47
  26. package/dist/lib/core/coverage-gate.d.ts +59 -0
  27. package/dist/lib/core/coverage-gate.js +58 -0
  28. package/dist/lib/core/doc-graph.d.ts +38 -0
  29. package/dist/lib/core/doc-graph.js +83 -0
  30. package/dist/lib/core/health.js +286 -5
  31. package/dist/lib/core/journey.js +26 -0
  32. package/dist/lib/core/registry.js +81 -6
  33. package/dist/lib/docs-reference.d.ts +35 -0
  34. package/dist/lib/docs-reference.js +57 -0
  35. package/dist/lib/exec.d.ts +55 -0
  36. package/dist/lib/exec.js +141 -0
  37. package/dist/lib/project-wiring.js +6 -2
  38. package/dist/lib/session-memory.d.ts +38 -0
  39. package/dist/lib/session-memory.js +206 -0
  40. package/dist/lib/spec-trace.d.ts +46 -0
  41. package/dist/lib/spec-trace.js +184 -0
  42. package/dist/packages/adapter-git/src/index.js +13 -4
  43. package/dist/packages/adapter-nest/src/index.d.ts +2 -1
  44. package/dist/packages/adapter-nest/src/index.js +59 -1
  45. package/dist/packages/adapter-sqlite/src/index.d.ts +15 -1
  46. package/dist/packages/adapter-sqlite/src/index.js +61 -1
  47. package/dist/packages/context/src/index.d.ts +2 -0
  48. package/dist/packages/context/src/index.js +36 -15
  49. package/dist/packages/contracts/src/index.d.ts +64 -0
  50. package/dist/packages/core/src/index.d.ts +9 -1
  51. package/dist/packages/core/src/index.js +28 -3
  52. package/dist/packages/graph/src/index.js +14 -5
  53. package/dist/packages/llm/src/index.js +7 -24
  54. package/dist/packages/mcp/src/index.d.ts +8 -0
  55. package/dist/packages/mcp/src/index.js +12 -1
  56. package/dist/packages/observability/src/index.d.ts +11 -0
  57. package/dist/packages/observability/src/index.js +3 -0
  58. package/dist/packages/orchestration/src/index.d.ts +15 -1
  59. package/dist/packages/orchestration/src/index.js +127 -21
  60. package/dist/packages/planner/src/index.d.ts +7 -1
  61. package/dist/packages/planner/src/index.js +67 -10
  62. package/dist/packages/planner/src/proposal-store.d.ts +30 -0
  63. package/dist/packages/planner/src/proposal-store.js +109 -0
  64. package/dist/packages/policy/src/index.d.ts +9 -16
  65. package/dist/packages/policy/src/index.js +114 -31
  66. package/dist/packages/runtime/src/index.d.ts +16 -2
  67. package/dist/packages/runtime/src/index.js +176 -61
  68. package/dist/scripts/build-smart-context.d.ts +2 -0
  69. package/dist/scripts/build-smart-context.js +12 -3
  70. package/dist/scripts/code-context.d.ts +3 -1
  71. package/dist/scripts/code-context.js +13 -3
  72. package/dist/scripts/coverage-gate.d.ts +2 -0
  73. package/dist/scripts/coverage-gate.js +101 -0
  74. package/dist/scripts/eval-agents.d.ts +11 -0
  75. package/dist/scripts/eval-agents.js +96 -0
  76. package/dist/scripts/gen-commands-doc.d.ts +2 -0
  77. package/dist/scripts/gen-commands-doc.js +18 -0
  78. package/dist/scripts/hook-session-memory.d.ts +9 -0
  79. package/dist/scripts/hook-session-memory.js +20 -0
  80. package/dist/scripts/hook-session-start.js +34 -0
  81. package/dist/scripts/llm-fit.js +15 -6
  82. package/dist/scripts/simulate.js +16 -4
  83. package/dist/scripts/spec-trace.d.ts +10 -0
  84. package/dist/scripts/spec-trace.js +73 -0
  85. package/dist/scripts/sync-universal-memory.js +69 -4
  86. package/dist/scripts/token-benchmark.d.ts +33 -1
  87. package/dist/scripts/token-benchmark.js +179 -5
  88. package/dist/scripts/token-economy.js +3 -1
  89. package/dist/scripts/tools-doctor.d.ts +16 -1
  90. package/dist/scripts/tools-doctor.js +58 -17
  91. package/docs/commands.md +155 -0
  92. package/docs/fluxo.md +11 -7
  93. package/docs/init-project.md +3 -1
  94. package/docs/llm-fit-loop.md +20 -0
  95. package/docs/manual-operacional-cli-sdd-gsd.md +3 -2
  96. package/docs/produto/factsheet-marketing.md +7 -5
  97. package/docs/produto/roteiro-demo.md +14 -5
  98. package/docs/quick-reference.md +3 -3
  99. package/docs/token-optimization.md +10 -6
  100. package/memory/90-decisions/0091-memoria-de-sessao-por-hooks.md +40 -0
  101. package/memory/90-decisions/0092-criterios-de-aceite-ligados-a-testes.md +37 -0
  102. package/memory/90-decisions/0093-avaliacoes-com-agentes-reais.md +40 -0
  103. package/package.json +4 -2
  104. package/specs/avaliacoes-de-agentes/spec.md +52 -0
  105. package/specs/criterios-ligados-a-testes/spec.md +42 -0
  106. package/specs/memoria-de-sessao/spec.md +48 -0
  107. package/specs/v6-agent-runtime-portable/spec.md +83 -0
  108. package/specs/v6-core-consolidation/spec.md +70 -0
  109. package/specs/v6-docs-drift/spec.md +85 -0
  110. package/specs/v6-quality-gates/spec.md +104 -0
  111. package/specs/v6-token-economy/spec.md +84 -0
  112. package/templates/evals/agents/adr.json +25 -0
  113. package/templates/evals/agents/memoria.json +32 -0
  114. package/templates/evals/agents/proxima-acao.json +29 -0
  115. package/templates/evals/agents/spec-nova.json +26 -0
  116. package/templates/evals/agents/teste-do-criterio.json +29 -0
  117. package/templates/project/AGENTS.md +7 -0
  118. package/templates/project/CLAUDE.md +3 -2
  119. package/templates/project/skills/testing/SKILL.md +1 -1
package/CHANGELOG.md CHANGED
@@ -13,6 +13,114 @@ GitHub reusa esse bloco. O README também é reconciliado na mesma entrega — v
13
13
 
14
14
  ---
15
15
 
16
+ ## [5.3.1] — 2026-11-16 — Windows funcional
17
+
18
+ ### O que melhorou
19
+
20
+ - **`llm:run`, `llm:doctor` e `eval:agents` funcionam no Windows.** O Forja encontra e executa
21
+ os CLIs de agente instalados pelo npm (`codex.cmd`, `claude.cmd`, `gemini.cmd`) sem WSL.
22
+ O timeout derruba a árvore inteira do processo — um agente estourado para de queimar token.
23
+ - **`forja simulate` funciona no Windows.** O worktree Git é criado, o comando roda e a
24
+ limpeza fecha sem EPERM. O npm é resolvido pelo shim `.cmd` correto.
25
+ - **`spec:trace` conta critérios em checkouts CRLF.** Projetos clonados no Windows não
26
+ reportam mais 0/0 critérios por causa do separador de linha.
27
+ - **O CI bloqueia em toda célula.** Windows deixou de ser tolerância informacional e agora
28
+ segura o merge como ubuntu e macOS. Regressões de plataforma não chegam ao release.
29
+
30
+ ### Corrigido
31
+
32
+ - Spawn de `.cmd`/`.bat` sem `shell: true` (CVE-2024-27980) resolvido por launcher próprio
33
+ com quoting de cmd.exe testado contra injeção de argumentos (#86).
34
+ - `resolveCommand` prefere extensão executável (`.cmd`/`.exe`) sobre scripts sem extensão
35
+ que o `where` lista primeiro (#86).
36
+ - `sandboxEnvironment` inclui `APPDATA`, `LOCALAPPDATA`, `COMSPEC`, `PATHEXT` — npm e git
37
+ funcionam dentro do worktree sem herdar secrets (#86).
38
+ - Caminhos 8.3 (`RUNNER~1`) canonicalizados com `realpathSync` antes de comparação (#86).
39
+ - `parseCriteria` aceita CRLF (`\r?\n`) no checklist de specs (#86).
40
+
41
+ ### Adicionado
42
+
43
+ - `lib/exec.ts`: módulo portável de subprocesso — `resolveCommand`, `spawnAgent`, `runShell`,
44
+ `killTree`. Sem dependência nova. 14 testes incluindo roundtrip de argumentos hostis (#86).
45
+
46
+ ---
47
+
48
+ ## [5.3.0] — 2026-11-14 — Supervisão, execução vinculada e qualidade verificável
49
+
50
+ ### O que melhorou
51
+
52
+ - **Supervisão num painel de leitura.** Cinco abas reúnem próxima ação, rastreabilidade dos
53
+ critérios, custos observados, gates e operação. O painel usa as capacidades de leitura
54
+ declaradas pelo servidor, exige autenticação e não inventa custo quando não há uso medido.
55
+ - **Planejamento conectado ao contexto real.** A composição do servidor pode produzir propostas
56
+ revisáveis a partir de tarefas, handoffs e memória, com orçamento e proveniência. A revisão
57
+ fica persistida e verifica mudanças nas fontes; aprovar um plano não dispara execução nem
58
+ substitui a autorização das capacidades.
59
+ - **Tarefas acompanham a execução supervisionada.** Runtime, tarefa e handoff mantêm vínculos e
60
+ recuperação persistente. Conclusão exige validação independente; falha ou ausência de checks
61
+ não libera dependências. Uma sprint pausada impede novos pedidos de execução ou retomada,
62
+ sem impedir cancelamento nem reconciliação de resultados terminais.
63
+ - **Contexto mais enxuto e qualidade mensurável.** Trechos FTS5, sincronização incremental e
64
+ orçamento no contexto de código reduzem conteúdo desnecessário. A documentação de comandos
65
+ é derivada do registro; o diagnóstico detecta divergências e a cobertura tem piso versionado.
66
+ - **Quem vem da 5.1.0 também recebe as melhorias descritas na seção 5.2.0:** checkpoints de
67
+ sessão, critérios de aceite ligados a testes, avaliação de agentes e isolamento da auditoria
68
+ durante a suíte de testes.
69
+
70
+ ### Segurança e correções
71
+
72
+ - A autorização de capacidades usa categorias registradas pelo host, não a classificação
73
+ fornecida pelo cliente. A correção protege o caminho de execução supervisionada contra
74
+ autorização incorreta de operações de escrita.
75
+ - Aprovações ficam vinculadas à operação, entrada validada e escopo. Mudanças incompatíveis
76
+ com uma aprovação anterior exigem nova aprovação; evidências contraditórias não sustentam aceite.
77
+ - Falhas do CLI preservam o diagnóstico e não são convertidas em sucesso do runtime.
78
+ - Caminhos e leitura de documentos toleram diferenças de separadores e CRLF; a saída JSON
79
+ extensa não é truncada ao encerrar o processo.
80
+
81
+ ### Uso e limites conhecidos
82
+
83
+ - Integrações que registram capacidades podem declarar `CapabilityRegistration.categories`;
84
+ quando ausente, a classificação usa `definition.permissions`. `categories` enviado numa
85
+ requisição não altera a autorização. Preserve as categorias específicas no registro do host.
86
+ - O servidor padrão continua somente leitura. Planejamento com escrita, revisão e conclusão
87
+ validada exigem política, revisor confiável e validator configurados na composição do host.
88
+ - O dashboard é opcional e operado a partir do checkout; a instalação npm continua CLI-first.
89
+ - Pausar uma sprint não interrompe um handler já em andamento nem torna atômicas pausas
90
+ concorrentes com um pedido de execução.
91
+ - O inventário Windows de runtime de agentes, `simulate` e jornada `spec:trace` permanece
92
+ aberto em `specs/v6-quality-gates/spec.md`; esta versão não declara portabilidade completa.
93
+
94
+ ## [5.2.0] — 2026-10-22 — Memória de sessão, critérios ligados a testes e avaliação de agentes
95
+
96
+ ### O que melhorou
97
+
98
+ - **A IA não perde o fio quando o contexto é compactado.** Em projetos conectados ao Claude Code, cada
99
+ sessão que muda alguma coisa deixa um checkpoint em `memory/60-runs/sessions/` (arquivos editados,
100
+ specs tocadas, comandos `forja`, commits), atualizado ao fim de cada turno e antes de compactar.
101
+ Depois da compactação o checkpoint volta para a IA; numa sessão nova, ela vê onde a anterior parou.
102
+ Nenhum texto de prompt nem comando inteiro entra na memória. Projetos existentes ganham os hooks com
103
+ `forja project:upgrade --apply` (SPEC-052, ADR-0091).
104
+ - **Dá para saber quais critérios de aceite têm teste.** `forja spec:trace` lista, para cada `AC-N`
105
+ de cada spec, os testes que o citam (`SPEC-NNN AC-N` no nome ou num comentário), os critérios sem
106
+ teste e as citações a critérios que não existem mais. `--strict` vira gate: spec aprovada ou pronta
107
+ com lacuna sai com 2. O `AGENTS.md` e a skill `testing` do projeto ensinam a convenção (SPEC-053,
108
+ ADR-0092). Fixture com citações de exemplo fica entre `spec-trace:off` e `spec-trace:on`. No
109
+ próprio Forja, 48 de 340 critérios têm teste citando — o ponto de partida.
110
+ - **Dá para medir se os agentes seguem o Forja.** `forja eval:agents --agent claude|codex` roda uma
111
+ suíte de tarefas (registrar decisão, começar feature, testar um critério, responder pela memória,
112
+ achar a próxima ação) com o agente real num projeto descartável, corrige pelo que ficou no disco e
113
+ guarda o histórico em `.context/agent-evals.jsonl`, comparando com a execução anterior. Custa uma
114
+ sessão real por caso: há teto de custo por caso no Claude e timeout nos dois (SPEC-054, ADR-0093).
115
+
116
+ ### Corrigido
117
+
118
+ - **`npm test` não grava mais na sua trilha de auditoria.** Dois testes chamavam o CLI com o ambiente
119
+ do shell e deixavam entradas `spec:new` e `simulate --json` em `~/forja-workspace/.context/forja-runs.jsonl`
120
+ a cada execução da suíte. A suíte agora roda inteira com um workspace isolado
121
+ (`test/isolate-workspace.mjs`, pré-carregado pelo script `test`), e `test/test-isolation.test.js`
122
+ falha se o isolamento sair.
123
+
16
124
  ## [5.1.0] — 2026-10-21 — Skills, template de SaaS e mais agentes
17
125
 
18
126
  ### O que melhorou
package/README.md CHANGED
@@ -98,7 +98,8 @@ process followed?", the answer is a file, not a promise.
98
98
  - **Projects born connected to your AI** — `project:new` scaffolds a full project (memory, agents,
99
99
  a NestJS backend as the default boilerplate) and wires it to the AI you use: native instructions
100
100
  (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, Copilot), Claude Code hooks that open every session with the
101
- project state and attach the spec you mention, six role sub-agents, and the Forja MCP server in
101
+ project state, attach the spec you mention and save a checkpoint of each session to memory
102
+ (returned to the AI after compaction), six role sub-agents, and the Forja MCP server in
102
103
  Claude, Codex, Gemini and Copilot (VS Code). The
103
104
  memory is indexed from the first minute. `project:wire --check` proves it; `project:upgrade --apply`
104
105
  re-wires older projects without touching the user's code — or the whole workspace with `--all`
@@ -112,8 +113,10 @@ process followed?", the answer is a file, not a promise.
112
113
  against the installed tarball, and fail if any command writes into the package itself.
113
114
  - **3 integrated capabilities** (ADR-0016): **codegraph** (code analysis via MCP), **harness**
114
115
  (agent-team design), **ai-engineering** (knowledge base).
115
- - **LLM Fit Loop** — adapters de CLI (Codex, Claude; Gemini, Copilot CLI, Cursor e opencode em modo somente leitura), perfis no workspace, probes sem custo, observações e
116
- recomendação determinística por papel/tarefa; credenciais nunca entram no Forja.
116
+ - **LLM Fit Loop** — CLI adapters (Codex, Claude; Gemini, Copilot CLI, Cursor and opencode in
117
+ read-only mode), workspace profiles, no-cost probes, observations and deterministic recommendation
118
+ per role/task; credentials never enter Forja. `eval:agents` measures whether real agents follow the
119
+ Forja method on a task suite in a throwaway project (ADR-0093).
117
120
  - **Engineering Control Plane** (v3.0, ADR-0078) — the Engineering Graph turns ADRs/SPECs into
118
121
  first-class, queryable nodes; the Architecture Constitution checks real code against decisions
119
122
  already recorded; the Change Risk Engine scores a change 0-100 with named, evidenced factors;
@@ -122,6 +125,31 @@ process followed?", the answer is a file, not a promise.
122
125
  recommended agents, similar past incidents — before you start. Every score is information for a
123
126
  human/policy rule to consult, never an autonomous decision on its own.
124
127
 
128
+ ## What's new in 5.3.0
129
+
130
+ - **Read-only supervision dashboard:** overview, acceptance-criteria traceability, observed costs,
131
+ gates and operations share the server's capability registry. The optional dashboard runs from
132
+ this checkout and requires an access token; see the [demo guide](docs/produto/roteiro-demo.md).
133
+ Installing the npm package remains a CLI-first workflow.
134
+ - **Context-backed planning and linked execution:** server composition connects tasks, handoffs,
135
+ memory and budgets to persisted, reviewable proposals. Plan review does not authorize execution;
136
+ completion requires independent checks. The default server remains read-only: writable planning,
137
+ trusted review and validation require explicit host configuration.
138
+ - **Authorization belongs to the host:** registered capability categories determine policy, not
139
+ request-supplied categories. Custom registrations can set `CapabilityRegistration.categories`;
140
+ otherwise classification uses `definition.permissions`. Preserve custom categories in the host
141
+ registration rather than passing them only with execution requests.
142
+ - **Paused sprints reject new execute/resume requests** for linked runs, while cancellation and
143
+ terminal reconciliation remain available. This does not interrupt an in-flight handler or make
144
+ concurrent sprint changes atomic with dispatch.
145
+ - **Smaller context and measurable quality:** FTS5 snippets, incremental memory indexing, generated
146
+ command documentation and a versioned coverage floor. Upgrading from 5.1.0 also includes session
147
+ checkpoints, acceptance-criteria tracing and agent evaluations documented in the changelog.
148
+
149
+ Windows is fully supported since 5.3.1: `llm:run`, `llm:doctor`, `eval:agents`, `simulate` and
150
+ `spec:trace` work without WSL. The CI matrix blocks on all three OSes.
151
+ Details and upgrade notes: [CHANGELOG](CHANGELOG.md).
152
+
125
153
  ## ⚡ Quick start
126
154
 
127
155
  ```bash
@@ -129,7 +157,10 @@ process followed?", the answer is a file, not a promise.
129
157
  npm install -g forjajs
130
158
  forja # help grouped by domain
131
159
 
132
- # Prepare the production workspace (the fixed home for your projects)
160
+ # First run: creates the workspace and indexes the memory, confirming each step
161
+ forja setup # add --yes to accept every default
162
+
163
+ # Or prepare the production workspace by hand (the fixed home for your projects)
133
164
  forja workspace:init
134
165
 
135
166
  # Create a new project (generated in ~/forja-workspace/projects/<name>, already wired to your AI)
@@ -143,6 +174,7 @@ forja spec:new my-feature
143
174
  forja spec:plan my-feature
144
175
  forja spec:tasks my-feature
145
176
  forja spec:check my-feature
177
+ forja spec:trace my-feature # AC-N criteria × tests that cite them (SPEC-NNN AC-N)
146
178
  ```
147
179
 
148
180
  ### Already have a repository?
@@ -408,6 +440,7 @@ The docs are written in **Brazilian Portuguese** — that's part of the project'
408
440
  output, code, and ADRs are readable regardless of language.
409
441
 
410
442
  - [`DOC-MAP.md`](DOC-MAP.md) — map by role and by topic (start here)
443
+ - [`docs/commands.md`](docs/commands.md) — full command reference, generated from the registry (never hand-edited)
411
444
  - [`docs/processo-projeto.md`](docs/processo-projeto.md) — create vs update a project
412
445
  - [`docs/fluxo.md`](docs/fluxo.md) — the CLI-first cycle map
413
446
  - [`AGENTS.md`](AGENTS.md) — the 6 roles and the topology
@@ -429,6 +462,21 @@ output, code, and ADRs are readable regardless of language.
429
462
  The throughline: **turn knowledge that lives as convention into an executable invariant.** Each item
430
463
  below either closes a framework frontier with a gate, or carries that pattern into generated projects.
431
464
 
465
+ **Shipped** (v5.3.0 — Supervised execution)
466
+
467
+ - [x] **Read-only supervision dashboard** — overview, acceptance-criteria traceability, observed
468
+ costs, gates and operations share the server's capability registry; optional, token-gated,
469
+ runs from the checkout (CLI-first install unchanged).
470
+ - [x] **Context-backed planning & linked execution** — tasks, handoffs, memory and budgets connect
471
+ to persisted, reviewable proposals; plan review does not authorize execution; completion requires
472
+ independent checks. Default server remains read-only.
473
+ - [x] **Host-owned authorization** — registered capability categories determine policy, not
474
+ request-supplied categories; custom registrations declare `CapabilityRegistration.categories`.
475
+ - [x] **Paused-sprint guards** — linked runs reject execute/resume while the sprint is paused;
476
+ cancellation and terminal reconciliation remain available.
477
+ - [x] **Compact context & measurable quality** — FTS5 snippets, incremental memory indexing,
478
+ generated command documentation and a versioned coverage floor.
479
+
432
480
  **Shipped** (v3.0.0 — Engineering Control Plane, ADR-0078)
433
481
 
434
482
  - [x] **Engineering Graph** — ADRs/SPECs as first-class, queryable nodes (`adr:list/show/impact/graph`),
package/README.pt-BR.md CHANGED
@@ -85,13 +85,38 @@ E cada comando acima ficou gravado em `.context/forja-runs.jsonl` — quando a g
85
85
  - **Pipeline SDD + GSD** — `spec → plan → tasks → check`, decisões registradas como ADRs.
86
86
  - **Auto-verificação (invariantes que rodam)** — o framework prova a si mesmo: uma família de gates guarda cada fronteira (núcleo, tarball, coerência de doc, topologia de agentes, projeto gerado), e `check:all` roda a bateria inteira num veredito só. A governança deixa de depender de disciplina — vira harness.
87
87
  - **Economia de token medida, não afirmada** — a memória (`context.md` como mapa) economiza ~60% vs explorar no frio, e `token:economy` **prova** isso nos seus domínios. `code:context` entrega o mapa pronto; `memory:audit` garante que ele não mente sobre o código.
88
- - **Projetos que nascem conectados à sua IA** — `project:new` cria o scaffold completo (memória, agentes, backend NestJS como boilerplate padrão) e liga o projeto à IA que você usa: instruções nativas (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, Copilot), hooks do Claude Code que abrem cada sessão com o estado do projeto e anexam a spec citada no prompt, seis sub-agents por papel e o servidor MCP do Forja no Claude, Codex, Gemini e Copilot (VS Code). A memória já nasce indexada. `project:wire --check` prova a conexão; `project:upgrade --apply` religa projetos antigos sem tocar no código do usuário — ou o workspace inteiro com `--all` (ADR-0086). O backend NestJS segue o padrão oficial do NestJS 12 (ESM, Vitest, oxlint), e a página `/api/ops` mostra specs, handoffs em aberto e a memória indexada do projeto.
88
+ - **Projetos que nascem conectados à sua IA** — `project:new` cria o scaffold completo (memória, agentes, backend NestJS como boilerplate padrão) e liga o projeto à IA que você usa: instruções nativas (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, Copilot), hooks do Claude Code que abrem cada sessão com o estado do projeto, anexam a spec citada no prompt e gravam um checkpoint de cada sessão na memória (devolvido à IA depois da compactação), seis sub-agents por papel e o servidor MCP do Forja no Claude, Codex, Gemini e Copilot (VS Code). A memória já nasce indexada. `project:wire --check` prova a conexão; `project:upgrade --apply` religa projetos antigos sem tocar no código do usuário — ou o workspace inteiro com `--all` (ADR-0086). O backend NestJS segue o padrão oficial do NestJS 12 (ESM, Vitest, oxlint), e a página `/api/ops` mostra specs, handoffs em aberto e a memória indexada do projeto.
89
89
  - **Templates validados** — `project:new <nome> --template clean-arch` (DDD) ou `--template saas-starter` (SaaS multi-tenant com assinatura e faturamento) parte de um boilerplate cuja instalação, build, testes e lint são provados no CI; `project:templates` lista o que é template e o que é arquitetura de referência (ADR-0088).
90
- - **LLM Fit Loop** — `llm:run` executa tarefas supervisionadas por CLI (Codex, Claude; Gemini, Copilot CLI, Cursor e opencode em modo somente leitura), com perfis no workspace, probes sem custo, observações e recomendação por papel/tarefa; credenciais nunca entram no Forja (ADR-0090).
90
+ - **LLM Fit Loop** — `llm:run` executa tarefas supervisionadas por CLI (Codex, Claude; Gemini, Copilot CLI, Cursor e opencode em modo somente leitura), com perfis no workspace, probes sem custo, observações e recomendação por papel/tarefa; credenciais nunca entram no Forja (ADR-0090). `eval:agents` mede se agentes reais seguem o método do Forja numa suíte de tarefas em projeto descartável (ADR-0093).
91
91
  - **A jornada do usuário é gate** — `npm test` e `release:check` percorrem a jornada inteira (workspace → projeto → memória, contexto, specs, hooks, MCP e handoffs dentro do projeto), contra o fonte e contra o pacote instalado, e reprovam se algum comando escrever dentro do pacote.
92
92
  - **3 capacidades integradas** (ADR-0016): **codegraph** (análise de código via MCP), **harness** (desenho de times de agentes), **ai-engineering** (base de conhecimento).
93
93
  - **Engineering Control Plane** (v3.0, ADR-0078) — o Engineering Graph vira ADRs/SPECs em nós de primeira classe consultáveis; a Architecture Constitution checa o código real contra decisões já registradas; o Change Risk Engine pontua uma mudança 0-100 com fatores nomeados e evidenciados; `forja simulate` testa um ref num worktree isolado e nunca promove sozinho. Uma façade só, `forja engineer "<objetivo>"`, compõe tudo isso — contexto, ADRs relevantes, checagem de arquitetura, risco, agentes recomendados, incidentes parecidos — antes de você começar. Todo score é informação pra um humano/regra de política consultar, nunca uma decisão autônoma por si só.
94
94
 
95
+ ## Novidades da 5.3.0
96
+
97
+ - **Painel de supervisão somente leitura:** visão, rastreabilidade de critérios, custos observados,
98
+ gates e operação usam o registro de capacidades do servidor. O dashboard opcional roda pelo
99
+ checkout e exige token de acesso; veja o [roteiro de demonstração](docs/produto/roteiro-demo.md).
100
+ A instalação do pacote npm continua CLI-first.
101
+ - **Planejamento com contexto e execução vinculada:** a composição do servidor conecta tarefas,
102
+ handoffs, memória e orçamento a propostas persistidas e revisáveis. Revisar um plano não autoriza
103
+ execução; concluir exige checks independentes. O servidor padrão continua somente leitura:
104
+ planejamento com escrita, revisão confiável e validação exigem configuração explícita do host.
105
+ - **A autorização pertence ao host:** as categorias registradas da capacidade determinam a
106
+ política, não as categorias enviadas na requisição. Registros próprios podem declarar
107
+ `CapabilityRegistration.categories`; na ausência, a classificação usa `definition.permissions`.
108
+ Preserve categorias próprias no registro do host, em vez de enviá-las só nos pedidos de execução.
109
+ - **Sprint pausada recusa novos pedidos de execução e retomada** de runs vinculados, preservando
110
+ cancelamento e reconciliação terminal. Isso não interrompe um handler em andamento nem torna
111
+ atômicas as mudanças concorrentes na sprint e o disparo de execução.
112
+ - **Contexto menor e qualidade mensurável:** trechos FTS5, indexação incremental de memória,
113
+ documentação de comandos gerada e piso de cobertura versionado. Quem atualiza da 5.1.0 também
114
+ recebe checkpoints de sessão, rastreabilidade de critérios e avaliação de agentes descritos no changelog.
115
+
116
+ O Windows é suportado desde a 5.3.1: `llm:run`, `llm:doctor`, `eval:agents`, `simulate` e
117
+ `spec:trace` funcionam sem WSL. O CI bloqueia nos três SOs.
118
+ Detalhes e notas de atualização: [CHANGELOG](CHANGELOG.md).
119
+
95
120
  ## ⚡ Quick start
96
121
 
97
122
  ```bash
@@ -99,7 +124,10 @@ E cada comando acima ficou gravado em `.context/forja-runs.jsonl` — quando a g
99
124
  npm install -g forjajs
100
125
  forja # help agrupado por domínio
101
126
 
102
- # Preparar o workspace de produção (canto fixo dos projetos)
127
+ # Primeiro uso: cria o workspace e indexa a memória, confirmando cada passo
128
+ forja setup # com --yes aceita todos os padrões
129
+
130
+ # Ou preparar o workspace de produção à mão (canto fixo dos projetos)
103
131
  forja workspace:init
104
132
 
105
133
  # Criar um projeto novo (gera em ~/forja-workspace/projects/<nome>, já conectado à sua IA)
@@ -113,6 +141,7 @@ forja spec:new minha-feature
113
141
  forja spec:plan minha-feature
114
142
  forja spec:tasks minha-feature
115
143
  forja spec:check minha-feature
144
+ forja spec:trace minha-feature # critérios AC-N × testes que os citam (SPEC-NNN AC-N)
116
145
  ```
117
146
 
118
147
  ### Já tem um repositório?
@@ -203,6 +232,11 @@ Os scripts npm do repo são aliases finos que roteiam pelo core.
203
232
  ## Comandos essenciais
204
233
 
205
234
  ```bash
235
+ # Orientação — o caminho feliz
236
+ forja status # onde estou: workspace, sprint, specs, runs, handoffs
237
+ forja next # o que agora: uma linha — a próxima ação + o comando exato
238
+ forja help [<comando>|--all] # os essenciais, ou uso/args/exemplos de um comando
239
+
206
240
  # Workspace & projetos
207
241
  forja workspace:init # cria ~/forja-workspace
208
242
  forja project:new <nome> --ai claude,copilot # cria projeto no workspace, conectado à IA
@@ -213,7 +247,7 @@ forja project:list # lista projetos do workspace
213
247
  forja workspace:project:check <nome> # valida padrões num projeto do workspace
214
248
 
215
249
  # Pipeline SDD
216
- forja spec:new <slug> # também: spec:plan · spec:tasks · spec:check
250
+ forja spec:new <slug> # também: spec:plan · spec:tasks · spec:check · spec:trace
217
251
 
218
252
  # Sprint & handoffs (GSD)
219
253
  forja sprint:start # também: sprint:status · sprint:complete
@@ -324,6 +358,7 @@ A parte gerenciada pelo Forja em cada arquivo de instrução fica entre `<!-- fo
324
358
  ## Documentação
325
359
 
326
360
  - [`DOC-MAP.md`](DOC-MAP.md) — mapa por papel e por tópico (comece aqui)
361
+ - [`docs/commands.md`](docs/commands.md) — referência completa de comandos, gerada do registry (nunca editada à mão)
327
362
  - [`docs/processo-projeto.md`](docs/processo-projeto.md) — criar vs atualizar projeto
328
363
  - [`docs/fluxo.md`](docs/fluxo.md) — mapa do ciclo CLI-first
329
364
  - [`AGENTS.md`](AGENTS.md) — os 6 papéis e a topologia
@@ -346,6 +381,21 @@ O fio condutor: **converter conhecimento que vive em convenção em invariante e
346
381
  item abaixo ou fecha uma fronteira do framework por um gate, ou leva esse padrão para os projetos
347
382
  gerados.
348
383
 
384
+ **Entregue** (v5.3.0 — Execução supervisionada)
385
+
386
+ - [x] **Painel de supervisão somente leitura** — visão, rastreabilidade de critérios, custos
387
+ observados, gates e operação usam o registro de capacidades do servidor; opcional, com token,
388
+ roda pelo checkout (instalação CLI-first inalterada).
389
+ - [x] **Planejamento com contexto e execução vinculada** — tarefas, handoffs, memória e orçamento
390
+ conectam-se a propostas persistidas e revisáveis; revisar plano não autoriza execução; concluir
391
+ exige checks independentes. Servidor padrão continua somente leitura.
392
+ - [x] **Autorização pertence ao host** — categorias registradas da capacidade determinam a política,
393
+ não as categorias da requisição; registros próprios declaram `CapabilityRegistration.categories`.
394
+ - [x] **Guardas de sprint pausada** — runs vinculados recusam execute/resume com a sprint pausada;
395
+ cancelamento e reconciliação terminal permanecem disponíveis.
396
+ - [x] **Contexto compacto e qualidade mensurável** — trechos FTS5, indexação incremental de memória,
397
+ documentação de comandos gerada e piso de cobertura versionado.
398
+
349
399
  **Entregue** (v3.0.0 — Engineering Control Plane, ADR-0078)
350
400
 
351
401
  - [x] **Engineering Graph** — ADRs/SPECs como nós de primeira classe consultáveis
@@ -57,5 +57,4 @@ export declare function parseLegacyCommandInput(command: string, args: readonly
57
57
  readonly payload: InputRecord;
58
58
  };
59
59
  export declare function executeCliCapability(runtime: CliCapabilityRuntime, capabilityId: CapabilityId, payload: unknown, correlationId?: string): Promise<ExecutionResult>;
60
- export declare function normalizeCliResult(result: ExecutionResult): ExecutionResult;
61
60
  export {};
@@ -1,7 +1,7 @@
1
1
  import { randomUUID } from 'node:crypto';
2
2
  import { spawnSync } from 'node:child_process';
3
3
  import { CONTRACT_VERSION, } from '../../../packages/contracts/src/index.js';
4
- import { CapabilityRegistry, } from '../../../packages/core/src/index.js';
4
+ import { CapabilityRegistry, CapabilityExecutionFailure, } 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';
@@ -28,8 +28,7 @@ export const CLI_CAPABILITY_SPECS = [
28
28
  permissions: ['read'],
29
29
  risk: 'low',
30
30
  sideEffects: [],
31
- params: [],
32
- validateInput: emptyInput,
31
+ params: [{ name: 'json', kind: 'flag' }],
33
32
  },
34
33
  {
35
34
  id: 'code.impact',
@@ -130,14 +129,20 @@ export const CLI_CAPABILITY_SPECS = [
130
129
  {
131
130
  id: 'code.context',
132
131
  command: 'code:context',
133
- description: 'Pacote de contexto mínimo de um domínio (o mapa; + código com --code).',
132
+ description: 'Pacote de contexto mínimo de um domínio (o mapa; + código com --code, fatia inteira com --full).',
134
133
  categories: ['read'],
135
134
  permissions: ['read'],
136
135
  risk: 'low',
137
136
  sideEffects: [],
137
+ // Cada flag que `usage` anuncia tem que estar aqui: o roteador rebuilda o argv a partir destes
138
+ // params, e o que não é declarado é descartado em silêncio — `--full` existir no help e não chegar
139
+ // ao script é o pior tipo de flag (o usuário jura que pediu).
138
140
  params: [
139
141
  { name: 'domain', kind: 'positional' },
142
+ { name: 'query', kind: 'positional' },
140
143
  { name: 'code', kind: 'flag' },
144
+ { name: 'full', kind: 'flag' },
145
+ { name: 'project', kind: 'flag-value', flag: '--project' },
141
146
  ],
142
147
  },
143
148
  {
@@ -218,7 +223,7 @@ export const CLI_CAPABILITY_SPECS = [
218
223
  permissions: ['read'],
219
224
  risk: 'low',
220
225
  sideEffects: [],
221
- params: [],
226
+ params: [{ name: 'json', kind: 'flag' }],
222
227
  },
223
228
  {
224
229
  id: 'forja.next',
@@ -228,7 +233,32 @@ export const CLI_CAPABILITY_SPECS = [
228
233
  permissions: ['read'],
229
234
  risk: 'low',
230
235
  sideEffects: [],
231
- params: [],
236
+ params: [{ name: 'json', kind: 'flag' }],
237
+ },
238
+ // --- SPEC-057: os dois relatórios read-only que só existiam como script (dashboard/MCP) ---
239
+ {
240
+ id: 'spec.trace',
241
+ command: 'spec:trace',
242
+ description: 'Critérios de aceite × testes que os citam: cobertos, sem teste e órfãos.',
243
+ categories: ['read'],
244
+ permissions: ['read'],
245
+ risk: 'low',
246
+ sideEffects: [],
247
+ params: [
248
+ { name: 'slug', kind: 'positional' },
249
+ { name: 'strict', kind: 'flag' },
250
+ { name: 'json', kind: 'flag' },
251
+ ],
252
+ },
253
+ {
254
+ id: 'cost.economy',
255
+ command: 'cost:economy',
256
+ description: 'Custo real acumulado (USD) das execuções LLM registradas, por modelo.',
257
+ categories: ['read', 'database'],
258
+ permissions: ['read'],
259
+ risk: 'low',
260
+ sideEffects: [],
261
+ params: [{ name: 'json', kind: 'flag' }],
232
262
  },
233
263
  ];
234
264
  export const CLI_COMMAND_TO_CAPABILITY = Object.freeze(Object.fromEntries(CLI_CAPABILITY_SPECS.map((spec) => [spec.command, spec.id])));
@@ -298,7 +328,7 @@ export function parseLegacyCommandInput(command, args) {
298
328
  export async function executeCliCapability(runtime, capabilityId, payload, correlationId) {
299
329
  const definition = runtime.registry.describe(capabilityId);
300
330
  const categories = categoriesFor(definition.id);
301
- const result = await runtime.registry.execute({
331
+ return runtime.registry.execute({
302
332
  input: { capabilityId, payload },
303
333
  agent: runtime.agent,
304
334
  policy: runtime.policy,
@@ -307,23 +337,6 @@ export async function executeCliCapability(runtime, capabilityId, payload, corre
307
337
  categories,
308
338
  files: [],
309
339
  });
310
- return normalizeCliResult(result);
311
- }
312
- export function normalizeCliResult(result) {
313
- if (result.status !== 'succeeded' || result.output === undefined || !isRecord(result.output.payload))
314
- return result;
315
- const exitCode = result.output.payload.exitCode;
316
- if (typeof exitCode !== 'number' || exitCode === 0)
317
- return result;
318
- return {
319
- ...result,
320
- status: 'failed',
321
- error: {
322
- code: 'LEGACY_COMMAND_FAILED',
323
- message: `Legacy command exited with status ${exitCode}`,
324
- retryable: false,
325
- },
326
- };
327
340
  }
328
341
  function registerCliCapability(registry, runner, spec) {
329
342
  const now = new Date().toISOString();
@@ -347,6 +360,7 @@ function registerCliCapability(registry, runner, spec) {
347
360
  };
348
361
  const registration = {
349
362
  definition,
363
+ categories: spec.categories,
350
364
  validateInput: spec.validateInput ?? makeValidator(spec.params),
351
365
  validateOutput: validateCliPayload,
352
366
  handler: async (input) => {
@@ -360,11 +374,15 @@ function registerCliCapability(registry, runner, spec) {
360
374
  capturedAt,
361
375
  status: result.exitCode === 0 ? 'verified' : 'contradicted',
362
376
  };
363
- return {
377
+ const output = {
364
378
  capabilityId: spec.id,
365
379
  payload: { command: spec.command, args, ...result },
366
380
  evidence: [evidence],
367
381
  };
382
+ if (result.exitCode !== 0) {
383
+ throw new CapabilityExecutionFailure({ code: 'LEGACY_COMMAND_FAILED', message: `Legacy command exited with status ${result.exitCode}`, retryable: false }, output);
384
+ }
385
+ return output;
368
386
  },
369
387
  };
370
388
  registry.register(registration);
@@ -372,13 +390,6 @@ function registerCliCapability(registry, runner, spec) {
372
390
  function categoriesFor(id) {
373
391
  return CLI_CAPABILITY_SPECS.find((spec) => spec.id === id)?.categories ?? ['read'];
374
392
  }
375
- function emptyInput(value) {
376
- if (value === undefined || value === null)
377
- return {};
378
- if (!isRecord(value) || Object.keys(value).length > 0)
379
- throw new Error('Input must be an empty object');
380
- return {};
381
- }
382
393
  function validateCodeImpactInput(value) {
383
394
  const input = requireRecord(value);
384
395
  const symbol = input.symbol;
@@ -2,7 +2,9 @@
2
2
  import { buildApprovalDecisionBody } from '../approval';
3
3
  // @ts-expect-error Next resolves the adjacent TypeScript helper.
4
4
  import { isCallerAuthorized, matchesAllowedPrefix } from '../guard';
5
- const allowedPrefixes = ['/control-plane/metrics', '/observability/observations', '/events/stream', '/executions/', '/graph/query', '/graph/impact', '/approvals'];
5
+ // @ts-expect-error Next resolves the adjacent TypeScript helper.
6
+ import { capabilityIdFromExecutePath, isReadOnlyCapability } from '../capabilities';
7
+ const allowedPrefixes = ['/control-plane/metrics', '/observability/observations', '/events', '/executions/', '/graph/query', '/graph/impact', '/approvals', '/capabilities'];
6
8
  export async function GET(request, context) { return forward(request, await context.params, 'GET'); }
7
9
  export async function POST(request, context) { return forward(request, await context.params, 'POST'); }
8
10
  async function forward(request, params, method) {
@@ -16,6 +18,19 @@ async function forward(request, params, method) {
16
18
  return new Response(JSON.stringify({ error: { code: 'FORBIDDEN', message: 'Dashboard route is not allowed' } }), { status: 403, headers: { 'content-type': 'application/json' } });
17
19
  const backend = process.env.FORJA_API_URL ?? 'http://localhost:3000';
18
20
  const token = process.env.FORJA_API_TOKEN;
21
+ // ADR-0022, condição de retomada #2: o que o painel alcança é derivado do que o servidor declara,
22
+ // nunca de uma lista escrita à mão aqui. O dashboard anterior mantinha allowlist própria e por ela
23
+ // rodava comando que não passava pelos gates nem aparecia na auditoria; este portão existe para
24
+ // que executar pela UI seja o mesmo caminho auditado de sempre, e só para capacidades que não
25
+ // escrevem. Falha fechada: catálogo que não responde é 403, não é liberado.
26
+ if (method === 'POST') {
27
+ const capabilityId = capabilityIdFromExecutePath(path);
28
+ if (capabilityId !== null) {
29
+ const surface = await readCapabilitySurface(`${backend}/api/capabilities`, token, capabilityId);
30
+ if (surface === null || !isReadOnlyCapability(surface))
31
+ return new Response(JSON.stringify({ error: { code: 'FORBIDDEN', message: `Capability is not read-only: ${capabilityId}` } }), { status: 403, headers: { 'content-type': 'application/json' } });
32
+ }
33
+ }
19
34
  const headers = new Headers({ accept: request.headers.get('accept') ?? 'application/json' });
20
35
  if (token !== undefined)
21
36
  headers.set('authorization', `Bearer ${token}`);
@@ -41,3 +56,21 @@ async function forward(request, params, method) {
41
56
  responseHeaders.set('cache-control', cacheControl);
42
57
  return new Response(response.body, { status: response.status, headers: responseHeaders });
43
58
  }
59
+ /** A definição que o servidor declara para a capacidade, ou null quando o catálogo não responde. */
60
+ async function readCapabilitySurface(catalogUrl, token, id) {
61
+ const headers = new Headers({ accept: 'application/json' });
62
+ if (token !== undefined)
63
+ headers.set('authorization', `Bearer ${token}`);
64
+ try {
65
+ const catalog = await fetch(catalogUrl, { headers, cache: 'no-store' });
66
+ if (!catalog.ok)
67
+ return null;
68
+ const definitions = await catalog.json();
69
+ if (!Array.isArray(definitions))
70
+ return null;
71
+ return definitions.find((definition) => definition.id === id) ?? null;
72
+ }
73
+ catch {
74
+ return null;
75
+ }
76
+ }
@@ -0,0 +1,26 @@
1
+ /**
2
+ * Pure helpers backing the dashboard's read-only capability access, same pattern as `guard.ts`
3
+ * and `approval.ts`: no Next types in here, so the rules are unit-testable directly.
4
+ *
5
+ * ADR-0022 congelou o dashboard anterior porque ele mantinha uma allowlist de comandos própria,
6
+ * paralela ao registry — e nela existia comando que o registry não tinha, executado por fora dos
7
+ * gates e da trilha de auditoria. A condição de retomada #2 era derivar a exposição do registry.
8
+ * Aqui não há lista: o que o painel pode executar é decidido pelo que o próprio servidor declara
9
+ * em `/api/capabilities`, filtrado pela regra abaixo.
10
+ */
11
+ /** O mínimo de uma `CapabilityDefinition` (packages/contracts) que a regra precisa. */
12
+ export interface CapabilitySurface {
13
+ readonly id: string;
14
+ readonly permissions: readonly string[];
15
+ readonly sideEffects: readonly string[];
16
+ }
17
+ /**
18
+ * Read-only de verdade: sem permissão de escrita e sem efeito colateral declarado. `risk` não
19
+ * entra na regra porque é julgamento do autor da capacidade, não um fato sobre o que ela toca —
20
+ * `context.budget` é risk low e ainda assim grava `context_run_record`. Definição que não declara
21
+ * os dois campos é recusada: o portão falha fechado, não por falta de evidência de que escreve.
22
+ */
23
+ export declare function isReadOnlyCapability(capability: CapabilitySurface | null): boolean;
24
+ /** `/capabilities/spec.validate/execute` → `spec.validate`; qualquer outra forma → null. */
25
+ export declare function capabilityIdFromExecutePath(pathname: string): string | null;
26
+ export declare function isCapabilityListPath(pathname: string): boolean;
@@ -0,0 +1,39 @@
1
+ /**
2
+ * Pure helpers backing the dashboard's read-only capability access, same pattern as `guard.ts`
3
+ * and `approval.ts`: no Next types in here, so the rules are unit-testable directly.
4
+ *
5
+ * ADR-0022 congelou o dashboard anterior porque ele mantinha uma allowlist de comandos própria,
6
+ * paralela ao registry — e nela existia comando que o registry não tinha, executado por fora dos
7
+ * gates e da trilha de auditoria. A condição de retomada #2 era derivar a exposição do registry.
8
+ * Aqui não há lista: o que o painel pode executar é decidido pelo que o próprio servidor declara
9
+ * em `/api/capabilities`, filtrado pela regra abaixo.
10
+ */
11
+ /**
12
+ * Read-only de verdade: sem permissão de escrita e sem efeito colateral declarado. `risk` não
13
+ * entra na regra porque é julgamento do autor da capacidade, não um fato sobre o que ela toca —
14
+ * `context.budget` é risk low e ainda assim grava `context_run_record`. Definição que não declara
15
+ * os dois campos é recusada: o portão falha fechado, não por falta de evidência de que escreve.
16
+ */
17
+ export function isReadOnlyCapability(capability) {
18
+ if (capability === null)
19
+ return false;
20
+ if (!Array.isArray(capability.permissions) || !Array.isArray(capability.sideEffects))
21
+ return false;
22
+ if (capability.permissions.includes('write'))
23
+ return false;
24
+ return capability.sideEffects.length === 0;
25
+ }
26
+ /** `/capabilities/spec.validate/execute` → `spec.validate`; qualquer outra forma → null. */
27
+ export function capabilityIdFromExecutePath(pathname) {
28
+ const prefix = '/capabilities/';
29
+ const suffix = '/execute';
30
+ if (!pathname.startsWith(prefix) || !pathname.endsWith(suffix))
31
+ return null;
32
+ const id = pathname.slice(prefix.length, -suffix.length);
33
+ if (id.length === 0 || id.includes('/'))
34
+ return null;
35
+ return id;
36
+ }
37
+ export function isCapabilityListPath(pathname) {
38
+ return pathname === '/capabilities';
39
+ }