From 25cbf90dbe4cddd3f5616123e9d1dcc5c1b82868 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 7 Jul 2026 19:22:21 +0000 Subject: [PATCH 01/11] =?UTF-8?q?docs:=20v0.5.0=20release=20cut=20?= =?UTF-8?q?=E2=80=94=20substrate-v2=20command=20docs,=20team-memory=20guid?= =?UTF-8?q?e,=20honest=20limits?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README: new commands in the command list (ledger, reuse, context, imagine, diagnose, dash; uicheck + cost lines extended), a 'Team memory in three commands' section, and honest-limits additions (MinHash short-spec weakness, CSS var() indirection, measured-stages-only cost report, regex-approximate atlas) - ARCHITECTURE: PCM ledger documented as the convergent store for all memory subsystems (ADR-0006 cited); new modules added to the repo layout - docs/GUIDE: worked examples for ledger, reuse, context, diagnose, imagine, uicheck fingerprint/design, dash, and cost --stages; honest limits extended - ONBOARDING: 'Day two: the ledger is learning' subsection - CHANGELOG: [Unreleased] cut as [0.5.0] - 2026-07-07; footer compare links updated (missing 0.4.0 link added) - Version 0.4.0 -> 0.5.0 in package.json, package-lock.json, .claude-plugin/plugin.json, .codex-plugin/plugin.json, CITATION.cff (+ date-released), landing/index.html footer Co-Authored-By: Claude Claude-Session: https://claude.ai/code/session_01Fc2MvWJbQ1cyNQ76ymv4hs --- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- ARCHITECTURE.md | 26 +++++ CHANGELOG.md | 6 +- CITATION.cff | 4 +- ONBOARDING.md | 16 +++ README.md | 39 ++++++- docs/GUIDE.md | 219 ++++++++++++++++++++++++++++++++++++- landing/index.html | 2 +- package-lock.json | 4 +- package.json | 2 +- 11 files changed, 303 insertions(+), 19 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 1fd657e..af48b45 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -2,7 +2,7 @@ "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "forgekit", "displayName": "Forge", - "version": "0.4.0", + "version": "0.5.0", "description": "One config, every AI coding tool — cognitive substrate, tools, crew, guards, atlas, lean, recall from one source.", "author": { "name": "CodeWithJuber" }, "license": "MIT", diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 73b316e..2799d83 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "forgekit", - "version": "0.4.0", + "version": "0.5.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", diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 30e4277..78d3565 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -67,6 +67,21 @@ Stop-guard, so it works whether or not the model invokes it), **recall** (memory `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). + ## Component map — the reuse ledger (30 components) **Reuse (rename + swap brand token, logic unchanged):** @@ -132,6 +147,17 @@ forgekit/ 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` + reuse.js # proof-carrying artifact cache: fingerprint (MinHash+LSH), exact→near→adapt→miss ladder, atlas revalidation + 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) + 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) diff --git a/CHANGELOG.md b/CHANGELOG.md index b0d980a..cfbf59a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,8 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] +## [0.5.0] - 2026-07-07 + ### Added - **Loop closure (P5 of the substrate-v2 plan): doom-loop diagnosis, imagination, CUSUM @@ -344,7 +346,9 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). check; coverage + type-checking (`tsc --checkJs`); 2026 production-standard rules; OWASP-LLM / NIST SSDF / SLSA control mapping. -[Unreleased]: https://github.com/CodeWithJuber/forgekit/compare/v0.3.1...HEAD +[Unreleased]: https://github.com/CodeWithJuber/forgekit/compare/v0.5.0...HEAD +[0.5.0]: https://github.com/CodeWithJuber/forgekit/compare/v0.4.0...v0.5.0 +[0.4.0]: https://github.com/CodeWithJuber/forgekit/compare/v0.3.1...v0.4.0 [0.3.1]: https://github.com/CodeWithJuber/forgekit/compare/v0.3.0...v0.3.1 [0.3.0]: https://github.com/CodeWithJuber/forgekit/compare/v0.2.0...v0.3.0 [0.2.0]: https://github.com/CodeWithJuber/forgekit/compare/v0.1.0...v0.2.0 diff --git a/CITATION.cff b/CITATION.cff index 5b769ad..e9db382 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -1,8 +1,8 @@ cff-version: 1.2.0 message: "If you use forgekit, please cite it using this metadata." title: "Forge (forgekit)" -version: 0.4.0 -date-released: "2026-07-06" +version: 0.5.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 diff --git a/ONBOARDING.md b/ONBOARDING.md index 94afd25..0e5bd34 100644 --- a/ONBOARDING.md +++ b/ONBOARDING.md @@ -73,6 +73,22 @@ 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 + +Everything the substrate learned on day one — cortex lessons, remembered facts, +verified code — landed as claims in `.forge/ledger/`. Now it starts paying off: + +```bash +forge ledger stats # what the repo knows, by kind and trust level +forge ledger blame # who minted a claim, every oracle outcome, per-author trust +forge reuse query "" # verified code you already have — with its proof +``` + +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. + --- ## Forge principles diff --git a/README.md b/README.md index b09ca6e..b3e42d5 100644 --- a/README.md +++ b/README.md @@ -154,18 +154,24 @@ forge catalog Start-Here index of every tool / crew / guard forge substrate full pre-action cognitive-substrate check forge preflight assumption check — what a task names that the repo doesn't define +forge context budgeted context assembly + completeness gate — what an edit NEEDS known forge route cheapest capable model for a task (+ gateway config) forge impact predict blast radius for a symbol or file +forge imagine consequence simulation — predicted breaks + the minimal dry-run test suite forge scope decompose files into independent clusters forge anchor goal-drift check — are your git changes still on the stated goal? +forge diagnose doom-loop check — 3× the same failure mints a diagnosis + escalation forge verify independent verification — tests + hallucinated-symbol check -forge uicheck deterministic WCAG contrast check +forge uicheck deterministic UI checks — WCAG contrast · fingerprint · design gate +forge ledger proof-carrying memory — stats / verify / show / blame / query / merge / import +forge reuse proof-carrying code cache — query / mint --file / stats forge cortex self-correcting memory — status / why forge atlas build / query the code-graph (where-is-X, has-symbol) forge recall cross-session memory (list / add / consolidate) forge brain portable project memory inlined into AGENTS.md -forge cost real per-day spend via ccusage + the cost ceiling +forge dash local dashboard over the ledger, metrics, and blast radius +forge cost real per-day spend via ccusage · measured stage factors (--stages) forge scan vet a skill/MCP for injection/RCE before install forge harden wire gitleaks pre-commit + sandbox settings forge brand print the active brand token map @@ -174,15 +180,36 @@ forge brand print the active brand token map **→ Every command with a worked example, real output, and how to extend it: [`docs/GUIDE.md`](docs/GUIDE.md).** +## 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/`) built to merge without conflicts: + +```bash +forge init # once — also emits the .gitattributes union-merge rule the ledger needs +# …work normally: cortex and `forge remember` shadow claims into the ledger as you go… +git pull && forge ledger merge # fold in a teammate's ledger — conflict-free, any order +``` + +Identical knowledge minted independently converges to **one** claim with every author +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. + ## 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); and the substrate's rubrics are heuristic, not benchmarked. What's *asserted* is -safe to gate on (repo grounding, graph traversal, routing arithmetic, the test commands); -everything else is *advisory*. **Tests and human corrections always win.** Full list: -[docs/GUIDE.md → Honest limits](docs/GUIDE.md#honest-limits). +graph); and the substrate's rubrics are heuristic, not benchmarked. The newer subsystems +state theirs too: `forge reuse`'s MinHash near-match is weak on very short specs (a +few words hash to too few shingles to rank reliably); the UI fingerprint doesn't resolve +CSS `var()` indirection yet, so tokenized palettes are partially invisible to it; and +`forge cost --stages` reports **measured stages only** — a stage with no events says "no +data", never a default, and the ~90 % figure is a labeled *target*, not a claim. What's +*asserted* is safe to gate on (repo grounding, graph traversal, routing arithmetic, the +test commands); everything else is *advisory*. **Tests and human corrections always +win.** Full list: [docs/GUIDE.md → Honest limits](docs/GUIDE.md#honest-limits). ## Documentation diff --git a/docs/GUIDE.md b/docs/GUIDE.md index b5bd614..e654d94 100644 --- a/docs/GUIDE.md +++ b/docs/GUIDE.md @@ -266,15 +266,219 @@ Forge cortex — self-correcting project memory `forge cortex why ` shows the lessons that would be injected when you touch it. -### `forge uicheck ` — deterministic WCAG contrast +### `forge ledger` — proof-carrying team memory -Exact contrast math for UI work — asserted, never guessed. +The convergent store behind cortex, `recall`, `brain`, and `reuse`: every stored unit is +a content-addressed claim whose confidence (`val`) only independent oracles can move. +Lives in `.forge/ledger/` — git-committable, conflict-free merge. ```console -$ forge uicheck "#777" "#fff" +$ forge ledger stats +Forge ledger — proof-carrying memory + + claims: 12 (tombstoned 1) + lesson: 7 + fact: 4 + artifact: 1 + val: trusted 5 · uncertain 6 · dormant 1 + + stored in .forge/ledger/ (git-committable, conflict-free merge) +``` + +`forge ledger blame ` is the accountability view — every mint, every oracle +outcome, every retraction, and per-author trust: + +```console +$ forge ledger blame 3f2a +Forge ledger blame — lesson 3f2a91c04d7e + + val 0.82 (trust-weighted 0.84) + minted day 20640 by juber + confirm day 20641 test.run → npm-test#a41 by juber + confirm day 20643 human.accept → pr-118 by sam + + author trust (earned from oracle outcomes on their claims): + 0.93 juber +``` + +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. + +### `forge reuse` — proof-carrying code cache + +Verified code becomes an `artifact` claim keyed by a normalized task fingerprint; a +lookup walks exact → near → adapt → miss. An artifact serves **only while its proof +holds** — confidence above the 0.6 floor and every declared dependency still in the atlas. + +```console +$ forge reuse query "debounce user input before firing search" + NEAR hit (similarity 0.87) — module at src/lib/debounce.js + claim 9c41d2ab77e0 — `forge ledger blame 9c41d2ab` for its proof + +$ forge reuse query "quantum blockchain" + miss — nothing verified matches; generate, then `forge reuse mint` it +``` + +Mint after verification — without an evidence ref it sits at the 0.5 prior and does +**not** serve: + +```console +$ forge reuse mint "debounce helper for search input" --file src/lib/debounce.js --ref npm-test#green + minted: 9c41d2ab77e0 (1 export(s), 0 dep(s)) + serving: yes — verification evidence attached +``` + +`forge reuse stats` shows lookups by outcome + estimated tokens saved (from +`.forge/metrics.jsonl`). Honest limit: the MinHash near-match is weak on very short +specs — a few words hash to too few shingles to rank reliably. + +### `forge context ""` — budgeted assembly + completeness gate + +Derives the required-knowledge set for an edit (the target's definitions, hop-1 +dependents, sibling tests, trusted lessons), covers it under a token budget with a +compression ladder (full → head → pointer), and computes what's *missing* as a set +difference — not a feeling. + +```console +$ forge context "change verifyToken in src/auth.js to reject short tokens" +Forge context — budgeted assembly + completeness gate + + budget: 1840/12000 tokens · required 4 · COMPLETE + + def:src/auth.js [full] 620t + + deps:verifyToken [head] 410t + + tests:test/auth.test.js [full] 480t + + fact:c1d2e3f4 [full] 330t +``` + +On an incomplete assembly it lists the missing items and derived clarifying questions +("the task names `X` but the repo doesn't define it — which file implements it?") and +exits 1. `--budget ` tightens the window; a tight budget downgrades granularity +instead of silently dropping coverage. + +### `forge diagnose ""` — doom-loop check + +Hashes a failure into a normalized signature (line numbers, addresses, timestamps, +paths stripped) and counts recurrences. The 3rd identical hit is thrash: it mints a +`diagnosis` claim into the team ledger and tells the agent to stop retrying. + +```console +$ forge diagnose "TypeError: Cannot read properties of undefined (reading 'user')" --file src/session.js +Forge diagnose — doom-loop check + + signature: a41f7c20be91 · seen 3× in the recent failure window + diagnosis claim: 5d0e88c21f3a (`forge ledger show 5d0e88c2`) + + STOP retrying this fix. State the diagnosis out loud (claim 5d0e88c2 — `forge ledger show 5d0e88c2`, add what you already tried to its triedFixes), then escalate ONE model tier with the diagnosis as the head of the new prompt. The escalation must carry the diagnosis — never just "try again, but more expensive". +``` + +Below the threshold it just records and says keep going. Advisory — halting the retry +loop is the agent's move, not an exit code. Because the claim rides the team ledger, the +same loop becomes a one-per-team event, not one-per-session. + +### `forge imagine ""` — consequence simulation + +The static half of the paper's Eq. 4: entities → blast radius → predicted breaks with +confidence, plus the minimal test suite that covers them (weighted greedy set cover). + +```console +$ forge imagine "change verifyToken in src/auth.js to reject short tokens" +Forge imagine — consequence simulation (pre-action) + + targets: verifyToken, src/auth.js + risk score: 2.30 (Σ confidence over predicted breaks) + + predicted breaks (3): + 0.90 src/auth.js + 0.70 src/login.js + 0.70 src/session.js + + minimal dry-run suite (1) — run these, in this order: + - test/auth.test.js + + (sandboxed worktree dry-run of this suite lands as the P5 follow-up) +``` + +It also flags predicted breaks **no test covers** — the risk you can't dry-run away. + +### `forge uicheck` — deterministic UI checks + +Three subcommands, all static parsing — no LLM, no screenshots. + +**`contrast `** — exact WCAG math, asserted, never guessed (bare +`forge uicheck ` still works): + +```console +$ forge uicheck contrast "#777" "#fff" contrast #777 on #fff: 4.48:1 → fail (FAILS AA) ``` +**`fingerprint [--mint]`** — the design feature vector of your UI files: +palette (hue histogram), spacing base + on-scale fraction, fonts, radius/shadow levels. +`--mint` stores it as a shared `fingerprint` ledger claim — the design gate's "home": + +```console +$ forge uicheck fingerprint src/components/*.jsx --mint +Forge uicheck fingerprint — the design feature vector + + palette: 9 color(s), hue bins [2 0 0 1 3 0 0 0 0 2 1 0] + spacing: 4, 8, 16, 24 px — base 4, 96% on-scale + type: Inter, ui-monospace + shape: radii 6, 12 (2 level(s)) · 1 shadow level(s) + + minted fingerprint claim e7a90b12cd34 — the gate's "home" +``` + +**`design `** — the two-sided gate for generated UI (exit 1 on fail): slop +distance to known generic templates must stay HIGH, conformance to your minted project +fingerprint must stay LOW, plus scale-conformance checks (spacing on base, level caps). +Failures are actionable per-feature edits, never a bare score. Honest limit: the +fingerprint doesn't resolve CSS `var()` indirection yet — fully tokenized palettes are +partially invisible to it. + +### `forge dash [--port N]` — the local dashboard + +A read-only lens over `.forge/` — stdlib `node:http`, localhost-only, one +self-contained HTML page (no CDN, no build step). Panels: Ledger (claims with val bars, +contested claims, per-author trust), Cost/Cache (measured stage counters), and Impact +(blast-radius explorer). Every claim row shows its `forge ledger blame` command. + +```console +$ forge dash +Forge dash — read-only lens on .forge/ + + http://127.0.0.1:4242 (localhost-only · Ctrl-C to stop) +``` + +### `forge cost --stages` — the measured cost report + +Per-stage cost factors as pure arithmetic over `.forge/metrics.jsonl`. A stage with no +events says **no data** — never a default; the composed figure is a lower bound over +measured stages only. + +```console +$ forge cost --stages +Forge cost — measured stage factors (.forge/metrics.jsonl) + + stage factor events + gate 6.2% 16 + cache no data 0 + route no data 0 + context no data 0 + + composed measured reduction: 6.2% (from: gate) — lower bound, measured stages only + totals: 16 metric event(s) · ~0 tokens saved (stage self-estimates) + + context (not a local measurement): the paper measured a 62% routing saving on live tokens (paper §9) + target (unmet until measured): the plan's composed target is ~90% (docs/plans/substrate-v2/05-cost-model.md) +``` + +Plain `forge cost` remains the per-day spend view via `ccusage`. + ### The rest | Command | Answers | @@ -284,7 +488,7 @@ $ forge uicheck "#777" "#fff" | `forge doctor` | Health check: layers, install, drift, cortex. | | `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. | +| `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 harden` | Wire gitleaks pre-commit + sandbox settings. | | `forge spec [init\|lock\|check]` | Spec-as-contract drift check. | @@ -459,6 +663,13 @@ Edit `brand.json` (`FORGE_BRAND`), the `bin` key in `package.json`, and `name` i - **`recall` / `cortex` are file + prompt memory**, not weight-level learning. - **The atlas graph is regex-approximate** — conservative, not a sound call graph; dynamic dispatch and generated code can be missed. +- **`forge reuse`'s MinHash near-match is weak on very short specs** — a few words hash + to too few shingles to rank reliably; write a sentence, not a keyword. +- **The UI fingerprint doesn't resolve CSS `var()` indirection yet** — a fully + tokenized palette is partially invisible to the design gate. +- **`forge cost --stages` reports measured stages only** — a stage with no events says + "no data", never a default; the composed figure is a lower bound and ~90 % is a + labeled *target*, not a claim. - **The substrate's rubrics are heuristic, not benchmarked** — judge them after real use. What's *asserted* (safe to gate on): repo grounding, graph traversal, scope decomposition, routing arithmetic, and the test/build commands. Everything else is diff --git a/landing/index.html b/landing/index.html index 0e0c4b3..7096679 100644 --- a/landing/index.html +++ b/landing/index.html @@ -1097,7 +1097,7 @@

Give your agent a memory that gets better the more it's wrong.