forjajs 1.7.3 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (125) hide show
  1. package/CHANGELOG.md +31 -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 +26 -2
  125. package/README.en.md +0 -329
@@ -0,0 +1,15 @@
1
+ # ADR-0058 — Decisão de approval com identidade server-side
2
+
3
+ - **Status**: accepted
4
+ - **Data**: 2026-08-01
5
+ - **Contexto**: O dashboard precisava responder approvals sem permitir que o cliente escolhesse ou falsificasse o aprovador.
6
+ - **Decisão**: O cliente envia somente `approved` ou `rejected`. O Route Handler valida o valor, exige `FORJA_APPROVER_ID`, injeta o aprovador e timestamp, e encaminha a decisão ao Control Plane usando o token server-side.
7
+ - **Regras**:
8
+ - ausência de `FORJA_APPROVER_ID` retorna configuração indisponível;
9
+ - qualquer decisão fora do enum é rejeitada;
10
+ - o valor de `approverId` vindo do cliente é ignorado;
11
+ - Policy/ApprovalLedger continuam responsáveis por validade, expiração e idempotência semântica;
12
+ - a UI não exibe nem recebe segredo de autenticação.
13
+ - **Alternativas rejeitadas**: aceitar aprovador no body do browser; usar identidade fixa inventada; aprovar automaticamente quando não houver configuração.
14
+ - **Consequências**: O dashboard operacional exige configuração explícita do ambiente para decidir approvals. Listagem continua possível sem identidade de decisão.
15
+ - **Evidências**: `apps/dashboard/app/api/forja/approval.ts`, `apps/dashboard/app/api/forja/[...path]/route.ts`, `apps/dashboard/app/dashboard-client.tsx`, `test/dashboard-approval.test.js`, 267 testes.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "forjajs",
3
- "version": "1.7.3",
3
+ "version": "2.0.1",
4
4
  "description": "Forja — framework CLI-first de orquestração multiagente, memória hierárquica e geração de projetos com IA",
5
5
  "type": "module",
6
6
  "main": "index.js",
@@ -25,7 +25,8 @@
25
25
  ".github/copilot-instructions.md",
26
26
  ".memoryrc.json",
27
27
  "AGENTS.md",
28
- "README.en.md",
28
+ "README.md",
29
+ "README.pt-BR.md",
29
30
  "DOC-MAP.md",
30
31
  "CHANGELOG.md",
31
32
  "CONTRIBUTING.md",
@@ -83,6 +84,9 @@
83
84
  "code:impact": "node bin/forja.ts code:impact",
84
85
  "tools:doctor": "node bin/forja.ts tools:doctor",
85
86
  "release:check": "node bin/forja.ts release:check",
87
+ "dashboard:dev": "npm --prefix apps/dashboard run dev",
88
+ "dashboard:build": "npm --prefix apps/dashboard run build",
89
+ "dashboard:start": "npm --prefix apps/dashboard run start",
86
90
  "build": "tsc -p tsconfig.build.json",
87
91
  "types:check": "tsc --noEmit",
88
92
  "test": "node --test test/*.test.js"
@@ -109,8 +113,28 @@
109
113
  "allowScripts": {
110
114
  "better-sqlite3@12.11.1": true
111
115
  },
116
+ "overrides": {
117
+ "next": {
118
+ "postcss": "^8.5.25",
119
+ "sharp": "^0.35.3"
120
+ }
121
+ },
112
122
  "devDependencies": {
123
+ "@nestjs/common": "^11.1.28",
124
+ "@nestjs/core": "^11.1.28",
125
+ "@nestjs/platform-express": "^11.1.28",
126
+ "@nestjs/swagger": "^11.4.5",
127
+ "@tanstack/react-query": "^5.90.5",
128
+ "@types/express": "^5.0.6",
113
129
  "@types/node": "^26.1.1",
130
+ "@types/react": "^19.2.2",
131
+ "@types/react-dom": "^19.2.2",
132
+ "next": "^16.2.12",
133
+ "react": "^19.2.0",
134
+ "react-dom": "^19.2.0",
135
+ "reflect-metadata": "^0.2.2",
136
+ "rxjs": "^7.8.2",
137
+ "tsx": "^4.23.1",
114
138
  "typescript": "^5.9.3"
115
139
  }
116
140
  }
