CodeWithJuber · CodeWithJuber · Jul 7, 2026 · Jul 7, 2026 · Jul 7, 2026
@@ -42,13 +42,19 @@ packages; the production runtime remains Node-only and zero-dependency.
 
 ## Architecture — a four-layer config compiler with ONE source
 
-```
-                       source/rules.json  (canonical rules: git · testing · security · style)
-                                │           (+ source/substrate.json, source/mcp.json)
-                          forge sync  (emitter: content-hash + DO-NOT-EDIT headers)
-        ┌───────────────┬───────┴───────┬───────────────┬─────────────┐
-   Claude CLAUDE.md   Codex AGENTS.md  Cursor .mdc   Gemini settings  Aider .aider.conf.yml ...
-   (@AGENTS.md import)  (native)        /AGENTS.md    (context.fileName)  (read: AGENTS.md)
+```mermaid
+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"]
+    end
+    S -. configures .-> L4
+    K["cortex lessons · recall facts · reuse artifacts<br/>design fingerprints · diagnoses"] --> LG[("PCM ledger — .forge/ledger/<br/>content-addressed claims")]
+    O["independent oracles<br/>tests · CI · human accept/revert"] -->|"move val"| LG
+    LG <-->|"git union-merge, conflict-free"| TM["teammate ledgers"]
 ```
 
 Layers map onto the Claude Code substrate, brand-named, and are emitted cross-tool:
@@ -143,7 +149,7 @@ forgekit/
   brand.json              # single FORGE_BRAND token + layer-name map
   README.md               # Start-Here index + one bootstrap command
   src/
-    cli.js                # init | sync | doctor | taste | learn-consolidate | brand
+    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
@@ -163,9 +169,9 @@ forgekit/
     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/ mcp/atlas/ recall/ lean/ statusline.sh settings.template.json
+    tools/ crew/ guards/ rules/ recall/ taste/ statusline.sh settings.template.json
   templates/project-layer/  # per-repo template (was hostlelo-project-layer)
-  plugin/                 # plugin.json + marketplace.json → point at global/ (no dup)
+  .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
 ```

@@ -6,6 +6,17 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Changed
+
+- Docs consolidation pass: deduplicated cross-doc prose into single canonical homes
+  (the substrate README now points at the GUIDE's command reference, output table, and
+  honest-limits list instead of repeating them), added orientation diagrams
+  (ARCHITECTURE four-layer compiler + ledger, substrate-v2 phase graph with all phases
+  marked shipped, the GUIDE daily loop), brought the ROADMAP current, and refreshed the
+  model-facing skills/crew guidance for the v0.5.0 surface (`forge context`,
+  `forge imagine --run`, `forge diagnose`, `forge ledger blame`, `forge cost --stages`,
+  `forge uicheck design --taste`) without growing the skills' context payload.
+
 ## [0.5.0] - 2026-07-07
 
 ### Added

@@ -3,46 +3,42 @@
 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.
 
-## Now (`master`)
+## Now (`master`, v0.5.0)
 Cross-tool config for nine agents (Claude Code, Codex, Cursor, Gemini, Aider, Copilot,
 Windsurf, Zed, Continue) plus MCP config for Roo & VS Code, verification layer
 (`forge verify`), security gate (`forge scan`), portable memory (`forge brain`), cost
-governor (`forge cost`), spec-as-contract drift (`forge spec`), goal-drift check
-(`forge anchor`), and the cognitive-substrate pre-action gate (`forge substrate`,
-`forge impact`). The full paper and evidence bundle live in
-[docs/cognitive-substrate/](./docs/cognitive-substrate/). See
-[CHANGELOG.md](./CHANGELOG.md) `[Unreleased]`.
+governor (`forge cost`, `--stages` for measured factors), spec-as-contract drift
+(`forge spec`), goal-drift check (`forge anchor`), the cognitive-substrate pre-action
+gate (`forge substrate`, `forge impact`) — **plus the whole Substrate v2 surface**:
+`forge ledger` (proof-carrying team memory), `forge reuse` (verified-code cache),
+`forge context` (budgeted assembly + completeness gate), `forge diagnose` (doom-loop),
+`forge imagine [--run]` (consequence simulation + sandboxed dry-run), `forge uicheck`
+v2 (fingerprints + design gate), and `forge dash`. The full paper and evidence bundle
+live in [docs/cognitive-substrate/](./docs/cognitive-substrate/). See
+[CHANGELOG.md](./CHANGELOG.md).
 
