forjajs 1.7.3 → 2.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.
Files changed (125) hide show
  1. package/CHANGELOG.md +24 -0
  2. package/README.md +223 -217
  3. package/README.pt-BR.md +323 -0
  4. package/dist/apps/dashboard/app/api/forja/[...path]/route.d.ts +10 -0
  5. package/dist/apps/dashboard/app/api/forja/[...path]/route.js +36 -0
  6. package/dist/apps/dashboard/app/api/forja/approval.d.ts +1 -0
  7. package/dist/apps/dashboard/app/api/forja/approval.js +8 -0
  8. package/dist/apps/dashboard/app/dashboard-client.d.ts +1 -0
  9. package/dist/apps/dashboard/app/dashboard-client.jsx +62 -0
  10. package/dist/apps/dashboard/app/layout.d.ts +9 -0
  11. package/dist/apps/dashboard/app/layout.jsx +7 -0
  12. package/dist/apps/dashboard/app/page.d.ts +1 -0
  13. package/dist/apps/dashboard/app/page.jsx +5 -0
  14. package/dist/apps/dashboard/app/providers.d.ts +4 -0
  15. package/dist/apps/dashboard/app/providers.jsx +7 -0
  16. package/dist/apps/dashboard/next.config.d.mts +6 -0
  17. package/dist/apps/dashboard/next.config.mjs +8 -0
  18. package/dist/apps/dashboard/src/index.d.ts +14 -0
  19. package/dist/apps/dashboard/src/index.js +16 -0
  20. package/dist/apps/server/src/app.module.d.ts +5 -0
  21. package/dist/apps/server/src/app.module.js +16 -0
  22. package/dist/apps/server/src/forja-nest.module.d.ts +59 -0
  23. package/dist/apps/server/src/forja-nest.module.js +316 -0
  24. package/dist/apps/server/src/index.d.ts +15 -0
  25. package/dist/apps/server/src/index.js +7 -0
  26. package/dist/apps/server/src/main.d.ts +12 -0
  27. package/dist/apps/server/src/main.js +105 -0
  28. package/dist/apps/worker/src/main.d.ts +12 -0
  29. package/dist/apps/worker/src/main.js +18 -0
  30. package/dist/lib/core/health.js +1 -1
  31. package/dist/packages/adapter-git/src/index.d.ts +27 -0
  32. package/dist/packages/adapter-git/src/index.js +53 -0
  33. package/dist/packages/adapter-nest/src/index.d.ts +71 -0
  34. package/dist/packages/adapter-nest/src/index.js +142 -0
  35. package/dist/packages/adapter-sqlite/src/index.d.ts +99 -0
  36. package/dist/packages/adapter-sqlite/src/index.js +108 -0
  37. package/dist/packages/context/src/index.d.ts +52 -0
  38. package/dist/packages/context/src/index.js +108 -0
  39. package/dist/packages/contracts/src/index.d.ts +368 -0
  40. package/dist/packages/contracts/src/index.js +27 -0
  41. package/dist/packages/core/src/index.d.ts +68 -0
  42. package/dist/packages/core/src/index.js +141 -0
  43. package/dist/packages/evals/src/index.d.ts +22 -0
  44. package/dist/packages/evals/src/index.js +65 -0
  45. package/dist/packages/events/src/index.d.ts +47 -0
  46. package/dist/packages/events/src/index.js +96 -0
  47. package/dist/packages/graph/src/index.d.ts +80 -0
  48. package/dist/packages/graph/src/index.js +163 -0
  49. package/dist/packages/mcp/src/index.d.ts +119 -0
  50. package/dist/packages/mcp/src/index.js +153 -0
  51. package/dist/packages/observability/src/index.d.ts +132 -0
  52. package/dist/packages/observability/src/index.js +86 -0
  53. package/dist/packages/orchestration/src/index.d.ts +122 -0
  54. package/dist/packages/orchestration/src/index.js +178 -0
  55. package/dist/packages/planner/src/index.d.ts +22 -0
  56. package/dist/packages/planner/src/index.js +70 -0
  57. package/dist/packages/plugin-sdk/src/index.d.ts +56 -0
  58. package/dist/packages/plugin-sdk/src/index.js +55 -0
  59. package/dist/packages/policy/src/index.d.ts +80 -0
  60. package/dist/packages/policy/src/index.js +136 -0
  61. package/dist/packages/runtime/src/index.d.ts +91 -0
  62. package/dist/packages/runtime/src/index.js +217 -0
  63. package/dist/packages/sandbox/src/index.d.ts +64 -0
  64. package/dist/packages/sandbox/src/index.js +108 -0
  65. package/dist/packages/scheduler/src/index.d.ts +56 -0
  66. package/dist/packages/scheduler/src/index.js +123 -0
  67. package/dist/packages/sdk/src/index.d.ts +122 -0
  68. package/dist/packages/sdk/src/index.js +40 -0
  69. package/dist/packages/validator/src/index.d.ts +36 -0
  70. package/dist/packages/validator/src/index.js +60 -0
  71. package/docs/architecture/FORJA-2.0-ARCHITECTURE.md +109 -0
  72. package/docs/architecture/FORJA-2.0-IMPACT-FOUNDATION.md +273 -0
  73. package/docs/security/FORJA-2.0-RELEASE-AUDIT-2026-08-01.md +95 -0
  74. package/docs/vision/FORJA-2.0-VISION.md +72 -0
  75. package/memory/50-orchestration/handoffs/2026-07-31_architect_foundation-contracts.md +15 -0
  76. package/memory/50-orchestration/handoffs/2026-07-31_backend-nest.md +22 -0
  77. package/memory/50-orchestration/handoffs/2026-07-31_context-engine.md +16 -0
  78. package/memory/50-orchestration/handoffs/2026-07-31_control-plane.md +28 -0
  79. package/memory/50-orchestration/handoffs/2026-07-31_core-capability-registry.md +15 -0
  80. package/memory/50-orchestration/handoffs/2026-07-31_evals-plugin-sdk.md +22 -0
  81. package/memory/50-orchestration/handoffs/2026-07-31_events-scheduler.md +16 -0
  82. package/memory/50-orchestration/handoffs/2026-07-31_graphloop.md +16 -0
  83. package/memory/50-orchestration/handoffs/2026-07-31_mcp.md +21 -0
  84. package/memory/50-orchestration/handoffs/2026-07-31_nest-bootstrap.md +28 -0
  85. package/memory/50-orchestration/handoffs/2026-07-31_next-dashboard.md +22 -0
  86. package/memory/50-orchestration/handoffs/2026-07-31_observability.md +27 -0
  87. package/memory/50-orchestration/handoffs/2026-07-31_orchestration.md +21 -0
  88. package/memory/50-orchestration/handoffs/2026-07-31_planner-validator.md +16 -0
  89. package/memory/50-orchestration/handoffs/2026-07-31_policy-engine.md +14 -0
  90. package/memory/50-orchestration/handoffs/2026-07-31_runtime-control-plane.md +23 -0
  91. package/memory/50-orchestration/handoffs/2026-07-31_runtime-controlado.md +15 -0
  92. package/memory/50-orchestration/handoffs/2026-07-31_sandbox.md +21 -0
  93. package/memory/50-orchestration/handoffs/2026-07-31_sdk.md +27 -0
  94. package/memory/50-orchestration/handoffs/2026-07-31_sqlite-adapter.md +21 -0
  95. package/memory/50-orchestration/handoffs/2026-07-31_worker-dashboard-boundary.md +23 -0
  96. package/memory/50-orchestration/handoffs/2026-08-01_approval-server-identity.md +23 -0
  97. package/memory/50-orchestration/handoffs/2026-08-01_dashboard-auth-query.md +24 -0
  98. package/memory/50-orchestration/handoffs/2026-08-01_graphloop-approvals.md +23 -0
  99. package/memory/90-decisions/0034-forja-2-core-e-contratos.md +29 -0
  100. package/memory/90-decisions/0035-forja-2-local-first-e-autonomia.md +23 -0
  101. package/memory/90-decisions/0036-forja-2-capability-registry.md +30 -0
  102. package/memory/90-decisions/0037-forja-2-policy-engine-obrigatorio.md +28 -0
  103. package/memory/90-decisions/0038-forja-2-runtime-controlado.md +28 -0
  104. package/memory/90-decisions/0039-forja-2-event-bus-scheduler-local-first.md +31 -0
  105. package/memory/90-decisions/0040-forja-2-context-engine-budget-cache.md +32 -0
  106. package/memory/90-decisions/0041-forja-2-graphloop-separado-codegraph.md +32 -0
  107. package/memory/90-decisions/0042-forja-2-planner-validator-independentes.md +29 -0
  108. package/memory/90-decisions/0043-forja-2-orchestration-entities.md +16 -0
  109. package/memory/90-decisions/0044-forja-2-sandbox-worktree.md +19 -0
  110. package/memory/90-decisions/0045-forja-2-sqlite-adapter.md +19 -0
  111. package/memory/90-decisions/0046-forja-2-mcp-adapter.md +18 -0
  112. package/memory/90-decisions/0047-forja-2-backend-nest-adapter.md +19 -0
  113. package/memory/90-decisions/0048-forja-2-sdk-transport.md +18 -0
  114. package/memory/90-decisions/0049-forja-2-observability-control-plane.md +18 -0
  115. package/memory/90-decisions/0050-forja-2-control-plane-application-ports.md +18 -0
  116. package/memory/90-decisions/0051-forja-2-runtime-control-plane-composition.md +18 -0
  117. package/memory/90-decisions/0052-forja-2-deterministic-evaluation.md +15 -0
  118. package/memory/90-decisions/0053-forja-2-plugin-sdk-permissionado.md +16 -0
  119. package/memory/90-decisions/0054-forja-2-worker-dashboard-boundary.md +15 -0
  120. package/memory/90-decisions/0055-forja-2-next-dashboard-distribution.md +16 -0
  121. package/memory/90-decisions/0056-forja-2-dashboard-proxy-auth-query.md +16 -0
  122. package/memory/90-decisions/0057-forja-2-graphloop-approvals-dashboard.md +15 -0
  123. package/memory/90-decisions/0058-forja-2-approval-server-identity.md +15 -0
  124. package/package.json +28 -3
  125. package/README.en.md +0 -329
