@codewithjuber/forgekit 0.8.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
+  "name": "forge",
+  "owner": { "name": "CodeWithJuber" },
+  "plugins": [
+    {
+      "name": "forgekit",
+      "source": ".",
+      "description": "One config, every AI coding tool. Cross-tool rules emitter, enforced guards, code-graph, memory, and cost governor."
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "forgekit",
+  "displayName": "Forge",
+  "version": "0.8.0",
+  "description": "One config, every AI coding tool — cognitive substrate, tools, crew, guards, atlas, lean, recall from one source.",
+  "author": { "name": "CodeWithJuber" },
+  "license": "MIT",
+  "repository": "https://github.com/CodeWithJuber/forgekit",
+  "homepage": "https://github.com/CodeWithJuber/forgekit#readme",
+  "keywords": ["config", "cross-tool", "agents-md", "ai-coding", "claude-code", "cognitive-substrate"],
+  "skills": "./global/tools",
+  "agents": [
+    "./global/crew/frontend-verifier.md",
+    "./global/crew/independent-reviewer.md",
+    "./global/crew/scout.md",
+    "./global/crew/verifier.md"
+  ],
+  "hooks": "./hooks/hooks.json"
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,29 @@
+{
+  "name": "forgekit",
+  "version": "0.8.0",
+  "description": "One config, every AI coding tool — cognitive substrate, MCP tools, guards, atlas, recall, and routing from one source.",
+  "author": { "name": "CodeWithJuber", "url": "https://github.com/CodeWithJuber" },
+  "homepage": "https://github.com/CodeWithJuber/forgekit#readme",
+  "repository": "https://github.com/CodeWithJuber/forgekit",
+  "license": "MIT",
+  "keywords": ["codex", "mcp", "ai-coding", "agents-md", "cognitive-substrate"],
+  "skills": "skills",
+  "mcpServers": ".mcp.json",
+  "interface": {
+    "displayName": "Forge",
+    "shortDescription": "Cognitive substrate and one config for every AI coding tool.",
+    "longDescription": "Forge adds a pre-action cognitive substrate for coding agents: assumption gating, transparent model routing, impact prediction, scope decomposition, memory/learning context, and verification checklists. It also emits shared rules and MCP config for Codex, Claude Code, Cursor, Gemini, Aider, Copilot, Windsurf/Devin, Zed, Continue, and Roo.",
+    "developerName": "CodeWithJuber",
+    "category": "Productivity",
+    "capabilities": ["MCP", "Skills", "Code Review", "Verification"],
+    "websiteURL": "https://github.com/CodeWithJuber/forgekit",
+    "privacyPolicyURL": "https://github.com/CodeWithJuber/forgekit/blob/master/SECURITY.md",
+    "termsOfServiceURL": "https://github.com/CodeWithJuber/forgekit/blob/master/LICENSE",
+    "defaultPrompt": [
+      "Run Forge substrate before this edit.",
+      "Predict impact for this symbol.",
+      "Route this task to the right model tier."
+    ],
+    "brandColor": "#137A72"
+  }
+}

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "forge-cortex": {
+      "command": "forge",
+      "args": ["cortex-mcp"]
+    }
+  }
+}

package/ARCHITECTURE.md

