forjajs 2.0.1 → 2.0.2

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 (61) hide show
  1. package/CHANGELOG.md +15 -0
  2. package/dist/apps/cli/src/index.d.ts +44 -0
  3. package/dist/apps/cli/src/index.js +304 -0
  4. package/dist/apps/server/src/main.d.ts +7 -2
  5. package/dist/apps/server/src/main.js +65 -16
  6. package/dist/bin/forja.js +208 -0
  7. package/dist/lib/core/health.js +2 -1
  8. package/dist/lib/core/registry.d.ts +7 -0
  9. package/dist/lib/core/registry.js +7 -0
  10. package/dist/lib/core/release.d.ts +6 -0
  11. package/dist/packages/adapter-git/src/index.d.ts +12 -0
  12. package/dist/packages/adapter-git/src/index.js +45 -0
  13. package/dist/packages/adapter-sqlite/src/index.d.ts +59 -2
  14. package/dist/packages/adapter-sqlite/src/index.js +136 -0
  15. package/dist/packages/context/src/index.d.ts +8 -0
  16. package/dist/packages/context/src/index.js +7 -0
  17. package/dist/packages/events/src/index.d.ts +2 -0
  18. package/dist/packages/events/src/index.js +16 -0
  19. package/dist/packages/graph/src/index.d.ts +59 -3
  20. package/dist/packages/graph/src/index.js +139 -21
  21. package/dist/packages/mcp/src/index.d.ts +14 -0
  22. package/dist/packages/mcp/src/index.js +39 -5
  23. package/dist/packages/policy/src/index.d.ts +7 -0
  24. package/dist/packages/policy/src/index.js +17 -1
  25. package/dist/packages/runtime/src/index.d.ts +20 -1
  26. package/dist/packages/runtime/src/index.js +34 -1
  27. package/docs/2x/CLI-CAPABILITIES.md +35 -0
  28. package/docs/2x/IMPLEMENTATION-AUDIT.md +132 -0
  29. package/docs/2x/SPRINT-1-CLI-CAPABILITY-PLAN.md +53 -0
  30. package/docs/2x/SPRINT-10-GRAPH-SYNC-PLAN.md +54 -0
  31. package/docs/2x/SPRINT-11-GRAPH-SYNC-CLI-MCP-PLAN.md +38 -0
  32. package/docs/2x/SPRINT-2-CLI-CAPABILITY-PLAN.md +39 -0
  33. package/docs/2x/SPRINT-3-RUNTIME-PERSISTENCE-PLAN.md +42 -0
  34. package/docs/2x/SPRINT-4-MCP-REGISTRY-PLAN.md +35 -0
  35. package/docs/2x/SPRINT-5-SERVER-APPROVALS-AUDIT-PLAN.md +31 -0
  36. package/docs/2x/SPRINT-6-EVENTS-E2E-PLAN.md +55 -0
  37. package/docs/2x/SPRINT-7-GRAPHLOOP-PERSISTENCE-PLAN.md +60 -0
  38. package/docs/2x/SPRINT-8-CONTEXT-GRAPH-PLAN.md +64 -0
  39. package/docs/2x/SPRINT-9-DETERMINISTIC-EXTRACTORS-PLAN.md +51 -0
  40. package/memory/50-orchestration/handoffs/2026-08-01_sprint-1-cli-capabilities.md +41 -0
  41. package/memory/50-orchestration/handoffs/2026-08-01_sprint-10-graph-sync.md +23 -0
  42. package/memory/50-orchestration/handoffs/2026-08-01_sprint-11-graph-sync-cli-mcp.md +22 -0
  43. package/memory/50-orchestration/handoffs/2026-08-01_sprint-2-cli-capabilities.md +30 -0
  44. package/memory/50-orchestration/handoffs/2026-08-01_sprint-3-runtime-persistence.md +29 -0
  45. package/memory/50-orchestration/handoffs/2026-08-01_sprint-4-mcp.md +29 -0
  46. package/memory/50-orchestration/handoffs/2026-08-01_sprint-5-server-approvals-audit.md +22 -0
  47. package/memory/50-orchestration/handoffs/2026-08-01_sprint-6-events-e2e.md +25 -0
  48. package/memory/50-orchestration/handoffs/2026-08-01_sprint-7-graphloop.md +23 -0
  49. package/memory/50-orchestration/handoffs/2026-08-01_sprint-8-context-graph.md +23 -0
  50. package/memory/50-orchestration/handoffs/2026-08-01_sprint-9-extractors.md +21 -0
  51. package/memory/90-decisions/0059-cli-adapter-capability-registry.md +17 -0
  52. package/memory/90-decisions/0060-runtime-persistence-port.md +17 -0
  53. package/memory/90-decisions/0061-mcp-dynamic-registry-stdio.md +16 -0
  54. package/memory/90-decisions/0062-server-catalog-approval-audit.md +17 -0
  55. package/memory/90-decisions/0063-events-persistent-e2e.md +19 -0
  56. package/memory/90-decisions/0064-graphloop-sqlite-store.md +20 -0
  57. package/memory/90-decisions/0065-context-graph-source-cache.md +20 -0
  58. package/memory/90-decisions/0066-graph-deterministic-extractors.md +16 -0
  59. package/memory/90-decisions/0067-graph-sync-capability.md +17 -0
  60. package/memory/90-decisions/0068-graph-sync-cli-mcp.md +17 -0
  61. package/package.json +1 -1