package/CHANGELOG.md CHANGED
@@ -4,6 +4,30 @@ Histórico consolidado das mudanças estruturais do framework. Para decisões ar
4
4
 
5
5
  ---
6
6
 
7
+ ## [2.0.0] — 2026-08-01 — Fundação programável local-first
8
+
9
+ Primeira release da plataforma ForjaJS 2.0. A versão mantém a
10
+ CLI-first e adiciona um núcleo programável por agentes, com contratos
11
+ versionados, capabilities, runtime controlado, políticas, memória, GraphLoop,
12
+ contexto orçamentado, MCP, SDK, adapters oficiais, observabilidade e dashboard.
13
+
14
+ ### Adicionado
15
+ - Monorepo modular com `apps/server`, `apps/dashboard`, `apps/worker` e pacotes
16
+ de domínio/adaptação independentes de framework.
17
+ - Contracts, Capability Registry, Policy Engine, Runtime, Sprint/Task/Handoff,
18
+ Event Bus, Scheduler, Sandbox, Planner, Validator, GraphLoop e Context Engine.
19
+ - MCP, SDK, Plugin SDK, adapters SQLite/Git/NestJS, Control Plane e Evaluation
20
+ Engine.
21
+ - Dashboard Next.js com consultas, GraphLoop, aprovações e ações supervisionadas.
22
+ - Auditoria de segurança, release e migração documentada.
23
+
24
+ ### Validação do candidato
25
+ - TypeScript, builds e 267 testes determinísticos aprovados.
26
+ - `npm audit --offline --omit=dev --audit-level=high`: zero vulnerabilidades.
27
+ - Gitleaks: zero achados após limpeza dos artefatos de build.
28
+ - Release validada após merge da PR #40 e execução do gate de publicação sobre
29
+ o commit/tag limpos.
30
+
7
31
  ## [1.7.3] — 2026-07-23 — Doctor: permissão/lock não é corrupção
8
32
 
9
33
  O check `memory-db` (consumido por `tools:doctor` e pelo `SessionStart`) tratava **qualquer** falha
package/README.md CHANGED
@@ -1,323 +1,329 @@
1
1
  <h1 align="center">🔨 Forja</h1>
