Metadata-Version: 2.4
Name: atomadic-forge
Version: 0.14.1
Summary: Atomadic Forge — absorb, enforce, emerge. Polyglot (Python · JavaScript/TypeScript · Swift · Kotlin · Go) architecture guardian for AI-generated code.
Author: Atomadic
License-Expression: BUSL-1.1
Keywords: atomadic,ass-ade,monadic,architecture,forge,code-quality,ai,agents,javascript,typescript,polyglot
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click<9,>=8.1
Requires-Dist: typer<1,>=0.15
Requires-Dist: rich<16,>=14
Requires-Dist: pyyaml<7,>=6
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: import-linter<3,>=2.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: build<2,>=1; extra == "dev"
Requires-Dist: twine<7,>=5; extra == "dev"
Requires-Dist: tomli>=2; python_version < "3.11" and extra == "dev"
Requires-Dist: cryptography<48,>=42; extra == "dev"
Provides-Extra: signing
Requires-Dist: cryptography<48,>=42; extra == "signing"
Dynamic: license-file

<p align="center">
  <img src="assets/Atomadic-Forge-01.png" alt="Atomadic Forge" width="720"/>
</p>

# Atomadic Forge

## The Copilot's Copilot — built by agents, for agents

Forge is the architecture substrate that Cursor, Copilot, Claude Code,
Aider, Codex, and Devin call between turns. They generate code fast.
Forge gives that code architectural gravity — deterministic, signed,
mathematically-rigorous verification you can trust before you ship.

**Forge holds zero LLM clients.** The agent drives its own model; Forge
supplies certainty. That boundary is the whole product.

```
# From any MCP-aware agent (Cursor, Claude Code, Aider, Codex, Devin, …)
auto({
  "target":  "/path/to/messy-repo",
  "output":  "/path/to/clean-output",
  "package": "my_pkg",
  "apply":   true
})
# → scout → cherry-pick → assimilate → wire → certify → signed receipt
```

One call returns a tier-organized, import-law-enforced, certify-scored
package the agent continues building on. Forge keeps the law; the agent
stays in the loop.

### Why agents depend on it

| | Cursor / Claude Code / Codex / Aider | + Forge |
|---|---|---|
| **Generate code** | ✅ | (unchanged) |
| **Verify architecture** | ❌ | ✅ wire + certify + verify |
| **Cross-repo capability harvest** | ❌ | ✅ harvest + emergent_swarm (τ_trust gated) |
| **Refuse wrong tier before write** | ❌ | ✅ preflight_change |
| **Composite go/no-go ship gate** | ❌ | ✅ verify (PASS / REFINE / FAIL + next_command) |
| **Signed conformance proof** | ❌ | ✅ Receipt v1 |

### What just shipped (v0.14.0a10)