@@ -31,6 +31,22 @@ export interface CheckpointStore {
31
31
  save(checkpoint: Checkpoint): void | Promise<void>;
32
32
  get(runId: RunId): Checkpoint | undefined | Promise<Checkpoint | undefined>;
33
33
  }
34
+ export interface RuntimePersistence {
35
+ saveRun(run: RuntimeRun): void | Promise<void>;
36
+ getRun(runId: RunId): RuntimeRun | undefined | Promise<RuntimeRun | undefined>;
37
+ savePlan(runId: RunId, plan: readonly RuntimePlanStep[]): void | Promise<void>;
38
+ getPlan(runId: RunId): readonly RuntimePlanStep[] | undefined | Promise<readonly RuntimePlanStep[] | undefined>;
39
+ saveResults(runId: RunId, results: readonly ExecutionResult[]): void | Promise<void>;
40
+ getResults(runId: RunId): readonly ExecutionResult[] | undefined | Promise<readonly ExecutionResult[] | undefined>;
41
+ saveCursor(runId: RunId, nextStep: number, startedAt: number): void | Promise<void>;
42
+ getCursor(runId: RunId): {
43
+ readonly nextStep: number;
44
+ readonly startedAt: number;
45
+ } | undefined | Promise<{
46
+ readonly nextStep: number;
47
+ readonly startedAt: number;
48
+ } | undefined>;
49
+ }
34
50
  export interface RuntimeMemory {
35
51
  remember(run: RuntimeRun, result: ExecutionResult): void | Promise<void>;
36
52
  }
@@ -50,6 +66,7 @@ export interface RuntimeDependencies {
50
66
  readonly validator: RuntimeValidator;
51
67
  readonly contextBuilder?: RuntimeContextBuilder;
52
68
  readonly checkpointStore?: CheckpointStore;
69
+ readonly persistence?: RuntimePersistence;
53
70
  readonly memory?: RuntimeMemory;
54
71
  }