2
2
 
3
3
  <p align="center">
4
- <strong>Transforme IA de codificação em uma equipe de engenharia com processo e memória:<br>todo projeto nasce com spec, toda decisão vira ADR, e nada se perde entre sessões.</strong>
4
+ <strong>Turn coding AI into an engineering team with process and memory:<br>every project starts from a spec, every decision becomes an ADR, and nothing is lost between sessions.</strong>
5
5
  </p>
6
6
 
7
7
  <p align="center">
8
8
  <a href="https://www.npmjs.com/package/forjajs"><img src="https://img.shields.io/npm/v/forjajs?style=flat-square&color=cb3837&logo=npm" alt="npm"></a>
9
9
  <img src="https://github.com/allanpablo/forja/actions/workflows/ci.yml/badge.svg" alt="CI">
10
- <img src="https://img.shields.io/badge/operação-CLI--first-3553ff?style=flat-square" alt="CLI-first">
11
- <img src="https://img.shields.io/badge/agentes-6_papéis-orange?style=flat-square" alt="6 agentes">
10
+ <img src="https://img.shields.io/badge/operation-CLI--first-3553ff?style=flat-square" alt="CLI-first">
11
+ <img src="https://img.shields.io/badge/agents-6_roles-orange?style=flat-square" alt="6 agents">
12
12
  <img src="https://img.shields.io/badge/pipeline-SDD_+_GSD-teal?style=flat-square" alt="SDD+GSD">
13
- <img src="https://img.shields.io/badge/memória-SQLite_FTS5-green?style=flat-square" alt="Memória">
13
+ <img src="https://img.shields.io/badge/memory-SQLite_FTS5-green?style=flat-square" alt="Memory">
14
14
  <img src="https://img.shields.io/badge/node-%E2%89%A520-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node >= 20">
15
15
  <img src="https://img.shields.io/badge/license-MIT-1a1a1a?style=flat-square" alt="MIT">
16
16
  <img src="https://img.shields.io/badge/PRs-welcome-8957e5?style=flat-square" alt="PRs welcome">
17
17
  </p>
18
18
 
19
- <p align="center"><sub>🌐 <a href="README.en.md">English</a> · <strong>Português</strong></sub></p>
19
+ <p align="center"><sub>🌐 <strong>English</strong> · <a href="README.pt-BR.md">Português</a></sub></p>
20
20
 
21
21
  ---
22
22
 
23
- ## Por que a Forja existe
23
+ ## Why Forja exists
24
24
 
25
- Agentes de IA são **amnésicos e indisciplinados**: cada sessão recomeça do zero, decisões
26
- de arquitetura evaporam, o código diverge da intenção — e quem opera vários produtos ao
27
- mesmo tempo paga esse imposto multiplicado por N.
25
+ Coding agents are **amnesiac and undisciplined**: every session starts from zero, architecture
26
+ decisions evaporate, code drifts from intent — and if you run several products at once, you pay
27
+ that tax multiplied by N.
28
28
 
29
- A **Forja** é o estúdio em volta da IA. Ela coordena **6 papéis de agentes** num pipeline
30
- **Spec-Driven (SDD)** + **Get-Stuff-Done (GSD)**, mantém uma **memória hierárquica**
31
- indexada em SQLite que sobrevive entre sessões, e amarra tudo num **core CLI único com
32
- gates e trilha de auditoria** (`forja`, ADR-0020). Multi-IA por design (Claude, Copilot,
33
- Gemini, Codex). A operação é inteiramente via CLI.
29
+ **Forja** is the studio around the AI. It coordinates **6 agent roles** through a
30
+ **Spec-Driven (SDD)** + **Get-Stuff-Done (GSD)** pipeline, keeps a **hierarchical memory** indexed
31
+ in SQLite that survives across sessions, and ties it all together behind **a single core CLI with
32
+ gates and an audit trail** (`forja`, ADR-0020). Multi-AI by design (Claude, Copilot, Gemini,
33
+ Codex). Everything is driven from the CLI.
34
34
 
35
- **Para quem**: o dev solo ou time pequeno que opera múltiplos produtos com IA como
36
- principal força de trabalho — e precisa da disciplina de um time grande sem ter esse time.
35
+ **Who it's for**: the solo dev or small team running multiple products with AI as the main
36
+ workforce — and needing the discipline of a big team without having one.
37
37
 
38
- ## Os 3 pilares
38
+ ## The 3 pillars
39
39
 
40
- | Pilar | O que entrega | Prova |
40
+ | Pillar | What it delivers | Proof |
41
41
  |---|---|---|
42
- | **Memória que sobrevive** | contexto hierárquico, buscável, compartilhado entre sessões e IAs | SQLite FTS5, smart-context (ADR-0003) |
43
- | **Processo que governa** | nada vira código sem spec; nada estrutural sem ADR; comandos auditados | SDD+GSD, handoffs 7 campos (ADR-0005), core `forja` (ADR-0020) |
44
- | **Fábrica, não projeto único** | workspace multi-produto, times de agentes por projeto | ADR-0019, harness, codegraph (ADR-0017) |
42
+ | **Memory that survives** | hierarchical, searchable context, shared across sessions and AIs | SQLite FTS5, smart-context (ADR-0003) |
43
+ | **Process that governs** | nothing becomes code without a spec; nothing structural without an ADR; every command audited | SDD+GSD, 7-field handoffs (ADR-0005), `forja` core (ADR-0020) |
44
+ | **A factory, not a single project** | multi-product workspace, per-project agent teams | ADR-0019, harness, codegraph (ADR-0017) |
45
45
 
46
- > Este repositório é o **motor (framework)** — não hospeda aplicações em produção.
47
- > Os produtos do usuário vivem no **workspace Forja** (`~/forja-workspace` por padrão), fora deste repo.
48
- > Veja ADR-0019 para a rationale.
46
+ > This repository is the **engine (framework)** — it does not host production apps.
47
+ > Your products live in the **Forja workspace** (`~/forja-workspace` by default), outside this repo.
48
+ > See ADR-0019 for the rationale.
49
49
 
50
- ## 60 segundos de Forja
50
+ ## Forja in 60 seconds
51
51
 
