forjajs 2.0.1 → 2.0.3

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 (93) hide show
  1. package/CHANGELOG.md +15 -0
  2. package/README.md +22 -0
  3. package/README.pt-BR.md +22 -0
  4. package/dist/apps/cli/src/index.d.ts +44 -0
  5. package/dist/apps/cli/src/index.js +304 -0
  6. package/dist/apps/server/src/main.d.ts +9 -3
  7. package/dist/apps/server/src/main.js +70 -19
  8. package/dist/bin/forja.js +213 -0
  9. package/dist/lib/core/health.js +2 -1
  10. package/dist/lib/core/registry.d.ts +17 -0
  11. package/dist/lib/core/registry.js +17 -0
  12. package/dist/lib/core/release.d.ts +16 -0
  13. package/dist/packages/adapter-git/src/index.d.ts +14 -0
  14. package/dist/packages/adapter-git/src/index.js +66 -0
  15. package/dist/packages/adapter-sqlite/src/index.d.ts +59 -2
  16. package/dist/packages/adapter-sqlite/src/index.js +136 -0
  17. package/dist/packages/context/src/index.d.ts +8 -0
  18. package/dist/packages/context/src/index.js +7 -0
  19. package/dist/packages/contracts/src/index.d.ts +1 -1
  20. package/dist/packages/events/src/index.d.ts +2 -0
  21. package/dist/packages/events/src/index.js +16 -0
  22. package/dist/packages/graph/src/index.d.ts +59 -3
  23. package/dist/packages/graph/src/index.js +139 -21
  24. package/dist/packages/mcp/src/index.d.ts +14 -0
  25. package/dist/packages/mcp/src/index.js +39 -5
  26. package/dist/packages/plugin-docker/src/index.d.ts +3 -0
  27. package/dist/packages/plugin-docker/src/index.js +13 -0
  28. package/dist/packages/plugin-github/src/index.d.ts +3 -0
  29. package/dist/packages/plugin-github/src/index.js +13 -0
  30. package/dist/packages/policy/src/index.d.ts +7 -0
  31. package/dist/packages/policy/src/index.js +17 -1
  32. package/dist/packages/runtime/src/index.d.ts +20 -1
  33. package/dist/packages/runtime/src/index.js +34 -1
  34. package/dist/packages/sandbox/src/index.d.ts +2 -0
  35. package/dist/packages/sandbox/src/index.js +10 -0
  36. package/dist/scripts/context-benchmark.d.ts +2 -0
  37. package/dist/scripts/context-benchmark.js +39 -0
  38. package/dist/scripts/demo-autonomy.d.ts +15 -0
  39. package/dist/scripts/demo-autonomy.js +200 -0
  40. package/dist/scripts/server-persistence-probe.d.mts +1 -0
  41. package/dist/scripts/server-persistence-probe.d.ts +1 -0
  42. package/dist/scripts/server-persistence-probe.js +52 -0
  43. package/dist/scripts/server-persistence-probe.mjs +52 -0
  44. package/docs/2x/CLI-CAPABILITIES.md +35 -0
  45. package/docs/2x/IMPLEMENTATION-AUDIT.md +40 -0
  46. package/docs/2x/SPRINT-1-CLI-CAPABILITY-PLAN.md +53 -0
  47. package/docs/2x/SPRINT-10-GRAPH-SYNC-PLAN.md +54 -0
  48. package/docs/2x/SPRINT-11-GRAPH-SYNC-CLI-MCP-PLAN.md +38 -0
  49. package/docs/2x/SPRINT-12-REAL-AUTONOMY-PLAN.md +40 -0
  50. package/docs/2x/SPRINT-13-MCP-STDIO-PLAN.md +26 -0
  51. package/docs/2x/SPRINT-14-SERVER-RESTART-PLAN.md +28 -0
  52. package/docs/2x/SPRINT-15-CHAOS-SECURITY-PLAN.md +22 -0
  53. package/docs/2x/SPRINT-16-LAST-MILE-PLAN.md +25 -0
  54. package/docs/2x/SPRINT-2-CLI-CAPABILITY-PLAN.md +39 -0
  55. package/docs/2x/SPRINT-3-RUNTIME-PERSISTENCE-PLAN.md +42 -0
  56. package/docs/2x/SPRINT-4-MCP-REGISTRY-PLAN.md +35 -0
  57. package/docs/2x/SPRINT-5-SERVER-APPROVALS-AUDIT-PLAN.md +31 -0
  58. package/docs/2x/SPRINT-6-EVENTS-E2E-PLAN.md +55 -0
  59. package/docs/2x/SPRINT-7-GRAPHLOOP-PERSISTENCE-PLAN.md +60 -0
  60. package/docs/2x/SPRINT-8-CONTEXT-GRAPH-PLAN.md +64 -0
  61. package/docs/2x/SPRINT-9-DETERMINISTIC-EXTRACTORS-PLAN.md +51 -0
  62. package/memory/50-orchestration/handoffs/2026-08-01_sprint-1-cli-capabilities.md +41 -0
  63. package/memory/50-orchestration/handoffs/2026-08-01_sprint-10-graph-sync.md +23 -0
  64. package/memory/50-orchestration/handoffs/2026-08-01_sprint-11-graph-sync-cli-mcp.md +22 -0
  65. package/memory/50-orchestration/handoffs/2026-08-01_sprint-12-real-autonomy.md +16 -0
  66. package/memory/50-orchestration/handoffs/2026-08-01_sprint-2-cli-capabilities.md +30 -0
  67. package/memory/50-orchestration/handoffs/2026-08-01_sprint-3-runtime-persistence.md +29 -0
  68. package/memory/50-orchestration/handoffs/2026-08-01_sprint-4-mcp.md +29 -0
  69. package/memory/50-orchestration/handoffs/2026-08-01_sprint-5-server-approvals-audit.md +22 -0
  70. package/memory/50-orchestration/handoffs/2026-08-01_sprint-6-events-e2e.md +25 -0
  71. package/memory/50-orchestration/handoffs/2026-08-01_sprint-7-graphloop.md +23 -0
  72. package/memory/50-orchestration/handoffs/2026-08-01_sprint-8-context-graph.md +23 -0
  73. package/memory/50-orchestration/handoffs/2026-08-01_sprint-9-extractors.md +21 -0
  74. package/memory/50-orchestration/handoffs/2026-08-02_sprint-13-mcp-stdio.md +14 -0
  75. package/memory/50-orchestration/handoffs/2026-08-02_sprint-14-server-restart.md +15 -0
  76. package/memory/50-orchestration/handoffs/2026-08-02_sprint-15-chaos-security.md +13 -0
  77. package/memory/50-orchestration/handoffs/2026-08-02_sprint-16-last-mile.md +11 -0
  78. package/memory/90-decisions/0059-cli-adapter-capability-registry.md +17 -0
  79. package/memory/90-decisions/0060-runtime-persistence-port.md +17 -0
  80. package/memory/90-decisions/0061-mcp-dynamic-registry-stdio.md +16 -0
  81. package/memory/90-decisions/0062-server-catalog-approval-audit.md +17 -0
  82. package/memory/90-decisions/0063-events-persistent-e2e.md +19 -0
  83. package/memory/90-decisions/0064-graphloop-sqlite-store.md +20 -0
  84. package/memory/90-decisions/0065-context-graph-source-cache.md +20 -0
  85. package/memory/90-decisions/0066-graph-deterministic-extractors.md +16 -0
  86. package/memory/90-decisions/0067-graph-sync-capability.md +17 -0
  87. package/memory/90-decisions/0068-graph-sync-cli-mcp.md +17 -0
  88. package/memory/90-decisions/0069-real-autonomy-demo.md +16 -0
  89. package/memory/90-decisions/0070-mcp-stdio-real.md +11 -0
  90. package/memory/90-decisions/0071-server-persistence-composition.md +12 -0
  91. package/memory/90-decisions/0072-sandbox-security-boundaries.md +9 -0
  92. package/memory/90-decisions/0073-last-mile-rollback-benchmark-plugins.md +17 -0
  93. package/package.json +13 -3