- **`forge hive recap` — full lifecycle replay of one consensus** (v0.14.0a10) — new CLI verb + MCP tool (`hive_recap`, surface 60 → **61**). Returns proposer, `proposed_at`, intent, every vote (with rationale + timestamp), the resolution event if any, and a summary block (verdict, duration, voters). The "what happened on this consensus?" primitive — useful for audit trails, release-note quotes, post-mortem replay.
- **`forge hive needs-vote` — "what should I weigh in on?"** (v0.14.0a9) — new CLI verb + MCP tool (`hive_needs_vote`, surface 59 → **60**) returning open consensuses where the calling agent hasn't voted yet, ordered by `proposed_at`, with `votes_so_far` + `voters_so_far` context. Closes the gap between `hive_observe` (everything happening) and the act of voting. Doc agent used it immediately after release to discover its own proposal needed proposer-vote attention.
- **`docs/WORLD_COLLISION.md`** (v0.14.0a8) — the 11-step E2E walkthrough of *Atomadic-uses-Forge*. Six of the eleven steps have already fired this sprint with public-artifact evidence (`wisdom.jsonl` + `hive/consensus.jsonl`). Forge agent authored.
- **The 7 LIVE AAAA-Nexus primitives are now MCP tools** (v0.14.0a7) — `nexus_identity_verify`, `nexus_federation_mint`, `nexus_authorize_action`, `nexus_sys_trust_gate`, `nexus_contract_verify`, `nexus_lineage_record`, `nexus_ratchet_register`. Surface jumps **52 → 59 tools**. Any MCP-aware agent (Cognition, Cursor, Claude Code) calls them directly through Forge — no CLI `--nexus` flag round-trip. All seven proxied through `NexusClient.from_env()` with auth-precedence (subscription > master) and the same `NexusToolNotShipped` guard.
- **`forge hive result --nexus` — consensus → Nexus mirror** (v0.14.0a6) — extends the hive↔Nexus bridge from wisdom-only (v0.14.0a5) to also mirror consensus resolution events. Fires only on freshly-recorded resolutions; best-effort, local stays canonical on failure.
- **Hive ↔ Nexus bridge — live primitives only** (v0.14.0a5) — `forge wisdom record --nexus` mirrors confidence-≥0.85 wisdom entries to AAAA-Nexus's LIVE `lineage_record` primitive. New `a0/nexus_constants.py` enumerates the 7 LIVE primitives Cognition's handshake confirmed exist; `a2/nexus_client.py` raises `NexusToolNotShipped` on any call outside that set. The LoRA capture loop closed against the actually-deployed Nexus, not the planned-but-vapor surface.
- **`forge hive watch` — live tail of hive activity** (v0.14.0a4) — color-coded continuous tail of `hive_observe`. New events every `--interval` seconds (proposals cyan / approve votes green / refine yellow / reject red / resolutions bright-green bold / wisdom-new ✦ / wisdom-superseded ↺). The synchronized-message-demo surface — Thomas (or any operator) can watch the four agents coordinate in real time.
- **Relay protocol aligned with REAL Nexus surface** (v0.14.0a3) — Cognition agent's `WIS-cog-2026-05-06-handshake` wisdom entry surfaced that the AAAA-Nexus primitives v0.14 was originally designed against (`nexus_consensus_*`, `nexus_swarm_*`, `nexus_agent_*`) **don't exist on the deployed Worker**. Forge agent re-wrote `RELAY_PROTOCOL.md` against the 7 live primitives (`identity_verify`, `federation_mint`, `authorize_action`, `sys_trust_gate`, `contract_verify`, `lineage_record`, `ratchet_register`). The hive caught a design-against-vapor moment via public-artifact corroboration — no Thomas-relay required.
- **Relay wire-contract spec** (v0.14.0a2) — [docs/RELAY_PROTOCOL.md](docs/RELAY_PROTOCOL.md) defines endpoints, JSON-RPC envelope shape, audit-log format, and Worker-side enqueue pattern.
- **`forge relay serve` — Worker → Local relay (alpha)** (v0.14.0a1) — first half of the "no stubs fully Forge-compatible" goal. A thin stdlib HTTP service (`forge relay serve --host 127.0.0.1 --port 7409`) that receives signed JSON-RPC envelopes and dispatches them through `mcp_protocol.dispatch_request`. The Worker side ships separately; when both halves are live, the 12 currently-stubbed Worker tools become real. Audit log at `.atomadic-forge/relay/jobs.jsonl`.
- **`hive_observe` goes multi-source** (v0.13.4) — one call now merges wisdom events (`wisdom.new` / `wisdom.superseded`) AND consensus events (`consensus.proposed/vote/resolved`), filtered by the agent's `subscribes_to` set, with two independent cursors (`since_consensus_id` + `since_wisdom_id`). Live cross-stream view of hive activity since the agent's last sync.
- **Wisdom → recipe promotion** (v0.13.3) — `forge wisdom promote` (CLI) and `wisdom_promote` (MCP, 51 → **52 tools**) cluster active wisdom by tag overlap; clusters with ≥3 corroborated entries become draft-recipe candidates at `_private/research/recipe_drafts/<name>.md`. The bridge between provisional knowledge and curated process.
- **Hive sync pipeline** (v0.13.2) — 7 MCP tools (`hive_register / hive_observe / hive_propose / hive_vote / hive_result / hive_list / hive_deactivate`). The register-and-discover protocol that lets four-agent loops coordinate via append-only public artifacts — no direct messaging. Foundation for the Atomadic-as-sovereign-AI endpoint. Full reference: [docs/HIVE_PRIMITIVES.md](docs/HIVE_PRIMITIVES.md).
- **`tool_factory` kwargs-binding fix** (v0.13.2) — keyword-only impl signatures now register cleanly via `tool_factory(apply=true)`.
- **Wisdom DB on the MCP surface** (v0.13.1) — `wisdom_record / wisdom_query / wisdom_list / wisdom_recall` are first-class MCP tools. Any MCP-aware agent (Cognition, Cursor, Claude Code, Aider, Codex, Devin) can record / query / recall institutional memory directly.
- **Wisdom DB** (v0.13.0) — cross-session institutional memory at `.atomadic-forge/wisdom.jsonl`. Auto-hooks bracket every dev cycle: `forge recon` returns `prior_wisdom`; `forge verify` returns `wisdom_capture_prompt`. Agents inherit prior lessons without extra discipline; the substrate persists across conversations.
- **Canonical surface artifact** (v0.12.0) — `forge surface emit/check/diff` + `surface.json` checked into the repo + CI gate (`surface-drift.yml`). Every consumer reads the artifact; hand-maintained maps are gone. `legacy_endpoint_map` lets stale callers find renamed tools without a separate lookup.
- **`__version__` drift fix** (v0.12.0) — derived from `importlib.metadata` so `pyproject.toml` is the one source of truth. The v0.11.0 drift (pyproject 0.11.0, `__init__` 0.10.0) is structurally impossible going forward.
- **Polyglot expansion** (v0.11.0) — Swift, Kotlin, Go, `.mts`, `.cts` join Python and JS/TS. One pass, no language servers, no Node dependency.
- **Surface consolidated in v0.10.0** — 47 → 40 tools, zero capability lost. Merged `audit_list + why_did_this_change + what_failed_last_time → lineage`; `list_recipes + get_recipe → recipes`; `auto_plan + adapt_plan → plan`; `auto_step + auto_apply → plan_apply`.

---