52
52
  ```console
53
- $ forja spec:new pagamentos-pix
54
- ✓ Spec criada: specs/pagamentos-pix/spec.md # nada vira código sem isso
53
+ $ forja spec:new pix-payments
54
+ ✓ Spec created: specs/pix-payments/spec.md # nothing becomes code without this
55
55
 
56
- $ forja gsd:handoff plan pagamentos-pix
57
- Handoff registrado: product → sdd-architect # 7 campos, auditável (ADR-0005)
56
+ $ forja gsd:handoff plan pix-payments
57
+ Handoff recorded: product → sdd-architect # 7 fields, auditable (ADR-0005)
58
58
 
59
59
  $ forja code:impact processPayment
60
- Mapa de impacto: processPayment (profundidade 2) # blast radius ANTES de editar
61
- --- Chamadores diretos ---
60
+ Impact map: processPayment (depth 2) # blast radius BEFORE you edit
61
+ --- Direct callers ---
62
62
  BillingController.charge · RetryWorker.run
63
63
 
64
- $ forja gsd:check pagamentos-pix
64
+ $ forja gsd:check pix-payments
65
65
  OK GSD runbook OK Spec directory
66
66
  OK SDD spec check OK Codegraph
67
- Resultado: gates básicos prontos. # governança executável, não checklist
67
+ Result: baseline gates ready. # executable governance, not a checklist
68
68
  ```
69
69
 
70
- E cada comando acima ficou gravado em `.context/forja-runs.jsonl` — quando a governança pergunta "o processo foi seguido?", a resposta é um arquivo, não uma promessa.
70
+ And each command above was recorded in `.context/forja-runs.jsonl` — when governance asks "was the
71
+ process followed?", the answer is a file, not a promise.
71
72
 
72
- ## Por que não só…?
73
+ ## Why not just…?
73
74
 
74
- | Alternativa | Onde ela para | O que a Forja acrescenta |
75
+ | Alternative | Where it stops | What Forja adds |
75
76
  |---|---|---|
76
- | **Claude Code / Copilot puros** | brilhantes na sessão, amnésicos entre sessões | memória FTS5 + processo + auditoria em volta da IA |
77
- | **LangGraph / CrewAI** | infraestrutura para *construir* agentes | a camada de cima: opera o time de agentes no dia a dia |
78
- | **Templates & spec kits** | param quando a spec está escrita | pipeline completo até a governança, com gates que executam |
79
-
80
- ## Capacidades-chave
81
-
82
- - **Core CLI único** — todo comando de processo passa por `forja <comando>`: registry declarativo, gates transversais (workspace) e auditoria append-only em `.context/forja-runs.jsonl` (ADR-0020).
83
- - **Orquestração multiagente** — 6 papéis (orchestrator, context-engineer, sdd-architect, product, marketing, governance) com handoffs rastreados (7 campos, ADR-0005).
84
- - **Memória hierárquica** — global → domínio → tarefa → resumo, com busca FTS5 e *smart-context* em 3 modos (ADR-0003).
85
- - **Pipeline SDD + GSD** — `spec → plan → tasks → check`, decisões registradas como ADRs.
86
- - **Auto-verificação (invariantes que rodam)** — o framework prova a si mesmo: uma família de gates guarda cada fronteira (núcleo, tarball, coerência de doc, topologia de agentes, projeto gerado), e `check:all` roda a bateria inteira num veredito só. A governança deixa de depender de disciplina — vira harness.
87
- - **Economia de token medida, não afirmada** — a memória (`context.md` como mapa) economiza ~60% vs explorar no frio, e `token:economy` **prova** isso nos seus domínios. `code:context` entrega o mapa pronto; `memory:audit` garante que ele não mente sobre o código.
88
- - **Geração de projetos** — `project:new` cria scaffold completo no workspace (memória, agentes, instruções multi-IA, backend NestJS como boilerplate padrão) e registra a ficha; `project:upgrade` traz peças novas para projetos já gerados sem tocar no código do usuário.
89
- - **3 capacidades integradas** (ADR-0016): **codegraph** (análise de código via MCP), **harness** (desenho de times de agentes), **ai-engineering** (base de conhecimento).
77
+ | **Plain Claude Code / Copilot** | brilliant in-session, amnesiac between sessions | FTS5 memory + process + audit around the AI |
78
+ | **LangGraph / CrewAI** | infrastructure to *build* agents | the layer above: it *operates* the agent team day to day |
79
+ | **Templates & spec kits** | stop once the spec is written | the full pipeline through governance, with gates that execute |
80
+
81
+ ## Key capabilities
82
+
83
+ - **Single core CLI** — every process command goes through `forja <command>`: a declarative
84
+ registry, cross-cutting gates (workspace), and append-only audit in
85
+ `.context/forja-runs.jsonl` (ADR-0020).
86
+ - **Multi-agent orchestration** — 6 roles (orchestrator, context-engineer, sdd-architect, product,
87
+ marketing, governance) with tracked handoffs (7 fields, ADR-0005).
88
+ - **Hierarchical memory** — global → domain → task → summary, with FTS5 search and *smart-context*
89
+ in 3 modes (ADR-0003).
90
+ - **SDD + GSD pipeline** — `spec → plan → tasks → check`, decisions recorded as ADRs.
91
+ - **Self-verification (invariants that run)** — the framework proves itself: a family of gates guards
92
+ each frontier (core, tarball, doc coherence, agent topology, generated project), and `check:all`
93
+ runs the whole battery into a single verdict. Governance stops depending on discipline — it becomes
94
+ harness.
95
+ - **Token economy measured, not asserted** — memory (the `context.md` as a map) saves ~60% vs
96
+ exploring cold, and `token:economy` **proves** it across your domains. `code:context` delivers the
97
+ map ready to paste; `memory:audit` guarantees it doesn't lie about the code.
98
+ - **Project generation** — `project:new` scaffolds a full project (memory, agents, multi-AI
99
+ instructions, a NestJS backend as the default boilerplate) and registers the record; `project:upgrade`
100
+ brings new scaffold pieces to already-generated projects without touching the user's code.
101
+ - **3 integrated capabilities** (ADR-0016): **codegraph** (code analysis via MCP), **harness**
102
+ (agent-team design), **ai-engineering** (knowledge base).
90
103
 
91
104
  ## ⚡ Quick start