package/README.en.md DELETED
@@ -1,329 +0,0 @@
1
- <h1 align="center">🔨 Forja</h1>
2
-
3
- <p align="center">
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
- </p>
6
-
7
- <p align="center">
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
- <img src="https://github.com/allanpablo/forja/actions/workflows/ci.yml/badge.svg" alt="CI">
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
- <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/memory-SQLite_FTS5-green?style=flat-square" alt="Memory">
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
- <img src="https://img.shields.io/badge/license-MIT-1a1a1a?style=flat-square" alt="MIT">
16
- <img src="https://img.shields.io/badge/PRs-welcome-8957e5?style=flat-square" alt="PRs welcome">
17
- </p>
18
-
19
- <p align="center"><sub>🌐 <strong>English</strong> · <a href="README.md">Português</a></sub></p>
20
-
21
- ---
22
-
23
- ## Why Forja exists
24
-
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
-
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
-
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
-
38
- ## The 3 pillars
39
-
40
- | Pillar | What it delivers | Proof |
41
- |---|---|---|
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
-
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
-
50
- ## Forja in 60 seconds
51
-
52
- ```console
53
- $ forja spec:new pix-payments
54
- ✓ Spec created: specs/pix-payments/spec.md # nothing becomes code without this
55
-
56
- $ forja gsd:handoff plan pix-payments
57
- Handoff recorded: product → sdd-architect # 7 fields, auditable (ADR-0005)
58
-
59
- $ forja code:impact processPayment
60
- Impact map: processPayment (depth 2) # blast radius BEFORE you edit
61
- --- Direct callers ---
62
- BillingController.charge · RetryWorker.run
63
-
64
- $ forja gsd:check pix-payments
65
- OK GSD runbook OK Spec directory
66
- OK SDD spec check OK Codegraph
67
- Result: baseline gates ready. # executable governance, not a checklist
68
- ```
69
-
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.
72
-
73
- ## Why not just…?
74
-
75
- | Alternative | Where it stops | What Forja adds |
76
- |---|---|---|
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).
103
-
104
- ## ⚡ Quick start
105
-
106
- ```bash
107
- # Install (the package is forjajs; the command is forja)
108
- npm install -g forjajs
109
- forja # help grouped by domain
110
-
111
- # Prepare the production workspace (the fixed home for your projects)
112
- forja workspace:init
113
-
114
- # Create a new project (generated in ~/forja-workspace/projects/<name>)
115
- forja project:new my-project --ai claude,copilot
116
-
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
122
- ```
123
-
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).
129
-
130
- Step by step on **create vs update** a project: [`docs/processo-projeto.md`](docs/processo-projeto.md).
131
-
132
- ## How it works — the process
133
-
134
- ```
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)
138
- │
139
- ▼
140
- CLI-first CYCLE (docs/fluxo.md):
141
- 1·Understand → 2·Specify → 3·Architect → 4·Decompose → 5·Implement → 6·Govern → ✅
142
- ```
143
-
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`) |
152
-
153
- Full cycle map: [`docs/fluxo.md`](docs/fluxo.md).
154
-
155
- ## The 3 integrated capabilities
156
-
157
- | Capability | Role | How to use |
158
- |---|---|---|
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) |
162
-
163
- Details and reinstall: [`docs/capacidades-externas.md`](docs/capacidades-externas.md) · [ADR-0016](memory/90-decisions/0016-integracao-capacidades-externas.md).
164
-
165
- ## The `forja` core
166
-
167
- Every process command goes through a single entry point (ADR-0020):
168
-
169
- ```bash
170
- forja # help grouped by domain
171
- forja <command> [args] # in a cloned repo: node bin/forja.ts <command>
172
- ```
173
-
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.
178
-
179
- ## Essential commands
180
-
181
- ```bash
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
187
-
188
- # SDD pipeline
189
- forja spec:new <slug> # also: spec:plan · spec:tasks · spec:check
190
-
191
- # Sprint & handoffs (GSD)
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
223
- ```
224
-
225
- ## Framework vs workspace separation
226
-
227
- Forja is split in two:
228
-
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.
232
-
233
- The workspace path is resolved by priority:
234
-
235
- 1. `FORJA_WORKSPACE` environment variable
236
- 2. `workspaceRoot` field in `~/.forjarc.json`
237
- 3. Default: `~/forja-workspace`
238
-
239
- See ADR-0019 for the architectural decision.
240
-
241
- ## Repository structure (framework)
242
-
243
- ```
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
254
- ```
255
-
256
- ## Workspace structure
257
-
258
- ```
259
- ~/forja-workspace/
260
- projects/ # generated products
261
- memory/
262
- sqlite/universal.db # SQLite FTS5 for the products
263
- 30-projects/ # project records
264
- specs/ # product specs
265
- .context/ # product GSD runbooks
266
- README.md
267
- ```
268
-
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.
273
-
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
280
-
281
- ## Conventions
282
-
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.
287
-
288
- ## Roadmap
289
-
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.
321
-
322
- ---
323
-
324
- <p align="center">
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.
327
- </p>
328
-
329
- <p align="center"><sub>Forja (npm: <code>forjajs</code>) · MIT License · <a href="CONTRIBUTING.md">Contributing</a></sub></p>