55
72
  export declare class RuntimeError extends Error {
@@ -73,13 +90,15 @@ export declare class RuntimeEngine {
73
90
  constructor(dependencies: RuntimeDependencies, limits?: Partial<RuntimeLimits>);
74
91
  start(request: RuntimeStartRequest): Promise<RuntimeRun>;
75
92
  execute(runId: RunId): Promise<RuntimeRun>;
76
- resume(runId: RunId): Promise<RuntimeRun>;
93
+ recover(runId: RunId, policy: CapabilityExecutionRequest['policy']): Promise<RuntimeRun>;
94
+ resume(runId: RunId, policy?: CapabilityExecutionRequest['policy']): Promise<RuntimeRun>;
77
95
  pause(runId: RunId): RuntimeRun;
78
96
  cancel(runId: RunId): Promise<RuntimeRun>;
79
97
  get(runId: RunId): RuntimeRun;
80
98
  private validateAndFinish;
81
99
  private stop;
82
100
  private update;
101
+ private persist;
83
102
  private saveCheckpoint;
84
103
  private metrics;
85
104
  private auditFields;
@@ -64,6 +64,8 @@ export class RuntimeEngine {
64
64
  this.nextSteps.set(runId, 0);
65
65
  this.policies.set(runId, request.policy);
66
66
  this.startedAt.set(runId, Date.now());
67
+ await this.dependencies.persistence?.saveRun(run);
68
+ await this.dependencies.persistence?.saveCursor(runId, 0, this.startedAt.get(runId));
67
69
  try {
68
70
  this.update(runId, { state: 'planning' });
69
71
  const context = this.dependencies.contextBuilder === undefined ? undefined : await this.dependencies.contextBuilder.build(request.objective);
@@ -71,6 +73,8 @@ export class RuntimeEngine {
71
73
  if (plan.length > this.limits.maxSteps)
72
74
  return this.stop(runId, 'blocked', this.error('MAX_STEPS_EXCEEDED', 'Plan exceeds maximum steps', false));
73
75
  this.plans.set(runId, plan);
76
+ await this.dependencies.persistence?.savePlan(runId, plan);
77
+ await this.persist(runId);
74
78
  await this.saveCheckpoint(runId, 'planning', 0);
75
79
  return this.get(runId);
76
80
  }
@@ -127,6 +131,7 @@ export class RuntimeEngine {
127
131
  approval: step.approval,
128
132
  });
129
133
  this.results.get(runId)?.push(result);
134
+ await this.dependencies.persistence?.saveResults(runId, this.results.get(runId) ?? []);
130
135
  if (result.status === 'succeeded')
131
136
  break;
132
137
  if (!result.error?.retryable || attempt > this.limits.maxRetries)
@@ -141,10 +146,31 @@ export class RuntimeEngine {
141
146
  this.update(runId, { evidence: [...this.get(runId).evidence, ...result.evidence], changedFiles: files });
142
147
  await this.dependencies.memory?.remember(this.get(runId), result);
143
148
  this.nextSteps.set(runId, index + 1);
149
+ await this.dependencies.persistence?.saveCursor(runId, index + 1, this.startedAt.get(runId) ?? Date.now());
144
150
  await this.saveCheckpoint(runId, 'running', index + 1);
145
151
  }
146
152
  }
147
- async resume(runId) {
153
+ async recover(runId, policy) {
154
+ const persistence = this.dependencies.persistence;
155
+ if (persistence === undefined)
156
+ throw new RuntimeError('Runtime persistence is not configured');
157
+ const run = await persistence.getRun(runId);
158
+ const plan = await persistence.getPlan(runId);
159
+ if (run === undefined || plan === undefined)
160
+ throw new RuntimeError(`Persisted runtime is incomplete: ${runId}`);
161
+ const results = await persistence.getResults(runId);
162
+ const cursor = await persistence.getCursor(runId);
163
+ this.runs.set(runId, run);
164
+ this.plans.set(runId, plan);
165
+ this.results.set(runId, [...(results ?? [])]);
166
+ this.nextSteps.set(runId, cursor?.nextStep ?? run.steps);
167
+ this.policies.set(runId, policy);
168
+ this.startedAt.set(runId, cursor?.startedAt ?? Date.parse(run.createdAt));
169
+ return run;
170
+ }
171
+ async resume(runId, policy) {
172
+ if (!this.runs.has(runId) && policy !== undefined)
173
+ await this.recover(runId, policy);
148
174
  const run = this.get(runId);
149
175
  if (run.state !== 'paused' && run.state !== 'awaiting_approval')
150
176
  throw new RuntimeError(`Run is not resumable: ${run.state}`);
@@ -190,6 +216,13 @@ export class RuntimeEngine {
190
216
  }
191
217
  update(runId, patch) {
192
218
  this.runs.set(runId, { ...this.get(runId), ...patch, updatedAt: new Date().toISOString() });
219
+ void this.persist(runId);
220
+ }
221
+ async persist(runId) {
222
+ const persistence = this.dependencies.persistence;
223
+ if (persistence === undefined)
224
+ return;
225
+ await persistence.saveRun(this.get(runId));
193
226
  }
194
227
  async saveCheckpoint(runId, state, step) {
195
228
  const store = this.dependencies.checkpointStore;
@@ -0,0 +1,35 @@
1
+ # CLI como adaptador do Capability Registry
2
+
3
+ Sprint 1 unifica os três comandos de prova abaixo com o registry executável. O comando legado
4
+ continua disponível como alias; a lógica é executada por um handler injetado no adaptador, e não
5
+ por uma implementação paralela no CLI.
6
+
7
+ | Comando legado | Capability | Input | Observação |
8
+ | --- | --- | --- | --- |
9
+ | `tools:doctor` | `system.doctor` | `{}` | diagnóstico local determinístico |
10
+ | `code:impact <symbol> [depth]` | `code.impact` | `{ symbol, depth? }` | depth entre 1 e 10 |
11
+ | `context:budget <target> [limitTokens]` | `context.budget` | `{ target, limitTokens? }` | limite positivo |
12
+ | `spec:check [feature]` | `spec.validate` | `{ feature? }` | valida uma spec ou todas |
13
+ | `sprint:status [project]` | `sprint.status` | `{ project? }` | consulta a sprint atual |
14
+ | `gsd:handoff <phase> <slug> [context]` | `handoff.create` | `{ phase, slug, context? }` | grava handoff local governado |
15
+
16
+ ## Descoberta e execução
17
+
18
+ ```bash
19
+ forja capabilities:list --json
20
+ forja capabilities:describe code.impact --json
21
+ forja capability:execute code.impact --input '{"symbol":"CapabilityRegistry","depth":2}' --json
22
+ ```
23
+
24
+ Os três comandos legados também aceitam `--json` e retornam o mesmo `ExecutionResult` versionado:
25
+
26
+ ```bash
27
+ forja tools:doctor --json
28
+ forja code:impact CapabilityRegistry 2 --json
29
+ forja context:budget docs/2x/SPRINT-1-CLI-CAPABILITY-PLAN.md 10000 --json
30
+ ```
31
+
32
+ O envelope inclui `runId`, `correlationId`, `status`, `output`, `evidence` e erro normalizado
33
+ quando aplicável. Entrada inválida é rejeitada antes do handler; política é avaliada pelo
34
+ `CapabilityRegistry` antes da execução. Comandos ainda não migrados permanecem no dispatch
35
+ legado durante a migração progressiva.
@@ -0,0 +1,132 @@
1
+ # ForjaJS 2.x — Auditoria de implementação
2
+
3
+ **Escopo:** baseline publicado `2.0.1`, checkout local em 2026-08-01.
4
+ **Objetivo:** distinguir código executável/testado de fundações isoladas antes da
5
+ Sprint 1 de unificação da CLI com o Capability Registry.
6
+
7
+ ## Evidências consultadas
8
+
9
+ - `packages/contracts/src/index.ts`
10
+ - `packages/core/src/index.ts`
11
+ - `lib/core/registry.ts`
12
+ - `bin/forja.ts`
13
+ - `packages/mcp/src/index.ts`
14
+ - `packages/sdk/src/index.ts`
15
+ - `packages/adapter-nest/src/index.ts`
16
+ - `apps/server/src/main.ts`
17
+ - `scripts/tools-doctor.ts`
18
+ - `scripts/agent-harness.ts`
19
+ - `scripts/context-ops.ts`
20
+ - testes em `test/*registry*`, `test/mcp.test.js`, `test/sdk.test.js`,
21
+ `test/adapter-nest.test.js` e `test/harness.test.js`.
22
+
23
+ ## Matriz de implementação
24
+
25
+ | Componente | Existe | Integrado | Persistente | Testado | Produção |
26
+ | --- | ---: | ---: | ---: | ---: | ---: |
27
+ | Contratos versionados | sim | parcial | não aplicável | sim | parcial |
28
+ | `lib/core/registry.ts` — registry CLI | sim | sim, apenas CLI | auditoria JSONL | sim | sim |
29
+ | `CapabilityRegistry` | sim | CLI/server/MCP/runtime | não | sim | parcial |
30
+ | Adapter CLI → capability | sim | sim, 6 comandos | não | sim | parcial |
31
+ | ExecutionResult | sim | parcial, registry | não | sim | parcial |
32
+ | Policy Engine | sim | registry/runtime/MCP/server | approvals em SQLite no server | sim | parcial |
33
+ | Runtime Engine | sim | SQLite no server oficial; memória nos testes | runs, planos, resultados, estado e checkpoints em SQLite | sim | parcial |
34
+ | Sprint/Task/Handoff | sim | parcial | stores em memória/SQLite adapter separado | sim | parcial |
35
+ | Context Engine | sim | server/MCP/Runtime + fontes de memória/grafo | cache SQLite v5 | sim | parcial |
36
+ | GraphLoop | sim | MCP/server/Runtime/testes | SQLite v4; memória apenas em testes | sim | parcial |
37
+ | MCP | sim | tools/resources + registry dinâmico + stdio/server | auditoria MCP em SQLite no server | sim | parcial |
38
+ | SDK | sim | API REST esperada | remoto | sim | parcial |
39
+ | Sandbox | sim | isolada em testes | backend em memória/adapters | sim | parcial |
40
+ | Planner/Validator | sim | Runtime/testes | não aplicável | sim | parcial |
41
+ | Event Bus/Scheduler | sim | server/worker/testes | Event Bus no server usa SQLite; scheduler ainda separado | sim | parcial |
42
+ | Observabilidade/Control Plane | sim | server/dashboard | memória por padrão | sim | parcial |
43
+ | NestJS adapter/server | sim | server bootstrap | não | sim | parcial |
44
+ | Next.js dashboard | sim | consulta API/proxy | remoto | sim | parcial |
45
+
46
+ ## Achados principais
47
+
48
+ 1. O registry declarativo legado (`COMMANDS`) contém o comportamento público da
49
+ CLI: domínio, descrição, script, argumentos e gates. Ele não produz
50
+ `CapabilityDefinition` nem passa pelo `CapabilityRegistry`.
51
+ 2. O `CapabilityRegistry` valida, autoriza e normaliza `ExecutionResult`, mas
52
+ não conhece comandos legados e não possui um catálogo padrão registrado.
53
+ 3. A Sprint 5 corrigiu a composição do server: `apps/server/src/main.ts` agora
54
+ registra o mesmo catálogo de seis capabilities da CLI e inicializa approvals
55
+ e auditoria MCP no SQLite.
56
+ 4. MCP e SDK já possuem superfícies sobre capabilities, mas dependem de um
57
+ registry preenchido pelo consumidor.
58
+ 5. Os três comandos da Sprint 1 possuem handlers determinísticos existentes:
59
+ `tools:doctor` em `scripts/tools-doctor.ts`, `code:impact` em
60
+ `scripts/agent-harness.ts` e `context:budget` em `scripts/context-ops.ts`.
61
+ 6. A auditoria transversal existente em `bin/forja.ts` registra comando, args,
62
+ exit code e duração, mas não registra `runId`, `capabilityId` ou o envelope
63
+ completo de `ExecutionResult`.
64
+ 7. A Sprint 3 adicionou a porta `RuntimePersistence`, o adapter SQLite e a
65
+ recuperação explícita por policy; approvals e execução distribuída continuam pendentes.
66
+ 8. A Sprint 4 adicionou `forja_capability_describe`, ferramentas derivadas do registry e o
67
+ transporte local `mcp:start`; a Sprint 5 completou o catálogo padrão do server.
68
+ 9. A Sprint 5 passou o catálogo CLI, approvals e auditoria MCP para a composição oficial do
69
+ server; approvals e auditoria MCP usam SQLite.
70
+ 10. A Sprint 6 tornou o Event Bus restart-safe sobre `SqliteEventStore` e adicionou uma prova
71
+ E2E determinística; GraphLoop persistente e sandbox Git worktree continuam pendentes.
72
+ 11. A Sprint 7 extraiu `GraphStore`, adicionou `SqliteGraphStore` e ligou o mesmo grafo persistente
73
+ ao MCP e à memória de execução; Context Engine e engines de contradição/agenda ainda não estão
74
+ plenamente ligados ao store.
75
+ 12. A Sprint 8 ligou `GraphContextSource` e `SqliteContextCache` ao bootstrap oficial; a relevância
76
+ de grafo é lexical e determinística, enquanto trechos de arquivos e busca semântica continuam
77
+ fora do escopo.
78
+ 13. A Sprint 9 ampliou o extractor determinístico para símbolos, chamadas, ADRs, tarefas, handoffs,
79
+ testes e manifests; resolução semântica completa, commits e diffs ainda requerem extractors
80
+ específicos.
81
+ 14. A Sprint 10 adicionou `GraphIndexer`, `GitGraphDocumentSource` e a capability `graph.sync`;
82
+ a composição oficial usa o GraphLoop SQLite, mas poda de remoções e histórico de commits ainda
83
+ estão pendentes.
84
+ 15. A Sprint 11 expôs `graph.sync` no registry/CLI standalone e no MCP stdio, com métricas de
85
+ documentos, nós, arestas, arquivos e duração; observações persistentes do Control Plane ainda
86
+ são uma pendência distinta.
87
+
88
+ ## Mapa inicial comando → capability
89
+
90
+ | Comando legado | Capability alvo | Prova Sprint 1 |
91
+ | --- | --- | ---: |
92
+ | `tools:doctor` | `system.doctor` | sim |
93
+ | `code:impact` | `code.impact` | sim |
94
+ | `context:budget` | `context.budget` | sim |
95
+ | `spec:new` | `spec.create` | próxima |
96
+ | `spec:check` | `spec.validate` | sim, Sprint 2 |
97
+ | `sprint:start` | `sprint.start` | próxima |
98
+ | `sprint:status` | `sprint.status` | sim, Sprint 2 |
99
+ | `gsd:handoff` | `handoff.create` | sim, Sprint 2 |
100
+ | `context:smart` | `context.build` | próxima |
101
+ | `memory:compress` | `memory.compact` | próxima |
102
+
103
+ O restante do mapa é mantido como backlog de migração; nesta sprint nenhum
104
+ comando não comprovado será apresentado como integrado.
105
+
106
+ ## Hipóteses e informações ausentes
107
+
108
+ - A compatibilidade de saída textual dos três comandos deve ser preservada;
109
+ `--json` adicionará o envelope estruturado sem remover o modo humano.
110
+ - Os handlers legados continuam sendo a fonte determinística de execução nesta
111
+ sprint; a unificação elimina o registry paralelo, não reescreve os handlers.
112
+ - A persistência de approvals, eventos de runtime e execução distribuída permanece fora do
113
+ escopo após a Sprint 3.
114
+ - O contrato atual não possui um campo específico para argumentos de CLI; o
115
+ payload validado da capability carregará esses argumentos.
116
+
117
+ ## Decisão de escopo
118
+
119
+ Implementar um adapter na aplicação CLI que registra três capabilities no
120
+ `CapabilityRegistry`, delega os handlers legados por uma porta injetada e usa
121
+ `PolicyEngine` antes da execução. `bin/forja.ts` continuará adaptando comandos
122
+ não migrados durante a transição, mas os três comandos de prova não terão lógica
123
+ duplicada de negócio.
124
+
125
+ ## Riscos
126
+
127
+ - Alterar o dispatch pode mudar mensagens ou códigos de saída; testes de
128
+ equivalência devem comparar modo textual e modo JSON.
129
+ - `code:impact` depende de `codegraph` e tem fallback manual; o adapter não pode
130
+ transformar ausência de ferramenta em sucesso falso.
131
+ - `context:budget` grava uma medição no SQLite; a política deve declarar o
132
+ efeito de banco, mesmo sendo uma operação determinística.
@@ -0,0 +1,53 @@
1
+ # Sprint 1 — Unificar CLI e Capability Registry
2
+
3
+ ## Objetivo
4
+
5
+ Fazer três comandos legados passarem pelo mesmo registry, validação, policy e
6
+ envelope `ExecutionResult`, preservando a saída humana existente.
7
+
8
+ ## Escopo
9
+
10
+ Incluído:
11
+
12
+ - adapter CLI;
13
+ - mapa comando → capability para o catálogo inicial;
14
+ - schemas determinísticos de entrada;
15
+ - `system.doctor`, `code.impact`, `context.budget`;
16
+ - `capabilities:list`, `capabilities:describe` e
17
+ `capability:execute` em JSON;
18
+ - correlation ID e auditoria do resultado;
19
+ - testes de equivalência e rejeição de entrada.
20
+
21
+ Excluído:
22
+
23
+ - persistência do Runtime;
24
+ - MCP nativo;
25
+ - GraphLoop SQLite;
26
+ - sandbox/autonomia ponta a ponta;
27
+ - migração dos demais comandos.
28
+
29
+ ## Impacto
30
+
31
+ Arquivos esperados: `apps/cli/`, `bin/forja.ts`, contratos/testes e
32
+ documentação. O domínio em `packages/core` permanece independente de processo,
33
+ CLI e framework.
34
+
35
+ ## Critérios de aceite
36
+
37
+ 1. Os três comandos são descobertos por capability ID e alias.
38
+ 2. `forja capabilities:list --json` retorna definições versionadas.
39
+ 3. `forja capabilities:describe code.impact --json` retorna o contrato.
40
+ 4. Entradas inválidas são recusadas antes do handler.
41
+ 5. `forja capability:execute code.impact --input '{...}' --json` retorna
42
+ `ExecutionResult` com `runId`, `correlationId`, status e evidência.
43
+ 6. O modo textual dos três comandos preserva o comportamento legado.
44
+ 7. Policy negada não chama o handler.
45
+ 8. O gate de testes determinísticos passa sem alterar comandos fora do escopo.
46
+
47
+ ## Status de execução — 2026-08-01
48
+
49
+ Concluído para os três comandos de prova. O adapter está em `apps/cli/src/index.ts`, o dispatch
50
+ integrado está em `bin/forja.ts` e os testes estão em `test/cli-capability-adapter.test.js`.
51
+ `tools:doctor`, `context:budget` e `code:impact` foram executados com `--json` em workspace
52
+ temporário; os envelopes observados continham `runId`, `correlationId`, status, payload e
53
+ evidência. Os demais comandos permanecem fora do escopo desta sprint.
@@ -0,0 +1,54 @@
1
+ # Sprint 10 — Indexação incremental de workspace/Git
2
+
3
+ ## Objetivo
4
+
5
+ Transformar os extractors do GraphLoop em uma operação utilizável: listar
6
+ arquivos rastreáveis do workspace, gerar mutations determinísticas e expor o
7
+ processo como capability `graph.sync`.
8
+
9
+ ## Fluxo
10
+
11
+ ```text
12
+ GitWorkspaceSource
13
+ ↓
14
+ GraphIndexer
15
+ ↓
16
+ extractDeterministicRelations
17
+ ↓
18
+ GraphLoop.apply (checksum)
19
+ ↓
20
+ SqliteGraphStore
21
+ ```
22
+
23
+ ## Escopo
24
+
25
+ - `git ls-files --cached --others --exclude-standard -z` como fonte local;
26
+ - arquivos TypeScript/JavaScript/JSON/Markdown/YAML;
27
+ - exclusão de `.git`, `node_modules`, `dist`, `coverage`, binários e arquivos
28
+ maiores que 1 MB;
29
+ - indexação incremental por locator/checksum;
30
+ - capability `graph.sync` com `ExecutionResult` e evidência;
31
+ - composição da capability no server oficial.
32
+
33
+ ## Critérios de aceite
34
+
35
+ 1. Arquivos ignorados e não indexáveis não entram na fonte.
36
+ 2. Uma sincronização repetida retorna `skipped` sem duplicar arestas.
37
+ 3. Falha do Git é retornada como erro, não como sucesso vazio.
38
+ 4. A capability valida input antes do handler e exige permissão de escrita.
39
+ 5. O server registra `graph.sync` sobre o GraphLoop SQLite.
40
+ 6. A operação continua offline e não usa LLM.
41
+
42
+ ## Limites
43
+
44
+ - arquivos removidos não são podados automaticamente nesta sprint;
45
+ - commits e diffs não são entidades extraídas ainda;
46
+ - `git ls-files` exige um repositório válido para a fonte oficial.
47
+
48
+ ## Evidências
49
+
50
+ - `packages/graph/src/index.ts`;
51
+ - `packages/adapter-git/src/index.ts`;
52
+ - `apps/cli/src/index.ts`;
53
+ - `apps/server/src/main.ts`;
54
+ - testes de GraphIndexer, adapter Git e capability.
@@ -0,0 +1,38 @@
1
+ # Sprint 11 — Graph sync na CLI, MCP e observabilidade
2
+
3
+ ## Objetivo
4
+
5
+ Tornar `graph.sync` uma capability operável pela CLI standalone e pelo MCP
6
+ stdio, mantendo um único handler e registrando contagens, arquivos e duração.
7
+
8
+ ## Escopo
9
+
10
+ - alias declarativo `graph:sync` no registry do core;
11
+ - `capabilities:list`, `capabilities:describe` e `capability:execute` com
12
+ `graph.sync`;
13
+ - `mcp:start` descobrindo a ferramenta dinâmica pelo registry;
14
+ - composição local GraphLoop + SQLite + Git reutilizada pelos adaptadores;
15
+ - saída humana resumida e saída JSON estruturada;
16
+ - métricas `documents`, `indexed`, `skipped`, `nodes`, `edges`, `files` e
17
+ `durationMs` no resultado e no registro de auditoria CLI.
18
+
19
+ ## Critérios de aceite
20
+
21
+ 1. `graph.sync` aparece em `forja capabilities:list --json`.
22
+ 2. `forja graph:sync --json` indexa o repositório atual sem LLM.
23
+ 3. Reexecução usa checksum e informa documentos ignorados.
24
+ 4. MCP stdio deriva a ferramenta a partir do registry, sem lista duplicada.
25
+ 5. Policy exige permissão `write` para a capability.
26
+ 6. Falhas do Git retornam `ExecutionResult` falho.
27
+ 7. Testes, typecheck, build e release gate passam.
28
+
29
+ ## Evidência operacional
30
+
31
+ No workspace temporário da Sprint 11, a CLI descobriu `graph.sync` e a execução
32
+ indexou 867 documentos em 8,9s, retornando contagens estruturadas.
33
+
34
+ ## Limites
35
+
36
+ - CLI não faz poda de arquivos removidos;
37
+ - observabilidade detalhada fica no envelope/auditoria CLI; persistência de
38
+ observações do Control Plane para essa ação será consolidada em sprint futura.
@@ -0,0 +1,39 @@
1
+ # Sprint 2 — Expandir a migração CLI → Capability Registry
2
+
3
+ ## Objetivo
4
+
5
+ Migrar três comandos de processo para o mesmo adapter da Sprint 1, cobrindo validação de specs,
6
+ consulta de sprint e registro de handoff.
7
+
8
+ ## Escopo
9
+
10
+ - `spec:check` → `spec.validate`;
11
+ - `sprint:status` → `sprint.status`;
12
+ - `gsd:handoff` → `handoff.create`;
13
+ - schemas determinísticos e aliases legados;
14
+ - policy para a escrita auditável de handoff;
15
+ - testes de equivalência, validação e bloqueio de input;
16
+ - documentação e atualização do mapa de implementação.
17
+
18
+ Fora do escopo: persistência de runtime, MCP nativo, GraphLoop, sandbox e autonomia.
19
+
20
+ ## Critérios de aceite
21
+
22
+ 1. Os três IDs aparecem em `capabilities:list` e são descritos por ID ou alias.
23
+ 2. Argumentos posicionais legados são convertidos para payloads validados.
24
+ 3. `spec:check` e `sprint:status` permanecem operações de leitura.
25
+ 4. `gsd:handoff` declara permissão/efeito de escrita e passa pelo Policy Engine.
26
+ 5. Entrada inválida não chama o handler.
27
+ 6. Toda execução produz `ExecutionResult` e evidência `forja.cli`.
28
+ 7. A suíte determinística e o typecheck permanecem verdes.
29
+
30
+ ## Impacto
31
+
32
+ Arquivos afetados: `apps/cli/src/index.ts`, testes do adapter, auditoria e documentação. O
33
+ dispatch legado permanece como fallback para comandos ainda não migrados.
34
+
35
+ ## Hipóteses
36
+
37
+ - A saída textual dos scripts existentes permanece a fonte de compatibilidade.
38
+ - Handoff é uma operação de baixo risco quando limitado ao registro local e governado por policy.
39
+ - A persistência definitiva do ledger pertence à integração do Runtime, não a esta fatia.
@@ -0,0 +1,42 @@
1
+ # Sprint 3 — Runtime persistente e retomável
2
+
3
+ ## Objetivo
4
+
5
+ Fazer o Runtime sobreviver ao encerramento do processo, preservando execução, plano, resultados,
6
+ cursor, orçamento, evidências e checkpoints em SQLite.
7
+
8
+ ## Escopo
9
+
10
+ - porta `RuntimePersistence` independente de banco;
11
+ - tabelas SQLite versionadas para runs, planos, resultados e estado;
12
+ - `SqliteRuntimePersistence` no adapter oficial;
13
+ - recuperação explícita com policy fornecida novamente;
14
+ - backend NestJS usando SQLite no bootstrap oficial;
15
+ - teste de pausa → fechamento do banco → novo engine → retomada;
16
+ - migração idempotente e não destrutiva.
17
+
18
+ Fora do escopo: persistência de approvals, GraphLoop, sandbox, MCP nativo e execução paralela.
19
+
20
+ ## Critérios de aceite
21
+
22
+ 1. `RuntimeEngine` persiste alterações sem importar SQLite.
23
+ 2. Plano, resultados e próximo passo são recuperáveis por `runId`.
24
+ 3. Uma execução pausada pode ser retomada por uma nova instância do engine.
25
+ 4. Policy não é serializada como código; a recuperação exige policy ativa do processo.
26
+ 5. Bootstrap NestJS inicializa migrações e usa SQLite por padrão.
27
+ 6. Migrações podem ser reaplicadas sem duplicar estruturas ou dados.
28
+ 7. Testes existentes e teste de reinício passam.
29
+
30
+ ## Impacto
31
+
32
+ Afetados: `packages/runtime`, `packages/adapter-sqlite`, `apps/server` e testes. Nenhum pacote de
33
+ domínio conhece `better-sqlite3` ou SQL.
34
+
35
+ ## Riscos e hipóteses
36
+
37
+ - O processo deve fornecer a mesma policy/configuração ao recuperar uma execução; políticas não
38
+ são serializadas como funções.
39
+ - Persistência síncrona do adapter SQLite é aceitável para a primeira distribuição local-first;
40
+ backend assíncrono substituível permanece possível pela porta.
41
+ - Cancelamento durante uma capability em andamento continua dependente do handler e não é
42
+ interrompido à força.
@@ -0,0 +1,35 @@
1
+ # Sprint 4 — MCP nativo sobre o Capability Registry
2
+
3
+ ## Objetivo
4
+
5
+ Disponibilizar o catálogo de capabilities por MCP sem duplicar ferramentas, handlers ou regras de
6
+ policy, incluindo um transporte local JSON-RPC por stdio.
7
+
8
+ ## Escopo
9
+
10
+ - `forja mcp:start`;
11
+ - `tools/list`, `tools/call`, `resources/list`, `resources/read` e `initialize`;
12
+ - `forja_capability_describe`;
13
+ - ferramentas dinâmicas derivadas dos IDs visíveis no registry;
14
+ - execução dinâmica delegada ao mesmo `CapabilityRegistry`;
15
+ - identidade e permissões MCP locais;
16
+ - testes do adapter e smoke test stdio.
17
+
18
+ Fora do escopo: transporte HTTP/SSE MCP, autenticação remota, GraphLoop persistente e aprovação
19
+ interativa de ações críticas.
20
+
21
+ ## Critérios de aceite
22
+
23
+ 1. `mcp:start` responde JSON-RPC por linha sem depender de provedor externo.
24
+ 2. `tools/list` contém ferramentas fixas e uma ferramenta derivada por capability visível.
25
+ 3. `forja_capability_describe` retorna a definição versionada do registry.
26
+ 4. Execução dinâmica retorna `ExecutionResult` e passa pelo Policy Engine.
27
+ 5. Recursos MCP continuam disponíveis e erros são normalizados.
28
+ 6. Nenhuma regra de domínio é implementada dentro do transporte stdio.
29
+
30
+ ## Riscos e hipóteses
31
+
32
+ - O transporte stdio implementa o subconjunto local necessário para a operação do Forja; clientes
33
+ que exigirem recursos MCP adicionais ficam para uma sprint própria.
34
+ - Schemas de payload específicos ainda são genéricos porque `CapabilityDefinition` não carrega um
35
+ schema de input serializável; a validação definitiva continua no registry.
@@ -0,0 +1,31 @@
1
+ # Sprint 5 — Catálogo padrão, approvals e auditoria MCP
2
+
3
+ ## Objetivo
4
+
5
+ Fechar a composição oficial do server sobre o mesmo catálogo da CLI e tornar approvals e chamadas
6
+ MCP duráveis e auditáveis em SQLite.
7
+
8
+ ## Entregas
9
+
10
+ - `createDefaultCapabilityRegistry` no server com as seis capabilities migradas;
11
+ - `ApprovalStore` no Policy Engine;
12
+ - `SqliteApprovalStore` e migração SQLite v3;
13
+ - `McpAuditSink` e `SqliteMcpAuditSink`;
14
+ - auditoria de sucesso, falha e ferramenta inexistente;
15
+ - server inicializando catálogo, approvals e auditoria no banco do workspace.
16
+
17
+ ## Critérios de aceite
18
+
19
+ 1. Server e CLI descobrem os mesmos seis IDs.
20
+ 2. Approval criado antes do reinício pode ser consultado e decidido depois.
21
+ 3. Chamada MCP gera registro de auditoria sem derrubar o transporte se o sink falhar.
22
+ 4. Migrações v1–v3 são idempotentes e não destrutivas.
23
+ 5. Policy continua bloqueando ações fora do escopo.
24
+ 6. Testes, build e release gate passam.
25
+
26
+ ## Hipóteses e riscos
27
+
28
+ - O catálogo padrão usa os handlers determinísticos existentes; capabilities futuras devem ser
29
+ registradas no mesmo ponto de composição.
30
+ - A auditoria MCP usa `SqliteAuditStore` existente e não cria um ledger paralelo.
31
+ - `ApprovalLedger` mantém API síncrona nesta primeira distribuição local-first.
@@ -0,0 +1,55 @@
1
+ # Sprint 6 — Eventos persistentes e prova operacional
2
+
3
+ ## Objetivo
4
+
5
+ Conectar o Event Bus ao server oficial com log SQLite append-only e comprovar,
6
+ em um cenário determinístico, o fluxo supervisionado approval → sandbox →
7
+ runtime → validator → evento persistido.
8
+
9
+ ## Escopo
10
+
11
+ - hidratação do Event Bus a partir do store ao iniciar;
12
+ - idempotência e sequência por aggregate após reinício;
13
+ - persistência de eventos publicados pelo Control Plane no SQLite do workspace;
14
+ - prova E2E sem provedor de LLM, usando capability e sandbox simuladas;
15
+ - teste de aprovação, retomada, validação e registro de `execution.completed`.
16
+
17
+ ## Fora do escopo
18
+
19
+ - substituir o stream SSE em memória por broker externo;
20
+ - persistir subscriptions e dead letters entre processos;
21
+ - implementar o backend Git worktree real;
22
+ - integrar GraphLoop SQLite ou dashboard operacional.
23
+
24
+ ## Tarefas verificáveis
25
+
26
+ 1. Carregar eventos existentes antes de gerar sequência ou aceitar idempotency key.
27
+ 2. Instanciar `EventBus(SqliteEventStore)` no bootstrap NestJS.
28
+ 3. Encaminhar eventos do Control Plane para SSE e log durável.
29
+ 4. Executar a fixture de teste falho com aprovação humana e sandbox isolada.
30
+ 5. Validar aceitação independentemente do handler implementador.
31
+ 6. Rodar testes, typecheck, build e release gate.
32
+
33
+ ## Critérios de aceite
34
+
35
+ - duas instâncias do Event Bus sobre o mesmo SQLite preservam sequência e
36
+ idempotência;
37
+ - server inicializa runtime, approvals, MCP audit e eventos no mesmo banco;
38
+ - a prova E2E termina somente após aprovação e validator `accepted`;
39
+ - a prova registra um evento `execution.completed` persistido;
40
+ - nenhum teste depende de LLM, rede ou estado externo;
41
+ - documentação e ADR registram limites conhecidos.
42
+
43
+ ## Evidências esperadas
44
+
45
+ - `test/events-scheduler.test.js`;
46
+ - `test/autonomy-e2e.test.js`;
47
+ - `packages/events/src/index.ts`;
48
+ - `apps/server/src/main.ts`;
49
+ - saída de `npm test`, `tsc --noEmit`, `npm run build` e
50
+ `npm run release:check`.
51
+
52
+ ## Próxima dependência
53
+
54
+ A próxima sprint deve persistir o GraphLoop e ligar suas evidências ao mesmo
55
+ fluxo de execução, mantendo o Event Bus como trilha de integração.