-## Next — Substrate v2 (the whitepaper, completed)
-The full plan lives in [docs/plans/substrate-v2/](./docs/plans/substrate-v2/00-overview.md):
-every paper faculty and mechanism mapped to an algorithm, unified by the
-**Proof-Carrying Memory (PCM) protocol** (ADR-0006) — every stored thing is a claim that
-carries its evidence, earns confidence only from independent oracles, and merges across
-teammates conflict-free (git-native CRDT ledger).
+## Shipped — Substrate v2 (all phases P0–P8, v0.5.0)
+The plan lives in [docs/plans/substrate-v2/](./docs/plans/substrate-v2/00-overview.md)
+(phase dependency graph + acceptance gates, all marked done): every paper faculty and
+mechanism mapped to an algorithm, unified by the **Proof-Carrying Memory (PCM)
+protocol** (ADR-0006) — every stored thing is a claim that carries its evidence, earns
+confidence only from independent oracles, and merges across teammates conflict-free
+(git-native CRDT ledger).
 
-Phases (dependency-ordered; acceptance gates in the overview):
-- **P1 Ledger core** — claim store, Beta-posterior confidence, Eq. 3 retrieval;
-  cortex + recall migrate onto claim kinds.
-- **P2 Team memory** — `.forge/ledger/` union-merge over git; `forge ledger`.
-- **P3 Reuse cache** — proof-carrying artifact cache (`forge reuse`): verified code is
-  served with its evidence, revalidated against the atlas, demoted by outcomes.
-- **P4 Context assembly** — knapsack selection under a token budget + a set-cover
-  completeness gate that *computes* what's missing (`forge context`).
-- **P5 Loop closure** — outcome write-back band; doom-loop diagnosis + escalation;
-  imagination dry-run (impacted-test set cover + worktree sandbox); AST-tier atlas with
-  a mandatory impact gate; M3 partition planning, M4 CUSUM drift, M5 footprint metric,
-  M6 checkpoint cadence; outcome-calibrated routing.
-- **P6 UI quality gate** — design fingerprints, slop-distance + project-conformance
-  scoring, scale/palette conformance checks (`forge uicheck` v2, machine-readable taste).
-- **P7 `forge dash`** — local dashboard over the ledger, cost stages, cache, blast radius.
-- **P8 Evaluation** — measured per-stage cost report (target ~90 % composed; only
-  measured numbers get claimed — see [05-cost-model.md](./docs/plans/substrate-v2/05-cost-model.md)).
-
-Carried forward from the previous roadmap into these phases: calibration fixtures (P8),
-AST-backed impact (P5), Playwright testing (P6), MCP hygiene in `forge doctor` (P7).
+## Next
+- **Ledger read-path flip** — the ledger is the convergent *write* store today while
+  the legacy stores (`lessons/`, `recall`, `brain`) still serve reads; flip reads to be
+  ledger-first, then retire the legacy formats.
+- **Embeddings tier** — optional vector backend (ADR-0005 dependency tier, stdlib
+  fallback kept) for Eq. 3 retrieval and `forge reuse` near-match, where MinHash is
+  weak on short specs.
+- **Playwright loop** — drive a real browser in the UI gate: screenshot + interaction
+  checks feeding `forge uicheck` verdicts back as oracle evidence on design claims.
+- **Advisory → gated promotions** — outcome-calibrated routing weights, consolidation
+  promotion (ʿilm→fahm), M6 hazard estimates: advisory today, become blocking only
+  once fixtures measure them (overview §4 honesty register).
 
 ## Later / exploring
-- Optional embedding/vector backends for retrieval and cache near-match (ADR-0005 tier).
 - `forge verify` independent-review wired into CI with provenance gating.
 - Formal/semantic verification — documented as out-of-scope for now.
 - Parametric learning channel (LoRA distillation) — deliberately out of scope (ADR-0006).