@@ -0,0 +1,52 @@
1
+ import fs from 'node:fs';
2
+ import os from 'node:os';
3
+ import path from 'node:path';
4
+ import Database from 'better-sqlite3';
5
+ import { CapabilityRegistry } from "../packages/core/src/index.js";
6
+ import { EventBus } from "../packages/events/src/index.js";
7
+ import { GraphLoop } from "../packages/graph/src/index.js";
8
+ import { ApprovalLedger, PolicyEngine } from "../packages/policy/src/index.js";
9
+ import { InMemoryEventStream } from "../packages/adapter-nest/src/index.js";
10
+ import { createDefaultControlPlane } from "../apps/server/src/main.js";
11
+ import { SqliteApprovalStore, SqliteContextCache, SqliteEventStore, SqliteGraphStore, SqliteMigrationRunner, SqliteObservationStore, SqliteOrchestrationStore, SqliteRuntimePersistence } from "../packages/adapter-sqlite/src/index.js";
12
+ const agent = { id: 'server-persistence-agent', name: 'Persistence test agent', role: 'developer', autonomy: 'supervised' };
13
+ const definition = { schemaVersion: '2.0', createdAt: '2026-08-02T00:00:00.000Z', updatedAt: '2026-08-02T00:00:00.000Z', correlationId: 'server-persistence', id: 'server.persistence.read', version: '1.0.0', description: 'Deterministic persistence probe', permissions: ['read'], risk: 'low', sideEffects: [], requirements: [], supportsAutonomy: true, idempotent: true, timeoutMs: 1000, retry: { maxAttempts: 1, backoffMs: 0 }, aliases: [] };
14
+ function makeRegistry() {
15
+ const value = new CapabilityRegistry();
16
+ value.register({ definition, validateInput: (input) => input ?? {}, validateOutput: (output) => output, handler: async () => ({ capabilityId: definition.id, payload: { ok: true }, evidence: [{ id: 'server-persistence-evidence', source: 'server-persistence-test', locator: 'handler', capturedAt: '2026-08-02T00:00:00.000Z', status: 'verified' }] }) });
17
+ return value;
18
+ }
19
+ function makePolicy(database) {
20
+ return new PolicyEngine({ approvalLedger: new ApprovalLedger(new SqliteApprovalStore(database)), rules: [{ id: 'server-persistence-approval', priority: 10, effect: 'REQUIRE_APPROVAL', reason: 'Persistence probe requires approval', scope: {} }] });
21
+ }
22
+ function makeControlPlane(database, value, policy) {
23
+ const graph = new GraphLoop(new SqliteGraphStore(database));
24
+ const events = new EventBus(new SqliteEventStore(database));
25
+ return createDefaultControlPlane(new InMemoryEventStream(), value, policy, new SqliteRuntimePersistence(database), new ApprovalLedger(new SqliteApprovalStore(database)), events, graph, undefined, new SqliteOrchestrationStore(database), new SqliteObservationStore(database));
26
+ }
27
+ const root = fs.mkdtempSync(path.join(os.tmpdir(), 'forja-server-persistence-'));
28
+ const dbPath = path.join(root, 'runtime.db');
29
+ try {
30
+ const firstDatabase = new Database(dbPath);
31
+ new SqliteMigrationRunner(firstDatabase).apply();
32
+ const firstControlPlane = makeControlPlane(firstDatabase, makeRegistry(), makePolicy(firstDatabase));
33
+ const budget = { inputTokens: 40, outputTokens: 20, totalTokens: 60, usedTokens: 0 };
34
+ const started = await firstControlPlane.runtimeStart({ objective: 'restart persistence probe', agent, budget, steps: [{ capabilityId: definition.id, payload: {}, estimatedTokens: 10, categories: ['read'], environment: 'local', files: [], approval: { action: 'read.probe', justification: 'Prove approval persistence', impact: 'No files changed', expiresAt: '2099-01-01T00:00:00.000Z' } }] });
35
+ const awaiting = await firstControlPlane.runtimeExecute(started.runId);
36
+ const pending = await firstControlPlane.approvalList();
37
+ const graph = new GraphLoop(new SqliteGraphStore(firstDatabase));
38
+ graph.upsertNode({ id: 'restart-node', type: 'Task', label: 'restart persistence probe', status: 'verified' });
39
+ new SqliteContextCache(firstDatabase).set('restart-context', 'evidence context');
40
+ await new EventBus(new SqliteEventStore(firstDatabase)).append({ type: 'approval.requested', aggregateId: started.runId, payload: { approvalId: pending[0].id }, idempotencyKey: `approval:${pending[0].id}` });
41
+ await firstControlPlane.record({ traceId: 'restart-observation', runId: started.runId, outcome: 'blocked', contextRefs: ['restart-context'] });
42
+ firstDatabase.close();
43
+ const secondDatabase = new Database(dbPath);
44
+ const secondControlPlane = makeControlPlane(secondDatabase, makeRegistry(), makePolicy(secondDatabase));
45
+ const recovered = await secondControlPlane.runtimeGet(started.runId);
46
+ const result = { ok: recovered.runId === started.runId && awaiting.state === 'awaiting_approval', state: recovered.state, approvals: (await secondControlPlane.approvalList()).length, context: new SqliteContextCache(secondDatabase).get('restart-context'), graphNodes: new GraphLoop(new SqliteGraphStore(secondDatabase)).query({ labelIncludes: 'restart persistence' }).length, events: (await new EventBus(new SqliteEventStore(secondDatabase)).list()).length, observations: (await secondControlPlane.observations()).length };
47
+ secondDatabase.close();
48
+ console.log(JSON.stringify(result));
49
+ }
50
+ finally {
51
+ fs.rmSync(root, { recursive: true, force: true });
52
+ }
@@ -0,0 +1,52 @@
1
+ import fs from 'node:fs';
2
+ import os from 'node:os';
3
+ import path from 'node:path';
4
+ import Database from 'better-sqlite3';
5
+ import { CapabilityRegistry } from "../packages/core/src/index.js";
6
+ import { EventBus } from "../packages/events/src/index.js";
7
+ import { GraphLoop } from "../packages/graph/src/index.js";
8
+ import { ApprovalLedger, PolicyEngine } from "../packages/policy/src/index.js";
9
+ import { InMemoryEventStream } from "../packages/adapter-nest/src/index.js";
10
+ import { createDefaultControlPlane } from "../apps/server/src/main.js";
11
+ import { SqliteApprovalStore, SqliteContextCache, SqliteEventStore, SqliteGraphStore, SqliteMigrationRunner, SqliteObservationStore, SqliteOrchestrationStore, SqliteRuntimePersistence } from "../packages/adapter-sqlite/src/index.js";
12
+ const agent = { id: 'server-persistence-agent', name: 'Persistence test agent', role: 'developer', autonomy: 'supervised' };
13
+ const definition = { schemaVersion: '2.0', createdAt: '2026-08-02T00:00:00.000Z', updatedAt: '2026-08-02T00:00:00.000Z', correlationId: 'server-persistence', id: 'server.persistence.read', version: '1.0.0', description: 'Deterministic persistence probe', permissions: ['read'], risk: 'low', sideEffects: [], requirements: [], supportsAutonomy: true, idempotent: true, timeoutMs: 1000, retry: { maxAttempts: 1, backoffMs: 0 }, aliases: [] };
14
+ function makeRegistry() {
15
+ const value = new CapabilityRegistry();
16
+ value.register({ definition, validateInput: (input) => input ?? {}, validateOutput: (output) => output, handler: async () => ({ capabilityId: definition.id, payload: { ok: true }, evidence: [{ id: 'server-persistence-evidence', source: 'server-persistence-test', locator: 'handler', capturedAt: '2026-08-02T00:00:00.000Z', status: 'verified' }] }) });
17
+ return value;
18
+ }
19
+ function makePolicy(database) {
20
+ return new PolicyEngine({ approvalLedger: new ApprovalLedger(new SqliteApprovalStore(database)), rules: [{ id: 'server-persistence-approval', priority: 10, effect: 'REQUIRE_APPROVAL', reason: 'Persistence probe requires approval', scope: {} }] });
21
+ }
22
+ function makeControlPlane(database, value, policy) {
23
+ const graph = new GraphLoop(new SqliteGraphStore(database));
24
+ const events = new EventBus(new SqliteEventStore(database));
25
+ return createDefaultControlPlane(new InMemoryEventStream(), value, policy, new SqliteRuntimePersistence(database), new ApprovalLedger(new SqliteApprovalStore(database)), events, graph, undefined, new SqliteOrchestrationStore(database), new SqliteObservationStore(database));
26
+ }
27
+ const root = fs.mkdtempSync(path.join(os.tmpdir(), 'forja-server-persistence-'));
28
+ const dbPath = path.join(root, 'runtime.db');
29
+ try {
30
+ const firstDatabase = new Database(dbPath);
31
+ new SqliteMigrationRunner(firstDatabase).apply();
32
+ const firstControlPlane = makeControlPlane(firstDatabase, makeRegistry(), makePolicy(firstDatabase));
33
+ const budget = { inputTokens: 40, outputTokens: 20, totalTokens: 60, usedTokens: 0 };
34
+ const started = await firstControlPlane.runtimeStart({ objective: 'restart persistence probe', agent, budget, steps: [{ capabilityId: definition.id, payload: {}, estimatedTokens: 10, categories: ['read'], environment: 'local', files: [], approval: { action: 'read.probe', justification: 'Prove approval persistence', impact: 'No files changed', expiresAt: '2099-01-01T00:00:00.000Z' } }] });
35
+ const awaiting = await firstControlPlane.runtimeExecute(started.runId);
36
+ const pending = await firstControlPlane.approvalList();
37
+ const graph = new GraphLoop(new SqliteGraphStore(firstDatabase));
38
+ graph.upsertNode({ id: 'restart-node', type: 'Task', label: 'restart persistence probe', status: 'verified' });
39
+ new SqliteContextCache(firstDatabase).set('restart-context', 'evidence context');
40
+ await new EventBus(new SqliteEventStore(firstDatabase)).append({ type: 'approval.requested', aggregateId: started.runId, payload: { approvalId: pending[0].id }, idempotencyKey: `approval:${pending[0].id}` });
41
+ await firstControlPlane.record({ traceId: 'restart-observation', runId: started.runId, outcome: 'blocked', contextRefs: ['restart-context'] });
42
+ firstDatabase.close();
43
+ const secondDatabase = new Database(dbPath);
44
+ const secondControlPlane = makeControlPlane(secondDatabase, makeRegistry(), makePolicy(secondDatabase));
45
+ const recovered = await secondControlPlane.runtimeGet(started.runId);
46
+ const result = { ok: recovered.runId === started.runId && awaiting.state === 'awaiting_approval', state: recovered.state, approvals: (await secondControlPlane.approvalList()).length, context: new SqliteContextCache(secondDatabase).get('restart-context'), graphNodes: new GraphLoop(new SqliteGraphStore(secondDatabase)).query({ labelIncludes: 'restart persistence' }).length, events: (await new EventBus(new SqliteEventStore(secondDatabase)).list()).length, observations: (await secondControlPlane.observations()).length };
47
+ secondDatabase.close();
48
+ console.log(JSON.stringify(result));
49
+ }
50
+ finally {
51
+ fs.rmSync(root, { recursive: true, force: true });
52
+ }
@@ -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,40 @@
1
+ # ForjaJS 2.x — Implementation audit
2
+
3
+ Auditoria realizada em 2026-08-02 sobre o código executável e os testes do repositório. “Existe” só foi marcado quando há implementação; “produção” só quando a composição oficial ou o caminho CLI é exercitado.
4
+
5
+ | Componente | Existe | Integrado | Persistente | Testado | Produção |
6
+ | --- | ---: | ---: | ---: | ---: | ---: |
7
+ | Contratos versionados | sim | sim | n/a | sim | sim |
8
+ | Capability Registry | sim | sim | n/a | sim | sim |
9
+ | CLI adapter | sim | sim | n/a | sim | sim |
10
+ | Runtime | sim | sim | sim | sim | sim |
11
+ | Policy/approvals | sim | sim | sim | sim | sim |
12
+ | Sprint/Task/Handoff | sim | sim | sim | sim | sim |
13
+ | Context Engine | sim | sim | sim | sim | sim |
14
+ | GraphLoop | sim | sim | sim | sim | sim |
15
+ | Sandbox Git worktree | sim | sim | sessão | sim | sim |
16
+ | Sandbox rollback | sim | sim | sessão | sim | sim |
17
+ | Validator | sim | sim | n/a | sim | sim |
18
+ | Event Bus/Scheduler | sim | sim | sim | sim | sim |
19
+ | MCP stdio | sim | sim | n/a | sim | sim |
20
+ | SDK | sim | sim | n/a | sim | sim |
21
+ | Nest adapter/control plane | sim | sim | sim | sim | sim |
22
+ | Dashboard | sim | sim | via API | sim | parcial |
23
+ | Observability/Evals | sim | sim | sim | sim | sim |
24
+ | Plugin SDK | sim | sim | n/a | sim | sim |
25
+ | GitHub/Docker official boundaries | sim | não há handler externo | n/a | sim | boundary |
26
+
27
+ ## Evidências executadas
28
+
29
+ - `npm run demo:autonomy`: fixture externa, worktree Git, alteração real, `npm test`, diff, promoção, SQLite, GraphLoop e handoff.
30
+ - `test/mcp-stdio.test.js`: transporte JSON-RPC por processo filho, stdout limpo, tools/resources e shutdown.
31
+ - `test/server-persistence.test.js`: composição oficial SQLite, encerramento/recriação e recuperação de runtime, approval, contexto, grafo, evento e observação.
32
+ - `test/sandbox.test.js` e `test/adapter-git.test.js`: promoção e rollback explícitos.
33
+ - `test/context-benchmark.test.js`: benchmark determinístico; execução observada nesta árvore: baseline 214.549 tokens estimados, contexto selecionado 9.175, redução 95,72%, cache hit 1 e cobertura de evidência 1.
34
+ - `npm test -- --test-concurrency=1`: 300/300 aprovados.
35
+ - `npm run build`: aprovado.
36
+ - `git diff --check`: aprovado.
37
+
38
+ ## Limites honestos
39
+
40
+ Os plugins oficiais são boundaries permissionados, não clientes GitHub/Docker completos. O dashboard é superfície de supervisão e não foi usado como dependência do fluxo CLI-first. A estimativa de tokens é um proxy determinístico bytes/4, não telemetria de um provedor de modelo. Essas limitações impedem afirmar que todos os cenários externos são 10/10; o fluxo local-first comprovado está fechado.
@@ -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,40 @@
1
+ # Sprint 12 — Prova de autonomia supervisionada real
2
+
3
+ ## Objetivo
4
+
5
+ Substituir a prova E2E simulada por uma demonstração repetível que usa fixture externa,
6
+ Git worktree, arquivo real, teste real, aprovação persistida, promoção real e estado
7
+ auditável em SQLite.
8
+
9
+ ## Escopo
10
+
11
+ - `npm run demo:autonomy`;
12
+ - agente simulado determinístico, sem provedor LLM;
13
+ - Context Engine e GraphLoop antes do plano;
14
+ - Policy Engine e `ApprovalLedger` antes da escrita;
15
+ - `GitWorktreeBackend` no caminho principal;
16
+ - Validator independente antes da promoção;
17
+ - Sprint, Task, Handoff, Event Bus e auditoria persistidos.
18
+
19
+ ## Critérios de aceite
20
+
21
+ - fixture é criada fora do repositório do framework;
22
+ - teste inicia falhando e termina passando após edição na worktree;
23
+ - workspace principal da fixture só muda na promoção explícita;
24
+ - aprovação, run, checkpoint, sandbox, evento e handoff sobrevivem no SQLite;
25
+ - GraphLoop recebe evidências e relações da execução;
26
+ - Validator retorna `accepted` antes de `promote`;
27
+ - teste automatizado repete o fluxo e limpa seus artefatos temporários.
28
+
29
+ ## Fora do escopo
30
+
31
+ MCP stdio real, composição de servidor após restart abrupto, rollback automatizado,
32
+ contradições avançadas, plugins oficiais e benchmark comparativo de tokens. São as
33
+ próximas sprints de fechamento 10/10.
34
+
35
+ ## Evidências
36
+
37
+ - `scripts/demo-autonomy.ts`;
38
+ - `test/demo-autonomy.test.js`;
39
+ - `npm run demo:autonomy`;
40
+ - saída observada: validação `accepted`, uma alteração promovida, 18 nós e 14 arestas.
@@ -0,0 +1,26 @@
1
+ # Sprint 13 — MCP stdio real
2
+
3
+ ## Objetivo
4
+
5
+ Provar que clientes externos conseguem iniciar `forja mcp:start`, negociar o
6
+ protocolo JSON-RPC por stdio, descobrir tools, descrever e executar capability,
7
+ ler resource e encerrar sem perder o contrato de transporte.
8
+
9
+ ## Critérios de aceite
10
+
11
+ - processo MCP real é iniciado por `node bin/forja.ts mcp:start`;
12
+ - cada resposta é JSON-RPC válido em stdout;
13
+ - stdout não contém logs não-JSON e stderr permanece limpo no caminho feliz;
14
+ - `initialize`, `notifications/initialized`, `tools/list`, `tools/call`,
15
+ `resources/list` e `resources/read` funcionam;
16
+ - execução retorna `ExecutionResult` estruturado;
17
+ - EOF encerra o servidor com exit code 0.
18
+
19
+ ## Evidência
20
+
21
+ `test/mcp-stdio.test.js` executa um cliente filho real contra o transporte.
22
+
23
+ ## Próximo passo
24
+
25
+ Compor o mesmo transporte no servidor oficial e provar reinício abrupto com
26
+ runtime, approval, context cache e GraphLoop persistidos.
@@ -0,0 +1,28 @@
1
+ # Sprint 14 — Composição oficial persistente e restart
2
+
3
+ ## Objetivo
4
+
5
+ Provar que o backend Nest oficial compõe os adapters SQLite e recupera estado
6
+ operacional depois que a primeira composição é encerrada e uma segunda é criada.
7
+
8
+ ## Critérios de aceite
9
+
10
+ - RuntimeRun e plano são recuperáveis;
11
+ - approval pendente permanece disponível;
12
+ - checkpoint/runtime state são lidos pelo novo processo;
13
+ - Context cache, GraphLoop e Event Bus preservam dados;
14
+ - Sprint/Task/Handoff e Observabilidade usam stores SQLite no bootstrap;
15
+ - build estrito e probe em processo separado passam.
16
+
17
+ ## Evidência
18
+
19
+ `test/server-persistence.test.js` inicia `test/server-persistence-probe.mjs` com
20
+ `node --import tsx`; o probe cria duas composições oficiais contra o mesmo arquivo
21
+ SQLite e confirma run `awaiting_approval`, approval, contexto, grafo, eventos e
22
+ observações após o fechamento da primeira conexão.
23
+
24
+ ## Risco conhecido
25
+
26
+ Eventos publicados pelo Control Plane são assíncronos; o lifecycle oficial deve
27
+ adicionar drain explícito antes de shutdown gracioso. O probe aguarda o flush para
28
+ não confundir essa fronteira com perda de dados.
@@ -0,0 +1,22 @@
1
+ # Sprint 15 — Caos determinístico e hardening de segurança
2
+
3
+ ## Objetivo
4
+
5
+ Transformar falhas previsíveis em estados auditáveis, sem perder evidência nem
6
+ permitir que entradas externas escapem do escopo da execução.
7
+
8
+ ## Entregas
9
+
10
+ - approval expirada e reutilização recusadas;
11
+ - corrupção de payload SQLite falha explicitamente;
12
+ - policy continua deny-by-default;
13
+ - caminhos Graph/Git fora da raiz são ignorados;
14
+ - sandbox não herda secrets arbitrários do ambiente;
15
+ - testes MCP stdio cobrem payload/protocolo em processo real.
16
+
17
+ ## Fora do escopo desta fatia
18
+
19
+ Docker escape review, plugins maliciosos, lock SQLite sob concorrência,
20
+ checkpoint rollback automático, fuzzing de payload e benchmark de tokens. Esses
21
+ casos continuam como bloqueios de release 10/10, embora os gates básicos já
22
+ estejam cobertos.
@@ -0,0 +1,25 @@
1
+ # Sprint 16 — Última milha verificável
2
+
3
+ ## Objetivo
4
+
5
+ Fechar três lacunas objetivas da avaliação 10/10 sem criar novos módulos: rollback explícito do sandbox, benchmark reproduzível de contexto e plugins oficiais permissionados.
6
+
7
+ ## Escopo
8
+
9
+ - `promoted → rolled_back` no contrato e no `SandboxEngine`;
10
+ - reversão de patch real no `GitWorktreeBackend`;
11
+ - benchmark JSON determinístico em `npm run benchmark:context`;
12
+ - manifests oficiais `@forja/plugin-github` e `@forja/plugin-docker`;
13
+ - testes de contrato, rollback, benchmark e isolamento de permissões.
14
+
15
+ ## Critérios de aceite
16
+
17
+ - rollback rejeita sessão que não foi promovida;
18
+ - Git recebe o patch reverso antes da limpeza da worktree;
19
+ - benchmark mede baseline, contexto selecionado, checksum, cache hit e economia;
20
+ - plugins são descobertos pelo `PluginRegistry` e não acessam serviços sem permissão;
21
+ - `npm test -- --test-concurrency=1`, build e `git diff --check` passam.
22
+
23
+ ## Fora do escopo
24
+
25
+ Integrações de rede com GitHub, execução de Docker e rollback automático de qualquer comando externo. Esses handlers dependem de adapters do host e continuam governados pelo Policy Engine.
@@ -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.