diff --git a/ACCESSIBILITY.md b/ACCESSIBILITY.md index d7422fe..67130ad 100644 --- a/ACCESSIBILITY.md +++ b/ACCESSIBILITY.md @@ -1,21 +1,50 @@ # Accessibility -forgekit is a terminal tool plus docs and optional generated UI. Accessibility here means -the CLI output, the docs, and anything it generates are usable by everyone. - -## What we do -- **CLI output never relies on color alone** — status is shown by symbol *and* word - (`✓ ok`, `! warn`, `✗ fail`, `PASS`, `BLOCKED`), so it reads on monochrome terminals - and to screen readers. -- **Docs** use semantic Markdown: headings in order, real lists/tables, descriptive link - text, and alt text on badges. -- **Generated UI** (the `taste` design directions and any landing page) targets **WCAG 2.1 - AA**: sufficient contrast, visible keyboard focus, and `prefers-reduced-motion` support. - The `corporate` taste is the AA-first default. +forgekit is one brain for every AI coding agent — mostly a terminal tool, plus a few web +surfaces. This page says, honestly, what we check and what we don't. Where a claim is +machine-enforced we say so; where it isn't, we don't dress it up as conformance. + +## The surfaces + +forgekit has three places a person actually looks at output: + +- **CLI output** — every `forge` command. Plain text. +- **`forge dash`** — a localhost-only, read-only web dashboard over the ledger, metrics, and + blast radius (default port 4242; never exposed off `localhost`). +- **The public pages** — the landing page and the generated status page shipped to GitHub + Pages. + +## What we actually check + +- **CLI output never relies on color alone.** Status is carried by symbol *and* word + (`✓ ok`, `! warn`, `✗ fail`, `PASS`, `BLOCKED`), so it reads on a monochrome terminal and + through a screen reader. Color is decoration, not information. +- **The public pages are gated in CI by `forge uicheck`.** Three checks run before a page + ships: `uicheck contrast` (WCAG contrast ratios on the text/background token pairs), + `uicheck fingerprint`/`design` (the design system stays on one 8-color / 4px scale), and + `uicheck visual` (a Playwright rendered gate — the page is loaded in a real browser and the + render is checked). A page that regresses contrast does not merge. +- **The pages are reduced-motion-safe by construction.** The only motion is a scroll-reveal + effect, and it is *progressive enhancement*: it's JavaScript-gated, so with JS off — or for a + crawler, or a reader that ignores it — the full content is present and static. Nothing is + hidden behind an animation. +- **Docs use semantic Markdown:** headings in order, real lists and tables, descriptive link + text, and alt text on images and badges. + +## What we don't claim + +We do **not** claim a formal WCAG 2.1/2.2 AA conformance level across every surface — we +haven't run a full audit, and we'd rather under-promise. What's above is what the gates +actually enforce. Contrast is measured; keyboard and screen-reader traversal of the dashboard +is not yet part of the automated gate. Treat any gap as a bug, not a design choice. ## Reporting an accessibility issue -Open an issue with the `accessibility` label, or start a Discussion. We treat accessibility + +Open an issue with the `accessibility` label, or start a +[Discussion](https://github.com/CodeWithJuber/forgekit/discussions). We treat accessibility bugs as regular bugs, not nice-to-haves. ## Known gaps -A few CLI glyphs assume a UTF-8 terminal; ASCII fallbacks are welcome PRs. + +- A few CLI glyphs assume a UTF-8 terminal; ASCII fallbacks are welcome PRs. +- The `forge dash` dashboard has not been through a full keyboard / screen-reader audit. diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 72ae644..b063c92 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -1,18 +1,26 @@ -# Forge — architecture +# forgekit — architecture -> Cross-tool configuration layer for agentic AI coding assistants. One source of -> truth, emitted natively into every tool; a small set of *enforced* guards; a -> lean discipline; a code-graph (`atlas`); cross-session memory (`recall`); and a -> token-budget cost governor. Install as a Claude Code plugin, from public npm -> (`@codewithjuber/forgekit`), or from source. Near-zero learning curve. +> **One brain for every AI coding agent.** A large language model is stateless: one +> context window, wiped every call. It has no memory of what your team learned, no +> foresight about what an edit will break, and no enforced guardrails. forgekit is the +> **cognitive substrate** — the layer that runs *before* the model edits code, supplying +> proof-carrying memory, impact foresight, and enforced guardrails — and a **cross-tool +> config compiler** that delivers that brain as native config into every tool at once. -Grounded in a verified multi-source research pass (Reddit/HN/dev.to, GitHub issue -trackers, official vendor docs). Evidence + config-format verdicts in the appendix. +This document is the architecture reference. It is organized around four diagrams: -The cognitive-substrate paper bundle is committed under -[`docs/cognitive-substrate/`](docs/cognitive-substrate/). It includes the full PDF/HTML -paper, deliverable overview, evidence map, ecosystem map, and the original prototype -packages; the production runtime remains Node-only and zero-dependency. +1. the four-layer config compiler (one source → native configs), +2. the pre-action gate pipeline (`forge substrate`), +3. the proof-carrying-memory ledger and team merge, +4. the reuse / context loop. + +The runtime is **zero-dependency Node**. The code graph is `.forge/atlas.json` — plain +JSON, not a database. The ledger is a directory of content-addressed claims under +`.forge/ledger/`, committable to git. Optional tiers (`FORGE_EMBED` embeddings, +Playwright for `uicheck visual`) are opt-in and add no required dependencies. + +Every command referenced below is real and wired in `src/cli.js`. Run `forge --help` +for the full list. ## Locked decisions - **Brand = `Forge`** — CLI `forge`; layer names: skills→**tools**, agents→**crew**, @@ -20,73 +28,160 @@ packages; the production runtime remains Node-only and zero-dependency. Brand stored as **one token** (`brand.json` → `FORGE_BRAND`); rebrand = 1 edit. - **Distributable id = `forgekit`** (npm package + marketplace id) — fixed even if the brand token changes, so a rename never breaks install. -- **Scope = full multi-tool day 1** (Claude Code, Codex, Cursor, Gemini, Aider, - Copilot, Windsurf/Devin, Zed) via one canonical `AGENTS.md` source. +- **Scope = full multi-tool day 1** — nine tools plus MCP, from one canonical source. - **Install = all three channels** (plugin + hardened installer + npm CLI), all three pointing at the *same* tree ("one tree, three front doors"). -- **Replace Ponytail + Graphify with our own** — as *thin layers over proven - primitives*, not from-scratch reimplementations (reuse-first). +- **Own `lean` + `atlas`** — as *thin layers over proven primitives*, not + from-scratch reimplementations (reuse-first). -## The pains Forge answers (evidence-backed) +## 1. A four-layer config compiler with ONE source -| # | Pain | Evidence | Forge's answer | -|---|------|----------|----------------| -| 1 | **Rules files acknowledged then ignored** (worse after compaction) | 10+ claude-code issues (#15443, #17530, #19635, #21112, #46724…), Cursor #2572; Cursor ignores rules ~1/3 of the time | Move enforceable invariants **out of prose into guards** (deterministic hooks the model can't drift from); keep prose rules short + single-sourced | -| 2 | **Token/cost blowups** (20–40k fixed overhead, loop/cache explosions) | claude-code #4095 (1.67B tokens/5h, est. $16k–50k, loop+recursive-hook root cause) | `cost` governor: statusline meter + budget guard with **re-entrancy locks**; every guard idempotent, single-shot | -| 3 | **Goldfish memory across sessions**; lossy compaction | claude-code #14227; "lost my 4-hour session" posts; 729-upvote demand thread | `recall`: file-based store (1 fact/file) + SessionStart load guard + Haiku consolidation crew; secrets refused | -| 4 | **Trust/verification gap** — polished code, nonexistent APIs | arXiv 2603.27249 (42% AI-authored, 96% don't fully trust, 48% review) *[secondhand]* | Shift leverage to verification: `crew` verifiers + `atlas` flags calls to symbols not in the graph. **Boundary: reduces review burden, does not certify correctness** | -| 5 | **Permission-prompt fatigue** | Cursor forum #46908/#67491; Claude permissions docs | Sane read-only allowlist out of the box (git status/diff, ls/cat/rg, test/lint/build); push/commit/merge stay on `ask`. No `--dangerously-skip` | -| 6 | **No single context file works across tools** | AGENTS.md is de-facto standard (LF AAIF, Dec 2025) but Claude reads only CLAUDE.md, Gemini only GEMINI.md | The **emitter**: author once in `AGENTS.md`, generate each tool's native target | -| 7 | **Skill/plugin loading fragile** (marketplace dup inflates skill count ~19×; hooks silently die) | claude-code #14549 (3,218 reported vs 169 real); hook fragility cluster (#10450, #16326, #46808…) | `forge doctor` health command (chezmoi-doctor pattern); Forge keeps its own footprint minimal + de-duped | -| 8 | **Onboarding is a research project** across fragmented marketplaces | best-in-class survey (awesome-claude-code, chezmoi, create-t3-app) | `forge init` one-command bootstrap + a "Start-Here" indexed catalog with one-line *why* + freshness | - -## Architecture — a four-layer config compiler with ONE source +You author the substrate once. `forge sync` compiles that source into each tool's +native config. The four layers are how the brain is expressed; the compiler is how it +is delivered. ```mermaid +%%{init: {'theme':'base','themeVariables':{'primaryColor':'#201a15','primaryTextColor':'#f2ede7','primaryBorderColor':'#372c22','lineColor':'#f26430','secondaryColor':'#272019','tertiaryColor':'#171310','fontFamily':'ui-sans-serif, system-ui, sans-serif'}}}%% flowchart TD - S["source/ — rules.json · substrate.json · mcp.json"] -->|"forge sync: content-hash + DO-NOT-EDIT headers"| N["native configs: CLAUDE.md · AGENTS.md · .cursor · .gemini · .aider · …"] - subgraph L4["the four layers"] - T["tools — model-invoked skills"] - C["crew — sub-agents"] - G["guards — enforced hooks"] - M["mcp — atlas · substrate tools"] + S["source/
rules.json · substrate.json · mcp.json"] -->|"forge sync
content-hash + DO-NOT-EDIT headers"| N["native configs
CLAUDE.md · AGENTS.md · .cursor · .gemini · .aider · …"] + S -. configures .-> L + subgraph L["the four layers"] + direction LR + T["tools
model-invoked skills"] + C["crew
isolated sub-agents"] + G["guards (enforced)
deterministic hooks"] + M["mcp
atlas + substrate server"] end - S -. configures .-> L4 - K["cortex lessons · recall facts · reuse artifacts
design fingerprints · diagnoses"] --> LG[("PCM ledger — .forge/ledger/
content-addressed claims")] - O["independent oracles
tests · CI · human accept/revert"] -->|"move val"| LG + K["local events
cortex · recall · reuse · diagnose"] --> LG[("PCM ledger
.forge/ledger/")] + O["independent oracles
tests · CI · human accept/revert"] -->|"move confidence"| LG LG <-->|"git union-merge, conflict-free"| TM["teammate ledgers"] + classDef accent fill:#f26430,stroke:#f26430,color:#171310; + class G accent; ``` -Layers map onto the Claude Code substrate, brand-named, and are emitted cross-tool: +The four layers, brand-named and emitted cross-tool: - **tools** (`~/.forge/tools/` → `~/.claude/skills/`) — model-invoked capabilities. -- **crew** (`~/.forge/crew/` → `~/.claude/agents/`) — sub-agents (scout/verifier/frontend-verifier). +- **crew** (`~/.forge/crew/` → `~/.claude/agents/`) — isolated sub-agents + (scout / verifier / frontend-verifier). - **guards** (`~/.forge/guards/` → `settings.json` hooks) — **the only layer that - *enforces* rather than suggests.** This is the direct answer to pain #1: a guard - can't be "forgotten" the way CLAUDE.md prose drifts. -- **mcp** — unchanged (it's a protocol). Forge ships `atlas` (+ optional `recall` query). - -Cross-cutting: **atlas** (code-graph), **lean** (shipped as *both* a tool and a -Stop-guard, so it works whether or not the model invokes it), **recall** (memory). - -**cognitive substrate** (`forge substrate`, `forge impact`, and MCP tools -`substrate_check` / `predict_impact` / `assumption_gate`) composes atlas, preflight, -route, scope, cortex, and verify into one pre-action contract before mutating work. - -**PCM ledger** (`.forge/ledger/`; decision recorded in -[`docs/adr/0006-proof-carrying-memory.md`](docs/adr/0006-proof-carrying-memory.md)) — -the convergent store all memory subsystems write to. Every stored unit (cortex lesson, -`recall`/`brain` fact, reuse artifact, design fingerprint, doom-loop diagnosis) is a -content-addressed *claim*: claim bytes are a pure function of (kind, body, scope) — -byte-identical on every replica — evidence and tombstones are append-only hash-deduped -logs, and confidence (`val`) is a decayed Beta posterior moved only by independent -oracles (tests, CI, human accept/revert). Merge is a join-semilattice (property-tested: -commutative, associative, idempotent), so teammate ledgers converge in any order over -plain git — `forge init` emits the union-merge `.gitattributes` rule; `forge ledger -merge` folds in any other ledger tree. The legacy stores (`lessons/`, `recall`, `brain`) -remain the read path; the ledger is where their events converge. Surface: `forge ledger -stats | verify | show | blame | query | merge | import` (`--personal` for the -per-user ledger beside the global recall store). + *enforces* rather than suggests.** A guard is a deterministic hook the model cannot + drift from. Prose rules in CLAUDE.md get acknowledged and then forgotten after + compaction; a guard does not. Every enforceable invariant belongs here. +- **mcp** — the protocol layer. Forge ships the `atlas` code-graph server and the + substrate tools (`substrate_check` / `predict_impact` / `assumption_gate`). + +Cross-cutting concerns thread through all four: **atlas** (the code graph), **lean** +(minimalism — shipped as *both* a tool and a Stop-guard, so it applies whether or not +the model invokes it), and **recall** (memory). + +## 2. The pre-action gate — `forge substrate` + +**cognitive substrate** — the layer that runs *before* the model edits code. `forge +substrate ""` (and the MCP tool `substrate_check`) runs one ordered pass of +checks and returns a single verdict. It composes the individually-callable stages +(`preflight`, `route`, `atlas`, `impact`, `reuse`, `context`, `scope`, `lean`, +`anchor`, `verify`) into one pre-action contract. + +```mermaid +%%{init: {'theme':'base','themeVariables':{'primaryColor':'#201a15','primaryTextColor':'#f2ede7','primaryBorderColor':'#372c22','lineColor':'#f26430','secondaryColor':'#272019','tertiaryColor':'#171310','fontFamily':'ui-sans-serif, system-ui, sans-serif'}}}%% +flowchart LR + RE["referenced
entities"] --> PF["preflight
assumption gap"] + PF --> RT["route
cheapest tier"] + RT --> AT["atlas
code graph"] + AT --> IM["impact
blast radius"] + IM --> PT["predict
failing tests"] + PT --> RU["reuse
cache hit?"] + RU --> CX["context
completeness gate"] + CX --> SC["scope
coupled files"] + SC --> ME["memory
recall + lessons"] + ME --> MN["minimality
lean footprint"] + MN --> GA["goal-anchor
drift check"] + GA --> VD["verdict"] + classDef accent fill:#f26430,stroke:#f26430,color:#171310; + class VD accent; +``` + +**blast radius** — the set of files an edit is predicted to impact, read from the code +graph. `forge impact` computes it; the pipeline surfaces it before the model touches +anything. + +The verdict is **advisory by default** — it reports, it does not block. Set +`FORGE_ENFORCE=1` to turn the strongest signals into a hard block: + +- a **vacuous or underspecified** prompt (preflight finds no actionable intent), +- **un-assemblable required context** (the completeness gate cannot cover the edit set), +- a **blast radius over threshold** (default ~25 files). + +Everything else stays a warning the human can override. + +## 3. Proof-carrying memory — the ledger + team merge + +**proof-carrying memory (PCM)** — every stored fact, lesson, or reuse artifact is a +*claim* that carries its own evidence. It is trusted only once independent oracles +(tests, CI, a human accept/revert) raise its confidence above a floor. A wrong lesson +decays out instead of ossifying. + +All memory subsystems converge on one store. `recall`, `remember`/`brain`, `cortex` +lessons, `reuse` artifacts, and doom-loop `diagnose` results all write content-addressed +claims into `.forge/ledger/`. Because a claim's bytes are a pure function of +`(kind, body, scope)`, every replica computes the same identity — so teammate ledgers +fold together over plain git with no conflicts. + +```mermaid +%%{init: {'theme':'base','themeVariables':{'primaryColor':'#201a15','primaryTextColor':'#f2ede7','primaryBorderColor':'#372c22','lineColor':'#f26430','secondaryColor':'#272019','tertiaryColor':'#171310','fontFamily':'ui-sans-serif, system-ui, sans-serif'}}}%% +flowchart LR + subgraph EV["local events"] + direction TB + E1["recall / remember"] + E2["cortex lesson"] + E3["reuse mint"] + E4["diagnose"] + end + EV -->|"content-addressed claims"| LG[(".forge/ledger")] + O["independent oracles
tests · CI · human accept/revert"] -->|"append evidence
move confidence"| LG + TM["teammate ledgers"] <-->|"git union-merge
conflict-free"| LG + LG --> RV["merged read view
recall list · lesson inject · brain index"] + classDef accent fill:#f26430,stroke:#f26430,color:#171310; + class LG accent; +``` + +Mechanically: evidence and tombstones are append-only, hash-deduped logs; confidence +(`val`) is a decayed Beta posterior moved only by oracles; merge is a join-semilattice +(property-tested: commutative, associative, idempotent), so ledgers converge in any +order. `forge init` emits the union-merge `.gitattributes` rule; `forge ledger merge` +folds in any other ledger tree. The legacy stores remain the read path — the ledger is +where their events converge. Surface: `forge ledger stats | verify | show | blame | +query | ratify | retract | merge | import` (`--personal` for the per-user ledger). +Decision recorded in +[`docs/adr/0006-proof-carrying-memory.md`](docs/adr/0006-proof-carrying-memory.md). + +## 4. The reuse / context loop + +`forge reuse` is a proof-carrying code cache. A generated artifact is only served again +when its evidence still holds — the confidence is above the floor *and* its atlas +dependencies still resolve. Otherwise it falls through to generation and mints a fresh +claim on the way back. + +```mermaid +%%{init: {'theme':'base','themeVariables':{'primaryColor':'#201a15','primaryTextColor':'#f2ede7','primaryBorderColor':'#372c22','lineColor':'#f26430','secondaryColor':'#272019','tertiaryColor':'#171310','fontFamily':'ui-sans-serif, system-ui, sans-serif'}}}%% +flowchart LR + SP["spec"] --> FP["fingerprint
MinHash + LSH"] + FP --> LD["match ladder
exact → near → adapt → miss"] + LD --> GT{"confidence ≥ floor
AND deps resolve?"} + GT -->|"yes"| SV["serve (proof holds)"] + GT -->|"miss"| GN["generate"] + GN -->|"mint claim"| MT[(".forge/ledger")] + MT -.->|"available next time"| FP + classDef accent fill:#f26430,stroke:#f26430,color:#171310; + class SV accent; +``` + +The completeness gate on the retrieval side is `forge context ""`: it assembles a +budgeted context via set-cover over the predicted edit set (`R(edit)`), applies a +compression ladder, and reports the *computed missing set* — the inputs it could not +assemble. That missing set is exactly what the substrate pipeline's context stage reads +to decide whether an edit is safe to start. Surface: `forge reuse query | mint | stats`. ## Component map — the reuse ledger (30 components) @@ -98,49 +193,51 @@ session-learner` (guards) · `statusline` · `tech-currency · stack-notes · self-correction` (rules) · project-layer template. **Own-branded replacements (thin layer over proven primitive):** -- **`lean`** — *replaces Ponytail.* A model-invoked **tool** (YAGNI ladder, - reuse-before-build, shortest-diff) **+** a deterministic **`lean-guard`** Stop-hook - that nudges on oversized diffs. No plugin, no engine. -- **`atlas`** — *replaces Graphify.* Built on **serena/LSP** (already installed) + - tree-sitter fallback; see resolution below. +- **`lean`** — a model-invoked **tool** (YAGNI ladder, reuse-before-build, + shortest-diff) **+** a deterministic **`lean-guard`** Stop-hook that nudges on + oversized diffs. No plugin, no engine. +- **`atlas`** — a plain-JSON code graph built and read by Forge itself. No external + graph engine, no language server, no database. **Net-new (justified by a pain):** -- **`forge sync`** (emitter, pain #6) · **`forge doctor`** (health, pain #7) · - **`forge init`** (bootstrap, pain #8) · **`cost-budget` guard** (pain #2) · - **Start-Here catalog** (pain #8) · **`recall`** unified subsystem (pain #3, from - memory-keeper + memory-load + learn-consolidate). - -## `atlas` resolution (dedicated tech-selector) -Build on **serena (LSP), already installed** — not a new graph engine. tree-sitter -only as the AST/chunking fallback for files with no language server. -- `forge atlas build [path]` → LSP symbol/ref queries → **portable artifact** - `.forge/atlas.db` (SQLite) or `.forge/atlas.json`. -- `forge atlas query "what calls Z"` → reads the artifact directly (few hundred - tokens vs. reading 5 files). `forge atlas update [files]` → incremental. -- **Cross-tool by design:** Codex/Cursor/Gemini/Aider read the artifact via the CLI - or plain `jq`/SQLite — **no MCP dependency to consume**. MCP server is optional, - lazy-started, for Claude convenience only. -- Rejected: stack-graphs (GitHub *archived* 2025-09-09), SCIP (near-zero adoption), - embeddings (answers "similar" not "what calls Z"), ctags/ripgrep-as-index (no - semantic resolution), cloning Graphify's tree-sitter+NetworkX internals. +- **`forge sync`** (the cross-tool emitter) · **`forge doctor`** (health check) · + **`forge init`** (one-command bootstrap) · **`cost-budget` guard** · + **Start-Here catalog** · **`recall`** unified memory subsystem. + +## `atlas` — the code graph + +`forge atlas build [path]` walks the tree and writes a **portable JSON artifact**, +`.forge/atlas.json`. It is plain JSON on purpose: any tool can read it. + +- `forge atlas query "what calls Z"` reads the artifact directly — a few hundred tokens + instead of reading five files. +- `forge atlas has ` is the hallucinated-symbol check: if the model calls a + symbol that is not in the graph, the gate flags it. +- **Cross-tool by design:** Codex / Cursor / Gemini / Aider read `.forge/atlas.json` + via the CLI or plain `jq` — **no MCP dependency to consume.** The MCP server is + optional, lazy-started, for Claude convenience only. + +`atlas.json` is the single source the impact, reuse-revalidation, and hallucination-flag +stages all read. There is no SQLite database and no `.forge/atlas.db`. ## Verified cross-tool emit matrix -*(All rows confirmed against vendor docs in the research pass.)* +*(All rows confirmed against vendor docs.)* Forge emits config for **nine tools**, plus +an **MCP server** for Roo Code and VS Code. | Tool | Native target | How Forge emits | |------|---------------|-----------------| | **Claude Code** | `CLAUDE.md` (+ `.claude/rules/*.md`, `settings.json`); **no** AGENTS.md | Thin `CLAUDE.md` whose first line is `@AGENTS.md`; guards+permissions → `settings.json` | | **Codex** | `AGENTS.md` native (32 KiB cap) | Canonical `AGENTS.md` at root **is** the source; keep < 32 KiB or it silently truncates | | **Cursor** | `AGENTS.md` + `.cursor/rules/*.mdc` (`.cursorrules` deprecated) | `AGENTS.md` for flat rules; `.mdc` when scoping/precedence needed; never leave a legacy `.cursorrules` | -| **Gemini CLI** | `GEMINI.md` by default; **AGENTS.md only via `context.fileName` opt-in** | Write `.gemini/settings.json` `context.fileName:["AGENTS.md",…]` (avoids a 2nd copy) | +| **Gemini** | `GEMINI.md` by default; **AGENTS.md only via `context.fileName` opt-in** | Write `.gemini/settings.json` `context.fileName:["AGENTS.md",…]` (avoids a 2nd copy) | | **Aider** | `CONVENTIONS.md` via `read:` in `.aider.conf.yml` | Emit `.aider.conf.yml` with `read: AGENTS.md` | -| **Copilot** | root `AGENTS.md` (since 2025-08-28) + `.github/copilot-instructions.md` | Rely on root `AGENTS.md`; optional generated `.github` pointer | -| **Windsurf/Devin** | `AGENTS.md` auto-discovered; caps 6k/12k chars; mid-rebrand to Devin | Root `AGENTS.md` under caps; detect `.windsurf` vs `.devin` at init | +| **Copilot** | root `AGENTS.md` + `.github/copilot-instructions.md` | Rely on root `AGENTS.md`; optional generated `.github` pointer | +| **Windsurf/Devin** | `AGENTS.md` auto-discovered; caps 6k/12k chars | Root `AGENTS.md` under caps; detect `.windsurf` vs `.devin` at init | | **Zed** | first match of a precedence list incl. `AGENTS.md` | Emit `AGENTS.md` + doctor flags any earlier-precedence legacy file shadowing it | | **Continue** | `.continue/rules/*.md` + `.continue/mcpServers/*.yaml` | Emit a rules file plus the Forge MCP server config | -Roo Code and VS Code receive the Forge MCP server via `forge init` (`.roo/mcp.json`, -`.vscode/mcp.json`) rather than a rules file. +Roo Code and VS Code receive the Forge MCP server via `forge init` +(`.roo/mcp.json`, `.vscode/mcp.json`) rather than a rules file. ## Repo layout — one tree, three front doors ``` @@ -173,7 +270,7 @@ forgekit/ mcp.json # MCP server definitions emitted into each tool global/ # installs into ~/.forge, symlinked into ~/.claude tools/ crew/ guards/ rules/ recall/ taste/ statusline.sh settings.template.json - templates/project-layer/ # per-repo template (was hostlelo-project-layer) + templates/project-layer/ # per-repo template .claude-plugin/ .codex-plugin/ # plugin manifests → point at global/ + skills/ (no dup beyond the codex skill mirror) install.sh # hardened: idempotent, symlink, backup, no curl|sh bin/ # back-compat shims → src/cli.js @@ -185,24 +282,32 @@ Public site deploy (two independent Pages targets, both built from `landing/` + `scripts/build-pages.mjs`): `.github/workflows/static.yml` (GitHub Pages — assembles landing + status page into one `_site/`) · `.gitlab-ci.yml` (GitLab Pages — status page only). -plugin.json, install.sh, and the npm bin **all reference `global/` + `source/`** — -no duplication; each channel just runs `forge sync` at the end. A test asserts all -three resolve to `global/`. + +The plugin manifest, `install.sh`, and the npm bin **all reference `global/` + +`source/`** — no duplication; each channel just runs `forge sync` at the end. A test +asserts all three resolve to `global/`. ## Risks & honest boundaries -- **Enforcement ceiling** — guards enforce only what's expressible as a hook (paths, +- **Enforcement ceiling** — guards enforce only what is expressible as a hook (paths, format, diff-size, budget). Semantic rules ("prefer functional") stay prose and - *will* sometimes be ignored. Forge **reduces, doesn't eliminate** pain #1. Say so. -- **No weight-level learning** — `recall`/`self-improve` are file+prompt memory only. - No RL, no fine-tuning. Consolidation is a Haiku summarizer that can hallucinate → - advisory, human-reviewable, secret-free. -- **Hook fragility is upstream** — Windows/worktree/long-session hook failures affect - Forge guards too. Mitigate with defensive path resolution + doctor; inherit the ceiling. + *will* sometimes be ignored. Forge **reduces, does not eliminate** rule drift. Say so. +- **Verification reduces, does not certify** — `crew` verifiers and the `atlas has` + hallucination flag cut review burden; they do not prove the code correct. +- **No weight-level learning** — `recall` / `self-improve` are file-and-prompt memory + only. No RL, no fine-tuning. Consolidation is a Haiku summarizer that can hallucinate + → advisory, human-reviewable, secret-free. +- **Hook fragility is upstream** — Windows / worktree / long-session hook failures + affect Forge guards too. Mitigated with defensive path resolution + `forge doctor`; + the ceiling is inherited, not removed. - **Char caps** — Codex 32 KiB, Windsurf 6k/12k, marketplace budget truncation → `forge sync` enforces a source size budget. -- **Own atlas+lean = new maintenance surface** previously outsourced. Scope atlas to - the minimum graph that powers reuse + hallucination-flag, not a code-intel product. +- **Own atlas + lean = new maintenance surface** previously outsourced. Atlas is scoped + to the minimum graph that powers reuse + hallucination-flag, not a code-intel product. - **Three channels triple drift surface** — mitigated by "one tree" + the resolve test. +- **Not shipped (exploring)** — deeper language-server / serena-style semantic + resolution and an embeddings-backed atlas were prototyped but are **not in the + runtime**. The shipped code graph is plain-JSON, tree-walk based, zero-dependency. + `FORGE_EMBED` is the only embeddings path, and it is opt-in. --- See [ROADMAP.md](ROADMAP.md) for direction and [`docs/adr/`](docs/adr/) for the recorded diff --git a/CITATION.cff b/CITATION.cff index 14fd143..cdf6fbc 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -4,11 +4,12 @@ title: "Forge (forgekit)" version: 0.6.0 date-released: "2026-07-07" abstract: >- - One config for every AI coding agent — a cross-tool configuration layer plus a - cognitive substrate that gives a frozen model the memory, blast-radius awareness, and - guardrails it structurally lacks: an independent verification gate, self-correcting - project memory, portable memory, a security-vetting skill-gate, and a cost governor, - emitted natively to Claude Code, Codex, Cursor, Gemini, Aider, and more. + One brain for every AI coding agent — the cognitive substrate every frozen model is + missing. Forge gives a stateless model the memory, blast-radius foresight, and + guardrails it structurally lacks: proof-carrying team memory, an independent + verification gate, self-correcting project memory, a security-vetting skill-gate, and a + cost governor — authored once and emitted natively to Claude Code, Codex, Cursor, + Gemini, Aider, and more. type: software authors: - name: CodeWithJuber diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5f32734..c830e6e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,8 @@ # Contributing to forgekit -Thanks for your interest. forgekit stays small and dependency-free — please read -this before opening a PR. +forgekit is one brain for every AI coding agent — a cognitive substrate (memory, foresight, +guardrails) authored once and compiled into every tool's native config. Keeping that brain +small and dependency-free is the whole point, so please read this before opening a PR. ## Ground rules @@ -9,7 +10,7 @@ this before opening a PR. PRs adding one are rejected unless there's an exceptional, discussed reason. Dev dependencies (test/lint tooling) are fine. - **Node.js ESM only.** All code is ES modules (`"type": "module"`). No CommonJS. -- **Supported Node versions:** 18, 20, 22. +- **Supported Node versions:** 20 and 22 (the `>=20` engines floor; Node 18 is EOL). - **Cross-tool first.** New behavior should work across the tools forgekit targets (Claude Code, Codex, Cursor, Gemini, Aider, …), emitted from one source — not Claude-only. Say so in the PR if a piece is unavoidably tool-specific. @@ -29,11 +30,11 @@ npm run check # Biome lint + format check 1. Branch: `git checkout -b feat/my-change`. 2. Write the change **plus tests** — every new public function needs at least one test. Shell guards are tested via `spawnSync` (see `test/guards.test.js`). -3. Run `npm test` and `npm run check:fix` before committing. +3. Run `npm test`, `npm run typecheck`, and `npm run check:fix` before committing. 4. Use [Conventional Commits](https://www.conventionalcommits.org/): `feat(scope): description`, `fix: …`, `docs: …`. 5. Add a line to `CHANGELOG.md` under `## [Unreleased]`. -6. Open a PR. CI (tests on Node 18/20/22, Biome, shellcheck) must pass. +6. Open a PR. CI (tests on Node 20/22, Biome, typecheck, shellcheck) must pass. ## Project shape diff --git a/ONBOARDING.md b/ONBOARDING.md index 0e5bd34..dc89f8e 100644 --- a/ONBOARDING.md +++ b/ONBOARDING.md @@ -1,10 +1,17 @@ # Onboarding — five minutes to productive -> **Forge** is a cross-tool config layer plus a cognitive substrate for AI coding -> agents (Claude Code, Codex, Cursor, Gemini, Aider…). Author your rules once; it -> configures every tool and adds memory, blast-radius checks, and guardrails. +**One brain for every AI coding agent.** A language model is *stateless* — one +context window, wiped every call — so it has no memory of what your team learned, no +foresight about what an edit breaks, and no enforced guardrails. forgekit is the +**cognitive substrate** that supplies exactly those three things, and it delivers them +as native config to Claude Code, Codex, Cursor, Gemini, Aider, Copilot, Windsurf, Zed, +and Continue at once. Author the brain once; every tool reads it. + +This page is the fast path: install, configure a repo, do a task, and watch the ledger +start paying off on day two. ```mermaid +%%{init: {'theme':'base','themeVariables':{'primaryColor':'#201a15','primaryTextColor':'#f2ede7','primaryBorderColor':'#372c22','lineColor':'#f26430','secondaryColor':'#272019','tertiaryColor':'#171310','fontFamily':'ui-sans-serif, system-ui, sans-serif'}}}%% flowchart TD I["forge init"] --> Cfg["every tool configured
from one source"] Cfg --> Work["you work as usual"] @@ -12,6 +19,8 @@ flowchart TD Gate --> Edit["agent edits, with guardrails"] Edit --> Learn["cortex learns from corrections"] Learn -.->|next task is smarter| Work + classDef accent fill:#f26430,stroke:#f26430,color:#171310; + class Gate accent; ``` ## 1. Install (once) @@ -34,35 +43,43 @@ Full matrix (no-registry `github:` install, symlink dev setup) → ## 2. Configure a repo (once per repo) +One config for every tool. Author your rules once; `forge init` emits each tool's +native file. + ```bash cd ~/your-project forge init # emits AGENTS.md, CLAUDE.md, .gemini/settings.json, .aider.conf.yml … ``` Now Claude Code, Codex, Cursor, Gemini, Aider, Copilot, Windsurf, Zed, and Continue all -read the **same** rules — each from its own native file (plus MCP config for Roo and VS Code). +read the **same** rules — each from its own native file (plus MCP server config for Roo +Code and VS Code). -## 3. Change a rule - -Edit `source/rules.json` (or drop a per-repo `.forge/rules.json`), then: +Change a rule later by editing `source/rules.json` (or dropping a per-repo +`.forge/rules.json`), then: ```bash forge sync # recompiles into every tool; idempotent (only rewrites what changed) ``` -## 4. Use the cognitive substrate +## 3. Use the cognitive substrate + +The substrate is the layer that runs *before* the model edits code. One command runs +the whole pre-action gate: ```bash -forge substrate "" # ask/route/impact/scope/memory/verify in one pass +forge substrate "" # ask/route/impact/scope/reuse/context/memory/verify in one pass forge substrate "" --json -forge impact +forge impact # the blast radius on its own ``` -If `forge substrate` says `ASK FIRST`, ask the returned questions before editing. Read predicted impacted files before making mutating changes. +If `forge substrate` says `ASK FIRST`, ask the returned questions before editing. Read +the predicted impacted files — the **blast radius**, the set of files an edit is +predicted to touch — before any mutating change. Paper and evidence package: [docs/cognitive-substrate/](docs/cognitive-substrate/). -## 5. Use the extras +## 4. Use the extras ```bash forge atlas build # index this repo's symbols → .forge/atlas.json @@ -73,10 +90,13 @@ forge recall list # facts the recall-load guard injects next session forge catalog # the Start-Here index of everything ``` -## 6. Day two: the ledger is learning +## 5. Day two: the ledger is learning Everything the substrate learned on day one — cortex lessons, remembered facts, -verified code — landed as claims in `.forge/ledger/`. Now it starts paying off: +verified code — landed as claims in `.forge/ledger/`. This is **proof-carrying memory +(PCM)**: every stored fact carries its own evidence and is only trusted once independent +oracles (tests, CI, a human accept/revert) raise its confidence above a floor. A wrong +lesson decays out instead of ossifying. Now it starts paying off: ```bash forge ledger stats # what the repo knows, by kind and trust level @@ -87,7 +107,8 @@ forge reuse query "" # verified code you already h A `forge reuse query` hit points at working, test-confirmed code and the `forge ledger blame` command that proves it — reuse it instead of regenerating. And after `git pull`, `forge ledger merge ` folds a teammate's ledger in -conflict-free, so their lessons arrive with their provenance intact. +conflict-free (union-merge), so their lessons arrive with their provenance intact. The +ledger is shared team memory. --- @@ -100,14 +121,14 @@ behind the mechanisms. Rules the model can drift from live in prose; rules it must **never** break live in **guards** (deterministic shell hooks). A guard can't be forgotten after context -compaction. Move every enforceable invariant out of `CLAUDE.md` and into a guard; -keep the prose thin. +compaction. Move every enforceable invariant out of `CLAUDE.md` and into a guard; keep +the prose thin. ### 2. One source, many emitters Author rules **once** (`source/rules.json`); a deterministic compiler (`forge sync`) -emits each tool's native format with a content-hash header, so drift is detectable -and re-running is a no-op. No rule is ever written twice. +emits each tool's native format with a content-hash header, so drift is detectable and +re-running is a no-op. No rule is ever written twice. ### 3. Precompute, then serve @@ -124,28 +145,26 @@ symptom. Deletion over addition. Boring over clever. (See the `lean` tool.) ### 5. Reuse over rebuild — thin layers over proven primitives -"Our own" never means "reimplement a mature tool." `atlas` leans on LSP-class -primitives; `lean` is one rule file, not a plugin engine. The smallest surface that -delivers the capability. +"Our own" never means "reimplement a mature tool." The smallest surface that delivers +the capability: `lean` is one rule file, not a plugin engine. ### 6. Verify, don't assert -Nothing is "done" without a check you can run — a test, a build exit code, a -screenshot. Show the command and its output. Fix root causes; never suppress an -error to make a check pass. +Nothing is "done" without a check you can run — a test, a build exit code, a screenshot. +Show the command and its output. Fix root causes; never suppress an error to make a +check pass. ### 7. Re-entrancy safety -No guard may loop. Every guard is idempotent, holds an atomic lock while it runs, -and the one guard that calls a model (`session-learner`) is opt-in, gated, and -single-shot. The class of bug that once burned 1.67B tokens in five hours cannot -originate here. +No guard may loop. Every guard is idempotent, holds an atomic lock while it runs, and +the one guard that calls a model (`session-learner`) is opt-in, gated, and single-shot. +The class of bug that once burned 1.67B tokens in five hours cannot originate here. ### 8. Name the ceiling -Every deliberate simplification states its limit and upgrade path, in code and in -docs. Forge would rather ship an honest subset with a clear boundary than a vague -claim — see [the honest limits](docs/GUIDE.md#honest-limits). +Every deliberate simplification states its limit and upgrade path, in code and in docs. +Forge would rather ship an honest subset with a clear boundary than a vague claim — see +[the honest limits](docs/GUIDE.md#honest-limits). --- diff --git a/README.md b/README.md index a62ad3b..1e242c2 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Forge — one config for every AI coding agent +# Forge — one brain for every AI coding agent [![CI](https://github.com/CodeWithJuber/forgekit/actions/workflows/ci.yml/badge.svg)](https://github.com/CodeWithJuber/forgekit/actions/workflows/ci.yml) [![CodeQL](https://github.com/CodeWithJuber/forgekit/actions/workflows/codeql.yml/badge.svg)](https://github.com/CodeWithJuber/forgekit/actions/workflows/codeql.yml) @@ -7,44 +7,110 @@ [![node: >=20](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](./package.json) [![runtime deps: 0](https://img.shields.io/badge/runtime%20dependencies-0-brightgreen.svg)](./package.json) -**Author your rules once — Forge emits every AI coding tool's native config -(`CLAUDE.md`, `AGENTS.md`, `.cursor/rules`, `GEMINI.md`, MCP…) and adds the one thing a -frozen model structurally lacks: a proof-carrying memory your whole team shares, plus a -pre-action check that predicts what an edit will break.** - -Works with **Claude Code, Codex, Cursor, Gemini, Aider, Copilot, Windsurf, Zed, and -Continue** (plus MCP config for Roo and VS Code). Zero runtime dependencies — one -Node CLI, plain files in git, no server. - -> **Status: beta.** The core (`init`, `sync`, `substrate`, `impact`, `ledger`, guards) -> is tested and in daily use; some flags may change before `1.0`. - -## What you get (measured, not promised) - -Every number below is a median from `npm run bench` on this repo, recorded with its -environment block in [`reports/benchmarks.md`](reports/benchmarks.md) — the project rule -is *a number is an assumption until measured*. - -- **Blast-radius analysis before the edit** — "what does changing `verifyToken` - break?" answers in **0.43 ms** (warm code-graph), including the coupled files you - didn't name. On 6 hand-labeled cases from this repo's real import graph: recall - **0.97** vs **0.33** for looking at the edited file alone. -- **A full pre-action gate in 118 ms** — assumption check, model routing, reuse lookup, - context assembly, blast radius, scope, and goal anchor in one deterministic pass, no - LLM call. On Claude Code it runs on **every prompt, automatically**. -- **Cheapest-capable model routing, visible before dispatch** — the white paper's live - prototype measured **62.1% cost saved vs always-premium** on real models (paper §9; - that's the paper's measurement, not this repo's — `forge cost --stages` reports only - *your* measured stages). -- **A minimal dry-run test suite** — `forge imagine --run` selected 8 tests covering the - predicted breaks and ran them in **1.3 s** where this repo's full suite takes ~60 s - ([CHANGELOG 0.5.0](CHANGELOG.md)). -- **Conflict-free team memory** — merging two 500-claim ledger replicas takes - **158 ms**; the merge is a property-tested join-semilattice, so teammate ledgers - converge in any order over plain git. -- **Deterministic guards** for the rules a model must never break (protected paths, cost - budget, doom loops) — hooks can't be "forgotten" after a context compaction the way - `CLAUDE.md` prose can. +