@@ -39,6 +39,17 @@ substrate** (`forge substrate` — the pre-action check). The full argument is t
 
 ## The everyday workflow
 
+The daily loop — every outcome an oracle observes lands in the team ledger, and the
+ledger informs the next task:
+
+```mermaid
+flowchart LR
+    W["work — substrate pre-checks,<br/>then edit"] --> O["oracles — forge verify ·<br/>imagine --run · CI · human accept/revert"]
+    O -->|"outcomes move claim val"| L[("team ledger<br/>.forge/ledger/")]
+    L <-->|"git + forge ledger merge"| T["teammates' ledgers"]
+    L -->|"lessons · facts · reuse hits"| W
+```
+
 ```bash
 cd your-project
 forge init                              # once per repo: emit every tool's config
@@ -79,6 +90,8 @@ Forge substrate — pre-action check
   route: Haiku 4.5 (simple) · complexity 0.15
     driven by: base cost of any task
 
+  context: complete — 4 required item(s), 1840/12000 tokens (`forge context` for the assembly)
+
   impact: 3 file(s) predicted
     - src/auth.js
     - src/login.js
@@ -400,10 +413,14 @@ Forge imagine — consequence simulation (pre-action)
   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)
+  (measure it: re-run with --run — sandboxed worktree dry-run of HEAD)
 ```
 