@@ -0,0 +1,314 @@
+# forgekit — architecture
+
+> **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.
+
+This document is the architecture reference. It is organized around four diagrams:
+
+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**,
+  hooks→**guards**, code-graph→**atlas**, minimalism→**lean**, memory→**recall**.
+  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** — 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").
+- **Own `lean` + `atlas`** — as *thin layers over proven primitives*, not
+  from-scratch reimplementations (reuse-first).
+
+## 1. 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/<br/>rules.json · substrate.json · mcp.json"] -->|"forge sync<br/>content-hash + DO-NOT-EDIT headers"| N["native configs<br/>CLAUDE.md · AGENTS.md · .cursor · .gemini · .aider · …"]
+    S -. configures .-> L
+    subgraph L["the four layers"]
+        direction LR
+        T["tools<br/>model-invoked skills"]
+        C["crew<br/>isolated sub-agents"]
+        G["guards (enforced)<br/>deterministic hooks"]
+        M["mcp<br/>atlas + substrate server"]
+    end
+    K["local events<br/>cortex · recall · reuse · diagnose"] --> LG[("PCM ledger<br/>.forge/ledger/")]
+    O["independent oracles<br/>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;
+```
+
+The four layers, brand-named and emitted cross-tool:
+
+- **tools** (`~/.forge/tools/` → `~/.claude/skills/`) — model-invoked capabilities.
+- **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.** 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 "<task>"` (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<br/>entities"] --> PF["preflight<br/>assumption gap"]
+    PF --> RT["route<br/>cheapest tier"]
+    RT --> AT["atlas<br/>code graph"]
+    AT --> IM["impact<br/>blast radius"]
+    IM --> PT["predict<br/>failing tests"]
+    PT --> RU["reuse<br/>cache hit?"]
+    RU --> CX["context<br/>completeness gate"]
+    CX --> SC["scope<br/>coupled files"]
+    SC --> ME["memory<br/>recall + lessons"]
+    ME --> MN["minimality<br/>lean footprint"]
+    MN --> GA["goal-anchor<br/>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<br/>tests · CI · human accept/revert"] -->|"append evidence<br/>move confidence"| LG
+    TM["teammate ledgers"] <-->|"git union-merge<br/>conflict-free"| LG
+    LG --> RV["merged read view<br/>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<br/>MinHash + LSH"]
+    FP --> LD["match ladder<br/>exact → near → adapt → miss"]
+    LD --> GT{"confidence ≥ floor<br/>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 "<task>"`: 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)
+
+**Reuse (rename + swap brand token, logic unchanged):**
+`tech-selector · reuse-first · dev-radar · code-modernization · explore-plan-code ·
+cost-guard · ui-workflow · design-md · self-improve` (tools) · `scout · verifier ·
+frontend-verifier` (crew) · `protect-paths · format-on-edit · recall-load ·
+session-learner` (guards) · `statusline` · `tech-currency · stack-notes ·
+self-correction` (rules) · project-layer template.
+
+**Own-branded replacements (thin layer over proven primitive):**
+- **`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`** (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 <symbol>` 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.)* 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** | `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` + `.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.
+
+## Repo layout — one tree, three front doors
+```
+forgekit/
+  package.json            # npm CLI: bin `forge` → src/cli.js
+  brand.json              # single FORGE_BRAND token + layer-name map
+  README.md               # Start-Here index + one bootstrap command
+  src/
+    cli.js                # init | sync | doctor | substrate | ledger | reuse | … (`forge --help` for all)
+    sync.js               # emitter (source → per-tool targets); hash + DO-NOT-EDIT
+    doctor.js             # health checks
+    emit/                 # one module per tool (claude, codex, cursor, gemini, aider, copilot, windsurf, zed, continue) + mcp
+    ledger.js             # PCM core: content-addressed claims, oracle taxonomy, decayed Beta val, Eq. 3 retrieval, semilattice merge (ADR-0006)
+    ledger_store.js       # git-native on-disk ledger (.forge/ledger/): sharded claims, append-only evidence/tombstone logs, normal-form verify
+    ledger_bridge.js      # legacy-store bridge: cortex/recall/brain shadow-writes + idempotent `ledger import`
+    ledger_read.js        # merged legacy∪ledger read path: cortex lesson/fact injection, `recall list`, brain's AGENTS.md index all see teammate knowledge from `ledger merge`
+    reuse.js              # proof-carrying artifact cache: fingerprint (MinHash+LSH), exact→near→adapt→miss ladder, atlas revalidation
+    embed.js              # optional embeddings tier (ADR-0005): FORGE_EMBED=cmd:<cmd>|http:<url>, swaps MinHash/Jaccard for cosine in `reuse query`/`ledger query`, disk-cached at .forge/embed-cache.jsonl, silent fallback to MinHash
+    context.js            # budgeted context assembly + completeness gate: R(edit) set cover, compression ladder, computed missing-set
+    diagnose.js           # doom-loop diagnosis: normalized failure signatures; 3× = diagnosis claim + one-tier escalation
+    imagine.js            # consequence simulation (Eq. 4): predicted breaks + minimal dry-run suite via greedy set cover
+    uifingerprint.js      # deterministic design fingerprint + slop-distance / conformance gate (no LLM, no screenshots)
+    taste.js              # taste-profile system: applies design-taste profiles (brutalist, corporate, editorial, minimalist, playful; JSON in global/taste/) to parameterize `uicheck design` gate thresholds via --taste
+    dash.js               # localhost-only read-only dashboard over the ledger, metrics, and blast radius (node:http, one HTML page)
+    metrics.js            # stage-tagged .forge/metrics.jsonl — the measured events every cost figure is computed from
+    cost_report.js        # per-stage cost factors as pure arithmetic over metrics.jsonl; composes ONLY measured stages
+  source/
+    rules.json            # THE canonical rules source (git · testing · security · style)
+    substrate.json        # cognitive-substrate defaults (thresholds, routing, llm knobs)
+    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
+  .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
+  landing/                # hand-authored public landing page; design tokens shared with `forge dash`
+  scripts/
+    build-pages.mjs       # generates public/index.html, the live status page, from real repo data
+```
+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).
+
+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 is expressible as a hook (paths,
+  format, diff-size, budget). Semantic rules ("prefer functional") stay prose and
+  *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. 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
+architecture decisions (zero runtime deps, the SKILL.md standard, guard-over-prose).