92
105
 
93
106
  ```bash
94
- # Instalar (o pacote é forjajs; o comando é forja)
107
+ # Install (the package is forjajs; the command is forja)
95
108
  npm install -g forjajs
96
- forja # help agrupado por domínio
109
+ forja # help grouped by domain
97
110
 
98
- # Preparar o workspace de produção (canto fixo dos projetos)
111
+ # Prepare the production workspace (the fixed home for your projects)
99
112
  forja workspace:init
100
113
 
101
- # Criar um projeto novo (gera em ~/forja-workspace/projects/<nome>)
102
- forja project:new meu-projeto --ai claude,copilot
114
+ # Create a new project (generated in ~/forja-workspace/projects/<name>)
115
+ forja project:new my-project --ai claude,copilot
103
116
 
104
- # Entrar no ciclo SDD/GSD da primeira feature
105
- forja spec:new minha-feature
106
- forja spec:plan minha-feature
107
- forja spec:tasks minha-feature
108
- forja spec:check minha-feature
117
+ # Enter the SDD/GSD cycle for the first feature
118
+ forja spec:new my-feature
119
+ forja spec:plan my-feature
120
+ forja spec:tasks my-feature
121
+ forja spec:check my-feature
109
122
  ```
110
123
 
111
- > Clonou o repo em vez de instalar? Os mesmos comandos rodam como
112
- > `node bin/forja.ts <comando>` — os scripts npm são apenas aliases finos do core.
113
- > A fonte é TypeScript e roda nativa: **dev exige Node ≥ 22.6** (strip-types). O pacote *publicado*
114
- > embarca `dist/*.js` e roda em **Node ≥ 20** — o `release-gate` prova isso a cada release (SPEC-012).
124
+ > Cloned the repo instead of installing? The same commands run as
125
+ > `node bin/forja.ts <command>` — the npm scripts are just thin aliases of the core.
126
+ > The source is TypeScript and runs natively: **dev needs Node ≥ 22.6** (type stripping). The
127
+ > *published* package ships `dist/*.js` and runs on **Node ≥ 20** — the `release-gate` proves it
128
+ > every release (SPEC-012).
115
129
 
116
- Passo a passo de **criar vs atualizar** projeto: [`docs/processo-projeto.md`](docs/processo-projeto.md).
130
+ Step by step on **create vs update** a project: [`docs/processo-projeto.md`](docs/processo-projeto.md).
117
131
 
118
- ## Como funciona — o processo
132
+ ## How it works — the process
119
133
 
120
134
  ```
121
- 💡 Demanda
122
- ├─ projeto NÃO existe ─► project:new + boilerplate + harness (desenha o time)
123
- └─ projeto JÁ existe ──► overlay --only-memory + codegraph init (entende o código)
135
+ 💡 Demand
136
+ ├─ project does NOT exist ─► project:new + boilerplate + harness (designs the team)
137
+ └─ project DOES exist ─────► overlay --only-memory + codegraph init (understands the code)
124
138
  │
125
139
  ▼
126
- CICLO CLI-first (docs/fluxo.md):
127
- 1·Entender → 2·Especificar → 3·Arquitetar → 4·Decompor → 5·Implementar → 6·Governar → ✅
140
+ CLI-first CYCLE (docs/fluxo.md):
141
+ 1·Understand → 2·Specify → 3·Architect → 4·Decompose → 5·Implement → 6·Govern → ✅
128
142
  ```
129
143
 
130
- | Etapa | Papel | Capacidade |
131
- |-------|-------|------------|
132
- | 1 Entender | context-engineer | codegraph · ai-engineering |
133
- | 2 Especificar | product | — |
134
- | 3 Arquitetar | sdd-architect | harness · ADR |
135
- | 4 Decompor | sdd-architect | — |
136
- | 5 Implementar | orchestrator + worker | codegraph (MCP) |
137
- | 6 Governar | governance | codegraph (`affected`) |
144
+ | Step | Role | Capability |
145
+ |------|------|------------|
146
+ | 1 Understand | context-engineer | codegraph · ai-engineering |
147
+ | 2 Specify | product | — |
148
+ | 3 Architect | sdd-architect | harness · ADR |
149
+ | 4 Decompose | sdd-architect | — |
150
+ | 5 Implement | orchestrator + worker | codegraph (MCP) |
151
+ | 6 Govern | governance | codegraph (`affected`) |
138
152
 
139
- Mapa completo do ciclo: [`docs/fluxo.md`](docs/fluxo.md).
153
+ Full cycle map: [`docs/fluxo.md`](docs/fluxo.md).
140
154
 
141
- ## As 3 capacidades integradas
155
+ ## The 3 integrated capabilities
142
156
 
143
- | Capacidade | Papel | Como usar |
157
+ | Capability | Role | How to use |
144
158
  |---|---|---|
145
- | **codegraph** | análise de código (MCP local) | `forja code:index` · `codegraph explore "<área>"` · ferramentas MCP `codegraph_explore`/`codegraph_node` |
146
- | **harness** | desenho de times de agentes (plugin) | na sessão Claude Code: _"build a harness for this project"_ → gera `.claude/agents` + `.claude/skills` |
147
- | **ai-engineering** | base de conhecimento (referência) | ver [`docs/capacidades-externas.md`](docs/capacidades-externas.md) |
159
+ | **codegraph** | code analysis (local MCP) | `forja code:index` · `codegraph explore "<area>"` · MCP tools `codegraph_explore`/`codegraph_node` |
160
+ | **harness** | agent-team design (plugin) | in a Claude Code session: _"build a harness for this project"_ → generates `.claude/agents` + `.claude/skills` |
161
+ | **ai-engineering** | knowledge base (reference) | see [`docs/capacidades-externas.md`](docs/capacidades-externas.md) |
148
162
 
149
- Detalhes e reinstalação: [`docs/capacidades-externas.md`](docs/capacidades-externas.md) · [ADR-0016](memory/90-decisions/0016-integracao-capacidades-externas.md).
163
+ Details and reinstall: [`docs/capacidades-externas.md`](docs/capacidades-externas.md) · [ADR-0016](memory/90-decisions/0016-integracao-capacidades-externas.md).
150
164
 
151
- ## O core `forja`
165
+ ## The `forja` core
152
166
 
