# forjajs

> ForjaJS é uma plataforma local-first para memória, contexto, governança e execução supervisionada de agentes de desenvolvimento

Latest version **5.0.0** (published 2026-10-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install forjajs
pnpm add forjajs
yarn add forjajs
bun add forjajs
```

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 5.0.0 |
| Published | 2026-10-10 |
| First published | 2026-07-06 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Allan Pablo |
| Maintainers | allanpablo1 |
| Keywords | agents, agentic, agent-runtime, mcp, graph-memory, context-engineering, local-first, developer-tools, autonomous-agents, orchestration, memory, sqlite, sdd |

## Links

- npm: https://www.npmjs.com/package/forjajs
- Repository: https://github.com/allanpablo/forja
- Homepage: https://github.com/allanpablo/forja#readme
- Issues: https://github.com/allanpablo/forja/issues
- npm.io page: https://npm.io/package/forjajs

## Alternatives

- [d3-force-3d](https://npm.io/package/d3-force-3d.md) — 1.0M weekly downloads
- [ng2-charts](https://npm.io/package/ng2-charts.md) — 486.8K weekly downloads
- [@arcgis/core](https://npm.io/package/@arcgis/core.md) — 257.8K weekly downloads
- [react-sparklines](https://npm.io/package/react-sparklines.md) — 249.3K weekly downloads
- [react-native-gifted-charts](https://npm.io/package/react-native-gifted-charts.md) — 182.3K weekly downloads

## Recent versions

- 5.0.0 (latest) — 2026-10-10
- 4.1.2 — 2026-09-18
- 4.1.1 — 2026-09-08
- 4.1.0 — 2026-09-08
- 4.0.1 — 2026-09-05
- 4.0.0 — 2026-09-05
- 3.0.0 — 2026-09-01
- 2.0.4 — 2026-08-17
- 2.0.3 — 2026-08-02
- 2.0.2 — 2026-08-01
- 2.0.1 — 2026-08-01
- 2.0.0 — 2026-08-01
- 1.7.3 — 2026-07-23
- 1.7.2 — 2026-07-22
- 1.7.1 — 2026-07-22
- … 16 more at https://npm.io/package/forjajs/versions

## README

<h1 align="center">🔨 Forja</h1>

<p align="center">
  <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>
</p>

<p align="center">
  <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>
  <img src="https://github.com/allanpablo/forja/actions/workflows/ci.yml/badge.svg" alt="CI">
  <img src="https://img.shields.io/badge/operation-CLI--first-3553ff?style=flat-square" alt="CLI-first">
  <img src="https://img.shields.io/badge/agents-6_roles-orange?style=flat-square" alt="6 agents">
  <img src="https://img.shields.io/badge/pipeline-SDD_+_GSD-teal?style=flat-square" alt="SDD+GSD">
  <img src="https://img.shields.io/badge/memory-SQLite_FTS5-green?style=flat-square" alt="Memory">
  <img src="https://img.shields.io/badge/node-%E2%89%A522-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node >= 22">
  <img src="https://img.shields.io/badge/license-MIT-1a1a1a?style=flat-square" alt="MIT">
  <img src="https://img.shields.io/badge/PRs-welcome-8957e5?style=flat-square" alt="PRs welcome">
</p>

<p align="center"><sub>🌐 <strong>English</strong> · <a href="README.pt-BR.md">Português</a></sub></p>

---

## Why Forja exists

Coding agents are **amnesiac and undisciplined**: every session starts from zero, architecture
decisions evaporate, code drifts from intent — and if you run several products at once, you pay
that tax multiplied by N.

**Forja** is the studio around the AI. It coordinates **6 agent roles** through a
**Spec-Driven (SDD)** + **Get-Stuff-Done (GSD)** pipeline, keeps a **hierarchical memory** indexed
in SQLite that survives across sessions, and ties it all together behind **a single core CLI with
gates and an audit trail** (`forja`, ADR-0020). Multi-AI by design (Claude, Copilot, Gemini,
Codex). Everything is driven from the CLI.

**Who it's for**: the solo dev or small team running multiple products with AI as the main
workforce — and needing the discipline of a big team without having one.

## The 3 pillars

| Pillar | What it delivers | Proof |
|---|---|---|
| **Memory that survives** | hierarchical, searchable context, shared across sessions and AIs | SQLite FTS5, smart-context (ADR-0003) |
| **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) |
| **A factory, not a single project** | multi-product workspace, per-project agent teams | ADR-0019, harness, codegraph (ADR-0017) |

> This repository is the **engine (framework)** — it does not host production apps.
> Your products live in the **Forja workspace** (`~/forja-workspace` by default), outside this repo.
> See ADR-0019 for the rationale.

## Forja in 60 seconds

```console
$ forja spec:new pix-payments
✓ Spec created: specs/pix-payments/spec.md            # nothing becomes code without this

$ forja gsd:handoff plan pix-payments
Handoff recorded: product → sdd-architect             # 7 fields, auditable (ADR-0005)

$ forja code:impact processPayment
Impact map: processPayment (depth 2)                  # blast radius BEFORE you edit
--- Direct callers ---
BillingController.charge · RetryWorker.run

$ forja gsd:check pix-payments
OK   GSD runbook      OK   Spec directory
OK   SDD spec check   OK   Codegraph
Result: baseline gates ready.                         # executable governance, not a checklist
```

And each command above was recorded in `.context/forja-runs.jsonl` — when governance asks "was the
process followed?", the answer is a file, not a promise.

## Why not just…?

| Alternative | Where it stops | What Forja adds |
|---|---|---|
| **Plain Claude Code / Copilot** | brilliant in-session, amnesiac between sessions | FTS5 memory + process + audit around the AI |
| **LangGraph / CrewAI** | infrastructure to *build* agents | the layer above: it *operates* the agent team day to day |
| **Templates & spec kits** | stop once the spec is written | the full pipeline through governance, with gates that execute |

## Key capabilities

- **Single core CLI** — every process command goes through `forja <command>`: a declarative
  registry, cross-cutting gates (workspace), and append-only audit in
  `.context/forja-runs.jsonl` (ADR-0020).
- **Multi-agent orchestration** — 6 roles (orchestrator, context-engineer, sdd-architect, product,
  marketing, governance) with tracked handoffs (7 fields, ADR-0005).
- **Hierarchical memory** — global → domain → task → summary, with FTS5 search and *smart-context*
  in 3 modes (ADR-0003).
- **SDD + GSD pipeline** — `spec → plan → tasks → check`, decisions recorded as ADRs.
- **Self-verification (invariants that run)** — the framework proves itself: a family of gates guards
  each frontier (core, tarball, doc coherence, agent topology, generated project), and `check:all`
  runs the whole battery into a single verdict. Governance stops depending on discipline — it becomes
  harness.
- **Token economy measured, not asserted** — memory (the `context.md` as a map) saves ~60% vs
  exploring cold, and `token:economy` **proves** it across your domains. `code:context` delivers the
  map ready to paste; `memory:audit` guarantees it doesn't lie about the code.
- **Projects born connected to your AI** — `project:new` scaffolds a full project (memory, agents,
  a NestJS backend as the default boilerplate) and wires it to the AI you use: native instructions
  (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, Copilot), Claude Code hooks that open every session with the
  project state and attach the spec you mention, six role sub-agents, and the Forja MCP server in
  Claude, Codex, Gemini and Copilot (VS Code). The
  memory is indexed from the first minute. `project:wire --check` proves it; `project:upgrade --apply`
  re-wires older projects without touching the user's code — or the whole workspace with `--all`
  (ADR-0086). The NestJS backend follows the official NestJS 12 layout (ESM, Vitest, oxlint) and its
  `/api/ops` page shows the project's specs, open handoffs and indexed memory.
- **Validated templates** — `project:new <name> --template clean-arch` starts from a boilerplate whose
  install, build, tests and lint are proven in CI; `project:templates` lists what is a template and
  what is reference architecture (ADR-0088).
- **The user journey is a gate** — `npm test` and `release:check` run the whole journey (workspace →
  project → memory, context, specs, hooks, MCP, handoffs inside the project) against the source and
  against the installed tarball, and fail if any command writes into the package itself.
- **3 integrated capabilities** (ADR-0016): **codegraph** (code analysis via MCP), **harness**
  (agent-team design), **ai-engineering** (knowledge base).
- **LLM Fit Loop** — adapters de CLI, perfis no workspace, probes sem custo, observações e
  recomendação determinística por papel/tarefa; credenciais nunca entram no Forja.
- **Engineering Control Plane** (v3.0, ADR-0078) — the Engineering Graph turns ADRs/SPECs into
  first-class, queryable nodes; the Architecture Constitution checks real code against decisions
  already recorded; the Change Risk Engine scores a change 0-100 with named, evidenced factors;
  `forja simulate` tests a ref in an isolated worktree and never promotes on its own. One façade,
  `forja engineer "<goal>"`, composes all of it — context, relevant ADRs, architecture check, risk,
  recommended agents, similar past incidents — before you start. Every score is information for a
  human/policy rule to consult, never an autonomous decision on its own.

## ⚡ Quick start

```bash
# Install (the package is forjajs; the command is forja)
npm install -g forjajs
forja                    # help grouped by domain

# Prepare the production workspace (the fixed home for your projects)
forja workspace:init

# Create a new project (generated in ~/forja-workspace/projects/<name>, already wired to your AI)
forja project:new my-project --ai claude,copilot
cd ~/forja-workspace/projects/my-project
forja project:wire --check     # instructions, hooks, sub-agents and MCP connected
forja status                   # memory indexed, specs, handoffs — then open your AI here

# Enter the SDD/GSD cycle for the first feature
forja spec:new my-feature
forja spec:plan my-feature
forja spec:tasks my-feature
forja spec:check my-feature
```

### Already have a repository?

```bash
cd my-existing-app
forja project:wire --ai claude,codex   # native instructions, hooks, sub-agents, MCP
forja project:upgrade --apply          # memory and agents layer (additive: no backend, no overwrites)
forja sync:universal                   # index the memory
```

### Maintenance commands

```bash
forja project:upgrade --apply          # inside the project: new scaffold pieces + re-wire (pre-v5 projects)
forja project:upgrade --all            # every workspace project: dry-run report (--apply to apply)
forja project:wire --check
forja code:context <domain> --code
forja memory:audit
forja token:economy --project <project>
forja spec:set-status <feature> <spec|plan|tasks> <draft|approved>
```

### Prove supervised autonomy locally

The deterministic offline proof uses an external fixture, a real Git worktree,
human approval, a real `npm test`, diff validation, promotion, SQLite state,
GraphLoop evidence and a compact handoff:

```bash
npm run demo:autonomy
```

The full flow is documented in [`docs/2x/SPRINT-12-REAL-AUTONOMY-PLAN.md`](docs/2x/SPRINT-12-REAL-AUTONOMY-PLAN.md).

Measure the deterministic context baseline and cache evidence:

```bash
npm run benchmark:context
```

The sandbox also exposes an explicit, auditable rollback after promotion. Official
plugin boundaries are available as `@forja/plugin-github` and `@forja/plugin-docker`;
external network or Docker handlers must be injected and permissioned by the host.

> Cloned the repo instead of installing? The same commands run as
> `node bin/forja.ts <command>` — the npm scripts are just thin aliases of the core.
> The source is TypeScript and runs natively: **dev needs Node ≥ 22.6** (type stripping). The
> *published* package ships `dist/*.js` and requires **Node ≥ 22** — the `release-gate` installs the
> tarball and runs the full user journey on it every release (SPEC-012, ADR-0086).

Step by step on **create vs update** a project: [`docs/processo-projeto.md`](docs/processo-projeto.md).

## How it works — the process

```
💡 Demand
   ├─ project does NOT exist ─► project:new + boilerplate + harness (designs the team)
   └─ project DOES exist ─────► overlay --only-memory + codegraph init (understands the code)
                                              │
                                              ▼
   CLI-first CYCLE (docs/fluxo.md):
   1·Understand → 2·Specify → 3·Architect → 4·Decompose → 5·Implement → 6·Govern → ✅
```

| Step | Role | Capability |
|------|------|------------|
| 1 Understand | context-engineer | codegraph · ai-engineering |
| 2 Specify | product | — |
| 3 Architect | sdd-architect | harness · ADR |
| 4 Decompose | sdd-architect | — |
| 5 Implement | orchestrator + worker | codegraph (MCP) |
| 6 Govern | governance | codegraph (`affected`) |

Full cycle map: [`docs/fluxo.md`](docs/fluxo.md).

## The 3 integrated capabilities

| Capability | Role | How to use |
|---|---|---|
| **codegraph** | code analysis (local MCP) | `forja code:index` · `codegraph explore "<area>"` · MCP tools `codegraph_explore`/`codegraph_node` |
| **harness** | agent-team design (plugin) | in a Claude Code session: _"build a harness for this project"_ → generates `.claude/agents` + `.claude/skills` |
| **ai-engineering** | knowledge base (reference) | see [`docs/capacidades-externas.md`](docs/capacidades-externas.md) |

Details and reinstall: [`docs/capacidades-externas.md`](docs/capacidades-externas.md) · [ADR-0016](memory/90-decisions/0016-integracao-capacidades-externas.md).

## The `forja` core

Every process command goes through a single entry point (ADR-0020):

```bash
forja                              # help grouped by domain
forja <command> [args]             # in a cloned repo: node bin/forja.ts <command>
```

The core applies **gates** before running (e.g. product commands fail fast without a workspace) and
records an **audit** of each run (command, args, exit code, duration) in
`<workspace>/.context/forja-runs.jsonl` — the trail governance uses at review. The repo's npm
scripts are thin aliases that route through the core.

## Essential commands

```bash
# Orientation — the happy path
forja status                               # where am I: workspace, sprint, run, specs, runs, handoffs
forja next                                 # what now: one line — the next action + the exact command
forja help [<command>|--all]               # the core, or one command's usage/args/examples/next steps

# Workspace & projects
forja workspace:init                       # create ~/forja-workspace
forja project:new <name> --ai claude,copilot  # create a project in the workspace, wired to the AI
forja project:wire [--check]               # (inside a project) connect/verify instructions, hooks, MCP
forja project:upgrade --apply              # (inside a project) bring new scaffold + re-wire; --all for the workspace
forja project:templates                    # validated templates (project:new --template) vs reference
forja project:list                         # list workspace projects
forja workspace:project:check <name>       # validate standards in a workspace project

# SDD pipeline
forja spec:new <slug>                      # also: spec:plan · spec:tasks · spec:check

# Sprint & handoffs (GSD)
forja sprint:start                         # also: sprint:status · sprint:complete
forja gsd:plan <slug>                      # GSD runbook in .context/
forja gsd:handoff <intent> <slug>          # role-to-role handoff (ADR-0005)
forja agent:route list --open --mine       # open handoffs of this project (each one stamped with its project)
forja gsd:check <slug>                     # baseline runbook gates
forja orchestrate "<goal>" --slug <s>      # the default path: the whole SDD/GSD chain as a gated state machine (SPEC-021)
forja orchestrate:status <slug>            # the machine state: stages, gates, verdicts
forja orchestrate:advance <slug>           # run the stage gate; green → next; red → blocked

# Code analysis (codegraph)
forja code:check                           # trustworthy index (worktree + freshness)
forja code:impact <symbol>                 # callers + blast radius before you edit
forja code:query "<term>"                  # also: code:index · code:sync · code:status
forja drift:check [--domain <d>]           # reindex + flag 'verified' relations that stopped being true
forja adr:list                             # ADRs as first-class graph nodes, with status (SPEC-032)
forja adr:show <id>                        # status, source file, constraints
forja adr:impact <id>                      # who/what depends on this ADR — GraphLoop.impact()
forja adr:graph [<id>]                     # ADR/SPEC subgraph as JSON
forja architecture:compile                 # ADRs (## Constraints) → constitution.json (SPEC-033)
forja architecture:check                   # real code vs. the compiled Constitution
forja architecture:status                  # active/proposed rules, last compile
forja architecture:explain <rule-id>       # source ADR, original text, severity
forja architecture:approve <rule-id>       # promotes a proposed rule to active (via ApprovalLedger)
forja risk:assess [ref]                    # 0-100 change risk score, 7 named factors (SPEC-034)
forja risk:explain <assessment-id>         # replays a computed assessment, factor by factor
forja evidence:show <run-id>               # aggregated view of a persisted run (SPEC-035)
forja engineer "<objetivo>" [--ref <ref>] [--role <role>] [--json]  # façade: context + relevant ADRs + architecture check + risk + recommended agents + similar incidents + recommended flow (SPEC-035, SPEC-042)
forja agent:register <id> --role <role> [--provider <p>] [--model <m>] [--capabilities <c1,c2>] [--domains <d1,d2>]  # register/update an agent (SPEC-036)
forja agent:list                           # registered agents, with trustLevel if already scored
forja agent:show <id>                      # detail of one registered agent
forja agent:score <id> [--domain <d>]      # computes and persists trustLevel/autonomyLevel from real Observations
forja agent:history <id>                   # an agent's Observations, most recent first
forja agent:recommend --role <role> [--domain <d>]  # ranks registered agents by fit — information, not assignment (SPEC-037)
forja simulate <ref> [--command "npm test"] [--json]  # test+architecture+risk against an isolated worktree, never promotes (SPEC-038)
forja provenance:record <run-id>           # extracts file<->agent provenance from a persisted RuntimeRun (SPEC-039)
forja blame <file>                         # provenance history for a file — file granularity, not line
forja sbom [--json]                        # AI-SBOM: provenance report aggregated by agent
forja agent:monitor <id> [--window-hours <n>]  # compares recent behavior against historical baseline — information, never blocks (SPEC-040)
forja incident:record --title <t> [--description <d>]  # records an incident in the Engineering Graph (SPEC-041)
forja incident:list                        # recorded incidents, most recent first
forja incident:similar "<query>"           # keyword-based similar-incident suggestion — never applies anything

# Memory & context (workspace)
forja sync:universal                       # reindex the workspace SQLite FTS5
forja query:universal "<query>"            # FTS5 search
forja context:smart --mode task --task pix # smart-context: global | domain | task (ADR-0003)
forja memory:compress                      # archive old runs + VACUUM
forja memory:extract                       # extract global knowledge from memory

# LLM adapters and evidence
forja llm:profiles:init                    # create workspace-local adapter profiles
forja llm:doctor                           # verify configured CLIs without invoking a model
forja llm:recommend --role worker --task implementation
forja llm:run --profile codex --task specs/my-feature/spec.md
forja llm:eval --scope model --id codex:default
forja cost:economy                         # real $ cost per model, from the observation store

# Quality & release
forja project:check                        # framework standards (pre-commit)
forja tools:doctor                         # core X-ray; tells permission/lock from corruption; exit 1 if broken
forja release:check --publish              # tarball gate before publishing
forja project:smoke                        # generated-project gate; --full installs+builds; --ai <list> checks native instructions
forja project:dashboard                    # static status report
forja hook:session-start                   # what Claude Code runs at session start (briefing)
forja hook:user-prompt                     # what it runs per prompt (attaches the cited spec)

# Governance & audit
forja audit:sync                           # project the audit trail into a queryable table
forja audit:query --failed                 # query: --failed, --cmd <x>, --since 7d
forja governance:dashboard                 # static HTML panel (gates, SDD, audit) — no server
```

## Framework vs workspace separation

Forja is split in two:

1. **Framework** (this repository): the engine, conventions, scripts, and the framework's own memory.
2. **Workspace** (`~/forja-workspace` by default): the "fixed home" where product projects, their
   universal memory, and product specs live.

The workspace path is resolved by priority:

1. `FORJA_WORKSPACE` environment variable
2. `workspaceRoot` field in `~/.forjarc.json`
3. Default: `~/forja-workspace`

See ADR-0019 for the architectural decision.

## Repository structure (framework)

```
bin/          CLIs (forja — the core; init-project, create-memory-nest-kit)
lib/          Reusable modules; lib/core/ is the invariant engine (registry, checks, health, release, doc-graph, gates)
scripts/      Automation (sprint-manager, agent-router, sync-universal-memory, …)
specs/        The framework's own SDD pipeline (spec → plan → tasks)
boilerplates/ Stack templates (api-rest, saas, ecommerce, microservices, monorepo)
memory/       Framework memory (00-global … 90-decisions/ADRs)
docs/         Documentation by persona and by topic (see DOC-MAP.md)
prompts/      Portable prompts for the 6 roles
.claude/      Claude Code sub-agents and settings
projects/     LEGACY — do not use; projects live in the external workspace
```

## Workspace structure

```
~/forja-workspace/
  projects/              # generated products
  memory/
    sqlite/universal.db  # SQLite FTS5 for the products
    30-projects/         # project records
  specs/                 # product specs
  .context/              # product GSD runbooks
  README.md
```

## Inside a generated project

```
my-project/
  AGENTS.md              # how to operate the project — read natively by Codex, Copilot agent, Gemini
  CLAUDE.md, GEMINI.md   # import AGENTS.md (+ .github/copilot-instructions.md for Copilot)
  .claude/
    settings.json        # hooks: forja hook:session-start / hook:user-prompt
    agents/              # orchestrator, product, sdd-architect, context-engineer, governance, marketing
  .mcp.json              # forja MCP server (+ codegraph when installed)
  .codex/config.toml     # forja MCP for Codex · .gemini/settings.json (Gemini) · .vscode/mcp.json (Copilot)
  .forja/models.json     # AI fallback chain (engine switch)
  memory/                # hierarchical memory, indexed in memory/sqlite/ (git-ignored)
  specs/                 # spec → plan → tasks
  backend/               # NestJS 12, ESM + Vitest + oxlint (unless --skip-backend; or the --template's)
```

The Forja-managed part of each instruction file lives between `<!-- forja:begin -->` and
`<!-- forja:end -->`; everything outside it is yours and survives `project:wire`/`project:upgrade`.

## Documentation

The docs are written in **Brazilian Portuguese** — that's part of the project's identity. The CLI
output, code, and ADRs are readable regardless of language.

- [`DOC-MAP.md`](DOC-MAP.md) — map by role and by topic (start here)
- [`docs/processo-projeto.md`](docs/processo-projeto.md) — create vs update a project
- [`docs/fluxo.md`](docs/fluxo.md) — the CLI-first cycle map
- [`AGENTS.md`](AGENTS.md) — the 6 roles and the topology
- [`memory/90-decisions/`](memory/90-decisions/) — ADRs with rationale
- [`CHANGELOG.md`](CHANGELOG.md) — history

## Conventions

- **CLI-first** — sprints, SDD, GSD, handoffs, and governance by command; the UI is never a gate.
- **ADRs** — every structural decision becomes `memory/90-decisions/NNNN-title.md`.
- **Handoffs** — 7 required fields (ADR-0005), stored in SQLite (ADR-0008).
- **Releases** — every new version reconciles the README with its behavior and opens its
  `CHANGELOG.md` entry with a `### O que melhorou` section (product-language diff vs. the previous
  version, reused as the GitHub release note). Runbook: [`docs/publishing.md`](docs/publishing.md).
- **pt-BR** — communication and documentation in Portuguese.

## Roadmap

The throughline: **turn knowledge that lives as convention into an executable invariant.** Each item
below either closes a framework frontier with a gate, or carries that pattern into generated projects.

**Shipped** (v3.0.0 — Engineering Control Plane, ADR-0078)

- [x] **Engineering Graph** — ADRs/SPECs as first-class, queryable nodes (`adr:list/show/impact/graph`),
  deterministic extraction, no LLM (SPEC-032).
- [x] **Architecture Constitution** — ADR `## Constraints` compile into rules checked against real
  code (`architecture:compile/check/status/explain/approve`), reusing `ApprovalLedger`, not a
  parallel approval system (SPEC-033).
- [x] **Change Risk Engine** — a 0-100 score with 7 named, evidenced factors (`risk:assess/explain`);
  `PolicyEngine` can optionally consult it (`riskScoreRange`), never a parallel decision engine
  (SPEC-034).
- [x] **Evidence Ledger + `forja engineer`** — a per-run aggregated view, and the façade that
  composes context + relevant ADRs + architecture + risk + recommended agents + similar incidents +
  recommended flow before you start (SPEC-035, extended in SPEC-042).
- [x] **Agent Identity & Reputation, Smart Routing** — persistent agent registry with reputation
  derived from real behavior, never self-declared (`agent:register/score/recommend`, SPEC-036/037).
- [x] **Predictive Change Simulation** — `forja simulate <ref>` tests a ref in an isolated git
  worktree; never promotes on its own (SPEC-038).
- [x] **AI Code Provenance + Runtime Monitoring** — `forja blame`/`sbom` (file-granularity
  provenance), `agent:monitor` (behavior-anomaly detection vs. an agent's own baseline) — both
  information for `PolicyEngine`/a human to consult, never automatic (SPEC-039/040).
- [x] **Learning Loop** — `incident:record/list/similar`, keyword-based suggestion, never automatic
  application (SPEC-041).
- [x] **Autonomous Maintenance readiness** — ADR-0079 documents the guardrails any future real
  autonomous-maintenance spec must respect; deliberately not enabled yet, by the vision's own design.

**Shipped** (through v1.6.0)

- [x] **Gate family** — every framework frontier is guarded by an invariant that runs: core
  (`tools:doctor`, ADR-0023), tarball (`release:check`, ADR-0024), doc + ADR + agent-topology
  coherence (ADR-0025, SPEC-019), generated project (`project:smoke`, ADR-0029). And `check:all`
  runs the whole battery into one verdict (SPEC-020).
- [x] **TypeScript migration complete** — source 100% `.ts`, ships `dist/`, `noImplicitAny` ON. Found
  latent bugs no test caught (SPEC-012).
- [x] **Memory economy as a system** — **measured** (`token:economy` proves ~60% vs cold),
  **delivered** (`code:context`), **protected** (`memory:audit`, both directions), and **propagated**:
  the generated project inherits the maps gate (ADR-0030).
- [x] **`project:upgrade`** — update an already-generated project without losing code: additive, never
  overwrites (SPEC-018).
- [x] **Calibrated Clean Architecture** — layers where they pay off, lean where they don't; and the
  token claim **measured and corrected** — the saving is memory's, not the layers' (ADR-0027).
- [x] **Generated backend `builds` under new toolchains** — the template now matches the
  framework's `better-sqlite3` (^12, with prebuilds); `check:all --full` compiles the generated
  backend on Node 26.
- [x] **`release-auditor` consumes the gate** — the agent runs and judges `release:check --publish`
  (ADR-0024), including `consumer-spec-new`; it doesn't reimplement the procedure.

**Next** (by dependency, not by wish)

- [ ] **Cross-project Intelligence** (Phase 6 remainder) — correlating incidents across multiple
  repositories; needs a data source this single-repo workspace doesn't have yet.
- [ ] **Boilerplates beyond NestJS** — the process is stack-agnostic; the templates will follow.

Suggestions? Open an issue — a non-trivial feature here starts from a spec, yours included.

---

<p align="center">
  <strong>Did Forja help you tame your agents?</strong><br>
  A ⭐ is what carries the project to more devs still paying the amnesiac-AI tax.
</p>

<p align="center"><sub>Forja (npm: <code>forjajs</code>) · MIT License · <a href="CONTRIBUTING.md">Contributing</a></sub></p>

---
_Source: https://npm.io/package/forjajs · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
