29 added, 1 removed. Audit A to A.
# Forge repository guidance
## Overview
Forge is a local-first, model-agnostic AI coding harness and CLI implemented as a Rust Cargo workspace. One session core serves terminal, headless, remote web, mobile, and desktop surfaces; Model Mesh routes provider work, Store persists the audit trail, and Lattice provides local code intelligence.
## Verified checks
Run these from the repository root:
```bash
cargo fmt --all -- --check
cargo clippy --locked --all-targets --all-features
- cargo test --locked --all --all-features
+ FORGE_DB="$(mktemp -d)/forge.db" cargo test --locked --all --all-features
cargo build --release --locked --bin forge
```
+ `FORGE_DB` on the test command is not optional — see **Never let a dev build touch the real
+ store** below. A handful of tests open the default store when it is unset, and doing so has taken
+ the user's daemon down four times.
+
The first command was verified during setup. The remaining commands are the repository's documented workspace checks in `CONTRIBUTING.md`; CI runs the same checks with `RUSTFLAGS=-D warnings`. The workspace uses the stable Rust toolchain with `rustfmt` and `clippy` components, and requires Rust 1.88 or newer.
## Architecture
- `crates/` is the Cargo workspace and modular monolith. `forge-cli` is the binary/composition root; `forge-core` owns the session/agent loop and permission broker.
- `forge-types` holds shared domain types; `forge-config` handles layered configuration and secrets; `forge-store` encapsulates SQLite persistence.
- `forge-provider` abstracts model providers; `forge-mesh` performs task routing and failover; `forge-tools` owns coding tools; `forge-lsp` supplies live diagnostics; `forge-mcp` integrates MCP.
- `forge-tui` renders terminal interactions through presenter adapters. Keep the session core's Interaction interface surface-independent.
- `forge-index` implements Lattice code intelligence. Architecture decisions are recorded in `docs/architecture/decisions/`; substantial design changes should add an ADR or RFC.
+
+ ## Never let a dev build touch the real store
+
+ The single most damaging recurring failure in this repository, four times so far
+ (2026-07-17, twice on 2026-08-06, 2026-08-07). A binary built from a working tree opens
+ `~/.local/share/forge/forge.db` and runs whatever migrations the checked-out branch carries. The
+ installed release binary then refuses that store — `SchemaTooNew`, which is correct — and
+ `forge serve` cannot start. The last occurrence left the daemon at 632 consecutive failed restarts
+ with Forge Anywhere dark throughout, and recovery needs a hand-written `PRAGMA user_version` write.
+
+ Rules:
+
+ - **Tests**: always pass `FORGE_DB` pointing somewhere disposable. Never run the suite bare.
+ - **MCP server entries** pointing at `target/debug/forge` (this repo's own `.mcp.json` and the
+ untracked `.forge/mcp.toml`) must set `FORGE_DB` to a dev store. An agent session started on a
+ feature branch is otherwise enough to migrate production data.
+ - **Anything that spawns a child** which may reach a `forge` binary must scrub `FORGE_DB` from the
+ child's environment unless the child genuinely shares this store — `claude --print` loads the
+ project's `.mcp.json` and can spawn a `forge` grandchild that inherits it.
+ - Deliberately debugging against real data is fine — set `FORGE_DB` explicitly and know why.
+
+ Prevention lives in the code too: a `debug_assertions` build resolves to `forge-dev.db` rather
+ than the release store, so `cargo run` and `target/debug/forge` are isolated by default. Treat that
+ as a backstop, not a reason to drop the rules above — a release-profile build ignores it.
## Conventions
- Keep changes focused and explicit; comments should explain why rather than restate code.
- Add or update tests for new behavior and regressions where practical.
- Route side effects through the permission broker and keep SQLite access inside Store.
- Use branch names `feat/<slug>`, `fix/<slug>`, `refactor/<slug>`, `docs/<slug>`, `chore/<slug>`, `ci/<slug>`, or `perf/<slug>`.
- Use Conventional Commits (`feat:`, `fix:`, `refactor:`, `docs:`, `chore:`, `test:`, `perf:`, `ci:`).
- Do not edit generated or unrelated files. Before submitting, run the applicable formatting, lint, test, and build checks above.