forjajs 2.0.3 → 3.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude/agents/release-auditor.md +19 -10
- package/AGENTS.md +1 -1
- package/CHANGELOG.md +80 -0
- package/DOC-MAP.md +9 -0
- package/README.md +85 -5
- package/README.pt-BR.md +34 -5
- package/dist/apps/dashboard/app/api/forja/[...path]/route.js +8 -1
- package/dist/apps/dashboard/app/api/forja/guard.d.ts +24 -0
- package/dist/apps/dashboard/app/api/forja/guard.js +63 -0
- package/dist/apps/server/src/forja-nest.module.js +9 -4
- package/dist/apps/server/src/main.js +10 -1
- package/dist/bin/forja.js +14 -2
- package/dist/lib/code-context.js +6 -0
- package/dist/lib/core/architecture-gate.d.ts +20 -0
- package/dist/lib/core/architecture-gate.js +60 -0
- package/dist/lib/core/doc-graph.js +6 -4
- package/dist/lib/core/drift-gate.d.ts +18 -0
- package/dist/lib/core/drift-gate.js +55 -0
- package/dist/lib/core/gates.d.ts +9 -2
- package/dist/lib/core/gates.js +13 -2
- package/dist/lib/core/health.js +15 -0
- package/dist/lib/core/incident-search.d.ts +19 -0
- package/dist/lib/core/incident-search.js +32 -0
- package/dist/lib/core/model-pricing.d.ts +31 -0
- package/dist/lib/core/model-pricing.js +74 -0
- package/dist/lib/core/registry.d.ts +248 -0
- package/dist/lib/core/registry.js +249 -0
- package/dist/lib/core/release.d.ts +247 -0
- package/dist/lib/core/release.js +5 -1
- package/dist/lib/core/risk-collect.d.ts +19 -0
- package/dist/lib/core/risk-collect.js +173 -0
- package/dist/lib/drift-sentinel.d.ts +59 -0
- package/dist/lib/drift-sentinel.js +126 -0
- package/dist/lib/generators/memory-generator.js +8 -6
- package/dist/lib/generators/nest-generator.js +24 -10
- package/dist/lib/project-upgrade.js +1 -1
- package/dist/lib/workspace.d.ts +7 -0
- package/dist/lib/workspace.js +34 -5
- package/dist/packages/adapter-git/src/index.d.ts +1 -1
- package/dist/packages/adapter-git/src/index.js +11 -6
- package/dist/packages/adapter-nest/src/index.d.ts +19 -0
- package/dist/packages/adapter-nest/src/index.js +26 -1
- package/dist/packages/adapter-sqlite/src/index.d.ts +27 -1
- package/dist/packages/adapter-sqlite/src/index.js +49 -0
- package/dist/packages/contracts/src/index.d.ts +33 -0
- package/dist/packages/contracts/src/index.js +13 -0
- package/dist/packages/core/src/index.d.ts +12 -0
- package/dist/packages/core/src/index.js +29 -0
- package/dist/packages/engineering/architecture/src/index.d.ts +76 -0
- package/dist/packages/engineering/architecture/src/index.js +131 -0
- package/dist/packages/engineering/evidence/src/index.d.ts +41 -0
- package/dist/packages/engineering/evidence/src/index.js +31 -0
- package/dist/packages/engineering/identity/src/index.d.ts +57 -0
- package/dist/packages/engineering/identity/src/index.js +88 -0
- package/dist/packages/engineering/monitoring/src/index.d.ts +37 -0
- package/dist/packages/engineering/monitoring/src/index.js +40 -0
- package/dist/packages/engineering/provenance/src/index.d.ts +25 -0
- package/dist/packages/engineering/provenance/src/index.js +21 -0
- package/dist/packages/engineering/risk/src/index.d.ts +89 -0
- package/dist/packages/engineering/risk/src/index.js +120 -0
- package/dist/packages/graph/src/index.d.ts +23 -1
- package/dist/packages/graph/src/index.js +88 -15
- package/dist/packages/llm/src/index.d.ts +43 -0
- package/dist/packages/llm/src/index.js +131 -0
- package/dist/packages/mcp/src/index.js +27 -8
- package/dist/packages/orchestration/src/index.d.ts +11 -1
- package/dist/packages/orchestration/src/index.js +34 -7
- package/dist/packages/policy/src/index.d.ts +40 -0
- package/dist/packages/policy/src/index.js +39 -4
- package/dist/packages/runtime/src/index.js +3 -0
- package/dist/packages/sandbox/src/index.d.ts +47 -0
- package/dist/packages/sandbox/src/index.js +59 -0
- package/dist/packages/validator/src/index.d.ts +8 -0
- package/dist/packages/validator/src/index.js +21 -6
- package/dist/scripts/adr.d.ts +17 -0
- package/dist/scripts/adr.js +152 -0
- package/dist/scripts/agent-harness.js +14 -4
- package/dist/scripts/agent.d.ts +27 -0
- package/dist/scripts/agent.js +249 -0
- package/dist/scripts/architecture.d.ts +16 -0
- package/dist/scripts/architecture.js +186 -0
- package/dist/scripts/cost-economy.d.ts +2 -0
- package/dist/scripts/cost-economy.js +79 -0
- package/dist/scripts/demo-autonomy.js +15 -8
- package/dist/scripts/demo-workspace.d.ts +6 -0
- package/dist/scripts/demo-workspace.js +101 -0
- package/dist/scripts/drift-check.d.ts +17 -0
- package/dist/scripts/drift-check.js +63 -0
- package/dist/scripts/engineer.d.ts +20 -0
- package/dist/scripts/engineer.js +208 -0
- package/dist/scripts/evidence.d.ts +12 -0
- package/dist/scripts/evidence.js +55 -0
- package/dist/scripts/gates.d.ts +6 -2
- package/dist/scripts/gates.js +14 -4
- package/dist/scripts/incident.d.ts +19 -0
- package/dist/scripts/incident.js +103 -0
- package/dist/scripts/llm-fit.js +160 -0
- package/dist/scripts/provenance.d.ts +14 -0
- package/dist/scripts/provenance.js +114 -0
- package/dist/scripts/risk.d.ts +15 -0
- package/dist/scripts/risk.js +81 -0
- package/dist/scripts/simulate.d.ts +20 -0
- package/dist/scripts/simulate.js +150 -0
- package/dist/scripts/sync-universal-memory.js +19 -6
- package/docs/architecture/FORJA-3-ENGINEERING-INTELLIGENCE-ARCHITECTURE.md +442 -0
- package/docs/llm-fit-loop.md +41 -0
- package/docs/modos-de-operacao.md +52 -0
- package/docs/produto/factsheet-marketing.md +151 -0
- package/docs/produto/roteiro-demo.md +47 -0
- package/memory/40-delivery/current-sprint.md +3 -6
- package/memory/90-decisions/0074-llm-fit-loop-cli-adapters.md +51 -0
- package/memory/90-decisions/0075-workspace-demo-isolado.md +43 -0
- package/memory/90-decisions/0076-modos-embedded-e-studio.md +43 -0
- package/memory/90-decisions/0077-cost-aware-autonomy-budget.md +95 -0
- package/memory/90-decisions/0078-forjajs-3-engineering-control-plane.md +116 -0
- package/memory/90-decisions/0079-autonomous-maintenance-readiness.md +102 -0
- package/package.json +9 -2
- package/specs/agent-identity-reputation/plan.md +133 -0
- package/specs/agent-identity-reputation/spec.md +125 -0
- package/specs/agent-identity-reputation/tasks.md +51 -0
- package/specs/agent-runtime-monitoring/plan.md +78 -0
- package/specs/agent-runtime-monitoring/spec.md +92 -0
- package/specs/agent-runtime-monitoring/tasks.md +39 -0
- package/specs/ai-code-provenance/plan.md +71 -0
- package/specs/ai-code-provenance/spec.md +97 -0
- package/specs/ai-code-provenance/tasks.md +39 -0
- package/specs/architecture-constitution/plan.md +110 -0
- package/specs/architecture-constitution/spec.md +114 -0
- package/specs/architecture-constitution/tasks.md +58 -0
- package/specs/change-risk-engine/plan.md +130 -0
- package/specs/change-risk-engine/spec.md +119 -0
- package/specs/change-risk-engine/tasks.md +72 -0
- package/specs/cost-aware-autonomy-budget/spec.md +102 -0
- package/specs/drift-sentinel/spec.md +117 -0
- package/specs/engineer-facade-extension/plan.md +71 -0
- package/specs/engineer-facade-extension/spec.md +98 -0
- package/specs/engineer-facade-extension/tasks.md +36 -0
- package/specs/engineering-evidence-ledger/plan.md +121 -0
- package/specs/engineering-evidence-ledger/spec.md +90 -0
- package/specs/engineering-evidence-ledger/tasks.md +54 -0
- package/specs/engineering-graph-extensions/plan.md +92 -0
- package/specs/engineering-graph-extensions/spec.md +101 -0
- package/specs/engineering-graph-extensions/tasks.md +60 -0
- package/specs/engineering-intelligence/spec.md +177 -0
- package/specs/learning-loop-incidents/plan.md +59 -0
- package/specs/learning-loop-incidents/spec.md +93 -0
- package/specs/learning-loop-incidents/tasks.md +36 -0
- package/specs/predictive-change-simulation/plan.md +109 -0
- package/specs/predictive-change-simulation/spec.md +107 -0
- package/specs/predictive-change-simulation/tasks.md +41 -0
- package/specs/release-auditor-health/plan.md +88 -0
- package/specs/release-auditor-health/spec.md +82 -0
- package/specs/release-auditor-health/tasks.md +72 -0
- package/specs/smart-agent-routing/plan.md +55 -0
- package/specs/smart-agent-routing/spec.md +85 -0
- package/specs/smart-agent-routing/tasks.md +26 -0
- package/dist/scripts/server-persistence-probe.d.ts +0 -1
- package/dist/scripts/server-persistence-probe.js +0 -52
- package/dist/scripts/server-persistence-probe.mjs +0 -52
- /package/dist/scripts/{server-persistence-probe.d.mts → llm-fit.d.ts} +0 -0
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
# Plan: Engineering Evidence Ledger + `forja engineer` (façade)
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Status**: approved
|
|
5
|
+
- **Criado em**: 2026-09-01
|
|
6
|
+
|
|
7
|
+
## 1. Abordagem técnica
|
|
8
|
+
|
|
9
|
+
Dois entregáveis pequenos, ambos composição pura sobre o que já existe — nenhuma tabela SQLite
|
|
10
|
+
nova, nenhuma lógica de decisão nova:
|
|
11
|
+
|
|
12
|
+
1. `packages/engineering/evidence` — `buildEvidenceLedger(input)`, função pura que recebe um
|
|
13
|
+
`RuntimeRun` + `AuditRecord[]`/`ApprovalRequest[]` já filtrados + `ArchitectureCheckReport`/
|
|
14
|
+
`ChangeRiskAssessment` opcionais e devolve o JSON agregado (`run/intent/agent/risk/
|
|
15
|
+
architectureCheck/tests/approvals/commit`). `scripts/evidence.ts` é o adapter (`evidence:show
|
|
16
|
+
<run-id>`) que busca esses dados reais via `SqliteRuntimeRunStore`/`SqliteAuditStore`/
|
|
17
|
+
`ApprovalLedger`.
|
|
18
|
+
2. `scripts/engineer.ts` — `forja engineer "<objetivo>"`, façade que chama, nesta ordem:
|
|
19
|
+
`ContextEngine.build()` (grafo, mesmo padrão de `scripts/demo-autonomy.ts`) →
|
|
20
|
+
`GraphLoop.contextRecords(objetivo)` filtrado a nós ADR/SPEC (SPEC-032, reaproveitado, não uma
|
|
21
|
+
busca nova) → `architecture:check` (não escopado — antes de haver diff, não há arquivo pra
|
|
22
|
+
escopar; ver D1) → `RiskEngine.assess()` (só com `--ref`; ver D1) → fluxo recomendado, parseado
|
|
23
|
+
de `docs/fluxo.md` (D2 — parser, não cópia hardcoded).
|
|
24
|
+
|
|
25
|
+
## 2. Módulos afetados
|
|
26
|
+
|
|
27
|
+
| Caminho | Mudança | Risco |
|
|
28
|
+
|---|---|---|
|
|
29
|
+
| `packages/engineering/evidence/src/index.ts` | novo — `buildEvidenceLedger` | Baixo — mapeamento puro |
|
|
30
|
+
| `scripts/evidence.ts` | novo — `evidence:show <run-id>` | Baixo |
|
|
31
|
+
| `scripts/engineer.ts` | novo — `engineer "<objetivo>" [--ref <ref>] [--json]` | Médio — orquestra 4 subsistemas, mas cada chamada já existe |
|
|
32
|
+
| `lib/core/registry.ts` | 2 comandos novos | Baixo |
|
|
33
|
+
| `test/evidence-ledger.test.js` (novo) | testes puros de `buildEvidenceLedger` | — |
|
|
34
|
+
| `test/engineer-cli.test.js` (novo) | fixture git isolada, `engineer` ponta a ponta | — |
|
|
35
|
+
|
|
36
|
+
## 3. Diagrama de fluxo
|
|
37
|
+
|
|
38
|
+
```text
|
|
39
|
+
forja engineer "<objetivo>" [--ref <ref>]
|
|
40
|
+
│
|
|
41
|
+
├─► ContextEngine.build({ objective, graph: GraphContextSource(graph.contextRecords) })
|
|
42
|
+
├─► graph.contextRecords(objetivo) filtrado a nós ADR/SPEC (SPEC-032)
|
|
43
|
+
├─► architecture:check (constitution.json real, SPEC-033) — não escopado
|
|
44
|
+
├─► RiskEngine.assess() (SPEC-034) — só se --ref foi passado
|
|
45
|
+
└─► fluxo recomendado — parseado da tabela "Etapa → papel → comando" de docs/fluxo.md
|
|
46
|
+
│
|
|
47
|
+
▼
|
|
48
|
+
saída de texto (default) ou --json (AC-3: nunca sintetiza além do que cada
|
|
49
|
+
subsistema já disse)
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## 4. Contratos (API/CLI/Schema)
|
|
53
|
+
|
|
54
|
+
```ts
|
|
55
|
+
// packages/engineering/evidence/src/index.ts
|
|
56
|
+
export interface EvidenceLedgerInput {
|
|
57
|
+
readonly run: RuntimeRun;
|
|
58
|
+
readonly auditRecords: readonly AuditRecord[];
|
|
59
|
+
readonly approvals: readonly ApprovalRequest[];
|
|
60
|
+
readonly architectureCheck?: ArchitectureCheckReport;
|
|
61
|
+
readonly riskAssessment?: ChangeRiskAssessment;
|
|
62
|
+
readonly commit?: string;
|
|
63
|
+
}
|
|
64
|
+
export interface EvidenceLedgerRecord {
|
|
65
|
+
readonly run: { readonly runId: string; readonly state: string; readonly startedAt: string; readonly updatedAt: string; readonly steps: number; readonly changedFiles: readonly string[] };
|
|
66
|
+
readonly intent: string;
|
|
67
|
+
readonly agent: AgentIdentity;
|
|
68
|
+
readonly architectureCheck?: ArchitectureCheckReport;
|
|
69
|
+
readonly risk?: ChangeRiskAssessment;
|
|
70
|
+
readonly tests?: EvaluationResult;
|
|
71
|
+
readonly approvals: readonly ApprovalRequest[];
|
|
72
|
+
readonly commit?: string;
|
|
73
|
+
}
|
|
74
|
+
export function buildEvidenceLedger(input: EvidenceLedgerInput): EvidenceLedgerRecord;
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
evidence:show <run-id>
|
|
79
|
+
engineer "<objetivo>" [--ref <ref>] [--json]
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
## 5. Decisões e alternativas
|
|
83
|
+
|
|
84
|
+
**D1**: `forja engineer` roda `architecture:check` **não escopado** (relatório completo, não
|
|
85
|
+
filtrado a arquivos) e só inclui `risk` quando `--ref` é passado explicitamente. A visão original
|
|
86
|
+
lista os dois como parte fixa da composição, mas `forja engineer` roda **antes** de existir um
|
|
87
|
+
diff (é a ferramenta que orienta o início do trabalho) — não há arquivos afetados ainda para
|
|
88
|
+
escopar nenhum dos dois. Alternativa rejeitada: inferir arquivos afetados a partir do texto do
|
|
89
|
+
objetivo (aí sim seria síntese/adivinhação, proibido por AC-3). Quando `--ref` é passado (ex.:
|
|
90
|
+
objetivo já tem uma branch com commits), o risco entra completo, exatamente como `risk:assess`
|
|
91
|
+
computaria.
|
|
92
|
+
|
|
93
|
+
**D2**: o "fluxo recomendado" é **parseado** da tabela "Etapa → papel → comando" existente em
|
|
94
|
+
`docs/fluxo.md`, não copiado/hardcoded em `scripts/engineer.ts`. Só uma fonte de verdade para os 6
|
|
95
|
+
passos SDD/GSD — se `docs/fluxo.md` mudar, `forja engineer` acompanha sem exigir sincronização
|
|
96
|
+
manual. Parser é uma regex sobre linhas de tabela markdown (determinístico, sem LLM).
|
|
97
|
+
|
|
98
|
+
**D3**: `EvidenceLedgerInput` não busca dado nenhum sozinho — é `scripts/evidence.ts`/
|
|
99
|
+
`scripts/engineer.ts` que buscam `RuntimeRun`/`AuditRecord`/`ApprovalRequest` reais e montam o
|
|
100
|
+
input. `buildEvidenceLedger` é só o mapeamento — igual ao par engine-puro/CLI-adapter já usado em
|
|
101
|
+
`packages/engineering/architecture` e `packages/engineering/risk`.
|
|
102
|
+
|
|
103
|
+
## 6. Dependências
|
|
104
|
+
|
|
105
|
+
- SPEC-032 (`GraphLoop.contextRecords`), SPEC-033 (`checkConstitution`), SPEC-034
|
|
106
|
+
(`assessRisk`/`RiskEngine`) — todas já mergeadas/em PR quando este sprint começa.
|
|
107
|
+
- `packages/context.ContextEngine`/`GraphContextSource` (já existentes, mesmo padrão de
|
|
108
|
+
`scripts/demo-autonomy.ts`).
|
|
109
|
+
- `packages/adapter-sqlite.SqliteRuntimeRunStore`/`SqliteAuditStore` (já existentes).
|
|
110
|
+
|
|
111
|
+
## 7. Rollout
|
|
112
|
+
|
|
113
|
+
- [ ] Feature flag necessária? Não.
|
|
114
|
+
- [ ] Migração de dados existentes? Não.
|
|
115
|
+
- [ ] Doc/persona impactada? README (comandos novos).
|
|
116
|
+
|
|
117
|
+
## 8. Sinais de fracasso (kill criteria)
|
|
118
|
+
|
|
119
|
+
Já registrado no apêndice de `specs/engineering-intelligence/spec.md`, §8 deste spec: se a saída de
|
|
120
|
+
`forja engineer` sobre um objetivo real não for usável sem edição, o design da façade (não os
|
|
121
|
+
engines subjacentes, já validados nos Sprints 1-2) é revisado.
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# Spec: Engineering Evidence Ledger + `forja engineer` (façade)
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-035
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **Criado em**: 2026-09-01
|
|
7
|
+
- **Sprint alvo**: Sprint 3
|
|
8
|
+
- **ADRs relacionadas**: ADR-0078; depende de SPEC-032, SPEC-033, SPEC-034 (a façade compõe as
|
|
9
|
+
três)
|
|
10
|
+
|
|
11
|
+
## 1. Problema
|
|
12
|
+
|
|
13
|
+
`AuditRecord`/`Observation`/`RuntimeRun` já são gravados por run, mas cada um em sua própria
|
|
14
|
+
tabela/stream — não existe uma view única "o que aconteceu neste run, do intent à evidência".
|
|
15
|
+
Separadamente, montar o quadro completo de uma mudança antes de começar (contexto + arquitetura +
|
|
16
|
+
risco + ADRs relevantes) hoje exige rodar vários comandos manualmente.
|
|
17
|
+
|
|
18
|
+
## 2. Proposta de valor
|
|
19
|
+
|
|
20
|
+
Uma view agregada por run (Evidence Ledger) e uma façade única (`forja engineer`) que compõe tudo
|
|
21
|
+
que já existe — sem introduzir nenhuma fonte de dado nova.
|
|
22
|
+
|
|
23
|
+
## 3. User stories
|
|
24
|
+
|
|
25
|
+
- **Como** governance, **quero** um registro append-only por run (`intent`, `agent`, `risk`,
|
|
26
|
+
`architectureCheck`, `tests`, `approvals`, `commit`), **para que** eu audite uma execução sem
|
|
27
|
+
cruzar manualmente quatro tabelas.
|
|
28
|
+
- **Como** desenvolvedor, **quero** `forja engineer "<objetivo>"` trazendo de uma vez arquitetura
|
|
29
|
+
afetada, ADRs relevantes, risco estimado e o fluxo recomendado, **para que** eu comece o trabalho
|
|
30
|
+
já orientado.
|
|
31
|
+
|
|
32
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
33
|
+
|
|
34
|
+
- [x] AC-1: view agregada (função pura sobre `AuditRecord`/`Observation`/`RuntimeRun` já
|
|
35
|
+
persistidos) produz o JSON no formato do exemplo da visão original (`run`, `intent`, `agent`,
|
|
36
|
+
`risk`, `architectureCheck`, `tests`, `approvals`, `commit`) — sem nova tabela SQLite além
|
|
37
|
+
das já existentes.
|
|
38
|
+
- [x] AC-2: `forja engineer "<objetivo>"` compõe, nesta ordem: `ContextEngine.build()` (já
|
|
39
|
+
existente) → `GraphLoop`/ADR relevantes (SPEC-032) → `architecture:check` (SPEC-033;
|
|
40
|
+
não escopado sem `--ref`, ver D1 do plan — não há diff ainda antes do trabalho começar) →
|
|
41
|
+
`RiskEngine.assess()` (SPEC-034, só com `--ref`) → fluxo recomendado (parseado de
|
|
42
|
+
`docs/fluxo.md`, D2 do plan — não reinventado).
|
|
43
|
+
- [x] AC-3: saída de `forja engineer` é estruturada (JSON opcional via `--json`, texto legível por
|
|
44
|
+
padrão) e nunca afirma nada que os componentes subjacentes não afirmaram — sem síntese de
|
|
45
|
+
LLM que possa alucinar arquitetura inexistente.
|
|
46
|
+
- [x] AC-4: nenhuma lógica de negócio nova em `forja engineer` além de composição e formatação —
|
|
47
|
+
qualquer decisão real continua nos engines que ela chama.
|
|
48
|
+
|
|
49
|
+
## 5. Escopo
|
|
50
|
+
|
|
51
|
+
**Dentro**: view agregada de evidência; façade `forja engineer` na versão mínima descrita acima
|
|
52
|
+
(sem seleção de time de agentes, que depende de Agent Identity/Reputation, fora de escopo).
|
|
53
|
+
|
|
54
|
+
**Fora**: seleção/recomendação de agente ou modelo (Fase 3); relatório de release
|
|
55
|
+
(`release:engineering-report`, feature separada da visão original, útil mas não bloqueante para
|
|
56
|
+
esta fundação); qualquer persistência nova — esta spec é puramente uma camada de leitura/composição
|
|
57
|
+
sobre dados que Sprints 1-2 e o framework já existente produzem.
|
|
58
|
+
|
|
59
|
+
## 6. NFRs / restrições
|
|
60
|
+
|
|
61
|
+
- View de evidência é derivável a qualquer momento a partir do que já está persistido — se
|
|
62
|
+
recalculada, produz o mesmo resultado (sem estado próprio para divergir).
|
|
63
|
+
- `forja engineer` nunca é a única fonte de verdade de nada — é sempre um resumo do que os
|
|
64
|
+
componentes subjacentes já disseram, rastreável de volta a cada um.
|
|
65
|
+
|
|
66
|
+
## 7. Riscos e mitigação
|
|
67
|
+
|
|
68
|
+
| Risco | Probabilidade | Impacto | Mitigação |
|
|
69
|
+
|---|---|---|---|
|
|
70
|
+
| `forja engineer` virar um "resumo de LLM" que esconde de onde vieram os fatos | Média (é a tentação óbvia de UX) | Alta (quebra auditabilidade) | AC-3 proíbe síntese que não seja rastreável componente-a-componente |
|
|
71
|
+
| Evidence Ledger duplicar dado já em `AuditRecord`/`Observation` | Baixa se implementado como view | Média (duas fontes de verdade) | AC-1 explicitamente "função pura sobre dados já persistidos", sem gravação própria |
|
|
72
|
+
|
|
73
|
+
## 8. Métricas de sucesso
|
|
74
|
+
|
|
75
|
+
Rodar `forja engineer` para uma mudança real proposta neste repositório produz uma saída que um
|
|
76
|
+
humano usaria sem edição para decidir se e como prosseguir — mesma métrica da spec master, aqui
|
|
77
|
+
verificada no nível do comando específico.
|
|
78
|
+
|
|
79
|
+
**Validado**: `forja engineer "compilar a architecture constitution deste repositório"` rodado
|
|
80
|
+
contra este próprio repositório (grafo real, 1013 arquivos). Produziu contexto relevante (specs e
|
|
81
|
+
testes de SPEC-033), ADRs/SPECs corretos (ADR-0078, SPEC-032/033/034), `architecture:check` real
|
|
82
|
+
(constitution já compilada neste repo) e o fluxo recomendado de `docs/fluxo.md` — utilizável sem
|
|
83
|
+
edição.
|
|
84
|
+
|
|
85
|
+
**Achado real corrigido durante a implementação (não um bug de lógica — um limite de exibição
|
|
86
|
+
ausente)**: a primeira execução sem `maxItems` devolveu **1013** referências de contexto (todo o
|
|
87
|
+
grafo do repositório caiu dentro do orçamento de 20k tokens), tornando a saída inutilizável sem
|
|
88
|
+
edição — o oposto do que esta métrica pede. Corrigido passando `maxItems: 10` para
|
|
89
|
+
`ContextEngine.build()` (as 10 mais relevantes, já ordenadas por `ContextEngine`); a lista completa
|
|
90
|
+
continua disponível via `context:smart`/`code:query`, que `forja engineer` não substitui.
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# Tasks: Engineering Evidence Ledger + `forja engineer`
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Plan**: ./plan.md
|
|
5
|
+
- **Status**: approved
|
|
6
|
+
- **Criado em**: 2026-09-01
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## T1 — `buildEvidenceLedger` (view pura) + `evidence:show`
|
|
11
|
+
- **Owner**: worker
|
|
12
|
+
- **Estimativa**: M
|
|
13
|
+
- **Depende de**: —
|
|
14
|
+
- **Paths**: `packages/engineering/evidence/src/index.ts`, `scripts/evidence.ts`, `lib/core/registry.ts`
|
|
15
|
+
- **Done quando**:
|
|
16
|
+
- [ ] `buildEvidenceLedger` mapeia `EvidenceLedgerInput` → `EvidenceLedgerRecord` sem inventar
|
|
17
|
+
nenhum campo que não veio no input (AC-1)
|
|
18
|
+
- [ ] `evidence:show <run-id>` busca `RuntimeRun` real (`SqliteRuntimeRunStore`), `AuditRecord`s
|
|
19
|
+
(`SqliteAuditStore`, filtrado por `aggregateId === runId`), `ApprovalRequest`s
|
|
20
|
+
(`ApprovalLedger`, filtrado por `correlationId === runId`)
|
|
21
|
+
- [ ] testes unitários (sem `fs`/rede): campos opcionais ausentes não aparecem como `null`
|
|
22
|
+
inventado; `run-id` inexistente é erro claro, não JSON vazio
|
|
23
|
+
|
|
24
|
+
## T2 — `forja engineer "<objetivo>"` façade
|
|
25
|
+
- **Owner**: worker
|
|
26
|
+
- **Estimativa**: G
|
|
27
|
+
- **Depende de**: T1 (reaproveita o mesmo padrão engine-puro/CLI-adapter)
|
|
28
|
+
- **Paths**: `scripts/engineer.ts`, `lib/core/registry.ts`
|
|
29
|
+
- **Done quando**:
|
|
30
|
+
- [ ] compõe, na ordem do plan: `ContextEngine.build()` → `contextRecords` filtrado a ADR/SPEC →
|
|
31
|
+
`architecture:check` não escopado → `RiskEngine.assess()` só com `--ref` (D1) → fluxo
|
|
32
|
+
recomendado parseado de `docs/fluxo.md` (D2)
|
|
33
|
+
- [ ] `--json` produz JSON estruturado; sem a flag, texto legível
|
|
34
|
+
- [ ] nenhuma string sintetizada além do que os componentes já disseram (grep manual: sem
|
|
35
|
+
chamada de LLM/heurística de texto livre em `scripts/engineer.ts`)
|
|
36
|
+
- [ ] `forja tools:doctor` continua verde
|
|
37
|
+
|
|
38
|
+
## T3 — prova sobre objetivo real deste repositório
|
|
39
|
+
- **Owner**: worker
|
|
40
|
+
- **Estimativa**: P
|
|
41
|
+
- **Depende de**: T2
|
|
42
|
+
- **Paths**: `test/engineer-cli.test.js` (novo)
|
|
43
|
+
- **Done quando**:
|
|
44
|
+
- [ ] fixture git isolada: `engineer "<objetivo>"` roda ponta a ponta (sem `--ref`) e produz
|
|
45
|
+
texto com todas as seções (contexto, ADRs relevantes, architecture:check, fluxo)
|
|
46
|
+
- [ ] com `--ref`, a seção de risco aparece com score real
|
|
47
|
+
- [ ] `evidence:show` recupera um run persistido de ponta a ponta
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## Handoffs entre agentes
|
|
52
|
+
|
|
53
|
+
T1 → T2 → T3 sequencial. Sem handoff de papel — spec e plan já aprovados cobrem as decisões de
|
|
54
|
+
produto/arquitetura.
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
# Plan: Engineering Graph extensions (ADR/SPEC como nós de primeira classe)
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Status**: approved
|
|
5
|
+
- **Criado em**: 2026-09-01
|
|
6
|
+
|
|
7
|
+
## 1. Abordagem técnica
|
|
8
|
+
|
|
9
|
+
Estender `extractDeterministicRelations` (packages/graph) para ler o campo `Status` de ADR e de
|
|
10
|
+
Spec como propriedade dedicada (não `GraphNode.status`/`KnowledgeStatus` — ver AC-1, é um
|
|
11
|
+
vocabulário de domínio diferente). `GraphNodeSpec`/`GraphNode` (packages/contracts) ganham um campo
|
|
12
|
+
opcional `documentStatus?: string` — extensão aditiva, mesmo padrão já usado nesta mesma janela de
|
|
13
|
+
trabalho para `PolicyLimits.maxCostUsd`/`isPathWithinRoot`/`remoteAddress` em `HttpRequest`: nenhum
|
|
14
|
+
consumidor existente quebra, campo ausente = comportamento idêntico ao de hoje.
|
|
15
|
+
|
|
16
|
+
`adr:list`/`adr:show`/`adr:impact`/`adr:graph` são scripts novos (`scripts/adr.ts`), mesmo padrão
|
|
17
|
+
de `scripts/drift-check.ts`: comando de processo, não capability registrada — não escreve em
|
|
18
|
+
projeto, só lê o grafo.
|
|
19
|
+
|
|
20
|
+
## 2. Módulos afetados
|
|
21
|
+
|
|
22
|
+
| Caminho | Mudança | Risco |
|
|
23
|
+
|---|---|---|
|
|
24
|
+
| `packages/graph/src/index.ts` | `extractDeterministicRelations`: ler `- **Status**: <valor>` de ADR e `- **Status**: <valor>` de spec.md, embutir no label do nó | Baixo — aditivo, mesma função já testada |
|
|
25
|
+
| `scripts/adr.ts` | novo — `adr:list`/`adr:show`/`adr:impact`/`adr:graph` | Baixo — só leitura |
|
|
26
|
+
| `lib/core/registry.ts` | registrar os 4 comandos novos | Baixo |
|
|
27
|
+
| `test/graph.test.js` | testes para status de ADR/SPEC no extrator | — |
|
|
28
|
+
| `test/adr-cli.test.js` (novo) | testes de CLI para os 4 comandos | — |
|
|
29
|
+
|
|
30
|
+
## 3. Diagrama de fluxo
|
|
31
|
+
|
|
32
|
+
```text
|
|
33
|
+
memory/90-decisions/*.md ──┐
|
|
34
|
+
specs/*/spec.md ─┼─► extractDeterministicRelations (estendido)
|
|
35
|
+
│ │
|
|
36
|
+
│ ▼
|
|
37
|
+
│ GraphLoop.apply (existente, sem mudança)
|
|
38
|
+
│
|
|
39
|
+
▼
|
|
40
|
+
scripts/adr.ts (list/show/impact/graph)
|
|
41
|
+
│
|
|
42
|
+
▼
|
|
43
|
+
GraphLoop.query()/impact() (existente, sem mudança)
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## 4. Contratos (API/CLI/Schema)
|
|
47
|
+
|
|
48
|
+
```ts
|
|
49
|
+
// packages/contracts/src/index.ts (aditivo)
|
|
50
|
+
export interface GraphNode extends AuditFields {
|
|
51
|
+
// ...campos existentes inalterados...
|
|
52
|
+
readonly documentStatus?: string; // 'accepted'|'proposed'|'superseded'|'deprecated'|'rejected' (ADR) ou 'draft'|'review'|'approved'|'implementing'|'done'|'abandoned' (SPEC) — vocabulário do documento, não confundir com KnowledgeStatus
|
|
53
|
+
}
|
|
54
|
+
export interface GraphNodeSpec {
|
|
55
|
+
// ...campos existentes inalterados...
|
|
56
|
+
readonly documentStatus?: string;
|
|
57
|
+
}
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
adr:list # lista ADRs com status
|
|
62
|
+
adr:show <id> # mostra uma ADR: status, arquivo, resumo de constraints (se houver)
|
|
63
|
+
adr:impact <id> # usa GraphLoop.impact() — nós/arestas alcançáveis
|
|
64
|
+
adr:graph # exporta subgrafo (JSON) de nós ADR/SPEC + vizinhança
|
|
65
|
+
```
|
|
66
|
+
(sem prefixo `forja`/`npm run` aqui — comandos ainda não existem; ver convenção já usada em
|
|
67
|
+
`docs/architecture/FORJA-3-ENGINEERING-INTELLIGENCE-ARCHITECTURE.md`)
|
|
68
|
+
|
|
69
|
+
## 5. Decisões e alternativas
|
|
70
|
+
|
|
71
|
+
**D1**: `documentStatus?: string` como campo novo, aditivo, em `GraphNode`/`GraphNodeSpec`.
|
|
72
|
+
Alternativa rejeitada: usar `GraphNode.status` (`KnowledgeStatus`) — explicitamente proibido pela
|
|
73
|
+
spec (AC-1), mistura o ciclo de vida do documento com a epistemologia da aresta. Alternativa
|
|
74
|
+
descartada: embutir no `label` (string) — mais frágil (parse reverso, título com separador
|
|
75
|
+
colidindo) sem nenhuma economia real, já que extensão aditiva de contrato é o padrão já em uso
|
|
76
|
+
nesta mesma janela de trabalho para casos equivalentes.
|
|
77
|
+
|
|
78
|
+
## 6. Dependências
|
|
79
|
+
|
|
80
|
+
- Nenhuma spec bloqueadora. `packages/graph`, `scripts/`, `lib/core/registry.ts` já existentes.
|
|
81
|
+
|
|
82
|
+
## 7. Rollout
|
|
83
|
+
|
|
84
|
+
- [ ] Feature flag necessária? Não — leitura pura, sem side effect em projeto consumidor.
|
|
85
|
+
- [ ] Migração de dados existentes? Não — próxima reindexação (`code:sync`/`drift:check`) já
|
|
86
|
+
popula o status ao reprocessar os documentos.
|
|
87
|
+
- [ ] Doc/persona impactada? `docs/architecture/`, README (comandos novos).
|
|
88
|
+
|
|
89
|
+
## 8. Sinais de fracasso (kill criteria)
|
|
90
|
+
|
|
91
|
+
Se o parse de `label` para extrair status de volta (D1) se mostrar frágil (ADRs com título contendo
|
|
92
|
+
" · ") isso é motivo para promover à alternativa (b) do D1 antes de expandir mais consumidores.
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
# Spec: Engineering Graph extensions (ADR/SPEC como nós de primeira classe)
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-032
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **Criado em**: 2026-09-01
|
|
7
|
+
- **Sprint alvo**: Sprint 1 (ver `../engineering-intelligence/plan.md`)
|
|
8
|
+
- **ADRs relacionadas**: ADR-0078; nenhuma ADR própria esperada — extensão aditiva de vocabulário
|
|
9
|
+
sobre `GraphNode.type`/`GraphEdge.type`, que já são `string` livre em `packages/contracts`.
|
|
10
|
+
|
|
11
|
+
## 1. Problema
|
|
12
|
+
|
|
13
|
+
`extractDeterministicRelations` já cria nós `ADR` a partir do padrão `ADR-\d{4}` encontrado em
|
|
14
|
+
texto, mas trata isso como uma referência solta (uma aresta `DERIVED_FROM` para um nó `ADR` sem
|
|
15
|
+
metadado) — não lê o `## Status` do próprio arquivo de ADR, não sabe se está `accepted`,
|
|
16
|
+
`superseded` ou `deprecated`, e não faz o mesmo para `SPEC-\d{3}`. Sem isso, perguntas como
|
|
17
|
+
"quais componentes uma ADR supersedida ainda governa" não têm resposta estruturada.
|
|
18
|
+
|
|
19
|
+
## 2. Proposta de valor
|
|
20
|
+
|
|
21
|
+
ADRs e Specs passam a ser nós completos do grafo (com status, não só uma referência textual),
|
|
22
|
+
consultáveis via `adr:impact`/`adr:graph` e usados como insumo real do Change Risk Engine
|
|
23
|
+
(SPEC-034) e do Architecture Constitution (SPEC-033).
|
|
24
|
+
|
|
25
|
+
## 3. User stories
|
|
26
|
+
|
|
27
|
+
- **Como** sdd-architect, **quero** `forja adr:impact 0027` mostrando componentes/specs/testes
|
|
28
|
+
afetados, **para que** eu saiba o raio de explosão antes de superseder uma decisão.
|
|
29
|
+
- **Como** governance, **quero** saber que uma ADR está `superseded` sem precisar abrir o arquivo,
|
|
30
|
+
**para que** `architecture:check` não valide contra uma regra morta.
|
|
31
|
+
|
|
32
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
33
|
+
|
|
34
|
+
- [x] AC-1: extensão de `extractDeterministicRelations` (ou uma função irmã dedicada, decisão de
|
|
35
|
+
implementação) lê `- **Status**: <valor>` do frontmatter de ADR (já no formato existente,
|
|
36
|
+
`memory/90-decisions/_template.md`) e do campo `Status` de spec.md (`_templates/spec.md`), e
|
|
37
|
+
grava como propriedade do nó — decisão de implementação: usar `GraphNode.status`
|
|
38
|
+
(`KnowledgeStatus`) é a tentação óbvia mas **errada** (status de ADR — accepted/proposed/
|
|
39
|
+
superseded/deprecated/rejected — é um conceito de domínio diferente de
|
|
40
|
+
verified/inferred/hypothesis/contradicted/unknown, que descreve confiança epistêmica da
|
|
41
|
+
*aresta*, não o ciclo de vida do documento); a spec desta feature deve decidir isso
|
|
42
|
+
explicitamente no `plan.md`, não misturar os dois vocabulários.
|
|
43
|
+
- [x] AC-2: `forja adr:list`/`adr:show <id>` funcionam sobre `memory/90-decisions/` real deste
|
|
44
|
+
repositório.
|
|
45
|
+
- [x] AC-3: `forja adr:impact <id>` usa `GraphLoop.impact()` (já existente, sem reimplementar BFS)
|
|
46
|
+
para listar nós/arestas alcançáveis a partir do nó ADR.
|
|
47
|
+
- [x] AC-4: `forja adr:graph` exporta um subgrafo (JSON) navegável — sem visualização nesta spec
|
|
48
|
+
(Fase posterior, dashboard é consumidor per princípio da visão original).
|
|
49
|
+
- [x] AC-5: mesmo tratamento para `SPEC-\d{3}` (nó `SPEC`, status do template já existente:
|
|
50
|
+
draft/review/approved/implementing/done/abandoned).
|
|
51
|
+
|
|
52
|
+
**Nota de implementação (achado real, fora de escopo desta spec)**: rodar `adr:list`/`show`/
|
|
53
|
+
`impact` contra o repositório real (1014 arquivos rastreados) travou por dezenas de minutos neste
|
|
54
|
+
ambiente — não é bug de lógica (uma fixture isolada com 2 documentos passa em <1s, ver
|
|
55
|
+
`test/adr-cli.test.js`) nem específico deste comando: `GitGraphDocumentSource.listDocuments()` é
|
|
56
|
+
rápido (1 subprocesso `git ls-files` + leitura síncrona de arquivo), mas
|
|
57
|
+
`SqliteGraphStore.saveNode`/`saveEdge`/`saveEvidence` (packages/adapter-sqlite) fazem um `INSERT`
|
|
58
|
+
individual por chamada, sem transação — para ~1000 documentos com múltiplas relações cada, isso é
|
|
59
|
+
plausivelmente dezenas de milhares de writes SQLite não agrupados, cada um com custo de fsync.
|
|
60
|
+
Mesmo padrão usado por `drift:check`/`graph:sync` — não é regressão desta spec, mas um achado real
|
|
61
|
+
que vale uma spec própria de performance (`GraphLoop.apply()` já processa uma `GraphMutation`
|
|
62
|
+
inteira por documento; agrupar os saves de uma mutation numa única transação SQLite é o candidato
|
|
63
|
+
óbvio, não implementado aqui por estar fora do escopo declarado em §5).
|
|
64
|
+
|
|
65
|
+
**Corrigido posteriormente**: `GraphStore` ganhou um método opcional `transaction<T>(fn: () => T):
|
|
66
|
+
T`; `GraphLoop.transaction()` delega pra ele (cai pra só `fn()` quando o store não suporta, ex.
|
|
67
|
+
`InMemoryGraphStore`); `SqliteGraphStore.transaction` implementa com `BEGIN`/`COMMIT`/`ROLLBACK`
|
|
68
|
+
reais (testado, incluindo reversão de fato em erro — `test/adapter-sqlite.test.js`).
|
|
69
|
+
`GraphIndexer.sync()` agora envolve o loop inteiro de `apply()` numa única transação. Medido contra
|
|
70
|
+
este próprio repositório (`adr:list`, mesma máquina, antes/depois via `git stash`): 7,65s → 2,75s,
|
|
71
|
+
tempo de sistema (I/O) caindo de ~3s pra ~0,08s — confirma a causa (fsync por `INSERT`), não só a
|
|
72
|
+
teoria.
|
|
73
|
+
|
|
74
|
+
## 5. Escopo
|
|
75
|
+
|
|
76
|
+
**Dentro**: extração determinística de status de ADR/SPEC; `adr:list`/`adr:show`/`adr:impact`/
|
|
77
|
+
`adr:graph`; nenhuma mudança em `KnowledgeStatus` (contrato existente intocado).
|
|
78
|
+
|
|
79
|
+
**Fora**: visualização gráfica (Fase posterior); extração de `Requirement`/`BusinessRule` como
|
|
80
|
+
nós (a visão original pede, mas este repositório-framework não tem uma fonte de requisitos de
|
|
81
|
+
produto estruturada hoje — fica para quando um projeto consumidor real tiver essa fonte,
|
|
82
|
+
provavelmente via `docs/produto/`); `PullRequest`/`Commit`/`Release` como nós (SPEC-035/Provenance,
|
|
83
|
+
fase seguinte).
|
|
84
|
+
|
|
85
|
+
## 6. NFRs / restrições
|
|
86
|
+
|
|
87
|
+
- Determinístico, sem LLM (mesmo padrão do extrator já existente).
|
|
88
|
+
- Não quebra `extractDeterministicRelations` existente — testes atuais (`test/graph.test.js`)
|
|
89
|
+
continuam passando sem alteração de comportamento para os tipos de nó já existentes.
|
|
90
|
+
|
|
91
|
+
## 7. Riscos e mitigação
|
|
92
|
+
|
|
93
|
+
| Risco | Probabilidade | Impacto | Mitigação |
|
|
94
|
+
|---|---|---|---|
|
|
95
|
+
| Confundir status de documento com `KnowledgeStatus` de epistemologia da aresta | Média (é a armadilha óbvia) | Média (contamina semântica do grafo inteiro) | AC-1 marca a decisão como obrigatória e explícita no plan.md, não implícita no código |
|
|
96
|
+
| `adr:impact` ficar lento em grafos grandes | Baixa neste repositório (~78 ADRs hoje) | Baixa | `GraphLoop.impact()` já tem parâmetro `depth`; reaproveitar, não implementar limite novo |
|
|
97
|
+
|
|
98
|
+
## 8. Métricas de sucesso
|
|
99
|
+
|
|
100
|
+
`forja adr:impact 0020` (core/registry, uma das ADRs mais referenciadas do repositório) retorna um
|
|
101
|
+
conjunto de componentes que um mantenedor confirma como correto, sem falso-negativo óbvio.
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# Tasks: Engineering Graph extensions
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Plan**: ./plan.md
|
|
5
|
+
- **Status**: approved
|
|
6
|
+
- **Criado em**: 2026-09-01
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## T1 — `documentStatus` no contrato de grafo
|
|
11
|
+
- **Owner**: worker
|
|
12
|
+
- **Estimativa**: P
|
|
13
|
+
- **Depende de**: —
|
|
14
|
+
- **Paths**: `packages/contracts/src/index.ts`
|
|
15
|
+
- **Done quando**:
|
|
16
|
+
- [ ] `GraphNode`/`GraphNodeSpec` ganham `documentStatus?: string`
|
|
17
|
+
- [ ] `npx tsc --noEmit` limpo
|
|
18
|
+
- [ ] nenhum teste existente quebra (campo opcional)
|
|
19
|
+
|
|
20
|
+
## T2 — extrator lê status de ADR e de SPEC
|
|
21
|
+
- **Owner**: worker
|
|
22
|
+
- **Estimativa**: M
|
|
23
|
+
- **Depende de**: T1
|
|
24
|
+
- **Paths**: `packages/graph/src/index.ts`
|
|
25
|
+
- **Done quando**:
|
|
26
|
+
- [ ] `extractDeterministicRelations` popula `documentStatus` do nó ADR a partir de
|
|
27
|
+
`- **Status**: <valor>` no corpo do documento (formato de `memory/90-decisions/_template.md`)
|
|
28
|
+
- [ ] mesmo tratamento para nó `SPEC` a partir do campo `Status` de `specs/_templates/spec.md`
|
|
29
|
+
- [ ] testes em `test/graph.test.js` cobrindo ADR com/sem status e SPEC com/sem status
|
|
30
|
+
- [ ] testes passando
|
|
31
|
+
|
|
32
|
+
## T3 — `scripts/adr.ts`: list/show/impact/graph
|
|
33
|
+
- **Owner**: worker
|
|
34
|
+
- **Estimativa**: M
|
|
35
|
+
- **Depende de**: T2
|
|
36
|
+
- **Paths**: `scripts/adr.ts`, `lib/core/registry.ts`
|
|
37
|
+
- **Done quando**:
|
|
38
|
+
- [ ] `adr:list` lista ADRs reais de `memory/90-decisions/` com status
|
|
39
|
+
- [ ] `adr:show <id>` mostra status, arquivo, e (se houver) o texto de `## Constraints`
|
|
40
|
+
- [ ] `adr:impact <id>` usa `GraphLoop.impact()` já existente, sem reimplementar BFS
|
|
41
|
+
- [ ] `adr:graph` exporta subgrafo JSON de nós ADR/SPEC + vizinhança direta
|
|
42
|
+
- [ ] `forja tools:doctor` (`docs-commands`/`commands-documented`) continua verde após os
|
|
43
|
+
comandos novos serem documentados no README
|
|
44
|
+
|
|
45
|
+
## T4 — testes de CLI + integração com `code:sync`
|
|
46
|
+
- **Owner**: worker
|
|
47
|
+
- **Estimativa**: P
|
|
48
|
+
- **Depende de**: T3
|
|
49
|
+
- **Paths**: `test/adr-cli.test.js` (novo)
|
|
50
|
+
- **Done quando**:
|
|
51
|
+
- [ ] `adr:impact 0020` (ADR real deste repositório) retorna componentes plausíveis
|
|
52
|
+
- [ ] `npm test` verde, `npx tsc --noEmit` limpo
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## Handoffs entre agentes
|
|
57
|
+
|
|
58
|
+
T1→T2→T3→T4 é sequencial (cada uma consome o contrato/dado da anterior); sem handoff de papel
|
|
59
|
+
(tudo cai em `worker`, sem etapa própria de product/architect — spec e plan já aprovados cobrem
|
|
60
|
+
essa decisão).
|