[![PyPI](https://img.shields.io/pypi/v/atomadic-forge.svg)](https://pypi.org/project/atomadic-forge/)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License: BSL-1.1](https://img.shields.io/badge/License-BSL--1.1-yellow.svg)](LICENSE)
[![CI](https://github.com/atomadictech/atomadic-forge/actions/workflows/ci.yml/badge.svg)](https://github.com/atomadictech/atomadic-forge/actions/workflows/ci.yml)
[![Forge certify](https://img.shields.io/badge/forge_certify-100%2F100-brightgreen)](docs/SHOWCASE.md)
[![Product Hunt](https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1136405&theme=light&t=1777661664916)](https://www.producthunt.com/products/atomadic-forge-mcp-architecture-copilot)
[![MCP Registry](https://img.shields.io/badge/MCP-Official_Registry-blue)](https://registry.modelcontextprotocol.io/)

<!-- mcp-name: io.github.atomadictech/atomadic-forge -->

> **Absorb. Enforce. Emerge.** The architecture substrate for AI-generated code — now polyglot (Python, JavaScript / TypeScript, Swift, Kotlin, Go).

🔗 **Try it live:** [forge.atomadic.tech](https://forge.atomadic.tech) — paste any GitHub repo and watch the analysis in real time.

Forge is a monadic-architecture engine that does three things no existing
tool combines:

1. **Absorbs** Python, JavaScript / TypeScript, Swift, Kotlin, or Go repositories into a verified
   5-tier layout.
2. **Enforces** the upward-only import law on every emitted file.
3. **Emerges** new capabilities by composing what already exists — and
   refuses to credit code that lies about what it does.

It's the substrate Cursor and Devin and Lovable don't have. It runs on
free local models, free cloud tiers, or paid frontier models — same
loop, swap the LLM, watch the trajectory carry harder tasks higher.

**Five capabilities no other tool ships today:**

| Capability | Why it matters |
|---|---|
| **`verify`** | Single composite go/no-go ship gate — runs `wire + certify` (and optionally `score_patch + preflight_change`) and returns `PASS / REFINE / FAIL` with a recommended `next_command`. One call answers "is this ready?" |
| **`emergent_scan`** | Cross-domain composition discovery — finds novel a3 features you can ship by wiring existing symbols, without writing new logic |
| **`harvest`** | Cross-repo capability gap-finder. Diffs target against N≤23 sibling repos, ranks graft candidates by τ_trust-gated confidence (≥0.998354 → auto-applyable, below → review_required) |
| **`preflight_change`** | ASK BEFORE WRITING — surfaces wrong tier, forbidden imports, and scope violations before the agent generates a single line |
| **Receipt v1** | Signed conformance proof — JSON artifact CI, regulators, and downstream agents accept as evidence the package passed every gate |

**Languages:** Python (`.py`), JavaScript (`.js` / `.mjs` / `.cjs` / `.jsx`),
TypeScript (`.ts` / `.tsx` / `.mts` / `.cts`), Swift (`.swift`), Kotlin
(`.kt` / `.kts`), Go (`.go`). Cloudflare Workers, Node back-ends, native
mobile apps, and mixed-language repositories all classify in a single pass
— no Node dependency, no kotlinc, no swiftc, `node_modules/` skipped
automatically.

## Get started in 10 minutes

**Read [docs/FIRST_10_MINUTES.md](docs/FIRST_10_MINUTES.md).** It is
the canonical onboarding path: install, a 30-second offline demo, a
10-second free recon on your own repo, then a fork into either
"absorb existing code" or "generate from intent" with explicit cost,
privacy, and wallclock numbers.

For deeper paths once you have done the 10-minute path:

- [docs/HIVE_STATUS.md](docs/HIVE_STATUS.md) — live status board for the four-agent loop (Forge, Cognition / Atomadic, Doc, Research). Read first if you're an agent activating into this repo.
- [docs/HIVE_PRIMITIVES.md](docs/HIVE_PRIMITIVES.md) — the 7 `hive_*` MCP tools (register, observe, propose, vote, result, list, deactivate). The register-and-discover protocol that lets agents coordinate without direct messaging.
- [docs/RELAY_PROTOCOL.md](docs/RELAY_PROTOCOL.md) — wire contract between Worker MCP and `forge relay serve`. Endpoints, JSON-RPC envelope shape, audit-log format, Worker-side enqueue pattern.
- [docs/WORLD_COLLISION.md](docs/WORLD_COLLISION.md) — the 11-step E2E walkthrough of *Atomadic-uses-Forge*. The autonomous loop the four-agent hive is running toward.
- [docs/02-commands.md#forge-surface](docs/02-commands.md#forge-surface) — emit, verify, and diff the canonical `surface.json` artifact (CI gate + consumer bootstrap).
- [docs/02-commands.md#forge-wisdom](docs/02-commands.md#forge-wisdom) — append-only institutional memory: record lessons, query across sessions, auto-recall on recon.
- [docs/WORKER_VS_LOCAL_MCP.md](docs/WORKER_VS_LOCAL_MCP.md) — two MCP servers, two contracts: when to call which, and the args each accepts.
- [docs/MULTI_REPO.md](docs/MULTI_REPO.md) — absorb more than one repo at once.
- [docs/CI_CD.md](docs/CI_CD.md) — GitHub Actions, GitLab CI, pre-commit.
- [docs/AIR_GAPPED.md](docs/AIR_GAPPED.md) — offline / on-prem install.
- [docs/SHOWCASE.md](docs/SHOWCASE.md) — live trajectories of real runs.
- [docs/MARKET_POSITIONING.md](docs/MARKET_POSITIONING.md) — why Forge matters in the AI coding market.
- [docs/RELEASE_MESSAGING.md](docs/RELEASE_MESSAGING.md) — launch copy, HN post, outreach, and demo script.

### Polyglot recon (JS/TS in a single pass)

```bash
$ forge recon ./my-cloudflare-worker

Recon: ./my-cloudflare-worker
------------------------------------------------------------
  python files:     0
  javascript files: 4
  typescript files: 1
  primary language: javascript
  symbols:          17
  tier dist:        {'a0_qk_constants': 1, 'a1_at_functions': 2,
                     'a2_mo_composites': 1, 'a4_sy_orchestration': 1}
  effect dist:      {'pure': 9, 'state': 5, 'io': 3}
  recommendations:
    - JS/TS files are not yet split into aN_* tier directories —
      see suggested_tier per file in symbols[].
```

## Pipeline lanes

```bash
forge auto ./messy-repo ./out --apply       # Absorb a flat repo into 5-tier layout
forge evolve run "<intent>" ./out --auto 5  # LLM-driven recursive generation
forge demo run --preset NAME                # Click-to-launch-video preset
forge chat ask "what should I fix next?" --context .
```

**What Forge does:**
- Walks any Python or JavaScript/TypeScript repo, classifies every symbol into one of 5 architectural tiers
- Materializes into a tier-organized tree with strict upward-only imports
- Detects architecture violations (upward imports, misclassified symbols) — Python or JS, same law
- Scores conformance: documentation, tests, tier layout, import discipline
- Works with AI-generated code — absorbs it, fixes the architecture, ships it

**What Forge does NOT do:**
- Pretend `forge auto` magically finished your product; absorption creates a
  tiered starter skeleton. `iterate` / `evolve` can generate code through your
  configured LLM, but Forge still gates it with wire/certify feedback.
- Create semantic unification (two `User` classes stay two `User` classes)
- Bypass the 5-tier law (Forge itself passes its own `wire` scan 100%)
- Store secrets or credentials

## Why Forge exists

AI agents produce 30–50% of new code in many teams. The output is **fast and often correct**. But it's almost universally **architecturally incoherent**:

- God classes mixing concerns
- Leaky abstractions and circular imports
- Same concept named five different ways
- Test coverage is scattered
- No module organization

**Linters say "no."** Forge says **"yes, but reorganised like this"** and shows the diff.

Forge is **not a style checker**. It's an **architecture rebuilder**. It absorbs your code (including AI-generated code), re-tiers it, enforces the 5-tier monadic law, and emits a clean, verifiable structure with certification scores.

Release positioning: **AI coding agents create implementation velocity.
Forge adds architectural gravity.** See
[docs/MARKET_POSITIONING.md](docs/MARKET_POSITIONING.md) for the
market frame and source-backed claims.

## The 5-tier monadic law

Every source file (Python `.py`, JavaScript `.js`/`.mjs`/`.cjs`/`.jsx`, or
TypeScript `.ts`/`.tsx`) belongs to exactly one tier. **Tiers compose upward
only** — never sideways, never downward.

```
  a4_sy_orchestration/       ← CLI, entry points, top-level orchestration
           ↑
  a3_og_features/            ← Feature modules (compose a2 into capabilities)
           ↑
  a2_mo_composites/          ← Stateful classes (clients, registries, stores)
           ↑
  a1_at_functions/           ← Pure functions (validators, parsers, formatters)
           ↑
  a0_qk_constants/           ← Constants, enums, TypedDicts (zero logic)
```

| Tier | Directory | What lives here | May import |
|------|-----------|-----------------|------------|
| **a0** | `a0_qk_constants/` | Constants, enums, TypedDicts, config | Nothing |
| **a1** | `a1_at_functions/` | Pure stateless functions | a0 only |
| **a2** | `a2_mo_composites/` | Stateful classes, clients, stores | a0, a1 |
| **a3** | `a3_og_features/` | Features combining composites | a0–a2 |
| **a4** | `a4_sy_orchestration/` | CLI commands, entry points | a0–a3 |

### Why the tiers work

Each tier is a layer of **verified building blocks**. Higher tiers never invent logic — they **compose** blocks from lower tiers. This means:

- **a0 is bulletproof:** no imports, no logic, 100% verifiable
- **a1 is isolated:** pure functions on pure data, trivial to test
- **a2 wraps logic:** state + verified building blocks, testable in isolation
- **a3 orchestrates:** combines composites into features, handles cross-cutting concerns
- **a4 glues everything:** CLI layer only, zero business logic

**Upward-only import law:** `forge wire` detects violations, `import-linter` enforces at CI, contract lives in `pyproject.toml`.

## Installation

```bash
pip install atomadic-forge
forge --version   # atomadic-forge 0.14.0
forge doctor      # environment check
```

Then follow [docs/FIRST_10_MINUTES.md](docs/FIRST_10_MINUTES.md) for
the canonical first-run path (offline demo, free recon, then absorb or
generate).

**From source (contributors):**

```bash
git clone https://github.com/atomadictech/atomadic-forge && cd atomadic-forge
pip install -e ".[dev]"
python -m pytest               # 1179 collected (1177 passed, 2 skipped)
```

## AI Agent integration (MCP)

Forge ships a **Model Context Protocol server** — add it to Cursor, Claude Code, Aider, Devin, or any MCP-compatible agent and they can drive forge without touching the CLI:

```json
{
  "mcpServers": {
    "atomadic-forge": {
      "command": "forge",
      "args": ["mcp", "serve", "--project", "/path/to/your/repo"]
    }
  }
}
```

### All 63 MCP tools (local) · 40 on the deployed Worker

Grouped by purpose. Every tool is `tools/call`-able through the MCP
contract; every tool returns a versioned schema (`atomadic-forge.<tool>/v<n>`).
Run `forge mcp serve --help` for the full surface with examples.

**Pipeline** (the agent's normal day)
| Tool | One-liner |
|---|---|
| `recon` | Walk a repo and return a structured scout report (symbols, tier guess, effects). |
| `context_pack` | First-call repo bundle: score, blockers, risky files, best next action. |
| `preflight_change` | ASK BEFORE WRITING. Tier + import + scope check on a proposed edit. |
| `wire` | Detect upward-import violations across the tier graph. |
| `certify` | 0–100 go/no-go score with structural / runtime / behavioral / operational breakdown. |
| `verify` | **Composite ship gate.** Runs wire + certify (+ optional score_patch + preflight_change). Returns `PASS / REFINE / FAIL` + `next_command`. |
| `score_patch` | Predict certify-score impact of a unified diff before committing. |
| `select_tests` | Pick the smallest validation set that exercises the changed files. |
| `enforce` | Tier-law enforcement gate — fails loud on regressions. |
| `rollback_plan` | Reversal recipe for a proposed change (what to undo, in what order). |

**Auto-pipeline** (one-call absorb, plan, apply)
| Tool | One-liner |
|---|---|
| **`auto`** | Flagship one-shot: scout → cherry → assimilate → wire → certify. Used most. |
| `plan` | Generate a bounded execution plan (action cards with risk + rollback annotations). |
| `plan_apply` | Apply one card or all-applyable cards from a `plan` result. |
| `iterate_start` | Begin an LLM-driven iterate loop. Forge holds zero LLM clients — caller drives. |
| `iterate_continue` | Step the iterate loop. Each turn is observable; rollback is cheap. |
| `evolve_start` / `evolve_step` | Recursive iterate — each round seeds the next from the prior output. |
| **`cherry`** | Cherry-pick manifest of symbols from a scouted repo. Surgical control. |
| **`finalize`** | Materialize a cherry-pick into a tier-organized output package. |

**Cross-repo intelligence** (Round-4 / Round-5)
| Tool | One-liner |
|---|---|
| `recon_swarm` | Walk N≤23 repos and return a unified scout report. |
| `harvest` | τ_trust-gated graft proposals — capabilities your target lacks but your portfolio has. |
| `emergent_swarm` | Cross-repo emergent composition discovery. Finds new a3 features hiding in the union. |
| `guard_install` | Install the four-layer architectural immune system: pre-commit + GH Action + pyproject + CONTRIBUTING. |

**Code intel + audit**
| Tool | One-liner |
|---|---|
| `emergent_scan` | Cross-domain composition discovery on a single repo. |
| `synergy_scan` | Pairs of symbols whose composition exceeds the sum of parts. |
| `cna_check` | Compose-Not-Add. Flag features added when an existing composite would have served. |
| `call_graph` | Static call graph (Python + JS/TS), tier-coloured. |
| `smell_scan` | Architectural smells beyond simple tier-violations. |
| `manifest_diff` | Manifest-level diff between two scouts (added / removed / migrated symbols). |
| `lineage` | Decision audit — what changed, why, what failed last time. (Auto-detects mode from args.) |
| `commit_compose` | One-call Conventional Commit message builder from staged diff + intent. |
| `forge_locate` | Return the line range of well-known forge insertion points (saves ~1000 tokens vs reading the file). |

**Meta + ops**
| Tool | One-liner |
|---|---|
| `recipes` | Named golden-path recipes (`add_feature`, `bump_version`, `dev_cycle`, `release_hardening`, …). No name = catalogue; with name = full body. |
| `tool_factory` | Forge eats forge — meta-tool that scaffolds new MCP tools from a spec. |
| `doctor` | Health check; `include_worktree=true` adds worktree status. |
| `sidecar_validate` | Sidecar-mode contract test. |
| `compose_tools` | Compose multiple tools into a higher-level workflow. |
| `explain_repo` | Plain-English orientation for a repo. |
| `load_policy` | Load a custom certify / wire policy. |
| `trust_gate_response` | Trust-gate envelope for any agent response. |

> **v0.10.0 surface consolidation:** `lineage` merges
> `audit_list` + `why_did_this_change` + `what_failed_last_time`;
> `plan` merges `auto_plan` + `adapt_plan`; `plan_apply` merges
> `auto_step` + `auto_apply`; `recipes` merges `list_recipes` +
> `get_recipe`. `doctor` absorbs `worktree_status` (via
> `include_worktree=true`); `verify` absorbs `exported_api_check`
> (via `check_exports=true`). 47 → 40 tools, zero capability lost.

**5 resources:** Receipt schema · formalization docs · lineage chain · blocker summary · verdicts

```bash
forge mcp serve --help   # full tool + resource listing with examples
forge mcp doctor --project . --json
```

As of `0.5.2`, `tools/list` includes a `cli_command` fallback for
each MCP tool. `context-pack`, `preflight`, `select-tests`, and
`score-patch` also use language-aware validation commands so
JavaScript projects get `npm run verify` / `npm test` guidance and
documentation/research paths are treated as non-code project memory.

### Subscription required for `forge mcp serve`

Every `tools/call` against the MCP server is gated behind a paid Forge
subscription. Get a key at [https://atomadic.tech/forge](https://atomadic.tech/forge),
then run:

```bash
forge login                          # interactive: paste your fk_live_* key
export FORGE_API_KEY=fk_live_xxxxx   # or set the env var directly
forge mcp serve --project .
```

Read-only handshake methods (`initialize`, `ping`, `tools/list`,
`resources/list`) work without a key so MCP clients can complete the
connect handshake; `tools/call` and `resources/read` require an active
subscription. The verify endpoint at
`https://forge-auth.atomadic.tech/v1/forge/auth/verify` is contacted
on first call and the result is cached for 5 minutes; offline grace
keeps you running for 24 hours after the last successful verify.

Without a key (or with a revoked one), `tools/call` returns the
JSON-RPC error code `-32001` with `message="Forge subscription
required"` and an `upgrade_url` pointing back to the dashboard.

## Code-from-intent (LLM-driven, with Forge as the architectural backbone)

Plug a free Gemini key in and let the loop produce architecturally-coherent
code from a paragraph of intent:

```bash
# Get a free key at https://aistudio.google.com/apikey
export GEMINI_API_KEY=your-key-here          # never commit this

# Single-shot generate (one user-intent → multi-turn LLM loop):
forge iterate run "build a tiny calculator CLI" ./out \
    --package calc --provider gemini --max-iterations 4

# Recursive self-improvement: N rounds, catalog grows each round:
forge evolve run "build a markdown-to-PDF service" ./out \
    --auto 5 --provider gemini --target-score 80

# Pre-flight (no LLM call) — print the system + first prompt:
forge iterate preflight "..." --package whatever
```

Every Python `iterate` / `evolve` run now ends with a deterministic quality
phase: Forge adds conservative missing docstrings, writes `docs/API.md` and
`docs/TESTING.md`, and creates `tests/test_generated_smoke.py` so the
package has import-smoke coverage even when the model forgets tests. These
generated tests are a floor; add behavior tests for real inputs before
shipping.

### Chat copilot

Use your configured AI agent as a Forge-aware terminal copilot. The chat
surface uses the same provider layer as `iterate` and `evolve`, and can pack
bounded repo context without sending `.env` or obvious secret files.

```bash
# One-shot question with repo context
forge chat ask "what should I run before release?" --context .

# Interactive session against your AAAA-Nexus agent
export AAAA_NEXUS_API_KEY=...
forge chat repl --provider nexus --context src --context docs

# Offline smoke test for scripts / CI
forge chat ask "hello" --provider stub --no-cwd-context --json
```

### LLM provider matrix

| Provider | Cost | Env var | Default model | When to use |
|----------|------|---------|---------------|-------------|
| `gemini` | **free tier** | `GEMINI_API_KEY` / `GOOGLE_API_KEY` | `gemini-2.5-flash` | Best free cloud option; override with `FORGE_GEMINI_MODEL` |
| `nexus` / `aaaa-nexus` | paid | `AAAA_NEXUS_API_KEY` | (Nexus default) | AAAA-Nexus sovereign AI; most reliable for long runs |
| `anthropic` | paid | `ANTHROPIC_API_KEY` | `claude-sonnet-4-6` | Highest code quality (Claude 4.x; override with `claude-opus-4-7` for max reasoning or `claude-haiku-4-5-20251001` for speed) |
| `openai` | paid | `OPENAI_API_KEY` | `gpt-4o-mini` | Cheap GPT path; override to `gpt-4.1` or `gpt-4o` for higher quality |
| `openrouter` | **free tier available** | `OPENROUTER_API_KEY` | `inclusionai/ling-2.6-1t:free` | Access 200+ models; good fallback when Gemini quota exhausted; override with `FORGE_OPENROUTER_MODEL` |
| `ling` | **free** | `OPENROUTER_API_KEY` | `inclusionai/ling-2.6-1t:free` | Shortcut for Ling-2.6-1T (1T-param MoE, 262K ctx, SOTA SWE-bench) — frontier model at zero cost via OpenRouter |
| `ollama` | free, local | `FORGE_OLLAMA=1` | `qwen2.5-coder:7b` | Offline; fully private |
| `stub` | free, offline | n/a | n/a | Tests, CI, dry-runs |

`--provider auto` resolves in the code-defined order:
AAAA-Nexus, Anthropic, Gemini, OpenAI, OpenRouter, Ollama, then `stub`.
Explicit `--provider gemini` (or any other provider name) always wins.

For busy laptops or desktops, run Ollama with the small local profile:

```bash
export FORGE_OLLAMA=1
export FORGE_OLLAMA_MODEL=qwen2.5-coder:1.5b
export FORGE_OLLAMA_NUM_PREDICT=768
export FORGE_OLLAMA_TIMEOUT=180
forge chat ask "what should I fix next?" --provider ollama --context src
```

Use `qwen2.5-coder:7b` when the machine is idle and you want better code
quality. `FORGE_OLLAMA_NUM_PREDICT` caps each generation; lower it if
Ollama starts paging or crashing. `FORGE_OLLAMA_TIMEOUT` controls how long
Forge waits before returning a clear provider error.

## Commands

**Flagship:** `forge auto` does everything in one shot.

### Absorb pipeline

| Command | Purpose | Typical use |
|---------|---------|-------------|
| **`forge auto`** | Scout → cherry-pick → materialize → wire → certify. *The main verb.* | `forge auto ./repo ./out --apply` |
| `forge recon` | Walk a repo, classify every symbol. Shows tier distribution. | `forge recon ./repo` |
| `forge cherry` | Build a cherry-pick manifest. Select specific symbols or `--pick all`. | `forge cherry ./repo --pick all` |
| `forge finalize` | Materialize, wire, certify. Run separately if needed. | `forge finalize ./repo ./out --apply` |
| `forge wire` | Scan a tier tree for upward-import violations. | `forge wire ./out/src/package` |
| `forge certify` | Score: documentation, tests, tier layout, import discipline. | `forge certify ./out --fail-under 90` |
| `forge enforce` | Apply F-code-routed mechanical fixes (rollback-safe). | `forge enforce ./out/src/package` |
| `forge status` | Wire + certify in one call. The quick health check. | `forge status .` |

### Observability & compliance

| Command | Purpose |
|---------|---------|
| `forge audit list / show / log` | Browse `.atomadic-forge/lineage.jsonl` — run history, saved manifests. |
| `forge doctor` | Environment check — Python, optional deps (complexipy, cryptography). |
| `forge sbom` | Emit a CycloneDX 1.5 SBOM from the scout report. |
| `forge cs1` | Render a Conformity Statement (EU AI Act / SR 11-7 / FDA PCCP / CMMC-AI). |
| `forge diff` | Schema-aware compare of two scout or certify manifests. |
| `forge sidecar parse / validate` | Parse + cross-check `.forge` v1.0 sidecar grammar. |

### Agent & LLM loops

| Command | Purpose |
|---------|---------|
| `forge mcp serve` | Stdio JSON-RPC MCP server — 63 tools for Cursor / Claude Code / Aider / Devin. |
| `forge plan / plan-list / plan-show / plan-step / plan-apply` | Agent plan persistence and step-by-step apply. |
| `forge iterate` | LLM loop: intent → code → absorb → wire → score → iterate. Single shot. |
| `forge evolve` | Recursive improvement: N rounds, catalog grows each round. |
| `forge chat` | Terminal copilot over forge docs/source using the same AI provider layer. |
| `forge context-pack` | Pack bounded repo context for first-call orientation or targeted change/release/debug focus. |
| `forge worktree status` | Check branch, upstream drift, dirty files, version sync, and stale installed `forge` commands before editing. |
| `forge preflight` | Pre-edit guardrail — forbidden imports, tier checks. |
| `forge recipes` | List and fetch golden-path recipe templates. |

### Composition & tooling

| Command | Purpose |
|---------|---------|
| `forge emergent` | Symbol-level composition discovery. |
| `forge synergy` | Feature-pair detection + auto-generate adapters. |
| `forge commandsmith` | Auto-register CLI commands, regenerate `_registry.py`, smoke-test all verbs. |
| `forge lsp serve` | Stdio LSP server for `.forge` files (live diagnostics, hover, goto). |

## Targeted workflows

```bash
# Targeted: just see what's in a repo
forge recon ./repo

# Targeted: pick specific symbols
forge cherry ./repo --pick infer_tier --pick CherryPicker

# Targeted: merge two repos with conflict resolution
forge cherry ./repo-a --pick all
forge finalize ./repo-a ./out --apply --on-conflict rename

# Specialty: surface compositions across your own catalog
forge emergent scan
```

## Known limits (honest & concrete)

Forge ships with named limits. No overpromise.

1. **Python and JavaScript/TypeScript today; Rust / Go on the roadmap.** As of 0.2, `recon`, `wire`, and `certify` classify `.py`, `.js`, `.mjs`, `.cjs`, `.jsx`, `.ts`, and `.tsx`. The runtime-import smoke check (the +25 score component for "package actually loads in a fresh subprocess") and the behavioural pytest gate remain Python-only — JS/TS packages are scored on documentation, tests-present, tier layout, and upward-import discipline. The JS parser is regex + brace-walking, not a real AST; it handles the surface (imports, exports, class signals, Worker default-`{ fetch, scheduled }` shape) the tier law cares about.

2. **Building material, not shipping software.** `forge auto` output is a **tier-organised starter skeleton**, not a deployable app. Every `--apply` emits `STATUS.md` listing required follow-up:
   - Integration tests against real inputs
   - Runtime configuration (secrets, env vars, DB URLs)
   - Observability (logging, metrics, tracing)
   - Cross-symbol reconciliation (two `User` classes need unification, not duplication)

3. **Tier classification is heuristic.** Forge uses word-boundary tokens + body-state detection (mutable instance variables in Python; class declarations + module-level `let`/`var` in JS). The scout report logs the rationale per symbol so you can override misclassifications via `--override-tier`.

4. **No semantic merge.** Two `class User` from different repos don't auto-unify. Forge detects the collision via `--on-conflict` (rename | first | last | fail) and reports it. **You** decide how to reconcile.

5. **Auto-generated adapters are scaffolding.** The `synergy` pipeline emits adapters marked with `# REVIEW:` blocks. Read them. Refine them. They're templates, not production code.

6. **Certificates are locally signed only.** Ed25519 signing via `forge certify --local-sign` is available (requires `pip install cryptography`). Chain-of-custody / notarization infrastructure is a future milestone.

## Design philosophy

- **Absorb-first, generate-never.** Forge never writes code from scratch. It absorbs and reorganises code that already exists — including AI-generated code.

- **Dry-run by default.** No verb writes to disk without `--apply` or equivalent. Only `.atomadic-forge/` manifests (diagnostic reports) are written in dry-run mode.

- **The 5-tier law is non-negotiable.** Anything that ships with Forge passes its own `wire` scan. Forge's 53 source files live in a0–a4; it eats its own dogfood.

- **Honest output.** Every report includes `schema_version`. Every apply emits `STATUS.md` (required follow-up). Every artifact is provable and traced (lineage recorded in `.atomadic-forge/lineage.jsonl`).

- **Composability, not coupling.** Forge outputs JSON manifests at each stage (scout, cherry, assimilate, wire, certify). Pipe them. Script them. Build on them.

## Atomadic family

| Product | What it is | Status |
|---------|------------|--------|
| **AAAA-Nexus** | Trust/safety/payments substrate for autonomous agents | Live at [atomadic.tech](https://atomadic.tech) |
| **Atomadic Forge** | Absorb-and-emerge engine for developers (this repo) | **v0.14.0** — on PyPI, 1177 tests, 100/100, MCP server (63 tools local · 40 on Worker), four-agent hive primitives, AAAA-Nexus bridge, agent-to-agent handoffs |
| **Atomadic Assistant** | Sovereign AI assistant with cognitive loop on Cloudflare | In development |

## Pricing

Free for OSS / non-commercial. Paid hosted MCP at `forge.atomadic.tech/mcp` for
production agents.

| Tier | Monthly | What you get |
|---|---|---|
| **Free** | $0 | OSS, 25 calls/day, read-only tools |
| **Basic** | $19 | All 22 tools, 5k calls/mo, signed receipts |
| **Dev** | $39 | + custom recipes, 25k calls/mo, priority queue |
| **Pro** | $99/user | + compliance attestations, AAAA-Nexus notarization, cross-repo telemetry |
| **Enterprise** | from $2.5k | BSL commercial license, SSO, self-host, SLA |

**👑 Atomadic Lifetime Founder — $999 — first 25 only.** One key. Forever. Lifetime
Forge Standard Pro + Forge Deluxe (when launched) + AAAA-Nexus + every future
Atomadic product. See [forge.atomadic.tech/pricing](https://forge.atomadic.tech/pricing).

Pay-per-call (x402) and prepaid call packs ($25 / $100 / $500 / $2,500) are also
available on the hosted MCP.

## License

[Business Source License 1.1](LICENSE). Free for non-production use.
Commercial license required for production — see
[COMMERCIAL_LICENSE.md](COMMERCIAL_LICENSE.md). Change Date: 2030-04-27 →
Apache 2.0.

## Documentation

- **[Showcase](docs/SHOWCASE.md)** — Live runs with live results (start here)
- **[Landscape](docs/LANDSCAPE.md)** — How Forge sits next to Cursor / Devin / Lovable / Copilot Workspace
- **[Why now](docs/WHY_NOW.md)** — The urgency case for an architecture substrate
- **[Commands](docs/COMMANDS.md)** — Full reference for all 13+ verbs
- **[Release checklist](docs/RELEASE_CHECKLIST.md)** — Shippability gates, CLI scenarios, local-model smoke checks
- **[Roadmap](docs/ROADMAP.md)** — 0.2 / 0.3 / 1.0 milestones
- **[Architecture guide](ARCHITECTURE.md)** — How Forge itself is built (monadic tiers, data flows, design)
- **[Security policy](SECURITY.md)** — Private vulnerability reporting and secret-handling expectations
- **[Tutorials](docs/tutorials/)** — Quickstart, your-first-package, the 5-tier law, plug-in-LLMs, multi-repo absorb
- **[Contributing guide](CONTRIBUTING.md)** — How to extend Forge
- **[Changelog](CHANGELOG.md)** — Version history and roadmap

## For developers

**Forge itself is monadic.** Every source file belongs to one tier. The repo is a worked example:

```bash
python -m pytest                     # 1177 passed, 2 skipped
forge doctor                         # Environment check
forge wire src/atomadic_forge        # Scan for violations (PASS)
forge certify . --fail-under 100     # Score and gate the repo (100/100)
forge status .                       # Quick health snapshot
forge commandsmith smoke             # Smoke-test all 63 registered verbs
```

**Before submitting a PR:**
1. Run the test suite — must pass
2. Run `ruff check src/ tests/` — code style check
3. Run `forge wire src/atomadic_forge` — import discipline
4. Update CHANGELOG.md

## Status

**Production-ready for architecture enforcement. Working, honest, self-eating.**

- ✓ **1176 tests** passing, 2 skipped
- ✓ **100/100 certify** — forge scores itself on every CI run
- ✓ **0 wire violations** — forge passes its own import-law scan
- ✓ **On PyPI** — `pip install atomadic-forge` (latest: v0.14.0)
- ✓ **MCP server** — 63-tool surface (40 on the deployed Worker at `forge.atomadic.tech/mcp`, 63 in the local CLI / pip install); works with Cursor, Claude Code, Aider, Devin
- ✓ **Hive primitives** — `hive_register / observe / propose / vote / result / list / deactivate / watch / needs-vote / recap` for multi-agent consensus over append-only public artifacts
- ✓ **AAAA-Nexus bridge** — 7 LIVE primitives wired as MCP tools (`nexus_identity_verify`, `nexus_federation_mint`, `nexus_authorize_action`, `nexus_sys_trust_gate`, `nexus_contract_verify`, `nexus_lineage_record`, `nexus_ratchet_register`); wisdom + consensus auto-mirror at confidence ≥ 0.85
- ✓ **Multi-agent safeguards** — `cost_circuit_breaker`, `dedup_engine`, `agent_hire_protocol`, `hierarchical_memory` (MemGPT 4-tier)
- ✓ **8 LLM providers** — auto, AAAA-Nexus, Anthropic, Gemini, OpenAI, OpenRouter, **Ling-2.6-1T (free 1T-param frontier)**, Ollama (local)
- ✓ **Ed25519 signing** — `forge certify --local-sign`
- ✓ **CycloneDX SBOM** — `forge sbom`
- ✓ **Compliance mappings** — EU AI Act · NIST SR 11-7 · FDA PCCP · CMMC-AI
- ✓ **Polyglot** — Python + JavaScript + TypeScript, same 5-tier law
- ✗ Desktop GUI — moved to its own repo (atomadic-forge-tauri-studio)
- ✗ VS Code extension — moved to its own repo (atomadic-forge-vscode-ext)
- ✗ Cloudflare badge Worker — moved to its own repo (atomadic-forge-cloudflare-workers)
- ✗ Chain-of-custody notarization (future)
- ✗ Rust / Go tier classification (roadmap)

---

💰 **Interested in investing?** [invest.atomadic.tech](https://invest.atomadic.tech) — learn about the Atomadic Technologies ecosystem.