+ + + forgekit — one brain for every AI coding agent: the cognitive substrate (memory, foresight, guardrails) wraps a stateless model and ships as one config to nine AI coding tools + +

+ +Forge is one shared brain for your AI coding agents. It gives a stateless model the +three things it structurally lacks — memory, foresight, and enforced guardrails — and +delivers them into every tool you use. + +> The cognitive substrate every frozen model is missing — proof-carrying memory, impact +> foresight, and enforced guardrails — authored once and delivered as native config to +> Claude Code, Codex, Cursor, Gemini, Aider, Copilot, Windsurf, Zed, and Continue (plus +> MCP config for Roo and VS Code). + +> **Status: beta.** The core (`init`, `sync`, `substrate`, `impact`, `ledger`, guards) is +> tested and in daily use; some flags may change before `1.0`. + +## Contents + +- [The problem](#the-problem) +- [How it works — the loop](#how-it-works--the-loop) +- [What you get](#what-you-get) +- [60-second quickstart](#60-second-quickstart) +- [Commands](#commands) +- [Team memory in three commands](#team-memory-in-three-commands) +- [How it compares](#how-it-compares) +- [Honest limits](#honest-limits) +- [Why a cognitive substrate? The white paper](#why-a-cognitive-substrate-the-white-paper) +- [Public site](#public-site) · [Documentation](#documentation) · [Community & support](#community--support) + +## The problem + +A large language model is stateless — one context window, wiped every call. + +- It has **no memory** of what your team already learned. +- It has **no foresight** about what an edit will break. +- It has **no enforced guardrails** — prose rules get forgotten after a compaction. + +And every tool wants its own config file (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules`, +`GEMINI.md`, MCP…). Forge is the **cognitive substrate** — the layer that runs *before* +the model edits code, supplying memory, foresight, and guardrails — and the compiler that +delivers it into every tool from one source. + +## How it works — the loop + +Every task passes a fast, deterministic gate; every outcome flows back into a shared, +proof-carrying memory. + +```mermaid +%%{init: {'theme':'base','themeVariables':{'primaryColor':'#201a15','primaryTextColor':'#f2ede7','primaryBorderColor':'#372c22','lineColor':'#f26430','secondaryColor':'#272019','tertiaryColor':'#171310','fontFamily':'ui-sans-serif, system-ui, sans-serif'}}}%% +flowchart LR + T["task"] --> G["substrate gate
assume · route · reuse
context · impact"] + G -->|unclear| Q["ask clarifying
questions first"] + Q --> T + G -->|clear| A["agent acts"] + A --> O["oracles
tests · CI · human"] + O --> L["ledger write-back
claims + evidence"] + L --> M["team merge
plain git, conflict-free"] + M -.->|lessons and verified reuse| G + classDef accent fill:#f26430,stroke:#f26430,color:#171310; + class G accent; +``` + +Only independent oracles (tests, CI, a human accept/revert) move a memory's confidence — +so a wrong lesson decays out instead of ossifying. Full design: +[`ARCHITECTURE.md`](ARCHITECTURE.md). + +## What you get + +The day-to-day value first — the substrate gives a frozen model what it can't hold itself: + +- **Memory that persists across sessions and teammates.** Every lesson, fact, and verified + reuse is *proof-carrying memory (PCM)* — a claim that carries its own evidence and is only + trusted once independent oracles raise its confidence above a floor. Wrong lessons decay + out instead of ossifying. +- **Foresight before you break things.** Ask "what does changing `verifyToken` break?" and + get the *blast radius* — the set of files an edit is predicted to impact, read from the + code graph, including coupled files you never named. +- **Guardrails that can't be forgotten.** Deterministic hooks enforce the rules a model must + never break (protected paths, cost budget, doom loops) — they survive a context compaction + the way `CLAUDE.md` prose does not. +- **One config for 9 tools.** Author your rules once; Forge emits each tool's native config, + plus MCP for Roo and VS Code. Zero runtime dependencies — one Node CLI, plain files in git, + no server. + +### The measured evidence + +Every number is a median from `npm run bench` on this repo, recorded with its environment +block in [`reports/benchmarks.md`](reports/benchmarks.md) — the project rule is *a number is +an assumption until measured*. + +- **Blast radius in 0.43 ms** (warm code-graph). On 6 hand-labeled cases from this repo's + real import graph: recall **0.97** vs **0.33** for looking at the edited file alone. +- **A full pre-action gate in 118 ms** — assumption check, routing, reuse lookup, context + assembly, blast radius, scope, and goal anchor in one deterministic pass, no LLM call. On + Claude Code it runs on **every prompt, automatically**. +- **62.1% cost saved vs always-premium** — from the white paper's live routing prototype on + real models (paper §9; that's the paper's measurement, not this repo's — `forge cost + --stages` reports only *your* measured stages). +- **Conflict-free team memory** — merging two 500-claim ledger replicas takes **158 ms**; the + merge is a property-tested join-semilattice, so teammate ledgers converge in any order over + plain git. ## 60-second quickstart @@ -74,62 +140,52 @@ git pull && forge ledger merge On Claude Code the substrate then runs on **every prompt automatically** via a `UserPromptSubmit` hook — advisory only, silent on clean tasks. Every other tool gets a -native config rule plus MCP tools (`substrate_check`, `predict_impact`, -`assumption_gate`, `route_task`, `scope_files`) it can call itself. - -## How it works — the loop - -Every task passes a fast deterministic gate; every outcome flows back into a shared, -proof-carrying memory: - -```mermaid -flowchart LR - T["task"] --> G["substrate gate
assume · route · reuse
context · impact"] - G -->|unclear| Q["ask clarifying
questions first"] - Q --> T - G -->|clear| A["agent acts"] - A --> O["oracles
tests · CI · human"] - O --> L["ledger write-back
claims + evidence"] - L --> M["team merge
plain git, conflict-free"] - M -.->|lessons and verified reuse| G -``` - -Only independent oracles (tests, CI, a human accept/revert) move a memory's confidence — -so a wrong lesson decays out instead of ossifying. Full design: -[`ARCHITECTURE.md`](ARCHITECTURE.md). +native config rule plus MCP tools (`substrate_check`, `predict_impact`, `assumption_gate`, +`route_task`, `scope_files`) it can call itself. ## Commands +Advisory by default. Set `FORGE_ENFORCE=1` to turn the substrate into a hard block on the +strongest signals (vacuous prompt, un-assemblable required context, blast radius over the +default 25-file threshold). + | Group | Command | Does | | --- | --- | --- | -| **Config layer** (cross-tool `AGENTS.md` config) | `forge init` | emit this repo's config for every tool, one command | -| | `forge sync` | recompile `source/` → each tool's native files (idempotent) | -| | `forge doctor` | pass/fail health check (layers, install, drift, cortex) | +| **Config layer** | `forge init` | emit every tool's native config from one source | +| | `forge sync` | recompile canonical source → each tool's native files (idempotent) | +| | `forge doctor` | pass/fail health check: tools, guards, MCP, drift | +| | `forge harden` | wire gitleaks pre-commit + sandbox settings | | | `forge catalog` | Start-Here index of every tool / crew / guard | -| **Pre-action gate** | `forge substrate` | the full pre-action check in one pass | -| | `forge preflight` | assumption gate — what a task names that the repo doesn't define | -| | `forge route` | cheapest capable model for a task (+ gateway config) | -| | `forge impact` | blast radius for a symbol or file | -| | `forge imagine` | predicted breaks + the minimal dry-run test suite (`--run` executes it sandboxed) | +| | `forge brand` | print the brand token map | +| **Memory & team** | `forge ledger` | proof-carrying memory — stats / verify / show / blame / query / ratify / retract / merge / import | +| | `forge recall` | cross-session personal memory — list / add / consolidate | +| | `forge remember` | durable, repo-committable fact | +| | `forge brain` | portable project-memory index | +| | `forge cortex` | self-correcting lessons — `status` / `why` | +| | `forge reuse` | proof-carrying code cache — query / mint / stats | +| **Substrate (pre-action)** | `forge substrate` | the full pre-action gate in one pass | +| | `forge preflight` | assumption / info-gap check | +| | `forge route` | cheapest capable model tier (`route gateway` emits LiteLLM config) | +| | `forge impact` | predict blast radius for a symbol or file | +| | `forge scope` | cluster + surface coupled files | +| | `forge imagine` | consequence sim + minimal dry-run suite (`--run` executes it sandboxed) | | | `forge context` | budgeted context assembly + completeness gate | -| | `forge scope` | decompose files into independent clusters | -| | `forge anchor` | goal-drift check on your git changes | -| **Memory & team** | `forge ledger` | proof-carrying memory — stats / verify / show / blame / query / merge / import | -| | `forge cortex` | self-correcting lessons from *genuine* recurring mistakes | -| | `forge reuse` | proof-carrying code cache — served only while its proof holds | -| | `forge atlas` | build / query the code graph | -| | `forge recall` / `forge brain` | cross-session + portable project memory | -| **Quality gates** | `forge verify` | independent verification — real tests + hallucinated-symbol check | -| | `forge diagnose` | doom-loop check — 3× the same failure mints a diagnosis + escalation | -| | `forge uicheck` | deterministic UI checks — WCAG contrast · design fingerprint · slop gate | -| | `forge scan` / `forge harden` | vet a skill/MCP before install · wire secret-scan + sandbox | -| **Observability** | `forge dash` | local read-only dashboard over ledger, metrics, blast radius | +| | `forge atlas` | build / query / has (hallucinated-symbol check) the code graph | +| | `forge anchor` | goal-drift check (advisory) | +| | `forge diagnose` | doom-loop: same failure 3× → diagnosis + escalation | +| | `forge lean` | scope-minimality footprint (advisory) | | | `forge cost` | real per-day spend · measured stage factors (`--stages`) | +| **Verification & safety** | `forge verify` | independent gate — tests + hallucinated-symbol flag + provenance | +| | `forge scan` | skill-gate: vet a SKILL.md / .mcp.json for injection / RCE / exfil | +| | `forge spec` | spec-as-contract drift — init / lock / check | +| **UI / design** | `forge taste` | pick one visual direction → DESIGN.md | +| | `forge uicheck` | contrast · fingerprint · design · visual (WCAG · slop+conformance · Playwright) | +| **Observability** | `forge dash` | localhost-only read-only dashboard over ledger, metrics, blast radius (default port 4242) | **→ Every command with a worked example and real output: [`docs/GUIDE.md`](docs/GUIDE.md).** -## Team memory for AI agents, in three commands +## Team memory in three commands Everything the substrate learns — Cortex lessons, `forge remember` facts, verified reuse artifacts — lands as content-addressed claims in a git-native ledger (`.forge/ledger/`) @@ -145,10 +201,10 @@ Identical knowledge minted independently converges to **one** claim with every a preserved in its provenance; `forge ledger blame ` shows who minted it, every oracle outcome, and per-author trust. No server, no sync service — it's just files in git. -## How it compares — AI agent memory, LLM gateways, RAG +## How it compares -Structural differences only — each row is checkable against the named source, and the -full tables (including what each adjacent tool does *better*) are in +Structural differences only — each row is checkable against the named source, and the full +tables (including what each adjacent tool does *better*) are in [`reports/benchmarks.md` → Uniqueness](reports/benchmarks.md#uniqueness--structural-contrasts-with-adjacent-tools): | Property | Forge | Note stores / gateways / RAG | @@ -162,41 +218,49 @@ full tables (including what each adjacent tool does *better*) are in ## Honest limits -Forge states its own ceiling everywhere. In short: **guards reduce, don't eliminate** -the "ignored my rules" problem; `recall`/`cortex` are file memory, **not** weight-level -learning; the `atlas`/`impact` graph is regex-approximate (conservative, not a sound -call graph — the impact numbers above are n = 6 hand-labeled cases on one JavaScript -repo); the substrate's rubrics are heuristic; the MinHash near-match is weak on very short -specs (an optional embeddings backend — `FORGE_EMBED` — lifts this; MinHash stays the -zero-dependency default); and `forge cost --stages` reports **measured stages only** — a stage with -no events says "no data", never a default. What's *asserted* is safe to gate on (repo +Forge states its own ceiling everywhere. In short: **guards reduce, don't eliminate** the +"ignored my rules" problem; `recall`/`cortex` are file memory, **not** weight-level +learning; the `atlas`/`impact` graph is regex-approximate (conservative, not a sound call +graph — the impact numbers above are n = 6 hand-labeled cases on one JavaScript repo); the +substrate's rubrics are heuristic; the MinHash near-match is weak on very short specs (an +optional embeddings backend — `FORGE_EMBED` — lifts this; MinHash stays the zero-dependency +default); and `forge cost --stages` reports **measured stages only** — a stage with no +events says "no data", never a default. What's *asserted* is safe to gate on (repo grounding, graph traversal, routing arithmetic, test commands); everything else is *advisory*. **Tests and human corrections always win.** Full list: [docs/GUIDE.md → Honest limits](docs/GUIDE.md#honest-limits). -## Why a "cognitive substrate"? The white paper +## Why a cognitive substrate? The white paper A language model at inference is a fixed function `y = f(x)` — frozen weights, a bounded -window, no state between calls. Memory, foresight, and self-checking can't be prompted -into that shape; they have to be supplied from outside. The full argument, with every +window, no state between calls. Memory, foresight, and self-checking can't be prompted into +that shape; they have to be supplied from outside. The full argument, with every load-bearing statistic re-graded against primary sources, is the [cognitive-substrate white paper](docs/cognitive-substrate/). - ## Public site -Forgekit ships two static pages. [`landing/index.html`](landing/index.html) is a hand-authored landing page — the project's front door. [`public/index.html`](public/index.html) is a generated status page, intentionally static and auto-updated from real repository data (`package.json`, `README.md`, `CHANGELOG.md`, and `reports/benchmarks.md`) by the generator in [`scripts/build-pages.mjs`](scripts/build-pages.mjs). +Forgekit ships two static pages. [`landing/index.html`](landing/index.html) is a +hand-authored landing page — the project's front door. [`public/index.html`](public/index.html) +is a generated status page, intentionally static and auto-updated from real repository data +(`package.json`, `README.md`, `CHANGELOG.md`, and `reports/benchmarks.md`) by the generator +in [`scripts/build-pages.mjs`](scripts/build-pages.mjs). ```bash npm run pages:build # offline, deterministic repo-data build BUILD_PAGES_LIVE=1 npm run pages:build # also refresh public GitHub counters ``` -The optional live mode uses the no-auth GitHub repository API with timeouts, retries, jitter, and ETag/Last-Modified caching. +The optional live mode uses the no-auth GitHub repository API with timeouts, retries, +jitter, and ETag/Last-Modified caching. -Both pages share one design system (the same tokens as `forge dash`) and are gated by `forge uicheck design` and the rendered `forge uicheck visual` check. +Both pages share one design system (the same tokens as `forge dash`) and are gated by +`forge uicheck design` and the rendered `forge uicheck visual` check. -GitHub Pages is the primary deployment, via [`.github/workflows/static.yml`](.github/workflows/static.yml): the landing page is published at the site root and the status page at `/status/`. GitLab Pages ([`.gitlab-ci.yml`](.gitlab-ci.yml)) is unchanged and only deploys the status page at its root — it does not get the landing page. +GitHub Pages is the primary deployment, via [`.github/workflows/static.yml`](.github/workflows/static.yml): +the landing page is published at the site root and the status page at `/status/`. GitLab +Pages ([`.gitlab-ci.yml`](.gitlab-ci.yml)) is unchanged and only deploys the status page at +its root — it does not get the landing page. ## Documentation diff --git a/ROADMAP.md b/ROADMAP.md index a9bb853..ac6a6b9 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,5 +1,9 @@ # Roadmap +forgekit is one brain for every AI coding agent — the cognitive substrate (memory, foresight, +guardrails) that a stateless model is missing, authored once and delivered as native config to +every tool. This is where that brain is headed. + Direction, not promises — shaped by the two field reports this project is grounded in (the SDLC pain-point map and the ecosystem landscape). Open a Discussion to weigh in. diff --git a/SUPPORT.md b/SUPPORT.md index b1d685c..e296fdb 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -1,6 +1,7 @@ # Support -Thanks for using forgekit. Here's where to get help. +forgekit is one brain for every AI coding agent — the cognitive substrate (memory, foresight, +guardrails) authored once and delivered as native config to every tool. Here's where to get help. - **Questions / "how do I…"** → [Discussions](https://github.com/CodeWithJuber/forgekit/discussions) - **Bugs** → open an issue with the bug template (include `forge doctor` output + `node --version`). diff --git a/brand.json b/brand.json index b7679aa..79275bb 100644 --- a/brand.json +++ b/brand.json @@ -2,7 +2,7 @@ "brand": "Forge", "cli": "forge", "pkg": "forgekit", - "tagline": "One config, every AI coding tool.", + "tagline": "One brain for every AI coding agent.", "home": "~/.forge", "layers": { "tools": "skills (model-invoked capabilities)", diff --git a/docs/GUIDE.md b/docs/GUIDE.md index bde0809..21fb8b3 100644 --- a/docs/GUIDE.md +++ b/docs/GUIDE.md @@ -1,9 +1,16 @@ # Forge — the complete guide -Every command with a worked example and its **real** output, the everyday workflow, -how to make it run itself inside any agent, common recipes, and how to extend each -piece. If you just want to get going, the [5-minute onboarding](../ONBOARDING.md) is -shorter; this is the reference you come back to. +**One brain for every AI coding agent.** A language model is *stateless* — one context +window, wiped every call. It can't remember what your team learned, can't foresee what +an edit breaks, and has no enforced guardrails. Forge is the **cognitive substrate** — +the layer that runs *before* the model edits code — that supplies exactly those three +things, and it ships them as native config to nine AI coding tools at once. The brain is +the point; one config for every tool is how the brain gets delivered. + +This is the exhaustive reference: every command with a worked example and its **real** +output, the everyday workflow, how to make it run itself inside any agent, common +recipes, and how to extend each piece. If you just want to get going, the +[5-minute onboarding](../ONBOARDING.md) is shorter; this is the reference you come back to. - [Mental model](#mental-model) - [The everyday workflow](#the-everyday-workflow) @@ -14,6 +21,25 @@ shorter; this is the reference you come back to. - [Extending Forge](#extending-forge) - [Honest limits](#honest-limits) +### Command groups + +Every command is real and wired. Grouped by what it does: + +| Group | Commands | +| --- | --- | +| **Config / cross-tool sync** | `forge init` · `forge sync` · `forge doctor` · `forge harden` · `forge catalog` · `forge brand` | +| **Memory & ledger (PCM)** | `forge ledger` · `forge recall` · `forge remember` · `forge brain` · `forge cortex` · `forge reuse` | +| **Code graph & retrieval** | `forge atlas` · `forge context` | +| **Substrate / pre-action** | `forge substrate` · `forge preflight` · `forge route` · `forge impact` · `forge scope` · `forge imagine` · `forge anchor` · `forge diagnose` · `forge lean` · `forge cost` | +| **Verification & safety** | `forge verify` · `forge scan` · `forge spec` | +| **UI / design** | `forge taste` · `forge uicheck` | +| **Dashboard** | `forge dash` | + +Storage in one line: the code graph is `.forge/atlas.json` (plain JSON, not SQLite); the +ledger is content-addressed claims under `.forge/ledger/` (git-committable, union-merge). +The runtime is **zero-dependency Node** — optional tiers (`FORGE_EMBED` embeddings, +Playwright for `uicheck visual`) are opt-in and still add no required dependency. + --- ## Mental model @@ -43,11 +69,14 @@ The daily loop — every outcome an oracle observes lands in the team ledger, an ledger informs the next task: ```mermaid +%%{init: {'theme':'base','themeVariables':{'primaryColor':'#201a15','primaryTextColor':'#f2ede7','primaryBorderColor':'#372c22','lineColor':'#f26430','secondaryColor':'#272019','tertiaryColor':'#171310','fontFamily':'ui-sans-serif, system-ui, sans-serif'}}}%% flowchart LR W["work — substrate pre-checks,
then edit"] --> O["oracles — forge verify ·
imagine --run · CI · human accept/revert"] O -->|"outcomes move claim val"| L[("team ledger
.forge/ledger/")] L <-->|"git + forge ledger merge"| T["teammates' ledgers"] L -->|"lessons · facts · reuse hits"| W + classDef accent fill:#f26430,stroke:#f26430,color:#171310; + class L accent; ``` ```bash @@ -317,10 +346,11 @@ Forge ledger blame — lesson 3f2a91c04d7e The rest of the surface, briefly: `forge ledger merge ` folds in any other ledger tree (a teammate's checkout, a worktree, a backup) — `merged: 3 new claim(s), 5 new record(s) — conflict-free`, in any order; `query ""` ranks live claims by the -paper's Eq. 3; `show ` prints one claim with its computed `val`; `verify` recomputes -every content hash (CI-friendly, exit 1 on tampering); `import` back-fills legacy -lessons/facts idempotently. Add `--personal` to target the per-user ledger beside the -global recall store, `--json` for scripts. +paper's Eq. 3; `show ` prints one claim with its computed `val`; `ratify ` and +`retract ` are the human oracle — a manual accept or revert that appends evidence and +moves confidence; `verify` recomputes every content hash (CI-friendly, exit 1 on +tampering); `import` back-fills legacy lessons/facts idempotently. Add `--personal` to +target the per-user ledger beside the global recall store, `--json` for scripts. ### `forge reuse` — proof-carrying code cache @@ -560,10 +590,12 @@ Plain `forge cost` remains the per-day spend view via `ccusage`. | `forge catalog` | Start-Here index of every tool / crew / guard. | | `forge brain` / `forge remember` | Portable project memory inlined into `AGENTS.md`. | | `forge cost` | Real per-day spend (via `ccusage`) + the cost ceiling; `--stages` for the measured report. | -| `forge scan ` | Vet a skill/MCP for injection/RCE before install. | +| `forge scan ` | Vet a skill/MCP (SKILL.md/.mcp.json) for injection/RCE/exfil before install. | | `forge harden` | Wire gitleaks pre-commit + sandbox settings. | | `forge spec [init\|lock\|check]` | Spec-as-contract drift check. | | `forge brand` | Print the active brand token map. | +| `forge lean ""` | Scope-minimality footprint for a task — advisory (the Lean Path as a command). | +| `forge taste [