153
- Todos os comandos de processo passam por um único ponto de entrada (ADR-0020):
167
+ Every process command goes through a single entry point (ADR-0020):
154
168
 
155
169
  ```bash
156
- forja # help agrupado por domínio
157
- forja <comando> [args] # no repo clonado: node bin/forja.ts <comando>
170
+ forja # help grouped by domain
171
+ forja <command> [args] # in a cloned repo: node bin/forja.ts <command>
158
172
  ```
159
173
 
160
- O core aplica **gates** antes de executar (ex.: comandos de produto falham cedo sem
161
- workspace) e grava **auditoria** de cada execução (comando, args, exit code, duração)
162
- em `<workspace>/.context/forja-runs.jsonl` — a trilha que a governança usa no review.
163
- Os scripts npm do repo são aliases finos que roteiam pelo core.
174
+ The core applies **gates** before running (e.g. product commands fail fast without a workspace) and
175
+ records an **audit** of each run (command, args, exit code, duration) in
176
+ `<workspace>/.context/forja-runs.jsonl` — the trail governance uses at review. The repo's npm
177
+ scripts are thin aliases that route through the core.
164
178
 
165
- ## Comandos essenciais
179
+ ## Essential commands
166
180
 
167
181
  ```bash
168
- # Workspace & projetos
169
- forja workspace:init # cria ~/forja-workspace
170
- forja project:new <nome> --ai claude,copilot # cria projeto no workspace
171
- forja project:list # lista projetos do workspace
172
- forja project:upgrade # traz peças novas de scaffold p/ um projeto (aditivo; --apply)
173
- forja workspace:project:check <nome> # valida padrões num projeto do workspace
182
+ # Workspace & projects
183
+ forja workspace:init # create ~/forja-workspace
184
+ forja project:new <name> --ai claude,copilot # create a project in the workspace
185
+ forja project:list # list workspace projects
186
+ forja workspace:project:check <name> # validate standards in a workspace project
174
187
 
175
- # Pipeline SDD
176
- forja spec:new <slug> # também: spec:plan · spec:tasks · spec:check
188
+ # SDD pipeline
189
+ forja spec:new <slug> # also: spec:plan · spec:tasks · spec:check
177
190
 
178
191
  # Sprint & handoffs (GSD)
179
- forja sprint:start # também: sprint:status · sprint:complete
180
- forja gsd:plan <slug> # runbook GSD em .context/
181
- forja gsd:handoff <intent> <slug> # handoff entre papéis (ADR-0005)
182
- forja gsd:check <slug> # gates básicos do runbook
183
- forja orchestrate "<objetivo>" --slug <s> # abre a corrida: a cadeia SDD/GSD como máquina de estados (SPEC-021)
184
- forja orchestrate:status <slug> # o estado da máquina: etapas, gates, vereditos
185
- forja orchestrate:advance <slug> # roda o gate da etapa; verde → próxima; vermelho → trava
186
-
187
- # Análise de código (codegraph)
188
- forja code:check # índice confiável (worktree + freshness)
189
- forja code:impact <símbolo> # chamadores + blast radius antes de editar
190
- forja code:context <domínio> # pacote de contexto mínimo (o mapa; --code p/ o código)
191
- forja code:query "<termo>" # também: code:index · code:sync · code:status
192
-
193
- # Memória & contexto (workspace)
194
- forja sync:universal # reindexa SQLite FTS5 do workspace
195
- forja query:universal "<query>" # busca FTS5
196
- forja context:smart # smart-context (3 modos, ADR-0003)
197
- forja token:economy [--project <path>] # economia de token; --project mede seus domínios reais (ADR-0009)
198
- forja memory:compress # arquiva runs antigos + VACUUM
199
- forja memory:extract # extrai conhecimento global da memória
200
- forja memory:audit # coerência mapa↔código: mapa não mente + módulo sem mapa (SPEC-017)
201
-
202
- # Qualidade & release
203
- forja project:check # standards do framework (pre-commit)
204
- forja tools:doctor # raio-x do núcleo; separa permissão/lock de corrupção; exit 1 se quebrou
205
- forja release:check --publish # gate do tarball antes de publicar
206
- forja project:smoke # gate do projeto gerado; --full instala e builda o backend
207
- forja check:all # a bateria inteira de gates, um veredito; --full inclui os caros (SPEC-020)
208
- forja project:dashboard # relatório estático de status
209
-
210
- # Governança & auditoria
211
- forja audit:sync # projeta a trilha de auditoria numa tabela consultável
212
- forja audit:query --failed # consulta: --failed, --cmd <x>, --since 7d
213
- forja governance:dashboard # painel HTML estático (gates, SDD, auditoria) — sem servidor
192
+ forja sprint:start # also: sprint:status · sprint:complete
193
+ forja gsd:plan <slug> # GSD runbook in .context/
194
+ forja gsd:handoff <intent> <slug> # role-to-role handoff (ADR-0005)
195
+ forja gsd:check <slug> # baseline runbook gates
196
+ forja orchestrate "<goal>" --slug <s> # open a run: the SDD/GSD chain as a gated state machine (SPEC-021)
197
+ forja orchestrate:status <slug> # the machine state: stages, gates, verdicts
198
+ forja orchestrate:advance <slug> # run the stage gate; green → next; red → blocked
199
+
200
+ # Code analysis (codegraph)
201
+ forja code:check # trustworthy index (worktree + freshness)
202
+ forja code:impact <symbol> # callers + blast radius before you edit
203
+ forja code:query "<term>" # also: code:index · code:sync · code:status
204
+
205
+ # Memory & context (workspace)
206
+ forja sync:universal # reindex the workspace SQLite FTS5
207
+ forja query:universal "<query>" # FTS5 search
208
+ forja context:smart # smart-context (3 modes, ADR-0003)
209
+ forja memory:compress # archive old runs + VACUUM
210
+ forja memory:extract # extract global knowledge from memory
211
+
212
+ # Quality & release
213
+ forja project:check # framework standards (pre-commit)
214
+ forja tools:doctor # core X-ray; tells permission/lock from corruption; exit 1 if broken
215
+ forja release:check --publish # tarball gate before publishing
216
+ forja project:smoke # generated-project gate; --full installs and builds the backend
217
+ forja project:dashboard # static status report
218
+
219
+ # Governance & audit
220
+ forja audit:sync # project the audit trail into a queryable table
221
+ forja audit:query --failed # query: --failed, --cmd <x>, --since 7d
222
+ forja governance:dashboard # static HTML panel (gates, SDD, audit) — no server
214
223
  ```