-It also flags predicted breaks **no test covers** — the risk you can't dry-run away.
+Add **`--run`** to actually execute that suite in a sandboxed worktree of HEAD — the
+dry-run result lands as oracle evidence on the prediction. It refuses a dirty working
+tree (your uncommitted changes wouldn't be in the run); commit/stash first or pass
+`--allow-dirty` to knowingly measure the last commit. It also flags predicted breaks
+**no test covers** — the risk you can't dry-run away.
 
 ### `forge uicheck` — deterministic UI checks
 
@@ -590,8 +607,10 @@ real spend; the `cost-budget` guard warns when a day exceeds `FORGE_COST_CEILING
 session. For learned-from-mistakes memory, just work: Cortex captures recurring
 corrections on its own.
 
-**UI work.** `forge uicheck <fg> <bg>` for exact contrast; the `ui-workflow` and
-`taste` tools for the rest.
+**UI work.** `forge uicheck contrast <fg> <bg>` for exact contrast; `forge uicheck
+design <files> --taste <style>` as the anti-slop gate (mint the project fingerprint
+first: `forge uicheck fingerprint <files> --mint`); the `ui-workflow` and `taste`
+tools for the rest.
 
 ---
 

@@ -109,6 +109,12 @@ output (see [Use it in a script](#use-it-in-a-script)).
 | `forge anchor "<goal>"` | Are my changes still on the stated goal? | flags changed files that drifted off-goal |
 | `forge verify` | Did it actually work? | runs the real tests/build, not the model's word |
 
+The wider v0.5 surface — `forge context` (budgeted assembly + completeness gate),
+`forge imagine [--run]` (predicted breaks + minimal dry-run suite), `forge diagnose`
+(doom-loop), `forge ledger` / `forge reuse` (proof-carrying memory + code cache), and
+`forge uicheck` (the design gate) — is documented with real outputs in
+[docs/GUIDE.md → Command reference](../GUIDE.md#command-reference).
+
 Real output for the two most-used:
 
 ```console
@@ -132,34 +138,21 @@ $ forge impact verifyToken
 
 ## Read the result (what to do)
 
-| Field | What it means | Do this |
-| --- | --- | --- |
-| `okToProceed: false` | task is under-specified | ask the `assumption.questions`, don't guess |
-| `route.tier` | cheapest capable model | start there; only escalate if a verifier fails |
-| `impact.impactedFiles` | predicted blast radius | read these before editing |
-| `scope.clusters` | independent vs. coupled work | split independent groups into separate sessions |
-| `memory.advisory` | past lessons for this area | context, not law — tests override it |
-| `verification.checklist` | how to prove it works | run it, show the output, then say "done" |
+Field-by-field: what each verdict means and the action to take —
+[docs/GUIDE.md → Reading substrate output](../GUIDE.md#reading-substrate-output).
+The short version: `ASK FIRST` means ask, `route` means start cheap, `impact` means
+read those files first, and `verify` means show the output before saying "done".
 
 ---
 
 ## In other AI tools
 
 Tools without a hook surface get the substrate two ways, both written by `forge init`:
-
-1. **A rule in their config** (`AGENTS.md`, `.cursor/rules`, `GEMINI.md`, …): *"Before
-   ambiguous, expensive, multi-file, or mutating work, run `forge substrate "<task>" --json`
-   (or the MCP tool `substrate_check`). If `okToProceed` is false, ask the questions first."*
-
-2. **MCP tools** any MCP-capable agent can call directly:
-
-   | MCP tool | Does |
-   | --- | --- |
-   | `substrate_check` | full pre-action check |
-   | `assumption_gate` | ask/proceed + questions |
-   | `predict_impact` | blast radius |
-   | `route_task` | model recommendation |
-   | `scope_files` | independent vs. coupled |
+a rule in their native config telling the agent to run `forge substrate "<task>" --json`
+before ambiguous/expensive/mutating work, and MCP tools (`substrate_check`,
+`assumption_gate`, `predict_impact`, `route_task`, `scope_files`) any MCP-capable agent
+can call directly. Details + the exact rule wording:
+[docs/GUIDE.md → Auto-use inside an agent](../GUIDE.md#auto-use-inside-an-agent).
 
 Forge never pretends it can force a hook into a tool that has none — it's ambient on Claude
 Code, and agent-invoked everywhere else.
@@ -228,13 +221,10 @@ auditable. Off by default; the ambient Claude Code hook stays deterministic unle
 
 ## Honest limits
 
-Heuristic, not benchmarked; the graph is regex-approximate (conservative, not a sound call
-graph); assumption detection is lexical by default (opt into a verified LLM refinement with
-`FORGE_LLM=1` — see above); auto-run needs a hook surface (ambient on Claude Code,
-agent-invoked elsewhere). What's *asserted* is safe to gate on (repo grounding, graph
-traversal, scope, routing arithmetic, test commands); everything else is *advisory* — including
-every LLM proposal, which is verified against the repo/graph/tests before it counts and is
-never trusted blind. Tests and human corrections always win. Full list:
+Heuristic, not benchmarked; the graph is regex-approximate; assumption detection is
+lexical by default (`FORGE_LLM=1` adds the verified refinement above — proposals are
+checked against the repo/graph/tests before they count, never trusted blind); auto-run
+needs a hook surface. Tests and human corrections always win. The full, canonical list:
 [docs/GUIDE.md → Honest limits](../GUIDE.md#honest-limits).
 
 ---
@@ -249,8 +239,9 @@ never trusted blind. Tests and human corrections always win. Full list:
 - **[Ecosystem map](./ecosystem_map.md)** — each capability vs. the real 2026 tool stack
 - **[Prototype source](../../research/python-prototypes/)** — the auditable Python originals
 
-**How the paper maps to what ships (all 11):** memory → `recall`/`cortex` · learning →
-`cortex` · imagination → `impact` · self-correction → `verify`/`doom-loop` ·
-impact-awareness → `atlas`/`impact` · M1 routing → `route` · M2 assumption gate →
-`preflight` · M3 decomposition → `scope` · M4 goal-anchoring → `anchor` · M5 minimality →
-`lean`/`substrate` · M6 verification → `verify`/`substrate`.
+**How the paper maps to what ships (all 11):** memory → `recall`/`cortex`/`ledger` ·
+learning → `cortex` + ledger oracles · imagination → `imagine [--run]`/`impact` ·
+self-correction → `verify`/`diagnose` · impact-awareness → `atlas`/`impact` · M1 routing →
+`route` · M2 assumption gate → `preflight`/`context` · M3 decomposition → `scope` ·
+M4 goal-anchoring → `anchor` · M5 minimality → `lean`/`uicheck design` · M6 verification →
+`verify`/`substrate`.