215
224
 
216
- ## Separação framework × workspace
225
+ ## Framework vs workspace separation
217
226
 
218
- O Forja é dividido em duas partes:
227
+ Forja is split in two:
219
228
 
220
- 1. **Framework** (este repositório): motor, convenções, scripts e memória do próprio framework.
221
- 2. **Workspace** (`~/forja-workspace` por padrão): "canto fixo" onde vivem os projetos de produto, a memória universal deles e as specs de produto.
229
+ 1. **Framework** (this repository): the engine, conventions, scripts, and the framework's own memory.
230
+ 2. **Workspace** (`~/forja-workspace` by default): the "fixed home" where product projects, their
231
+ universal memory, and product specs live.
222
232
 
223
- O caminho do workspace é resolvido por prioridade:
233
+ The workspace path is resolved by priority:
224
234
 
225
- 1. Variável de ambiente `FORJA_WORKSPACE`
226
- 2. Campo `workspaceRoot` em `~/.forjarc.json`
227
- 3. Padrão: `~/forja-workspace`
235
+ 1. `FORJA_WORKSPACE` environment variable
236
+ 2. `workspaceRoot` field in `~/.forjarc.json`
237
+ 3. Default: `~/forja-workspace`
228
238
 
229
- Veja ADR-0019 para a decisão arquitetural.
239
+ See ADR-0019 for the architectural decision.
230
240
 
231
- ## Estrutura do repositório (framework)
241
+ ## Repository structure (framework)
232
242
 
233
243
  ```
234
- bin/ CLIs (forja — o core; init-project, create-memory-nest-kit)
235
- lib/ Módulos reutilizáveis; lib/core/ é o motor de invariantes (registry, checks, health, release, doc-graph, gates)
236
- scripts/ Automação (sprint-manager, agent-router, sync-universal-memory, …)
237
- specs/ Pipeline SDD do próprio framework (spec → plan → tasks)
238
- boilerplates/ Templates de stack (api-rest, saas, ecommerce, microservices, monorepo)
239
- memory/ Memória do framework (00-global … 90-decisions/ADRs)
240
- docs/ Documentação por persona e por tópico (ver DOC-MAP.md)
241
- prompts/ Prompts portáteis dos 6 papéis
242
- .claude/ Sub-agents e settings do Claude Code
243
- projects/ LEGADO — não usar; projetos vivem no workspace externo
244
+ bin/ CLIs (forja — the core; init-project, create-memory-nest-kit)
245
+ lib/ Reusable modules; lib/core/ is the invariant engine (registry, checks, health, release, doc-graph, gates)
246
+ scripts/ Automation (sprint-manager, agent-router, sync-universal-memory, …)
247
+ specs/ The framework's own SDD pipeline (spec → plan → tasks)
248
+ boilerplates/ Stack templates (api-rest, saas, ecommerce, microservices, monorepo)
249
+ memory/ Framework memory (00-global … 90-decisions/ADRs)
250
+ docs/ Documentation by persona and by topic (see DOC-MAP.md)
251
+ prompts/ Portable prompts for the 6 roles
252
+ .claude/ Claude Code sub-agents and settings
253
+ projects/ LEGACY — do not use; projects live in the external workspace
244
254
  ```
245
255
 
246
- ## Estrutura do workspace
256
+ ## Workspace structure
247
257
 
248
258
  ```
249
259
  ~/forja-workspace/
250
- projects/ # produtos gerados
260
+ projects/ # generated products
251
261
  memory/
252
- sqlite/universal.db # SQLite FTS5 dos produtos
253
- 30-projects/ # fichas dos projetos
254
- specs/ # specs de produto
255
- .context/ # runbooks GSD de produto
262
+ sqlite/universal.db # SQLite FTS5 for the products
263
+ 30-projects/ # project records
264
+ specs/ # product specs
265
+ .context/ # product GSD runbooks
256
266
  README.md
257
267
  ```
258
268
 
259
- ## Documentação
269
+ ## Documentation
270
+
271
+ The docs are written in **Brazilian Portuguese** — that's part of the project's identity. The CLI
272
+ output, code, and ADRs are readable regardless of language.
260
273
 
261
- - [`DOC-MAP.md`](DOC-MAP.md) — mapa por papel e por tópico (comece aqui)
262
- - [`docs/processo-projeto.md`](docs/processo-projeto.md) — criar vs atualizar projeto
263
- - [`docs/fluxo.md`](docs/fluxo.md) — mapa do ciclo CLI-first
264
- - [`AGENTS.md`](AGENTS.md) — os 6 papéis e a topologia
265
- - [`memory/90-decisions/`](memory/90-decisions/) — ADRs com rationale
266
- - [`CHANGELOG.md`](CHANGELOG.md) — histórico
274
+ - [`DOC-MAP.md`](DOC-MAP.md) — map by role and by topic (start here)
275
+ - [`docs/processo-projeto.md`](docs/processo-projeto.md) — create vs update a project
276
+ - [`docs/fluxo.md`](docs/fluxo.md) — the CLI-first cycle map
277
+ - [`AGENTS.md`](AGENTS.md) — the 6 roles and the topology
278
+ - [`memory/90-decisions/`](memory/90-decisions/) — ADRs with rationale
279
+ - [`CHANGELOG.md`](CHANGELOG.md) — history
267
280
 
268
- ## Convenções
281
+ ## Conventions
269
282
 
270
- - **CLI-first** — sprints, SDD, GSD, handoffs e governança por comando; o front nunca é gate.
271
- - **ADRs** — toda decisão estrutural vira `memory/90-decisions/NNNN-titulo.md`.
272
- - **Handoffs** — 7 campos obrigatórios (ADR-0005), gravados no SQLite (ADR-0008).
273
- - **pt-BR** — comunicação e documentação em português.
283
+ - **CLI-first** — sprints, SDD, GSD, handoffs, and governance by command; the UI is never a gate.
284
+ - **ADRs** — every structural decision becomes `memory/90-decisions/NNNN-title.md`.
285
+ - **Handoffs** — 7 required fields (ADR-0005), stored in SQLite (ADR-0008).
286
+ - **pt-BR** — communication and documentation in Portuguese.
274
287
 
275
288
  ## Roadmap
276
289
 
277
- O fio condutor: **converter conhecimento que vive em convenção em invariante executável.** Cada
278
- item abaixo ou fecha uma fronteira do framework por um gate, ou leva esse padrão para os projetos
279
- gerados.
280
-
281
- **Entregue** (até v1.6.0)
282
-
283
- - [x] **Família de gates** — cada fronteira do framework guarda por um invariante que roda: núcleo
284
- (`tools:doctor`, ADR-0023), tarball (`release:check`, ADR-0024), coerência de doc + ADRs + topologia
285
- de agentes (ADR-0025, SPEC-019), projeto gerado (`project:smoke`, ADR-0029). E `check:all` reúne a
286
- bateria num veredito (SPEC-020).
287
- - [x] **Migração TypeScript completa** — fonte 100% `.ts`, publica `dist/`, `noImplicitAny` ON. Achou
288
- bugs latentes que nenhum teste pegava (SPEC-012).
289
- - [x] **Economia de memória como sistema** — **medida** (`token:economy` prova ~60% vs frio),
290
- **entregue** (`code:context`), **protegida** (`memory:audit`, nas duas direções) e **propagada**: o
291
- projeto gerado herda o gate dos mapas (ADR-0030).
292
- - [x] **`project:upgrade`** — atualizar um projeto já gerado sem perder código: aditivo, nunca
293
- sobrescreve (SPEC-018).
294
- - [x] **Clean Architecture calibrado** — camadas onde se pagam, enxuto onde não; e a claim de token
295
- **medida e corrigida** — a economia é da memória, não das camadas (ADR-0027).
296
-
297
- **Próximos passos** (por dependência, não por desejo)
298
-
299
- - [x] **`builds` do backend gerado sob toolchain novo** — o template alinhou o `better-sqlite3` ao
300
- do framework (^12, com prebuilds); o `check:all --full` compila o backend gerado em Node 26.
301
- - [x] **`release-auditor` consome o gate** — o agente executa e julga `release:check --publish`
302
- (ADR-0024), incluindo o `consumer-spec-new`; não reimplementa o procedimento.
303
- - [ ] **Boilerplates além de NestJS** — o processo é agnóstico de stack; os templates vão atrás.
304
- - [ ] **(visão) o motor de orquestração** — a cadeia de handoffs que **roda**, não só é coerente
305
- (SPEC-019 deixou como futuro). O namesake executando: candidato ao 2.0.
306
-
307
- Sugestões? Abra uma issue — feature não-trivial aqui começa por spec, inclusive as suas.
308
-
309
- ## English
310
-
311
- Full English version: **[README.en.md](README.en.md)**. In short — **Forja** turns coding AI into an
312
- engineering team with process and memory: every project starts from a spec, every structural
313
- decision becomes an ADR, and nothing is lost between sessions. Documentation is in Brazilian
314
- Portuguese — that's part of the project's identity; the CLI and the code are readable regardless.
290
+ The throughline: **turn knowledge that lives as convention into an executable invariant.** Each item
291
+ below either closes a framework frontier with a gate, or carries that pattern into generated projects.
292
+
293
+ **Shipped** (through v1.6.0)
294
+
295
+ - [x] **Gate family** — every framework frontier is guarded by an invariant that runs: core
296
+ (`tools:doctor`, ADR-0023), tarball (`release:check`, ADR-0024), doc + ADR + agent-topology
297
+ coherence (ADR-0025, SPEC-019), generated project (`project:smoke`, ADR-0029). And `check:all`
298
+ runs the whole battery into one verdict (SPEC-020).
299
+ - [x] **TypeScript migration complete** — source 100% `.ts`, ships `dist/`, `noImplicitAny` ON. Found
300
+ latent bugs no test caught (SPEC-012).
301
+ - [x] **Memory economy as a system** — **measured** (`token:economy` proves ~60% vs cold),
302
+ **delivered** (`code:context`), **protected** (`memory:audit`, both directions), and **propagated**:
303
+ the generated project inherits the maps gate (ADR-0030).
304
+ - [x] **`project:upgrade`** — update an already-generated project without losing code: additive, never
305
+ overwrites (SPEC-018).
306
+ - [x] **Calibrated Clean Architecture** — layers where they pay off, lean where they don't; and the
307
+ token claim **measured and corrected** — the saving is memory's, not the layers' (ADR-0027).
308
+
309
+ **Next** (by dependency, not by wish)
310
+
311
+ - [x] **Generated backend `builds` under new toolchains** — the template now matches the
312
+ framework's `better-sqlite3` (^12, with prebuilds); `check:all --full` compiles the generated
313
+ backend on Node 26.
314
+ - [x] **`release-auditor` consumes the gate** — the agent runs and judges `release:check --publish`
315
+ (ADR-0024), including `consumer-spec-new`; it doesn't reimplement the procedure.
316
+ - [ ] **Boilerplates beyond NestJS** — the process is stack-agnostic; the templates will follow.
317
+ - [ ] **(vision) the orchestration engine** — the handoff chain that **runs**, not just is coherent
318
+ (SPEC-019 left it as future). The namesake executing: a 2.0 candidate.
319
+
320
+ Suggestions? Open an issue — a non-trivial feature here starts from a spec, yours included.
315
321
 
316
322
  ---
317
323
 
318
324
  <p align="center">
319
- <strong>A Forja te ajudou a domar seus agentes?</strong><br>
320
- Uma ⭐ é o que faz o projeto chegar a mais devs que estão pagando o imposto da IA amnésica.
325
+ <strong>Did Forja help you tame your agents?</strong><br>
326
+ A ⭐ is what carries the project to more devs still paying the amnesiac-AI tax.
321
327
  </p>
322
328
 
323
- <p align="center"><sub>Forja (npm: <code>forjajs</code>) · MIT License · <a href="CONTRIBUTING.md">Contribuindo</a></sub></p>
329
+ <p align="center"><sub>Forja (npm: <code>forjajs</code>) · MIT License · <a href="CONTRIBUTING.md">Contributing</a></sub></p>