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/.github/workflows/bump.yml b/.github/workflows/bump.yml
new file mode 100644
index 0000000..4bd1a35
--- /dev/null
+++ b/.github/workflows/bump.yml
@@ -0,0 +1,67 @@
+# One-click release kickoff: Actions -> "Bump version" -> Run workflow.
+# Runs the tests, bumps every version field via scripts/bump.mjs (package.json,
+# package-lock.json, both plugin manifests, CITATION.cff, landing page, CHANGELOG
+# rotation), commits "chore(release): vX.Y.Z", tags vX.Y.Z, and pushes commit + tag.
+#
+# Pushing the v* tag is what normally triggers release.yml — but pushes made with
+# the default GITHUB_TOKEN deliberately do NOT trigger other workflows (GitHub's
+# recursion guard). So this workflow also dispatches release.yml on the new tag
+# explicitly, which needs `actions: write` (granted below). No PAT required.
+name: Bump version
+
+on:
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: "Bump type (auto = conventional commits since last tag: BREAKING -> major, feat -> minor, else patch)"
+        type: choice
+        default: auto
+        options:
+          - auto
+          - patch
+          - minor
+          - major
+
+permissions:
+  contents: write # push the release commit + tag
+  actions: write # dispatch release.yml on the new tag
+
+concurrency:
+  group: bump
+  cancel-in-progress: false
+
+jobs:
+  bump:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # full history + tags so "auto" can read commits since the last tag
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm test # never tag a broken tree
+      - name: Bump version fields + rotate CHANGELOG
+        id: bump
+        env:
+          BUMP: ${{ inputs.bump }}
+        run: |
+          VERSION="$(node scripts/bump.mjs "$BUMP")"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+      - name: Commit, tag, push
+        env:
+          VERSION: ${{ steps.bump.outputs.version }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add -A
+          git commit -m "chore(release): v$VERSION"
+          git tag -a "v$VERSION" -m "v$VERSION"
+          git push origin HEAD "v$VERSION"
+      - name: Trigger the release workflow on the new tag
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ steps.bump.outputs.version }}
+        run: gh workflow run release.yml --ref "v$VERSION"
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index ab35964..cd2c215 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1,5 +1,6 @@
-# CI gate for every push and PR: test matrix (Node 18/20/22), Biome lint+format, ShellCheck,
-# the zero-runtime-dependency assertion, and dependency review. All must pass to merge.
+# CI gate for every push and PR: test matrix (Node 20/22 — matches the ">=20" engines
+# field; 18 is EOL), Biome lint+format, ShellCheck, the zero-runtime-dependency assertion,
+# the version-drift guard, and dependency review. All must pass to merge.
 name: CI
 
 on:
@@ -17,7 +18,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        node: [18, 20, 22]
+        node: [20, 22]
     steps:
       - uses: actions/checkout@v7
       - uses: actions/setup-node@v6
@@ -58,6 +59,15 @@ jobs:
       - run: node -e "process.exit(Object.keys(require('./package.json').dependencies||{}).length)"
       - run: npm pack --dry-run
 
+  version-drift:
+    name: Version fields agree
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      # package.json, package-lock.json, .claude-plugin/plugin.json, .codex-plugin/plugin.json,
+      # and CITATION.cff must all carry the same version (scripts/bump.mjs keeps them in sync).
+      - run: node scripts/bump.mjs check
+
   dependency-review:
     name: Dependency review
     runs-on: ubuntu-latest
diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml
new file mode 100644
index 0000000..42b45d9
--- /dev/null
+++ b/.github/workflows/codeql.yml
@@ -0,0 +1,32 @@
+# CodeQL static analysis for the JavaScript sources (src/, hooks/, test/). Findings land
+# in Security -> Code scanning. This is CodeQL "advanced setup": if the repo ever had
+# "default setup" enabled (Settings -> Code security), disable it there so the two don't
+# fight over the same analysis slot.
+name: CodeQL
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+  schedule:
+    - cron: "23 4 * * 1" # weekly, Monday 04:23 UTC — catches new queries, not just new code
+
+permissions:
+  contents: read
+
+jobs:
+  analyze:
+    name: Analyze (javascript-typescript)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write # upload SARIF results to code scanning
+    steps:
+      - uses: actions/checkout@v7
+      - uses: github/codeql-action/init@v4
+        with:
+          languages: javascript-typescript
+          build-mode: none # interpreted — nothing to compile
+      - uses: github/codeql-action/analyze@v4
+        with:
+          category: "/language:javascript-typescript"
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 69a1f12..ab8853a 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,10 +1,17 @@
-# Push a v* tag -> test -> publish to public npm (with provenance) -> cut a GitHub Release.
-# Requires one repo secret: NPM_TOKEN (an npm "Automation" token). See docs/RELEASING.md.
+# Runs on a v* tag push, or via workflow_dispatch ON A TAG REF (bump.yml uses the
+# dispatch path because pushes made with the default GITHUB_TOKEN never trigger
+# other workflows). Flow: test -> assert tag == package.json version -> publish to
+# public npm (with provenance) -> cut a GitHub Release.
+#
+# npm publish is SKIPPED with a warning — not failed — when the NPM_TOKEN secret is
+# missing, so the GitHub Release is still created. Add an npm "Automation" token as
+# the NPM_TOKEN repo secret to enable publishing. See docs/RELEASING.md.
 name: Release
 
 on:
   push:
     tags: ["v*"]
+  workflow_dispatch: # dispatched by bump.yml with --ref vX.Y.Z; must target a tag
 
 permissions:
   contents: read
@@ -15,7 +22,15 @@ jobs:
     permissions:
       contents: write # create the GitHub Release
       id-token: write # npm provenance (supply-chain attestation)
+    env:
+      # secrets are not directly usable in step `if:`, so surface presence here.
+      HAS_NPM_TOKEN: ${{ secrets.NPM_TOKEN != '' }}
     steps:
+      - name: Assert this run targets a v* tag
+        if: github.ref_type != 'tag'
+        run: |
+          echo "::error::Release must run on a v* tag ref (got '${{ github.ref }}'). Use the 'Bump version' workflow to cut one."
+          exit 1
       - uses: actions/checkout@v7
         with:
           fetch-depth: 0 # full history so release notes can diff from the last tag
@@ -26,9 +41,24 @@ jobs:
           cache: npm
       - run: npm ci
       - run: npm test
-      - run: npm publish --provenance --access public
+      - name: Assert tag matches package.json version
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          PKG="v$(node -p "require('./package.json').version")"
+          if [ "$TAG" != "$PKG" ]; then
+            echo "::error::Tag $TAG does not match package.json version $PKG. Re-run the 'Bump version' workflow instead of tagging by hand."
+            exit 1
+          fi
+      - name: Publish to npm (with provenance)
+        if: env.HAS_NPM_TOKEN == 'true'
+        run: npm publish --provenance --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - name: Skip npm publish (NPM_TOKEN not set)
+        if: env.HAS_NPM_TOKEN != 'true'
+        run: |
+          echo "::warning::NPM_TOKEN secret is not set — SKIPPING npm publish. The GitHub Release is still created. To publish, add an npm Automation token as the NPM_TOKEN repo secret (Settings -> Secrets and variables -> Actions) and re-run this workflow. See docs/RELEASING.md."
       - name: Create GitHub Release
         env:
           GH_TOKEN: ${{ github.token }}
diff --git a/.github/workflows/repo-settings.yml b/.github/workflows/repo-settings.yml
index 8402fc2..16df971 100644
--- a/.github/workflows/repo-settings.yml
+++ b/.github/workflows/repo-settings.yml
@@ -3,15 +3,18 @@
 #
 # NOTE: editing repo settings needs an ADMIN-scoped token. The default GITHUB_TOKEN
 # cannot be granted `administration`, so add a fine-grained PAT (Administration: write,
-# Metadata: read) as the repo secret ADMIN_TOKEN. Without it the job will 403 — in that
-# case just run the two `gh` commands below locally once (they need no workflow):
+# Metadata: read) as the repo secret ADMIN_TOKEN. Without it the job SKIPS with a
+# warning (soft fail) — in that case just run the two `gh` commands below locally once
+# (they need no workflow):
 #
 #   gh repo edit CodeWithJuber/forgekit \
 #     --description "One config for every AI coding agent — cross-tool config + a cognitive substrate (memory, blast-radius, guardrails) for Claude Code, Codex, Cursor, Gemini, Aider, and more." \
 #     --homepage "https://github.com/CodeWithJuber/forgekit#readme" \
-#     --add-topic claude-code --add-topic ai-coding --add-topic ai-agents --add-topic mcp \
-#     --add-topic agents-md --add-topic cross-tool --add-topic cognitive-substrate \
-#     --add-topic developer-tools --add-topic cli --add-topic codex --add-topic cursor
+#     --add-topic ai-agents --add-topic claude-code --add-topic codex --add-topic cursor \
+#     --add-topic developer-tools --add-topic llm --add-topic memory --add-topic mcp \
+#     --add-topic agent-memory --add-topic cost-optimization --add-topic code-quality \
+#     --add-topic cli --add-topic zero-dependency --add-topic crdt --add-topic team-memory \
+#     --add-topic ai-coding --add-topic agents-md --add-topic cross-tool --add-topic cognitive-substrate
 #   gh api --method PATCH /repos/CodeWithJuber/forgekit -F has_discussions=true
 name: Repo settings
 
@@ -27,15 +30,22 @@ jobs:
     steps:
       - name: Apply About, topics, and Discussions
         env:
-          GH_TOKEN: ${{ secrets.ADMIN_TOKEN || github.token }}
+          GH_TOKEN: ${{ secrets.ADMIN_TOKEN }}
           REPO: ${{ github.repository }}
         run: |
+          if [ -z "$GH_TOKEN" ]; then
+            echo "::warning::ADMIN_TOKEN secret is not set — skipping. Editing repo settings needs a fine-grained PAT (Administration: write, Metadata: read) saved as the ADMIN_TOKEN repo secret; the default GITHUB_TOKEN cannot be granted 'administration'. Alternatively run the gh commands from this workflow's header comment locally."
+            exit 0
+          fi
           set -e
+          # 19 topics (GitHub caps at 20): discoverability terms first, project-specific last.
           gh repo edit "$REPO" \
             --description "One config for every AI coding agent — cross-tool config + a cognitive substrate (memory, blast-radius, guardrails) for Claude Code, Codex, Cursor, Gemini, Aider, and more." \
             --homepage "https://github.com/CodeWithJuber/forgekit#readme" \
-            --add-topic claude-code --add-topic ai-coding --add-topic ai-agents --add-topic mcp \
-            --add-topic agents-md --add-topic cross-tool --add-topic cognitive-substrate \
-            --add-topic developer-tools --add-topic cli --add-topic codex --add-topic cursor
+            --add-topic ai-agents --add-topic claude-code --add-topic codex --add-topic cursor \
+            --add-topic developer-tools --add-topic llm --add-topic memory --add-topic mcp \
+            --add-topic agent-memory --add-topic cost-optimization --add-topic code-quality \
+            --add-topic cli --add-topic zero-dependency --add-topic crdt --add-topic team-memory \
+            --add-topic ai-coding --add-topic agents-md --add-topic cross-tool --add-topic cognitive-substrate
           gh api --method PATCH "/repos/$REPO" -F has_discussions=true
           echo "Applied About, topics, and Discussions for $REPO."
diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml
new file mode 100644
index 0000000..45431e4
--- /dev/null
+++ b/.github/workflows/scorecard.yml
@@ -0,0 +1,35 @@
+# OSSF Scorecard: weekly supply-chain posture check (branch protection, token permissions,
+# pinned dependencies, ...). publish_results feeds the public viewer/API at
+# https://scorecard.dev/viewer/?uri=github.com/CodeWithJuber/forgekit — required for the
+# Scorecard badge. Results also land in Security -> Code scanning as SARIF.
+# Scorecard itself will flag tag-pinned actions; this repo pins to major tags and lets
+# Dependabot track them (see .github/dependabot.yml) — accepted trade-off, documented here.
+name: Scorecard
+
+on:
+  push:
+    branches: [master] # default branch only — publish_results requires it
+  schedule:
+    - cron: "30 5 * * 1" # weekly, Monday 05:30 UTC
+
+permissions: read-all
+
+jobs:
+  analysis:
+    name: Scorecard analysis
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write # upload SARIF to code scanning
+      id-token: write # sign results so scorecard.dev will publish them
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false # scorecard checks for exactly this
+      - uses: ossf/scorecard-action@v2
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          publish_results: true
+      - uses: github/codeql-action/upload-sarif@v4
+        with:
+          sarif_file: results.sarif
diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml
new file mode 100644
index 0000000..67dcc6b
--- /dev/null
+++ b/.github/workflows/security.yml
@@ -0,0 +1,30 @@
+# Secret scanning gate: gitleaks over the FULL git history on every push and PR.
+# Deliberately blocking — a real credential in the tree or history should fail the build,
+# not warn. (Rotate first, then rewrite/land; a red X is the cheap part of a leak.)
+#
+# Why this passes on our own redaction tests: test/_fixtures.js assembles secret-LOOKING
+# strings at RUNTIME via .join() precisely so no secret-format literal exists in any blob
+# for a scanner to match. Verified clean with gitleaks 8.16 across the whole history and
+# working tree before this workflow was added — no .gitleaks.toml allowlist is needed.
+name: Security
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  gitleaks:
+    name: Secret scan (gitleaks)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # gitleaks scans commit history, not just the checkout
+      - uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ github.token }} # PR comments / job summary
+          # GITLEAKS_LICENSE is only required for ORG-owned repos; this repo is user-owned.
diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml
index bb749a5..5bfb7ef 100644
--- a/.github/workflows/stale.yml
+++ b/.github/workflows/stale.yml
@@ -5,6 +5,7 @@ name: Stale
 on:
   schedule:
     - cron: "0 3 * * *"
+  workflow_dispatch: # allow a manual run to test the config
 
 permissions:
   issues: write
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..9808ddf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,8 +6,42 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-07-07
+
 ### Added
 
+- Security & OSS hardening: CodeQL, gitleaks secret-scan (blocking; verified clean on the
+  full history), and OSSF Scorecard workflows; refreshed repo topics; SECURITY.md now
+  states the supported line (0.5.x) and documents the ledger's forgery-resistance
+  properties (content-hash verification; oracle weights never trusted from records).
+- **UI fingerprints resolve CSS `var()` indirection**, so design systems declared as
+  custom properties fingerprint fully (the dashboard now reads as a 6-value 4px scale
+  with two radius levels instead of one lonely spacing value), and the five taste
+  profiles gain machine-readable constraint JSONs (`global/taste/<name>.json`) wired
+  into `forge uicheck design --taste <name>` — with auto-pickup from a
+  `forge taste`-managed DESIGN.md. Prose steers generation; the JSON is what the gate
+  checks.
+- **One-click release automation.** `scripts/bump.mjs` (node stdlib only, unit-tested)
+  bumps every version field in one shot — `package.json`, `package-lock.json`, both
+  plugin manifests, `CITATION.cff`, the landing page — rotates the CHANGELOG
+  `[Unreleased]` section under a dated heading, and prints the new version;
+  `npm run bump -- <patch|minor|major|auto>` (auto = conventional commits since the last
+  tag: BREAKING → major, feat → minor, else patch). The new `bump.yml` workflow makes a
+  release one click from the Actions tab (commit + tag + dispatch of `release.yml`);
+  `release.yml` now soft-skips npm publish when `NPM_TOKEN` is missing instead of
+  failing, and CI gained a version-drift guard (`node scripts/bump.mjs check`).
+- **Benchmark harness (`npm run bench`) + measured results doc.** `bench/bench.mjs`
+  (node stdlib only) measures the substrate primitives as medians of N runs after
+  warmup — atlas build/incremental/impact latency on this repo, ledger
+  mint+put/loadClaims/mergeDirs/val() on seeded synthetic fixtures, reuse fingerprint +
+  exact/near-LSH lookup at 100 and 1000 artifacts, `assemble()` and full
+  `substrateCheck` wall time — and writes the tables plus an environment block into
+  `reports/benchmarks.md`. The same run scores `impact()` precision/recall/F1 against a
+  committed, hand-labeled case set from this repo's real import graph
+  (`bench/impact_cases.mjs`, every reference cited; one known-miss alias case kept in on
+  purpose), reported next to — never blended with — the paper prototype's
+  mutation-derived numbers, plus a structural-only contrast with adjacent tools (note
+  stores, LLM gateways, plain RAG), every row checkable from the named source.
 - **Loop closure (P5 of the substrate-v2 plan): doom-loop diagnosis, imagination, CUSUM
   drift, checkpoint cadence.** `forge diagnose "<error>"` hashes each failure into a
   signature (line numbers, addresses, timestamps, and absolute paths normalized out) and
@@ -18,8 +52,12 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   static half of the consequence simulator (paper Eq. 4): entities → blast radius →
   predicted breaks with confidence, plus the minimal dry-run test suite via weighted greedy
   set cover (weight = file size as a duration proxy; classic ln-n approximation) and
-  `riskScore = Σ confidence` — the sandboxed worktree runner that executes the suite is the
-  P5 follow-up. `anchor.cusum()` adds the M4 one-sided CUSUM control chart (k = 0.35,
+  `riskScore = Σ confidence`. **`forge imagine --run` executes that minimal suite in a
+  sandboxed ephemeral git worktree** (HEAD-only — refused on a dirty tree unless
+  `--allow-dirty`), parses the TAP summary into per-file verdicts, always removes the
+  worktree (verified in a finally), and meters the run (`stage: "imagine"`); on this repo
+  the 8-test selected suite measured 1.3 s where the full suite takes ~60 s.
+  `anchor.cusum()` adds the M4 one-sided CUSUM control chart (k = 0.35,
   h = 1.0): sustained small drift alarms, a single exploratory spike drains back to zero.
   `verify.checkpointCadence()` prices M6's "when to check?" as the optimal-stopping
   threshold rule `n* = ⌈checkCost / (pErr·tokensPerStep·costPerToken)⌉`, clamped to
@@ -344,7 +382,10 @@ 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
+[Unreleased]: https://github.com/CodeWithJuber/forgekit/compare/v0.4.0...HEAD
+[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 <id-prefix>         # who minted a claim, every oracle outcome, per-author trust
+forge reuse query "<what you're about to build>"   # 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 <path>` 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 <spec> / mint <spec> --file <path> / stats
 forge cortex      self-correcting memory — status / why <symbol>
 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 <path-to-their-ledger>   # 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 <id>` 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/SECURITY.md b/SECURITY.md
index 8db16b1..d932055 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -2,12 +2,12 @@
 
 ## Supported Versions
 
-Only the latest release of forgekit receives security updates.
+Only the latest minor line of forgekit receives security updates.
 
-| Version  | Supported |
-| -------- | --------- |
-| latest   | ✅ Yes    |
-| < latest | ❌ No     |
+| Version | Supported |
+| ------- | --------- |
+| 0.5.x   | ✅ Yes    |
+| < 0.5   | ❌ No     |
 
 ## Reporting a Vulnerability
 
@@ -35,19 +35,43 @@ supply-chain risk — always review a third-party skill/plugin before installing
 
 ## Threat model (what's in and out of scope)
 
-**In scope:** the forgekit CLI and its emitters/guards; the `skill-gate` scanner; secret
-handling in guards; the install channels; the supply chain of our own dev dependencies.
+**In scope:** the forgekit CLI and its emitters/guards; the `skill-gate` scanner
+(including prompt-injection patterns `forge scan` should catch but doesn't); secret
+handling in guards; the published npm package (`@codewithjuber/forgekit`) and its
+install channels; the team ledger's integrity properties (below); the supply chain of
+our own dev dependencies.
 
 **Out of scope:** vulnerabilities in the third-party tools Forge configures (Claude Code,
 Cursor, Codex, …) or the MCP servers/skills you choose to install — report those upstream.
 Forge reduces risk (vetting before install, secret redaction, sandbox wiring) but is not
 itself a sandbox.
 
+## Ledger forgery resistance
+
+The team ledger (proof-carrying memory) is shared, mergeable state — so it is designed to
+resist forged confidence, not just corruption:
+
+- **Content-addressed claims.** A claim's id *is* the hash of its canonical JSON bytes.
+  `forge ledger verify` recomputes every content hash and reports any record whose bytes
+  don't match its address as tampered/invalid.
+- **Oracle weights are never trusted from records.** `val()` re-reads each oracle's weight
+  from the in-code `ORACLES` table at read time; a `w` field stored in an evidence record
+  is audit metadata only. A forged record cannot grant itself extra weight.
+- **Append-only, hash-deduped evidence logs.** Merge is a conflict-free set union; corrupt
+  or unknown-oracle lines are skipped rather than counted. Confidence is earned from valid
+  evidence, never asserted by a record.
+
+Protocol details: [docs/plans/substrate-v2/01-pcm-protocol.md](./docs/plans/substrate-v2/01-pcm-protocol.md).
+A way to make the ledger report a `val` its evidence doesn't support is a security bug —
+report it.
+
 ## Hardening for maintainers
 
 - Require 2FA for anyone with write access; use least-privilege tokens.
 - Branch-protect `master`: require PR + green CI + review; block force-push.
-- Enable GitHub secret scanning and CodeQL **default setup** (Settings → Code security).
+- Enable GitHub secret scanning + push protection (Settings → Code security). In CI:
+  CodeQL (`.github/workflows/codeql.yml` — advanced setup, so keep *default setup* off),
+  gitleaks (`security.yml`, blocking), and OSSF Scorecard (`scorecard.yml`).
 - Dependency updates land via Dependabot (7-day cooldown); the `dependency-review` job blocks
   PRs that introduce known-vulnerable or disallowed-license dependencies.
 - Releases publish from CI with npm provenance (OIDC) + a scoped `NPM_TOKEN` — never a
diff --git a/bench/bench.mjs b/bench/bench.mjs
new file mode 100644
index 0000000..1e8b693
--- /dev/null
+++ b/bench/bench.mjs
@@ -0,0 +1,524 @@
+// forge bench — deterministic micro/meso benchmarks for the substrate primitives.
+// Discipline (docs/plans/substrate-v2/05-cost-model.md, whitepaper C6): a number is an
+// assumption until measured. Everything here is MEASURED on the machine that runs it —
+// median of N timed runs after warmup, environment recorded next to every table, no
+// projections, no blending with the paper's prototype numbers.
+//
+// Node stdlib only. Run: `npm run bench`. Output: a table on stdout AND the measured
+// section of reports/benchmarks.md (between the BENCH:RESULTS markers — the prose
+// around it is hand-written and not touched by this script).
+//
+// What is benchmarked on what:
+//  - atlas/context/substrate run against a COPY of this repo in os.tmpdir (bench/
+//    excluded so the harness's own imports don't perturb the impact-quality eval;
+//    .forge excluded so the copy starts cold). The copy is deleted afterwards.
+//  - ledger/reuse run against synthetic fixtures generated with a seeded PRNG
+//    (mulberry32) — deterministic across runs and machines, built in os.tmpdir,
+//    cleaned up.
+import { execFileSync } from "node:child_process";
+import { cpSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { arch, cpus, platform, tmpdir, totalmem } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { performance } from "node:perf_hooks";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { build as buildAtlas, impact } from "../src/atlas.js";
+import { assemble } from "../src/context.js";
+import { evalImpact } from "../src/eval.js";
+import { mintClaim, outcomeRecord, val } from "../src/ledger.js";
+import { appendEvidence, loadClaims, mergeDirs, putClaim } from "../src/ledger_store.js";
+import { artifactClaim, fingerprint, lookup } from "../src/reuse.js";
+import { substrateCheck } from "../src/substrate.js";
+import { IMPACT_CASES } from "./impact_cases.mjs";
+
+// ---------------------------------------------------------------------------
+// Pure helpers (exported for the smoke test — no benchmark runs on import).
+// ---------------------------------------------------------------------------
+
+/** Median of a sample list (even n → mean of the middle two). */
+export function median(xs) {
+  if (!xs.length) return NaN;
+  const s = [...xs].sort((a, b) => a - b);
+  const mid = s.length >> 1;
+  return s.length % 2 ? s[mid] : (s[mid - 1] + s[mid]) / 2;
+}
+
+/** Nearest-rank p95 (with n < 20 this is simply the max — say so, don't smooth). */
+export function p95(xs) {
+  if (!xs.length) return NaN;
+  const s = [...xs].sort((a, b) => a - b);
+  return s[Math.min(s.length - 1, Math.ceil(0.95 * s.length) - 1)];
+}
+
+/** ms with sensible precision: 0.042 ms / 1.3 ms / 412 ms / 1503 ms. */
+export function fmtMs(ms) {
+  if (!Number.isFinite(ms)) return "n/a";
+  if (ms < 0.1) return `${ms.toFixed(3)} ms`;
+  if (ms < 10) return `${ms.toFixed(2)} ms`;
+  if (ms < 100) return `${ms.toFixed(1)} ms`;
+  return `${Math.round(ms)} ms`;
+}
+
+/** Integer rate with thousands separators: 12,340/s. */
+export function fmtRate(perSec) {
+  if (!Number.isFinite(perSec)) return "n/a";
+  return `${Math.round(perSec).toLocaleString("en-US")}/s`;
+}
+
+/** Plain monospace table (also valid Markdown when `markdown` is set). */
+export function formatTable(headers, rows, { markdown = false } = {}) {
+  const all = [headers, ...rows.map((r) => r.map(String))];
+  const widths = headers.map((_, c) => Math.max(...all.map((r) => (r[c] ?? "").length)));
+  const line = (r, pad = " ") =>
+    `|${r.map((cell, c) => ` ${(cell ?? "").padEnd(widths[c], pad)} `).join("|")}|`;
+  const sep = markdown
+    ? `|${widths.map((w) => `${"-".repeat(w + 2)}`).join("|")}|`
+    : line(
+        headers.map(() => ""),
+        "-",
+      );
+  return [line(headers), sep, ...rows.map((r) => line(r.map(String)))].join("\n");
+}
+
+/** Time fn: `warmup` unmeasured runs, then `runs` measured ones. Returns samples +
+ *  stats. fn receives a counter that NEVER repeats across warmup and measured runs,
+ *  so fixtures keyed by it (fresh directories) can't collide — a measured run must
+ *  never silently hit a warmup run's already-written state. */
+export function timeIt(fn, { runs = 5, warmup = 1 } = {}) {
+  let k = 0;
+  for (let i = 0; i < warmup; i++) fn(k++);
+  const samples = [];
+  for (let i = 0; i < runs; i++) {
+    const t0 = performance.now();
+    fn(k++);
+    samples.push(performance.now() - t0);
+  }
+  return { samples, median: median(samples), p95: p95(samples), runs, warmup };
+}
+
+// Deterministic PRNG — fixture generation must be identical on every run/machine.
+export function mulberry32(seed) {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+const VOCAB =
+  `add remove update handle parse render validate merge sort filter cache load store fetch
+   compute batch stream retry queue flush index search rank group split join trim wrap
+   pagination cursor listing endpoint request response payload schema record entry field
+   column widget layout panel button badge banner report summary metric signal window`
+    .split(/\s+/)
+    .filter(Boolean);
+
+/** Deterministic prose-like spec of `len` tokens (no idents/paths/numbers, no secrets). */
+export function makeSpec(rand, len = 40) {
+  const words = [];
+  for (let i = 0; i < len; i++) words.push(VOCAB[Math.floor(rand() * VOCAB.length)]);
+  return words.join(" ");
+}
+
+// ---------------------------------------------------------------------------
+// Fixture builders
+// ---------------------------------------------------------------------------
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = dirname(HERE);
+const SKIP_COPY = new Set(["node_modules", "bench"]);
+
+function copyRepo() {
+  const dst = mkdtempSync(join(tmpdir(), "forge-bench-repo-"));
+  cpSync(REPO_ROOT, dst, {
+    recursive: true,
+    filter: (src) => {
+      const name = basename(src);
+      return !(SKIP_COPY.has(name) || (name.startsWith(".") && src !== REPO_ROOT));
+    },
+  });
+  return dst;
+}
+
+function fillLedger(dir, { count, offset = 0, evidenceEvery = 4 }) {
+  for (let i = 0; i < count; i++) {
+    const n = offset + i;
+    const minted = mintClaim({
+      kind: "fact",
+      body: { name: `bench-fact-${n}`, text: `deterministic bench fact number ${n}` },
+      scope: { level: "repo" },
+      provenance: { agent: "bench", author: "bench" },
+      t: 0,
+    });
+    if (!minted.ok) throw new Error(minted.reason);
+    putClaim(dir, minted.claim);
+    if (n % evidenceEvery === 0) {
+      const o = outcomeRecord({
+        oracle: "test.run",
+        result: "confirm",
+        ref: `bench:run:${n}`,
+        author: "bench",
+        t: 0,
+      });
+      if (o.ok) appendEvidence(dir, minted.claim.id, o.outcome);
+    }
+  }
+}
+
+/** n in-memory artifact claims, each with one test.run confirm so it clears SERVE_FLOOR. */
+function makeArtifacts(n) {
+  const rand = mulberry32(42);
+  const claims = [];
+  const specs = [];
+  for (let i = 0; i < n; i++) {
+    const spec = makeSpec(rand, 40);
+    specs.push(spec);
+    const minted = artifactClaim(
+      { spec, code: { inline: `// artifact ${i}` }, iface: [`benchExport${i}`], deps: [] },
+      0,
+    );
+    if (!minted.ok) throw new Error(minted.reason);
+    const o = outcomeRecord({
+      oracle: "test.run",
+      result: "confirm",
+      ref: `bench:artifact:${i}`,
+      author: "bench",
+      t: 0,
+    });
+    minted.claim.evidence = o.ok ? [o.outcome] : [];
+    claims.push(minted.claim);
+  }
+  return { claims, specs };
+}
+
+const coldSketches = (claims) => {
+  for (const c of claims) delete c._sketch;
+};
+
+// ---------------------------------------------------------------------------
+// The run
+// ---------------------------------------------------------------------------
+
+function environment() {
+  let commit = "unknown";
+  try {
+    commit = execFileSync("git", ["rev-parse", "HEAD"], { cwd: REPO_ROOT }).toString().trim();
+  } catch {}
+  return {
+    node: process.version,
+    cpu: cpus()[0]?.model ?? "unknown",
+    cores: cpus().length,
+    memGB: Math.round(totalmem() / 2 ** 30),
+    platform: platform(),
+    arch: arch(),
+    commit,
+    date: new Date().toISOString(),
+  };
+}
+
+function runBenchmarks() {
+  process.env.FORGE_AUTHOR = "bench"; // no git subprocess variance inside timed loops
+  const cleanup = [];
+  const rows = []; // [suite, benchmark, median, p95, runs, notes]
+  const push = (suite, name, t, notes = "") =>
+    rows.push([suite, name, fmtMs(t.median), fmtMs(t.p95), `${t.runs}`, notes]);
+
+  try {
+    // --- atlas: build / incremental / impact query, on a copy of this repo ---------
+    const repo = copyRepo();
+    cleanup.push(repo);
+    let atlas = null;
+    const tFull = timeIt(
+      () => {
+        rmSync(join(repo, ".forge"), { recursive: true, force: true });
+        atlas = buildAtlas({ root: repo });
+      },
+      { runs: 5, warmup: 1 },
+    );
+    push(
+      "atlas",
+      "full build (this repo)",
+      tFull,
+      `${atlas.files} files, ${atlas.symbols.length} symbols, ${atlas.edges.length} edges`,
+    );
+    const tIncr = timeIt(
+      () => {
+        atlas = buildAtlas({ root: repo });
+      },
+      { runs: 5, warmup: 1 },
+    );
+    push("atlas", "incremental rebuild (unchanged)", tIncr, "per-file hash cache hit");
+    const target = "claimText";
+    let impactResult = impact(atlas, target); // warms the memoized adjacency index
+    const tImpact = timeIt(
+      () => {
+        impactResult = impact(atlas, target);
+      },
+      { runs: 30, warmup: 3 },
+    );
+    push(
+      "atlas",
+      `impact("${target}") (warm adjacency)`,
+      tImpact,
+      `${impactResult.impactedFiles.length} files impacted`,
+    );
+
+    // --- impact-oracle quality on the committed labeled cases ----------------------
+    const quality = evalImpact(atlas, IMPACT_CASES);
+
+    // --- ledger: mint+put, loadClaims, mergeDirs, val -------------------------------
+    const ledgerScratch = mkdtempSync(join(tmpdir(), "forge-bench-ledger-"));
+    cleanup.push(ledgerScratch);
+    const N_CLAIMS = 1000;
+    let mintDir = "";
+    const tMint = timeIt(
+      (i) => {
+        mintDir = join(ledgerScratch, `mint-${i}`);
+        fillLedger(mintDir, { count: N_CLAIMS });
+      },
+      { runs: 5, warmup: 1 }, // disk-bound: 5 runs, median damps fs-cache noise
+    );
+    push("ledger", `mint+put ${N_CLAIMS} claims`, tMint, fmtRate(N_CLAIMS / (tMint.median / 1000)));
+    let claims1k = [];
+    const tLoad = timeIt(
+      () => {
+        claims1k = loadClaims(mintDir);
+      },
+      { runs: 5, warmup: 1 },
+    );
+    push("ledger", `loadClaims at ${claims1k.length} claims`, tLoad, "full state from disk");
+    const srcA = join(ledgerScratch, "replica-a");
+    const srcB = join(ledgerScratch, "replica-b");
+    fillLedger(srcA, { count: 500, offset: 0 });
+    fillLedger(srcB, { count: 500, offset: 250 }); // 250 shared, 250 new each side
+    const MERGE_RUNS = { runs: 3, warmup: 1 };
+    for (let k = 0; k < MERGE_RUNS.runs + MERGE_RUNS.warmup; k++)
+      cpSync(srcA, join(ledgerScratch, `merge-${k}`), { recursive: true }); // setup, untimed
+    let mergeStats = { claims: 0, records: 0 };
+    const tMerge = timeIt((k) => {
+      mergeStats = mergeDirs(join(ledgerScratch, `merge-${k}`), srcB);
+    }, MERGE_RUNS);
+    push(
+      "ledger",
+      "mergeDirs 2×500-claim replicas (250 shared)",
+      tMerge,
+      `+${mergeStats.claims} claims, +${mergeStats.records} records`,
+    );
+    let valSum = 0;
+    const tVal = timeIt(
+      () => {
+        valSum = 0;
+        for (const c of claims1k) valSum += val(c, 30);
+      },
+      { runs: 20, warmup: 2 },
+    );
+    push(
+      "ledger",
+      `val() over ${claims1k.length} claims`,
+      tVal,
+      `${fmtRate(claims1k.length / (tVal.median / 1000))} (mean val ${(valSum / claims1k.length).toFixed(2)})`,
+    );
+
+    // --- reuse: fingerprint throughput, lookup at 100 and 1000 artifacts -----------
+    const rand = mulberry32(7);
+    const fpSpecs = Array.from({ length: 2000 }, () => makeSpec(rand, 40));
+    const tFp = timeIt(
+      () => {
+        for (const s of fpSpecs) fingerprint(s);
+      },
+      { runs: 5, warmup: 1 },
+    );
+    push(
+      "reuse",
+      `fingerprint ${fpSpecs.length} specs`,
+      tFp,
+      fmtRate(fpSpecs.length / (tFp.median / 1000)),
+    );
+    for (const n of [100, 1000]) {
+      const { claims, specs } = makeArtifacts(n);
+      const exactQ = specs[n >> 1];
+      const nearQ = `${specs[n >> 1]} gently`; // superset tokens → Jaccard ≈ 0.97 → near tier
+      let hit = null;
+      const tExact = timeIt(
+        () => {
+          coldSketches(claims); // fresh-process behavior: no memoized sketches
+          hit = lookup(claims, exactQ);
+        },
+        { runs: 10, warmup: 2 },
+      );
+      push("reuse", `lookup exact @ ${n} artifacts`, tExact, `tier=${hit.tier}`);
+      const tNear = timeIt(
+        () => {
+          coldSketches(claims);
+          hit = lookup(claims, nearQ);
+        },
+        { runs: 5, warmup: 1 },
+      );
+      push(
+        "reuse",
+        `lookup near (LSH) @ ${n} artifacts`,
+        tNear,
+        `tier=${hit.tier}, j=${hit.jaccard?.toFixed(2) ?? "-"}`,
+      );
+    }
+
+    // --- context: assemble() on this repo for a representative task ----------------
+    const task =
+      "add a keywords field to `mintClaim` in src/ledger.js and update `claimText` and `val`";
+    let ctx = null;
+    const tCtx = timeIt(
+      () => {
+        ctx = assemble(repo, task, { atlas });
+      },
+      { runs: 10, warmup: 2 },
+    );
+    push(
+      "context",
+      "assemble() (this repo, 3-symbol task)",
+      tCtx,
+      `${ctx.tokens}/${ctx.budget} tokens, ${ctx.required.length} required, ${ctx.ok ? "complete" : "incomplete"}`,
+    );
+
+    // --- substrate: full substrateCheck wall time -----------------------------------
+    let sub = null;
+    const tSub = timeIt(
+      () => {
+        sub = substrateCheck(repo, task, { allowBuild: true, llm: false });
+      },
+      { runs: 3, warmup: 1 },
+    );
+    push(
+      "substrate",
+      "substrateCheck (allowBuild, llm off)",
+      tSub,
+      `${sub.impact?.impactedFiles?.length ?? 0} impacted files, route ${sub.route?.tier ?? "?"}`,
+    );
+
+    return { rows, quality };
+  } finally {
+    for (const dir of cleanup) rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Reporting
+// ---------------------------------------------------------------------------
+
+const RESULT_HEADERS = ["suite", "benchmark", "median", "p95", "runs", "notes"];
+const QUALITY_HEADERS = ["case (target)", "precision", "recall", "F1", "predicted", "truth"];
+const SERIES_HEADERS = ["series", "precision", "recall", "F1", "ground truth"];
+
+/** Paper prototype vs this repo — two different methodologies, side by side and
+ *  labeled, NEVER averaged or blended. The paper row is a constant from the
+ *  whitepaper (Figure 5 / deliverable-package.md), not something this harness ran. */
+export function seriesRows(quality) {
+  return [
+    [
+      "paper prototype (Python, mutation-derived)",
+      "0.63",
+      "1.00",
+      "0.75",
+      "mutation testing against a real suite",
+    ],
+    [
+      "this repo (regex atlas, hand-labeled)",
+      quality.oracle.precision.toFixed(2),
+      quality.oracle.recall.toFixed(2),
+      quality.oracle.f1.toFixed(2),
+      `${quality.n} hand-labeled cases (bench/impact_cases.mjs)`,
+    ],
+  ];
+}
+
+export function qualityRows(quality) {
+  const rows = quality.perCase.map((p) => [
+    p.target,
+    p.oracle.precision.toFixed(2),
+    p.oracle.recall.toFixed(2),
+    p.oracle.f1.toFixed(2),
+    `${p.oracle.predicted}`,
+    `${p.oracle.groundTruth}`,
+  ]);
+  rows.push([
+    `mean of ${quality.n}`,
+    quality.oracle.precision.toFixed(2),
+    quality.oracle.recall.toFixed(2),
+    quality.oracle.f1.toFixed(2),
+    "",
+    "",
+  ]);
+  return rows;
+}
+
+const BEGIN = "<!-- BENCH:RESULTS:BEGIN (generated by bench/bench.mjs — do not edit) -->";
+const END = "<!-- BENCH:RESULTS:END -->";
+
+function resultsMarkdown(env, rows, quality) {
+  const q = qualityRows(quality);
+  return [
+    BEGIN,
+    "",
+    "### Environment (machine section)",
+    "",
+    "```json",
+    JSON.stringify(env, null, 2),
+    "```",
+    "",
+    "### Measured results",
+    "",
+    formatTable(RESULT_HEADERS, rows, { markdown: true }),
+    "",
+    "### Impact-oracle quality (hand-labeled cases, this repo)",
+    "",
+    formatTable(QUALITY_HEADERS, q, { markdown: true }),
+    "",
+    `Edited-file-only baseline recall over the same cases: **${quality.baseline.recall.toFixed(2)}**.`,
+    "",
+    "Two methodologies, side by side — different codebases, different ground-truth",
+    "derivations, so the rows are comparable in spirit only and are never blended:",
+    "",
+    formatTable(SERIES_HEADERS, seriesRows(quality), { markdown: true }),
+    "",
+    END,
+  ].join("\n");
+}
+
+function writeReport(env, rows, quality) {
+  const path = join(REPO_ROOT, "reports", "benchmarks.md");
+  const section = resultsMarkdown(env, rows, quality);
+  let text;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch {
+    text = `# Benchmarks\n\n${BEGIN}\n${END}\n`;
+  }
+  const begin = text.indexOf(BEGIN);
+  const end = text.indexOf(END);
+  text =
+    begin !== -1 && end !== -1
+      ? text.slice(0, begin) + section + text.slice(end + END.length)
+      : `${text.trimEnd()}\n\n${section}\n`;
+  writeFileSync(path, text);
+  return path;
+}
+
+function main() {
+  const env = environment();
+  const t0 = performance.now();
+  const { rows, quality } = runBenchmarks();
+  const total = performance.now() - t0;
+  process.stdout.write(
+    `forge bench — median of N runs after warmup (node ${env.node}, ${env.cpu})\n\n`,
+  );
+  process.stdout.write(`${formatTable(RESULT_HEADERS, rows)}\n\n`);
+  process.stdout.write("impact-oracle quality (hand-labeled cases, this repo):\n\n");
+  process.stdout.write(`${formatTable(QUALITY_HEADERS, qualityRows(quality))}\n\n`);
+  process.stdout.write("vs the paper prototype (different methodology — never blended):\n\n");
+  process.stdout.write(`${formatTable(SERIES_HEADERS, seriesRows(quality))}\n\n`);
+  const path = writeReport(env, rows, quality);
+  process.stdout.write(`wrote ${path} (total bench time ${fmtMs(total)})\n`);
+}
+
+const isMain = process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url;
+if (isMain) main();
diff --git a/bench/impact_cases.mjs b/bench/impact_cases.mjs
new file mode 100644
index 0000000..a11bd14
--- /dev/null
+++ b/bench/impact_cases.mjs
@@ -0,0 +1,103 @@
+// Labeled impact-oracle cases derived from THIS repo's real import graph.
+//
+// Labeling rule (hand-verified by reading the actual source, then double-checked with
+// grep): `expected` = the defining file PLUS every file with a DIRECT reference to the
+// target symbol — an `import { X }` with a use, or a call site of `X(`. The defining
+// file is always labeled: an edit to the target trivially impacts its own file (same
+// convention as the existing fixture in test/eval.test.js and the paper's mutation
+// methodology, where the mutated file itself counts). Transitive dependents are
+// deliberately NOT labeled: the oracle predicts them (its job — err toward inclusion),
+// so they count against precision here, exactly like the paper's mutation-derived
+// scoring penalized over-approximation. Every label is grep-checkable by anyone.
+//
+// These cases are evaluated against an atlas built over a copy of this repo that
+// EXCLUDES bench/ — otherwise the harness's own imports of these symbols would
+// perturb the measurement it is taking.
+//
+// Verified references, per case (as of the commit this file lands in):
+//
+// normalizeSpec (src/reuse.js)
+//   - src/reuse.js        defines it; fingerprint() and artifactClaim() call it
+//   - test/reuse.test.js  imports { normalizeSpec } and calls it directly
+//
+// evalImpact (src/eval.js)
+//   - src/eval.js         defines it (no other same-file caller)
+//   - test/eval.test.js   imports { evalImpact } and calls it — the only referencer
+//
+// isStale (src/atlas.js)
+//   - src/atlas.js        defines it
+//   - src/verify.js       imports { isStale } from ./atlas.js and calls it
+//   - src/doctor.js       imports { isStale } from ./atlas.js and calls it
+//   - test/atlas.test.js  imports { isStale } and calls it
+//
+// mergeStates (src/ledger.js)
+//   - src/ledger.js       defines it
+//   - src/ledger_store.js imports { mergeStates } (importState calls it)
+//   - test/ledger.test.js imports { mergeStates } and calls it
+//
+// claimText (src/ledger.js)
+//   - src/ledger.js       defines it; sketchOf() calls it (same-file caller)
+//   - src/context.js      imports { claimText } and calls it
+//   - src/dash.js         imports { claimText } and calls it
+//   - src/cli.js          dynamic-imports { claimText } and calls it
+//   - test/ledger.test.js imports { claimText } and calls it
+//   (test/dash.test.js mentions the name only inside an assertion message — a string,
+//    not a reference — so it is NOT labeled as a dependent.)
+//
+// contentHash (src/util.js) — the deliberately hard case: wide fan-out plus one
+// reference the regex atlas is KNOWN to miss (src/atlas.js binds it to an alias,
+// `const hash = contentHash;`, with no call parentheses — and the JS import regex
+// captures module paths, not named bindings — so no edge exists; that is a real,
+// documented false negative, kept in the labels on purpose).
+//   - src/util.js         defines it
+//   - src/atlas.js        imports { contentHash }, aliases it (const hash = contentHash)
+//   - src/cortex_hook.js  imports { contentHash } and calls it
+//   - src/diagnose.js     imports { contentHash } and calls it
+//   - src/ledger.js       imports { contentHash } and calls it
+//   - src/reuse.js        imports { contentHash } and calls it
+
+export const IMPACT_CASES = [
+  {
+    target: "normalizeSpec",
+    expected: ["src/reuse.js", "test/reuse.test.js"],
+    editedFile: "src/reuse.js",
+  },
+  {
+    target: "evalImpact",
+    expected: ["src/eval.js", "test/eval.test.js"],
+    editedFile: "src/eval.js",
+  },
+  {
+    target: "isStale",
+    expected: ["src/atlas.js", "src/verify.js", "src/doctor.js", "test/atlas.test.js"],
+    editedFile: "src/atlas.js",
+  },
+  {
+    target: "mergeStates",
+    expected: ["src/ledger.js", "src/ledger_store.js", "test/ledger.test.js"],
+    editedFile: "src/ledger.js",
+  },
+  {
+    target: "claimText",
+    expected: [
+      "src/ledger.js",
+      "src/context.js",
+      "src/dash.js",
+      "src/cli.js",
+      "test/ledger.test.js",
+    ],
+    editedFile: "src/ledger.js",
+  },
+  {
+    target: "contentHash",
+    expected: [
+      "src/util.js",
+      "src/atlas.js",
+      "src/cortex_hook.js",
+      "src/diagnose.js",
+      "src/ledger.js",
+      "src/reuse.js",
+    ],
+    editedFile: "src/util.js",
+  },
+];
diff --git a/biome.json b/biome.json
index 19e1794..1a74a63 100644
--- a/biome.json
+++ b/biome.json
@@ -3,7 +3,7 @@
   "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true },
   "files": {
     "ignoreUnknown": true,
-    "includes": ["src/**", "test/**"]
+    "includes": ["src/**", "test/**", "scripts/**", "bench/**"]
   },
   "formatter": {
     "enabled": true,
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 <symbol>` shows the lessons that would be injected when you touch it.
 
-### `forge uicheck <fg> <bg>` — 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 <id-prefix>` 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 <path>` 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 "<text>"` ranks live claims by the
+paper's Eq. 3; `show <id>` 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 "<task>"` — 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 <tokens>` tightens the window; a tight budget downgrades granularity
+instead of silently dropping coverage.
+
+### `forge diagnose "<error>"` — 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 "<task>"` — 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 <fg> <bg>`** — exact WCAG math, asserted, never guessed (bare
+`forge uicheck <fg> <bg>` still works):
+
+```console
+$ forge uicheck contrast "#777" "#fff"
   contrast #777 on #fff: 4.48:1  →  fail (FAILS AA)
 ```
 
+**`fingerprint <file...> [--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 <file...>`** — 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 <path>` | 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/docs/RELEASING.md b/docs/RELEASING.md
index 151d127..ae35080 100644
--- a/docs/RELEASING.md
+++ b/docs/RELEASING.md
@@ -1,46 +1,99 @@
 # Releasing Forge
 
-Releases are automated by [`.github/workflows/release.yml`](../.github/workflows/release.yml):
-**push a `v*` tag → it runs the tests, publishes to public npm (with provenance), and
-cuts a GitHub Release** with auto-generated notes.
+Releases are one click. Two workflows do everything:
 
-## One-time setup (maintainer)
+1. [`bump.yml`](../.github/workflows/bump.yml) — **Actions → "Bump version" → Run
+   workflow**. It runs the tests, bumps every version field, rotates the CHANGELOG,
+   commits `chore(release): vX.Y.Z`, tags `vX.Y.Z`, pushes both, and kicks off the
+   release workflow on the new tag.
+2. [`release.yml`](../.github/workflows/release.yml) — runs on any `v*` tag: tests →
+   npm publish (with provenance, if `NPM_TOKEN` is set) → GitHub Release with
+   auto-generated notes.
 
-The workflow needs a single secret to publish:
+## The one-click flow
 
-1. Create an [npmjs.com](https://www.npmjs.com/) account and make sure it can publish to
-   the `@codewithjuber` scope.
+Go to **Actions → Bump version → Run workflow** and pick a bump type:
+
+| choice  | effect                                                                       |
+| ------- | ---------------------------------------------------------------------------- |
+| `auto`  | derived from conventional commits since the last tag: `BREAKING CHANGE` / `type!:` → major, `feat:` → minor, anything else → patch. Falls back to the CHANGELOG `[Unreleased]` body (BREAKING → major, `### Added` → minor, other content → patch). |
+| `patch` / `minor` / `major` | explicit                                                       |
+
+What happens, in order:
+
+1. `npm ci && npm test` — a broken tree is never tagged.
+2. `node scripts/bump.mjs <choice>` updates **every** version field:
+   `package.json`, `package-lock.json` (both fields), `.claude-plugin/plugin.json`,
+   `.codex-plugin/plugin.json`, `CITATION.cff` (version + release date), the landing
+   page footer, and moves the CHANGELOG `[Unreleased]` section under
+   `## [X.Y.Z] - <today>` (compare links included).
+3. Commit `chore(release): vX.Y.Z`, annotated tag `vX.Y.Z`, push commit + tag.
+4. `gh workflow run release.yml --ref vX.Y.Z`. (This explicit dispatch exists because
+   pushes made with the default `GITHUB_TOKEN` intentionally do **not** trigger other
+   workflows — GitHub's recursion guard. A tag pushed by a human still triggers
+   `release.yml` the normal way.)
+
+`release.yml` then re-runs the tests, asserts the tag matches `package.json`, publishes
+`@codewithjuber/forgekit@X.Y.Z` to public npm with provenance, and creates the GitHub
+Release. Verify:
+
+- npm: <https://www.npmjs.com/package/@codewithjuber/forgekit>
+- releases: <https://github.com/CodeWithJuber/forgekit/releases>
+
+## NPM_TOKEN setup (one-time, optional but recommended)
+
+Publishing needs one repo secret:
+
+1. Create an [npmjs.com](https://www.npmjs.com/) account that can publish to the
+   `@codewithjuber` scope.
 2. Generate an **Automation** access token (npm → Access Tokens → Generate → *Automation*).
-3. Add it to the repo: **Settings → Secrets and variables → Actions → New repository
+3. Add it as a repo secret: **Settings → Secrets and variables → Actions → New repository
    secret**, name **`NPM_TOKEN`**.
 
-That's the only manual step. Without it the publish step fails; everything else still runs.
+**Soft-skip behavior:** if `NPM_TOKEN` is missing, `release.yml` does **not** fail — it
+skips the npm publish with a loud warning and still creates the GitHub Release. Add the
+token later and re-run the workflow from the release tag: `npm publish` refuses to
+overwrite an existing version, so re-runs are safe and only the missing step takes effect.
 
-## Cutting a release
+## Local / manual usage
 
 ```bash
-# 1. bump the version (updates package.json + package-lock.json, no tag yet)
-npm version minor --no-git-tag-version      # or: patch / major
+npm run bump -- patch        # or minor / major / auto — edits files, prints new version
+npm run bump -- auto --dry-run   # compute only, write nothing
+node scripts/bump.mjs check  # assert all version fields agree (same guard CI runs)
+npm pack --dry-run           # inspect exactly what would ship to npm
+```
 
-# 2. move the [Unreleased] notes into a new dated section in CHANGELOG.md, then commit
-git add -A && git commit -m "chore(release): v$(node -p "require('./package.json').version")"
+If you bump locally instead of via the Actions tab, finish the job by hand — commit,
+tag, push (a human-pushed tag *does* trigger `release.yml`):
 
-# 3. tag and push — this is what triggers the release workflow
+```bash
 V="v$(node -p "require('./package.json').version")"
+git add -A && git commit -m "chore(release): $V"
 git tag -a "$V" -m "$V"
 git push origin master "$V"
 ```
 
-The workflow then publishes `@codewithjuber/forgekit@<version>` to npm and creates the
-matching GitHub Release. Verify:
+## Guard rails
 
-- npm: <https://www.npmjs.com/package/@codewithjuber/forgekit>
-- releases: <https://github.com/CodeWithJuber/forgekit/releases>
+- **CI version-drift guard**: `node scripts/bump.mjs check` fails CI if `package.json`,
+  `package-lock.json`, `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, or
+  `CITATION.cff` disagree about the version.
+- **Tag/version assert**: `release.yml` refuses a tag that doesn't match `package.json`
+  (hand-rolled tags that skipped the bump script fail fast with a clear error).
+- `scripts/bump.mjs` refuses to rotate the CHANGELOG onto a version that already has a
+  section, and errors when `auto` finds nothing to release.
+
+## Related workflow secrets
+
+- `NPM_TOKEN` (above) — npm publish; missing = publish skipped, release still cut.
+- `ADMIN_TOKEN` — only used by `repo-settings.yml` (repo description/topics/Discussions
+  need a fine-grained PAT with *Administration: write*; the default `GITHUB_TOKEN`
+  cannot get that scope). Missing = that workflow skips with a warning; the equivalent
+  `gh` commands are in its header comment.
 
-## Notes
+## Semver notes
 
-- **Semver**: `patch` = fixes, `minor` = new commands/flags (backward compatible),
-  `major` = breaking changes. Pre-`1.0`, breaking changes may ship in a `minor`.
-- Consumers install with no token: `npm install -g @codewithjuber/forgekit`.
-- Re-running a failed release is safe — `npm publish` refuses to overwrite a version that
-  already exists, so only the missing steps take effect.
+`patch` = fixes, `minor` = new commands/flags (backward compatible), `major` = breaking
+changes. Pre-`1.0`, breaking changes may ship in a `minor`. Consumers install with no
+token: `npm install -g @codewithjuber/forgekit`.
diff --git a/global/taste/brutalist.json b/global/taste/brutalist.json
new file mode 100644
index 0000000..35b9d9c
--- /dev/null
+++ b/global/taste/brutalist.json
@@ -0,0 +1,9 @@
+{
+  "name": "brutalist",
+  "why": "Raw, honest, high-contrast (brutalist.md): pure #000/#FFF plus ONE loud accent -> max_hues 1 with chroma pinned high (chroma = HSL saturation/100 proxy, 0-1); 'DON'T round corners' -> radius_levels [0,0]; no SOFT shadows but a hard offset shadow is idiomatic brutalism -> shadow_levels [0,1]; visible size jumps -> wide geometric ratio; tau_slop is the highest of all profiles because brutalism must sit maximally far from the generic soft-template look.",
+  "palette": { "max_hues": 1, "chroma": [0.7, 1.0], "neutrals": "stark" },
+  "space": { "scale": "geometric", "ratio": [1.5, 2.0], "base": [4, 8] },
+  "type": { "max_families": 2 },
+  "shape": { "radius_levels": [0, 0], "shadow_levels": [0, 1] },
+  "gate": { "tau_slop": 0.45, "tau_conform": 0.5 }
+}
diff --git a/global/taste/corporate.json b/global/taste/corporate.json
new file mode 100644
index 0000000..3871392
--- /dev/null
+++ b/global/taste/corporate.json
@@ -0,0 +1,9 @@
+{
+  "name": "corporate",
+  "why": "Trustworthy, clear, accessible (corporate.md): one professional primary (#2563EB) plus three semantic states -> max_hues 4; mid-to-high but never neon chroma (chroma = HSL saturation/100 proxy, 0-1); cool slate neutrals; 'consistent 8px spacing' -> base [8], linear scale with modest ratio; one clean sans -> max_families 1; moderate rounding and subtle elevation -> radius [1,2] / shadow [0,2]; tau_slop is the LOWEST of all profiles because corporate deliberately stays near convention, and tau_conform is tight because consistency is the whole point.",
+  "palette": { "max_hues": 4, "chroma": [0.3, 0.9], "neutrals": "cool" },
+  "space": { "scale": "linear", "ratio": [1.25, 1.5], "base": [8] },
+  "type": { "max_families": 1 },
+  "shape": { "radius_levels": [1, 2], "shadow_levels": [0, 2] },
+  "gate": { "tau_slop": 0.2, "tau_conform": 0.4 }
+}
diff --git a/global/taste/editorial.json b/global/taste/editorial.json
new file mode 100644
index 0000000..a43fd2b
--- /dev/null
+++ b/global/taste/editorial.json
@@ -0,0 +1,9 @@
+{
+  "name": "editorial",
+  "why": "Magazine-grade (editorial.md): warm paper + rich ink + ONE muted accent, but max_hues 2 because the HSL saturation/100 chroma proxy (0-1) counts warm paper itself (#FBFAF7-class, s well above the neutral cutoff) as a hue bin — one accent + the paper cast; low-to-mid chroma band (#7C6A4E sits near 0.23); warm neutrals; spacious geometric rhythm near the classic 1.4-1.62 ratios; 'exactly one serif + one sans', 'DON'T use more than two families' -> max_families 2; thin rules over boxes -> radius [0,1], shadow [0,1]; tau_slop 0.35 (the spec Section 3 example) because considered typography must clear the template look by a wide margin.",
+  "palette": { "max_hues": 2, "chroma": [0.1, 0.45], "neutrals": "warm" },
+  "space": { "scale": "geometric", "ratio": [1.4, 1.62], "base": [4, 8] },
+  "type": { "max_families": 2 },
+  "shape": { "radius_levels": [0, 1], "shadow_levels": [0, 1] },
+  "gate": { "tau_slop": 0.35, "tau_conform": 0.5 }
+}
diff --git a/global/taste/minimalist.json b/global/taste/minimalist.json
new file mode 100644
index 0000000..9a7d314
--- /dev/null
+++ b/global/taste/minimalist.json
@@ -0,0 +1,9 @@
+{
+  "name": "minimalist",
+  "why": "Restraint (minimalist.md): near-monochrome with exactly ONE saturated accent for the primary action -> max_hues 1, chroma band around a committed accent like #2563EB (chroma = HSL saturation/100 proxy, 0-1); neutral near-white/ink base; '8px spacing scale' -> base [8], calm linear-to-wide steps; one sans, 2 weights -> max_families 1; hairlines only, 'no bounce, no shadow' / 'DON'T add drop shadows' -> shadow_levels [0,0], radius [0,1]; tau_slop 0.3 because minimal surfaces are CLOSE to flat templates by construction yet must still avoid the default-blue-card centroid, tau_conform tight because a minimal system tolerates zero drift.",
+  "palette": { "max_hues": 1, "chroma": [0.4, 0.9], "neutrals": "neutral" },
+  "space": { "scale": "linear", "ratio": [1.5, 2.0], "base": [8] },
+  "type": { "max_families": 1 },
+  "shape": { "radius_levels": [0, 1], "shadow_levels": [0, 0] },
+  "gate": { "tau_slop": 0.3, "tau_conform": 0.4 }
+}
diff --git a/global/taste/playful.json b/global/taste/playful.json
new file mode 100644
index 0000000..702c48a
--- /dev/null
+++ b/global/taste/playful.json
@@ -0,0 +1,9 @@
+{
+  "name": "playful",
+  "why": "Friendly, energetic (playful.md): '2-3 saturated hues' -> max_hues 3, the most permissive palette of the five, with chroma pinned high but short of neon-on-neon (chroma = HSL saturation/100 proxy, 0-1); warm soft background neutrals; grid-aligned but generous -> geometric 1.25-1.5 on a 4/8 base; one rounded sans plus an optional display face -> max_families 2; 'rounded fills (radius 12-20px)' and soft shadows -> radius [1,3], shadow [1,2] (some rounding and lift is REQUIRED, not just allowed); default tau_slop 0.25 — playful legitimately lives nearer the card-and-radius territory templates also occupy.",
+  "palette": { "max_hues": 3, "chroma": [0.55, 1.0], "neutrals": "warm" },
+  "space": { "scale": "geometric", "ratio": [1.25, 1.5], "base": [4, 8] },
+  "type": { "max_families": 2 },
+  "shape": { "radius_levels": [1, 3], "shadow_levels": [1, 2] },
+  "gate": { "tau_slop": 0.25, "tau_conform": 0.5 }
+}
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 @@ <h2>Give your agent a memory that gets better the more it's wrong.</h2>
 
     <footer>
       <div class="wrap foot-in">
-        <div class="mono">Forge Cortex · forgekit v0.4.0 · MIT</div>
+        <div class="mono">Forge Cortex · forgekit v0.5.0 · MIT</div>
         <div>
           <a href="https://github.com/CodeWithJuber/forgekit">GitHub</a>
           <a href="https://github.com/CodeWithJuber/forgekit/issues">Issues</a>
diff --git a/package-lock.json b/package-lock.json
index 6bda059..4920cd5 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "@codewithjuber/forgekit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@codewithjuber/forgekit",
-      "version": "0.4.0",
+      "version": "0.5.0",
       "license": "MIT",
       "bin": {
         "forge": "src/cli.js"
@@ -17,7 +17,7 @@
         "typescript": "^6"
       },
       "engines": {
-        "node": ">=18"
+        "node": ">=20"
       },
       "funding": {
         "url": "https://github.com/sponsors/CodeWithJuber"
diff --git a/package.json b/package.json
index 216e241..bb96f0f 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@codewithjuber/forgekit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "One config for every AI coding agent \u2014 a cross-tool config layer plus a cognitive substrate (memory, blast-radius, guardrails) for Claude Code, Codex, Cursor, Gemini, Aider, and more.",
   "type": "module",
   "bin": {
@@ -52,12 +52,14 @@
   ],
   "scripts": {
     "test": "node --test test/*.test.js",
+    "bench": "node bench/bench.mjs",
     "lint": "biome lint .",
     "format": "biome format --write .",
     "check": "biome check .",
     "check:fix": "biome check --write .",
     "typecheck": "tsc -p tsconfig.json",
     "coverage": "node --test --experimental-test-coverage test/*.test.js",
+    "bump": "node scripts/bump.mjs",
     "forge": "node src/cli.js"
   },
   "keywords": [
diff --git a/reports/benchmarks.md b/reports/benchmarks.md
new file mode 100644
index 0000000..cc5b013
--- /dev/null
+++ b/reports/benchmarks.md
@@ -0,0 +1,187 @@
+# Benchmarks — measured numbers only
+
+> Discipline ([05-cost-model.md](../docs/plans/substrate-v2/05-cost-model.md), whitepaper C6):
+> **a number is an assumption until measured.** Every figure in the generated section below
+> came from an actual run of `npm run bench` on the machine recorded in the environment
+> block — no projections, no targets, no numbers copied forward from a different machine.
+> Re-run `npm run bench` (≈10 s, node stdlib only) and the generated section is rewritten
+> in place with your machine's numbers.
+
+## Methodology
+
+- **Median of N runs after warmup.** Each row states its own `runs`; warmup runs (1–3 per
+  row) are executed and discarded so JIT compilation and cold module state don't pollute
+  the samples. p95 is nearest-rank — with fewer than 20 samples that is simply the max,
+  reported as such rather than smoothed.
+- **Timing** is `performance.now()` around the call, single process, no concurrency.
+- **Repo-scale benchmarks** (atlas, context, substrate, impact quality) run against a copy
+  of this repo in `os.tmpdir`, excluding `bench/` (so the harness's own imports don't
+  perturb the impact-quality eval) and dot-directories (`.git`, `.forge` — the copy starts
+  cold). The copy is deleted afterwards.
+- **Synthetic fixtures** (ledger, reuse) are generated with a seeded PRNG (mulberry32,
+  fixed seeds) — byte-identical fixtures on every run and machine — built in `os.tmpdir`
+  and cleaned up.
+
+### What each number does — and does not — mean
+
+- **atlas / full build**: directory walk + read + regex extraction + edge resolution +
+  writing `.forge/atlas.json` and the per-file cache, on this repo's file count (recorded
+  in the row's notes). Repo-shape-specific; not comparable across repos.
+- **atlas / incremental rebuild (unchanged)**: by design the incremental path still reads
+  and re-hashes every tracked file — the saving over a full build is the skipped regex
+  extraction only. This row is that claim, measured.
+- **atlas / impact query**: marginal per-query latency with the memoized reverse-adjacency
+  index already built (it is built once per atlas and cached — `ADJ_CACHE` in
+  `src/atlas.js`). The first query on a fresh atlas additionally pays that index build.
+- **ledger / mint+put**: `mintClaim` + `putClaim` per claim (synchronous file write each),
+  with one evidence append every 4th claim. Disk-bound; the throughput figure is
+  claims/sec at the row's median. This is the noisiest row in the file: on a shared or
+  virtualized disk, back-to-back invocations of the whole bench have produced medians
+  from ~150 ms to ~830 ms for this row (4–6×) while the CPU-bound rows moved by percents
+  — read it as "thousands of claims/sec, I/O-dominated", not as a stable constant of the
+  code.
+- **ledger / mergeDirs**: replica directories are pre-copied *outside* the timing; the
+  number is `loadState` of both sides + semilattice union + idempotent re-puts + reindex.
+- **ledger / val()**: pure in-memory scoring; the fixture gives most claims 0–1 evidence
+  records, and val() cost scales with evidence count — a heavily-evidenced ledger will be
+  slower per claim.
+- **reuse / lookup**: the memoized `_sketch` cache is stripped before every timed run, so
+  each run behaves like a fresh CLI process. The *exact* tier returns before any pool
+  sketching (normalized-string compare); the *near* tier pays MinHash-sketching the whole
+  candidate pool plus LSH banding — that difference is the point of reporting both.
+- **context / assemble()**: warm atlas, empty ledger (the repo copy has no `.forge`),
+  includes the real file reads for pinned items. Task: a three-symbol, one-file edit spec.
+- **substrate / substrateCheck**: the whole deterministic gate — preflight grounding,
+  routing rubric, up to 8 impact queries, reuse lookup, context assembly, scope
+  decomposition, lessons, minimality, goal anchor — with `llm: false`. **No model latency
+  is included anywhere in this file**; with LLM adjudication enabled, wall time is
+  dominated by the model call, which is exactly why it ships opt-in.
+
+Micro-medians below ~1 ms are subject to GC/JIT jitter even after warmup; treat them as
+order-of-magnitude, not three-significant-digit truths.
+
+### Impact-oracle quality: how the labels were made
+
+Cases live in [`bench/impact_cases.mjs`](../bench/impact_cases.mjs), scored by
+`evalImpact()` (`src/eval.js`). Labeling rule: `expected` = the defining file plus every
+file with a **direct, hand-verified reference** (an `import { X }` with a use, or a call
+site) — each one listed, per file, in the fixture's comments, checkable with grep.
+Transitive dependents are *not* labeled, so the oracle's transitive predictions count
+against precision — the same over-approximation penalty the paper's mutation-derived
+scoring applied. The set deliberately includes one case (`contentHash`) with a reference
+the regex atlas is **known to miss** (`src/atlas.js` binds it to an alias without calling
+it: `const hash = contentHash;` — no call parentheses, and the JS import regex captures
+module paths, not named bindings), so recall is measured against a documented false
+negative rather than a curated-to-be-perfect set.
+
+What these numbers do **not** mean: n = 6 cases, one JavaScript repo, symbols chosen to be
+uniquely named (the atlas resolves ambiguous names to nothing — a separate, known
+limitation). They are not comparable to the paper's numbers, which came from mutation
+testing a Python codebase against a real test suite. The two appear side by side below,
+labeled, and are never blended.
+
+<!-- BENCH:RESULTS:BEGIN (generated by bench/bench.mjs — do not edit) -->
+
+### Environment (machine section)
+
+```json
+{
+  "node": "v22.22.2",
+  "cpu": "Intel(R) Xeon(R) Processor @ 2.80GHz",
+  "cores": 4,
+  "memGB": 16,
+  "platform": "linux",
+  "arch": "x64",
+  "commit": "eb68ea97dbbf226580fd9a03cef26806c15bc2e9",
+  "date": "2026-07-07T19:36:54.342Z"
+}
+```
+
+### Measured results
+
+| suite     | benchmark                                   | median  | p95     | runs | notes                                  |
+|-----------|---------------------------------------------|---------|---------|------|----------------------------------------|
+| atlas     | full build (this repo)                      | 131 ms  | 140 ms  | 5    | 145 files, 2777 symbols, 7892 edges    |
+| atlas     | incremental rebuild (unchanged)             | 55.7 ms | 75.9 ms | 5    | per-file hash cache hit                |
+| atlas     | impact("claimText") (warm adjacency)        | 0.43 ms | 0.51 ms | 30   | 5 files impacted                       |
+| ledger    | mint+put 1000 claims                        | 834 ms  | 994 ms  | 5    | 1,199/s                                |
+| ledger    | loadClaims at 1000 claims                   | 55.8 ms | 56.1 ms | 5    | full state from disk                   |
+| ledger    | mergeDirs 2×500-claim replicas (250 shared) | 158 ms  | 188 ms  | 3    | +250 claims, +313 records              |
+| ledger    | val() over 1000 claims                      | 0.28 ms | 0.42 ms | 20   | 3,547,798/s (mean val 0.53)            |
+| reuse     | fingerprint 2000 specs                      | 142 ms  | 152 ms  | 5    | 14,043/s                               |
+| reuse     | lookup exact @ 100 artifacts                | 0.12 ms | 0.16 ms | 10   | tier=exact                             |
+| reuse     | lookup near (LSH) @ 100 artifacts           | 9.96 ms | 13.5 ms | 5    | tier=near, j=0.98                      |
+| reuse     | lookup exact @ 1000 artifacts               | 0.43 ms | 0.76 ms | 10   | tier=exact                             |
+| reuse     | lookup near (LSH) @ 1000 artifacts          | 107 ms  | 110 ms  | 5    | tier=near, j=0.95                      |
+| context   | assemble() (this repo, 3-symbol task)       | 3.80 ms | 8.94 ms | 10   | 2617/6000 tokens, 9 required, complete |
+| substrate | substrateCheck (allowBuild, llm off)        | 118 ms  | 120 ms  | 3    | 18 impacted files, route simple        |
+
+### Impact-oracle quality (hand-labeled cases, this repo)
+
+| case (target) | precision | recall | F1   | predicted | truth |
+|---------------|-----------|--------|------|-----------|-------|
+| normalizeSpec | 1.00      | 1.00   | 1.00 | 2         | 2     |
+| evalImpact    | 1.00      | 1.00   | 1.00 | 2         | 2     |
+| isStale       | 1.00      | 1.00   | 1.00 | 4         | 4     |
+| mergeStates   | 1.00      | 1.00   | 1.00 | 3         | 3     |
+| claimText     | 1.00      | 1.00   | 1.00 | 5         | 5     |
+| contentHash   | 0.38      | 0.83   | 0.53 | 13        | 6     |
+| mean of 6     | 0.90      | 0.97   | 0.92 |           |       |
+
+Edited-file-only baseline recall over the same cases: **0.33**.
+
+Two methodologies, side by side — different codebases, different ground-truth
+derivations, so the rows are comparable in spirit only and are never blended:
+
+| series                                     | precision | recall | F1   | ground truth                                  |
+|--------------------------------------------|-----------|--------|------|-----------------------------------------------|
+| paper prototype (Python, mutation-derived) | 0.63      | 1.00   | 0.75 | mutation testing against a real suite         |
+| this repo (regex atlas, hand-labeled)      | 0.90      | 0.97   | 0.92 | 6 hand-labeled cases (bench/impact_cases.mjs) |
+
+<!-- BENCH:RESULTS:END -->
+
+## Uniqueness — structural contrasts with adjacent tools
+
+Adjacent tools per [ecosystem_map.md](../docs/cognitive-substrate/ecosystem_map.md). Every
+row is a **structural** claim checkable from the named spec/source — no adjectives, no
+multipliers. The last row of each table points the other way: what the adjacent tools do
+that forgekit structurally does not.
+
+### Validity-anchored claims vs note stores (Mem0, claude-mem, Auto Memory)
+
+| structural property | forgekit PCM ledger | note stores |
+|---|---|---|
+| confidence moved only by independent oracles | yes — the `ORACLES` table in `src/ledger.js` is the closed set of who may move confidence; evidence without a verifiable ref is rejected (`outcomeRecord`) | no — notes are stored as written; no oracle taxonomy exists |
+| stored evidence weight distrusted | yes — `val()` re-reads weight from the `ORACLES` table, never the stored record; `verify()` flags a recorded weight that disagrees with the table | n/a — there are no evidence records to forge |
+| retrieval ranks by verified validity | yes — Eq. 3 score includes a `g·val` term (`EQ3_WEIGHTS`, `score()` in `src/ledger.js`) | no — similarity and/or recency only |
+| unreviewed knowledge decays toward *uncertainty*, not deletion | yes — time-decayed Beta posterior pulls val back to the 0.5 prior; below 0.35 a claim goes dormant but is kept for audit (`DORMANT_VAL`) | no — a note persists unchanged until manually deleted or compacted |
+| conflict-free team merge | yes — claim bytes are a pure function of (kind, body, scope); logs are hash-deduped unions; merge is a join-semilattice (`mergeStates`, property-tested), with a `merge=union` gitattributes rule | no — per-machine SQLite or a hosted store; no CRDT merge contract |
+| self-confirmation cannot buy trust | yes — `authorTrust()` excludes an author's own evidence on their own claims | no equivalent mechanism |
+| secrets refused at write time | yes — `SECRET_RE` enforced at both `mintClaim` and `putClaim` | not a protocol invariant |
+| **what the note stores have that forgekit doesn't** | — | hosted sync, web UI, embedding-based semantic search, LLM summarization pipelines; forgekit's ledger is files-in-git with MinHash similarity only |
+
+### Transparent routing rubric vs LLM gateways (LiteLLM, OpenRouter, Portkey)
+
+| structural property | forgekit `forge route` | LLM gateways |
+|---|---|---|
+| routing decision visible *before* dispatch | yes — returns band, signals, and per-signal reasons the user can read and override (`src/route.js`) | decision is made inside the proxy at request time |
+| rubric versioned in the repo | yes — deterministic scoring over `src/model_tiers.json`, diffable in PRs | routing/cost logic lives in gateway config or the provider's service |
+| same input ⇒ same route | yes — regex rubric is deterministic; LLM adjudication is opt-in and clamped inside band rails (a proposal can never jump past them) | depends on gateway load/cost/failover state |
+| **what the gateways have that forgekit doesn't** | — | they actually *move traffic*: proxying, failover, quotas, key management. `forge route` is advisory and at most **emits** a LiteLLM config exposing its tiers as aliases (`src/route.js`) — it is a transparency layer over gateways, not a replacement |
+
+### Proof-carrying reuse vs plain RAG retrieval
+
+| structural property | forgekit reuse cache | plain RAG |
+|---|---|---|
+| serving gated on verification evidence | yes — `SERVE_FLOOR = 0.6` (`src/reuse.js`); a fresh, unverified mint sits at the 0.5 prior and is **not** served, whatever its similarity | serves on similarity alone |
+| retrieved code revalidated against the current code graph | yes — `revalidate()` checks every declared dep still resolves in the atlas before a hit is served | no dependency contract on retrieved chunks |
+| cache demotes itself on ground truth | yes — a failed revalidation appends `graph.reval` *contradict* evidence to the ledger (`reuseQuery`), and the demotion reaches teammates through the merge | index reflects content until re-embedded; retrieval outcomes don't feed back |
+| explicit hit tiers with committed thresholds | yes — exact / near (J ≥ 0.8) / adapt (J ≥ 0.6) ladder with LSH banding (`NEAR_J`, `ADAPT_J`, `bandKeys`) | top-k cosine; thresholds are informal per deployment |
+| **what RAG has that forgekit doesn't** | — | dense embeddings catch paraphrase and cross-language semantics that token-level MinHash misses; RAG works over any corpus with zero curation — the reuse cache only holds artifacts someone minted *with proof* |
+
+## Reproduce
+
+```sh
+npm run bench   # ≈10 s; prints the tables and rewrites the generated section above
+npm test        # includes a smoke test of the harness's pure helpers (test/bench.test.js)
+```
diff --git a/scripts/bump.mjs b/scripts/bump.mjs
new file mode 100644
index 0000000..d0fcc04
--- /dev/null
+++ b/scripts/bump.mjs
@@ -0,0 +1,322 @@
+#!/usr/bin/env node
+/**
+ * Zero-dependency version bump for forgekit (node stdlib only).
+ *
+ * Usage:
+ *   node scripts/bump.mjs <patch|minor|major|auto>   # bump every version field + CHANGELOG
+ *   node scripts/bump.mjs check                      # assert all version fields agree (CI guard)
+ *   node scripts/bump.mjs <kind> --dry-run           # compute + print, write nothing
+ *
+ * "auto" heuristic (deliberately simple):
+ *   1. Conventional commits since the last v* tag:
+ *        BREAKING CHANGE / "type!:" -> major, feat -> minor, anything else -> patch.
+ *   2. If git yields no commits, fall back to the CHANGELOG [Unreleased] body:
+ *        "BREAKING" -> major, a "### Added" section -> minor, any other content -> patch.
+ *   3. Nothing found anywhere -> error (nothing to release).
+ *
+ * Files touched (all version fields in the repo):
+ *   package.json, package-lock.json (root "version" + packages[""].version),
+ *   .claude-plugin/plugin.json, .codex-plugin/plugin.json,
+ *   CITATION.cff (version + date-released), landing/index.html (display string),
+ *   CHANGELOG.md ([Unreleased] rotated under "## [X.Y.Z] - <date>" + compare links).
+ *
+ * Prints ONLY the new version on stdout (diagnostics go to stderr) so callers can
+ * capture it: NEW="$(node scripts/bump.mjs auto)".
+ */
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// ---------------------------------------------------------------------------
+// Pure version math
+// ---------------------------------------------------------------------------
+
+export function parseVersion(v) {
+  const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(String(v).trim());
+  if (!m) throw new Error(`unsupported version format: ${JSON.stringify(v)} (want X.Y.Z)`);
+  return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]) };
+}
+
+export function computeNext(current, kind) {
+  const { major, minor, patch } = parseVersion(current);
+  switch (kind) {
+    case "major":
+      return `${major + 1}.0.0`;
+    case "minor":
+      return `${major}.${minor + 1}.0`;
+    case "patch":
+      return `${major}.${minor}.${patch + 1}`;
+    default:
+      throw new Error(`unknown bump kind: ${JSON.stringify(kind)} (want patch|minor|major)`);
+  }
+}
+
+/**
+ * Conventional-commit heuristic. `commits` is [{ subject, body }].
+ * BREAKING -> major, feat -> minor, anything else -> patch, no commits -> null.
+ */
+export function inferKindFromCommits(commits) {
+  if (!commits || commits.length === 0) return null;
+  let kind = "patch";
+  for (const { subject = "", body = "" } of commits) {
+    if (/^[a-z]+(\([^)]*\))?!:/.test(subject) || /BREAKING[ -]CHANGE/.test(`${subject}\n${body}`)) {
+      return "major";
+    }
+    if (/^feat(\([^)]*\))?:/.test(subject)) kind = "minor";
+  }
+  return kind;
+}
+
+/**
+ * CHANGELOG fallback heuristic on the [Unreleased] body.
+ * "BREAKING" -> major, "### Added" section -> minor, other content -> patch, empty -> null.
+ */
+export function inferKindFromChangelog(unreleasedBody) {
+  const body = (unreleasedBody || "").trim();
+  if (!body) return null;
+  if (/\bBREAKING\b/.test(body)) return "major";
+  if (/^### Added\b/m.test(body)) return "minor";
+  return "patch";
+}
+
+// ---------------------------------------------------------------------------
+// CHANGELOG rotation (pure)
+// ---------------------------------------------------------------------------
+
+/** Returns the text between "## [Unreleased]" and the next "## [" heading (or EOF/link refs). */
+export function extractUnreleased(changelog) {
+  const start = changelog.search(/^## \[Unreleased\][^\n]*\n/m);
+  if (start === -1) return null;
+  const afterHeading = changelog.indexOf("\n", start) + 1;
+  const rest = changelog.slice(afterHeading);
+  const next = rest.search(/^(## \[|\[Unreleased\]:)/m);
+  return next === -1 ? rest : rest.slice(0, next);
+}
+
+/**
+ * Moves the [Unreleased] body under "## [newVersion] - date", leaves a fresh empty
+ * [Unreleased], and rewrites the keep-a-changelog compare links at the bottom.
+ */
+// Complete regex escape (CodeQL js/incomplete-sanitization): versions are semver-shaped
+// by the time main() calls this, but rotateChangelog is exported — escape EVERY
+// metacharacter, not just dots, so a direct caller can't smuggle a pattern in.
+const reEscape = (s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+export function rotateChangelog(changelog, newVersion, prevVersion, date) {
+  if (new RegExp(`^## \\[${reEscape(newVersion)}\\]`, "m").test(changelog)) {
+    throw new Error(`CHANGELOG.md already has a [${newVersion}] section`);
+  }
+  const body = extractUnreleased(changelog);
+  if (body === null) throw new Error("CHANGELOG.md has no ## [Unreleased] section");
+  const start = changelog.search(/^## \[Unreleased\][^\n]*\n/m);
+  const afterHeading = changelog.indexOf("\n", start) + 1;
+  const head = changelog.slice(0, afterHeading);
+  const tail = changelog.slice(afterHeading + body.length);
+  const released = `\n## [${newVersion}] - ${date}\n\n${body.trim()}\n\n`;
+  let out = head + released + tail;
+
+  // Rewrite the compare links: [Unreleased] -> vNEW...HEAD, insert [NEW] -> vPREV...vNEW.
+  const refRe = /^\[Unreleased\]:\s*(\S+?)\/compare\/\S+\s*$/m;
+  const refMatch = refRe.exec(out);
+  if (refMatch) {
+    const base = refMatch[1];
+    out = out.replace(
+      refRe,
+      `[Unreleased]: ${base}/compare/v${newVersion}...HEAD\n` +
+        `[${newVersion}]: ${base}/compare/v${prevVersion}...v${newVersion}`,
+    );
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// File mutation
+// ---------------------------------------------------------------------------
+
+export const JSON_VERSION_FILES = [
+  "package.json",
+  ".claude-plugin/plugin.json",
+  ".codex-plugin/plugin.json",
+];
+
+function readIfExists(file) {
+  return fs.existsSync(file) ? fs.readFileSync(file, "utf8") : null;
+}
+
+/** Replaces the first `"version": "<old>"` in raw JSON text (keeps formatting/escapes). */
+export function setJsonVersionText(text, oldVersion, newVersion) {
+  const needle = `"version": "${oldVersion}"`;
+  const idx = text.indexOf(needle);
+  if (idx === -1) throw new Error(`no "version": "${oldVersion}" field found`);
+  const out = `${text.slice(0, idx)}"version": "${newVersion}"${text.slice(idx + needle.length)}`;
+  JSON.parse(out); // sanity: still valid JSON
+  return out;
+}
+
+/** Collects every tracked version field, as { file: version }. Missing files are skipped. */
+export function collectVersions(root) {
+  const found = {};
+  for (const rel of JSON_VERSION_FILES) {
+    const text = readIfExists(path.join(root, rel));
+    if (text !== null) found[rel] = JSON.parse(text).version;
+  }
+  const lockText = readIfExists(path.join(root, "package-lock.json"));
+  if (lockText !== null) {
+    const lock = JSON.parse(lockText);
+    found["package-lock.json (root)"] = lock.version;
+    if (lock.packages?.[""]) found['package-lock.json (packages."")'] = lock.packages[""].version;
+  }
+  const cff = readIfExists(path.join(root, "CITATION.cff"));
+  if (cff !== null) {
+    const m = /^version:\s*(\S+)\s*$/m.exec(cff);
+    if (m) found["CITATION.cff"] = m[1];
+  }
+  return found;
+}
+
+/**
+ * Writes `newVersion` (and `date`) into every version field. Returns the list of
+ * files changed. Files absent from `root` are skipped so fixtures can be partial.
+ */
+export function applyBump(root, currentVersion, newVersion, date) {
+  const changed = [];
+  const write = (rel, text) => {
+    fs.writeFileSync(path.join(root, rel), text);
+    changed.push(rel);
+  };
+
+  for (const rel of JSON_VERSION_FILES) {
+    const text = readIfExists(path.join(root, rel));
+    if (text !== null) write(rel, setJsonVersionText(text, currentVersion, newVersion));
+  }
+
+  const lockRel = "package-lock.json";
+  const lockText = readIfExists(path.join(root, lockRel));
+  if (lockText !== null) {
+    const lock = JSON.parse(lockText);
+    lock.version = newVersion;
+    if (lock.packages?.[""]) lock.packages[""].version = newVersion;
+    write(lockRel, `${JSON.stringify(lock, null, 2)}\n`);
+  }
+
+  const cffRel = "CITATION.cff";
+  const cff = readIfExists(path.join(root, cffRel));
+  if (cff !== null) {
+    write(
+      cffRel,
+      cff
+        .replace(/^version:\s*.*$/m, `version: ${newVersion}`)
+        .replace(/^date-released:\s*.*$/m, `date-released: "${date}"`),
+    );
+  }
+
+  const landingRel = "landing/index.html";
+  const landing = readIfExists(path.join(root, landingRel));
+  if (landing !== null && /forgekit v\d+\.\d+\.\d+/.test(landing)) {
+    write(landingRel, landing.replace(/forgekit v\d+\.\d+\.\d+/g, `forgekit v${newVersion}`));
+  }
+
+  const clRel = "CHANGELOG.md";
+  const changelog = readIfExists(path.join(root, clRel));
+  if (changelog !== null) {
+    write(clRel, rotateChangelog(changelog, newVersion, currentVersion, date));
+  }
+
+  return changed;
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+function today() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function gitCommitsSinceLastTag(root) {
+  const git = (args) =>
+    execFileSync("git", args, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+  try {
+    let range;
+    try {
+      const tag = git(["describe", "--tags", "--abbrev=0", "--match", "v*"]).trim();
+      range = [`${tag}..HEAD`];
+    } catch {
+      range = ["HEAD"]; // no tag yet: consider all commits
+    }
+    const raw = git(["log", ...range, "--pretty=%s%x1f%b%x1e"]);
+    return raw
+      .split("\x1e")
+      .map((c) => c.trim())
+      .filter(Boolean)
+      .map((c) => {
+        const [subject, body = ""] = c.split("\x1f");
+        return { subject: subject.trim(), body: body.trim() };
+      });
+  } catch {
+    return null; // not a git checkout
+  }
+}
+
+function runCheck(root) {
+  const found = collectVersions(root);
+  const versions = new Set(Object.values(found));
+  if (versions.size === 1) {
+    process.stderr.write(`version fields agree: ${[...versions][0]}\n`);
+    return 0;
+  }
+  process.stderr.write("version drift detected:\n");
+  for (const [file, v] of Object.entries(found)) process.stderr.write(`  ${file}: ${v}\n`);
+  return 1;
+}
+
+function main(argv) {
+  const flags = argv.filter((a) => a.startsWith("--"));
+  const args = argv.filter((a) => !a.startsWith("--"));
+  const dryRun = flags.includes("--dry-run");
+  const cmd = args[0];
+  const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+  if (cmd === "check") return runCheck(root);
+
+  if (!["patch", "minor", "major", "auto"].includes(cmd)) {
+    process.stderr.write(
+      "usage: node scripts/bump.mjs <patch|minor|major|auto|check> [--dry-run]\n",
+    );
+    return 2;
+  }
+
+  const current = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")).version;
+  let kind = cmd;
+  if (cmd === "auto") {
+    const commits = gitCommitsSinceLastTag(root);
+    kind = inferKindFromCommits(commits);
+    if (!kind) {
+      kind = inferKindFromChangelog(
+        extractUnreleased(readIfExists(path.join(root, "CHANGELOG.md")) || ""),
+      );
+    }
+    if (!kind) {
+      process.stderr.write(
+        "auto: no commits since the last tag and an empty CHANGELOG [Unreleased] — nothing to release\n",
+      );
+      return 1;
+    }
+    process.stderr.write(`auto -> ${kind}\n`);
+  }
+
+  const next = computeNext(current, kind);
+  if (dryRun) {
+    process.stderr.write(`dry-run: ${current} -> ${next} (no files written)\n`);
+  } else {
+    const changed = applyBump(root, current, next, today());
+    process.stderr.write(`bumped ${current} -> ${next}: ${changed.join(", ")}\n`);
+  }
+  process.stdout.write(`${next}\n`);
+  return 0;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  process.exit(main(process.argv.slice(2)));
+}
diff --git a/src/cli.js b/src/cli.js
index 34bf381..7a5b5da 100755
--- a/src/cli.js
+++ b/src/cli.js
@@ -19,7 +19,8 @@ const COMMANDS = {
   cost: "real per-day spend via ccusage + measured stage factors (--stages)",
   spec: "spec-as-contract — init (OpenSpec) / lock / check drift",
   cortex: "self-correcting project memory — status / why <symbol>",
-  ledger: "proof-carrying memory — stats / verify / show / blame / query / merge / import",
+  ledger:
+    "proof-carrying memory — stats / verify / show / blame / query / ratify / retract / merge / import",
   reuse: "proof-carrying code cache — query <spec> / mint <spec> --file <path> / stats",
   context: "budgeted context assembly + completeness gate — what an edit NEEDS known",
   preflight: "assumption check — what a task names that the repo doesn't define",
@@ -191,7 +192,7 @@ async function run(argv) {
   }
   if (cmd === "ledger") {
     const ls = await import("./ledger_store.js");
-    const { epochDay } = await import("./util.js");
+    const { epochDay, gitAuthor } = await import("./util.js");
     const root = process.cwd();
     // --personal targets the ledger beside the global recall store (~/.forge/recall/
     // ledger) — otherwise facts shadowed by `forge recall add` would be write-only,
@@ -283,6 +284,55 @@ async function run(argv) {
       }
       return;
     }
+    // The two writes (08-dashboard-ux.md §2) — CLI twins of the dashboard's POSTs, so
+    // the dashboard stays a convenience, never a requirement. Both append-only.
+    if (sub === "ratify") {
+      const id = args[2];
+      if (!id || id.length < 2) {
+        console.error("usage: forge ledger ratify <id-prefix (≥2 chars)>");
+        process.exitCode = 1;
+        return;
+      }
+      // Human-only promotion: the author is YOUR git identity, minted as a decision claim.
+      const r = ls.ratify(dir, id, { author: gitAuthor(), t: nowDay });
+      if (!r.ok) {
+        console.error(`  ${r.reason}`);
+        process.exitCode = 1;
+        return;
+      }
+      if (json) return console.log(JSON.stringify(r, null, 2));
+      console.log(
+        `  ratified ${r.ratifies.slice(0, 12)} → decision ${r.decisionId.slice(0, 12)}${r.existed ? " (already ratified — same decision)" : ""}`,
+      );
+      return;
+    }
+    if (sub === "retract") {
+      const id = args[2];
+      const ri = args.indexOf("--reason");
+      const reason = ri >= 0 ? (args[ri + 1] ?? "") : "";
+      if (!id || id.length < 2 || id === "--reason" || !reason) {
+        console.error('usage: forge ledger retract <id-prefix> --reason "<why>"');
+        process.exitCode = 1;
+        return;
+      }
+      const hit = ls.getClaimByPrefix(dir, id);
+      if (!hit) {
+        console.error(`  no claim matching ${id}`);
+        process.exitCode = 1;
+        return;
+      }
+      const r = ls.tombstone(dir, hit.id, { author: gitAuthor(), reason, t: nowDay });
+      if (!r.ok) {
+        console.error(`  ${r.reason}`);
+        process.exitCode = 1;
+        return;
+      }
+      if (json) return console.log(JSON.stringify({ ...r, id: hit.id }, null, 2));
+      console.log(
+        `  retracted ${hit.id.slice(0, 12)} — ${reason}${r.deduped ? " (already retracted with this record)" : ""}`,
+      );
+      return;
+    }
     if (sub === "query") {
       const q = args.slice(2).join(" ");
       if (!q) {
@@ -327,7 +377,7 @@ async function run(argv) {
       return;
     }
     console.error(
-      `ledger: unknown subcommand "${sub}" (stats | verify | show <id> | blame <id> | query <text> | merge <path> | import) [--personal] [--json]`,
+      `ledger: unknown subcommand "${sub}" (stats | verify | show <id> | blame <id> | query <text> | ratify <id> | retract <id> --reason "<why>" | merge <path> | import) [--personal] [--json]`,
     );
     process.exitCode = 1;
     return;
@@ -787,6 +837,9 @@ async function run(argv) {
       return;
     }
     const rec = r.routeTask(process.cwd(), task);
+    // P8 route metering — explicit CLI path only (hooks that route stay write-free);
+    // best-effort, a metrics failure must never block the recommendation.
+    r.meterRoute(process.cwd(), task, rec);
     if (json) {
       console.log(JSON.stringify(rec, null, 2));
       return;
@@ -859,19 +912,87 @@ async function run(argv) {
     return; // advisory — halting the retry loop is the AGENT's move, not an exit code
   }
   if (cmd === "imagine") {
-    const { imagineTask, renderImagine } = await import("./imagine.js");
+    const { dryRun, imagineTask, renderImagine } = await import("./imagine.js");
     const json = argv.includes("--json");
+    const doRun = argv.includes("--run");
+    const allowDirty = argv.includes("--allow-dirty");
+    const FLAGS = new Set(["--json", "--run", "--allow-dirty"]);
     const task = argv
       .slice(1)
-      .filter((a) => a !== "--json")
+      .filter((a) => !FLAGS.has(a))
       .join(" ");
     if (!task) {
-      console.error('usage: forge imagine "<task>" [--json]');
+      console.error('usage: forge imagine "<task>" [--run] [--allow-dirty] [--json]');
       process.exitCode = 1;
       return;
     }
-    const r = imagineTask(process.cwd(), task);
-    console.log(json ? JSON.stringify(r, null, 2) : renderImagine(r));
+    const root = process.cwd();
+    const r = imagineTask(root, task);
+    if (!doRun) {
+      console.log(json ? JSON.stringify(r, null, 2) : renderImagine(r));
+      return;
+    }
+    // --run: the static prediction first (always), then the measured half. The sandbox
+    // is a git worktree of HEAD — uncommitted changes are INVISIBLE to it — so a dirty
+    // tree is refused by default rather than silently dry-running the wrong code.
+    if (!json) console.log(renderImagine(r, { footer: false }));
+    if (!allowDirty) {
+      let dirty = "";
+      try {
+        const { execFileSync } = await import("node:child_process");
+        dirty = execFileSync("git", ["status", "--porcelain"], {
+          cwd: root,
+          encoding: "utf8",
+          stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+      } catch {} // not a repo / no git → dryRun reports its own precondition failure
+      if (dirty) {
+        console.error(
+          "\n  imagine --run refused: the working tree is dirty and the sandbox runs HEAD,\n" +
+            "  so your uncommitted changes would NOT be in the dry-run. Commit or stash them,\n" +
+            "  or pass --allow-dirty to knowingly measure the last commit instead.",
+        );
+        process.exitCode = 1;
+        return;
+      }
+    }
+    const d = dryRun(root, { tests: r.tests });
+    // Metrics are best-effort telemetry (05-cost-model.md) — never let recording
+    // failure break the verdict. Only a run that happened is worth counting.
+    try {
+      if (d.durationMs !== undefined) {
+        const { record } = await import("./metrics.js");
+        record(root, {
+          stage: "imagine",
+          outcome: d.ok && d.failed === 0 ? "clean" : "breaks",
+          ref: task.slice(0, 120),
+          durationMs: d.durationMs,
+        });
+      }
+    } catch {}
+    if (json) {
+      console.log(JSON.stringify({ ...r, dryRun: d }, null, 2));
+      return;
+    }
+    if (!d.ok) {
+      console.log(`\n  dry-run: did not produce a verdict — ${d.reason}`);
+      if (d.output) console.log(`\n${d.output.replace(/^/gm, "    ")}`);
+      process.exitCode = 1;
+      return;
+    }
+    console.log(`\n  dry-run (sandboxed worktree of HEAD · ${d.runner}):`);
+    console.log(
+      `    pass ${d.passed} · fail ${d.failed} · ${d.durationMs}ms · worktree ${d.worktree}`,
+    );
+    if (d.perFile)
+      for (const [t, s] of Object.entries(d.perFile))
+        console.log(`    ${s === "pass" ? "ok  " : "FAIL"} ${t}`);
+    if (d.failed > 0) {
+      console.log("\n  measured consequence: the selected suite BREAKS at HEAD — output tail:");
+      console.log(`\n${(d.output || "").replace(/^/gm, "    ")}`);
+    } else {
+      console.log("\n  measured consequence: the selected suite is green at HEAD.");
+    }
     return;
   }
   if (cmd === "lean") {
@@ -928,11 +1049,16 @@ async function run(argv) {
     const sub = argv[1];
     if (sub === "fingerprint" || sub === "design") {
       const ui = await import("./uifingerprint.js");
-      const json = argv.includes("--json");
-      const files = argv.slice(2).filter((a) => !a.startsWith("--"));
-      if (!files.length) {
+      // `--taste <name>` (design only) takes a VALUE — splice it out before the
+      // file filter so the profile name is never mistaken for a file.
+      const args = argv.slice(2);
+      const tasteIdx = args.indexOf("--taste");
+      const tasteArg = tasteIdx >= 0 ? (args.splice(tasteIdx, 2)[1] ?? null) : null;
+      const json = args.includes("--json");
+      const files = args.filter((a) => !a.startsWith("--"));
+      if (!files.length || (tasteIdx >= 0 && !tasteArg)) {
         console.error(
-          `usage: ${BRAND.cli} uicheck ${sub} <file...> [--json]${sub === "fingerprint" ? " [--mint]" : ""}`,
+          `usage: ${BRAND.cli} uicheck ${sub} <file...> [--json]${sub === "fingerprint" ? " [--mint]" : " [--taste <name>]"}`,
         );
         process.exitCode = 1;
         return;
@@ -971,17 +1097,43 @@ async function run(argv) {
       }
       // design — the two-sided gate: fail when too close to generic OR (when the
       // project has minted its fingerprint) too far from the project's own system.
+      // A taste profile (explicit --taste, else the style pinned by a
+      // `forge taste`-managed DESIGN.md) overrides thresholds + adds its checks.
+      const tasteName = tasteArg ?? ui.activeTasteStyle(process.cwd());
+      const profile = tasteName ? ui.loadTasteProfile(tasteName) : null;
+      if (tasteArg && !profile) {
+        // Explicit --taste must exist; an auto-picked style without a JSON sibling
+        // silently falls back to defaults (custom prose styles stay legal).
+        console.error(
+          `unknown taste profile "${tasteArg}" — run \`${BRAND.cli} taste\` to list styles`,
+        );
+        process.exitCode = 1;
+        return;
+      }
       const projectFp = ui.loadProjectFingerprint(process.cwd());
-      const gate = ui.uiGate(fp, { projectFp });
-      const checks = ui.scaleChecks(fp);
+      const tauSlop = profile?.gate?.tau_slop ?? ui.UI_GATE_DEFAULTS.tauSlop;
+      const tauConform = profile?.gate?.tau_conform ?? ui.UI_GATE_DEFAULTS.tauConform;
+      const gate = ui.uiGate(fp, { projectFp, tauSlop, tauConform });
+      const checks = [...ui.scaleChecks(fp), ...(profile ? ui.profileChecks(fp, profile) : [])];
       const fail = !gate.pass || checks.some((c) => !c.pass);
       if (json) {
         console.log(
-          JSON.stringify({ ...gate, checks, hasProjectFingerprint: !!projectFp }, null, 2),
+          JSON.stringify(
+            {
+              ...gate,
+              checks,
+              hasProjectFingerprint: !!projectFp,
+              taste: profile ? tasteName : null,
+              tauSlop,
+              tauConform,
+            },
+            null,
+            2,
+          ),
         );
       } else {
-        const { tauSlop, tauConform } = ui.UI_GATE_DEFAULTS;
         console.log(`${BRAND.brand} uicheck design — slop distance + project conformance\n`);
+        if (profile) console.log(`  taste:         ${tasteName} (thresholds from its profile)`);
         console.log(
           `  slop distance: ${gate.slop}  (need ≥ ${tauSlop} — farther from generic is better)`,
         );
diff --git a/src/dash.html b/src/dash.html
index 4d09d65..4d49cac 100644
--- a/src/dash.html
+++ b/src/dash.html
@@ -124,6 +124,15 @@
   .blame:hover { color: var(--ember); }
   .blame.copied { color: var(--ember); }
 
+  /* the two writes (spec §2): small per-row actions, append-only on the server */
+  .act {
+    font: 11px var(--mono); color: var(--faint); cursor: pointer;
+    border: 1px solid var(--line); border-radius: var(--r-s);
+    padding: 0 var(--s1); white-space: nowrap; display: inline-block;
+  }
+  .act:hover { color: var(--ember); border-color: var(--ember); background: var(--ember-wash); }
+  td.acts { white-space: nowrap; }
+
   select, input[type="text"] {
     font: 12px var(--mono); color: var(--fg);
     background: var(--panel-2); border: 1px solid var(--line); border-radius: var(--r-s);
@@ -185,7 +194,7 @@ <h2>Impact — blast radius <span class="cmd">.forge/atlas.json</span></h2>
     </section>
   </main>
 
-  <footer>read-only lens on .forge/ — every number traces to <span class="mono">forge ledger blame &lt;id&gt;</span>. ratify/retract land in a later phase.</footer>
+  <footer>lens on .forge/ — every number traces to <span class="mono">forge ledger blame &lt;id&gt;</span>. the only writes are ratify/retract (append-only; CLI twins: <span class="mono">forge ledger ratify|retract</span>).</footer>
 
 <script>
 "use strict";
@@ -202,6 +211,15 @@ <h2>Impact — blast radius <span class="cmd">.forge/atlas.json</span></h2>
 const blameCell = (id8) =>
   '<td><span class="blame" data-id8="' + esc(id8) + '">forge ledger blame ' + esc(id8) + "</span></td>";
 
+// The two writes (spec §2), per live row. Ratify = human-only hikma promotion (the
+// server stamps YOUR git identity as author); retract = tombstone with a reason.
+// A tombstoned row gets neither — retraction is already the terminal append.
+const actionsCell = (c) => c.tombstoned ? "<td></td>" :
+  '<td class="acts"><span class="act" data-act="ratify" data-id8="' + esc(c.id8) +
+  '" title="promote to hikma — mints a decision claim with you as author">ratify ▸</span> ' +
+  '<span class="act" data-act="retract" data-id8="' + esc(c.id8) +
+  '" title="tombstone this claim with a reason (append-only)">retract ✕</span></td>';
+
 const claimRows = (claims) => claims.map((c) =>
   '<tr class="' + (c.tombstoned ? "tomb" : "") + '">' +
   '<td class="mono faint">' + esc(c.id8) + "</td>" +
@@ -211,11 +229,11 @@ <h2>Impact — blast radius <span class="cmd">.forge/atlas.json</span></h2>
   '<td class="num">' + c.evidenceCount + "</td>" +
   '<td class="muted">' + esc(c.author || "—") + "</td>" +
   '<td class="text">' + esc(c.text) + "</td>" +
-  blameCell(c.id8) + "</tr>").join("");
+  blameCell(c.id8) + actionsCell(c) + "</tr>").join("");
 
 const claimTable = (claims) =>
   "<table><thead><tr><th>id</th><th>kind</th><th>val</th><th>evid</th><th>author</th>" +
-  "<th>claim</th><th>provenance</th></tr></thead><tbody>" + claimRows(claims) + "</tbody></table>";
+  "<th>claim</th><th>provenance</th><th>actions</th></tr></thead><tbody>" + claimRows(claims) + "</tbody></table>";
 
 let DATA = null;
 
@@ -316,7 +334,31 @@ <h2>Impact — blast radius <span class="cmd">.forge/atlas.json</span></h2>
   renderCost(DATA);
 }
 
+// The two writes: POST then refresh — the ledger on disk is the only state, the page
+// just re-reads it. retract prompts for its reason (spec: tombstone WITH a reason).
+async function runWrite(act, id8) {
+  const body = { id: id8 };
+  if (act === "retract") {
+    const reason = prompt("retract " + id8 + " — reason (recorded in the tombstone):");
+    if (reason === null) return; // cancelled
+    body.reason = reason;
+  }
+  const res = await fetch("/api/" + act, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const r = await res.json().catch(() => ({}));
+  if (!res.ok) alert(act + " failed: " + (r.reason || r.error || res.status));
+  await refresh();
+}
+
 document.addEventListener("click", (ev) => {
+  const act = ev.target.closest(".act");
+  if (act) {
+    runWrite(act.dataset.act, act.dataset.id8).catch(() => {});
+    return;
+  }
   const el = ev.target.closest(".blame");
   if (!el) return;
   navigator.clipboard?.writeText("forge ledger blame " + el.dataset.id8).then(() => {
diff --git a/src/dash.js b/src/dash.js
index c69b399..50ee5dc 100644
--- a/src/dash.js
+++ b/src/dash.js
@@ -1,19 +1,28 @@
 // forge dash — the local dashboard (docs/plans/substrate-v2/08-dashboard-ux.md, P7):
-// a read-only lens on the .forge/ stores. DATA (dashData → one JSON payload) is
+// a read-mostly lens on the .forge/ stores. DATA (dashData → one JSON payload) is
 // separated from SERVING (serve → a node:http stdlib server) so the payload is
 // testable without sockets. One self-contained HTML page (src/dash.html — inline
 // CSS/JS, no CDN, no framework, no build step), localhost-only by default, zero
-// runtime deps. Read-mostly by design: the two writes the spec names (ratify /
-// retract POSTs) are a follow-up — this phase never writes anything.
+// runtime deps. Exactly the two writes the spec names (§2) exist — POST /api/ratify
+// (human-only ḥikma promotion, mints a decision claim) and POST /api/retract
+// (tombstone with a reason). Both are append-only, so the dashboard can never
+// corrupt the ledger; everything else stays read-only.
 import { readFileSync } from "node:fs";
 import { createServer } from "node:http";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { impact, load as loadAtlas } from "./atlas.js";
 import { authorTrust, claimText, val, validOutcome } from "./ledger.js";
-import { loadClaims, repoLedger, stats } from "./ledger_store.js";
+import {
+  getClaimByPrefix,
+  loadClaims,
+  ratify,
+  repoLedger,
+  stats,
+  tombstone,
+} from "./ledger_store.js";
 import { read as readMetrics, summarize } from "./metrics.js";
-import { epochDay } from "./util.js";
+import { epochDay, gitAuthor } from "./util.js";
 
 /** A claim is contested when its val sits in this band AND it carries ≥1 oracle
  *  contradiction — genuinely disputed, not merely fresh (a fresh claim is 0.5 with
@@ -107,9 +116,57 @@ const sendJson = (res, code, body) => {
   res.end(JSON.stringify(body));
 };
 
+/** Small JSON body reader for the two POSTs — capped so a runaway client can't buffer
+ *  unbounded bytes into a localhost convenience server. */
+const BODY_CAP = 64 * 1024;
+const readBody = (req) =>
+  new Promise((resolve, reject) => {
+    let body = "";
+    req.setEncoding("utf8");
+    req.on("data", (chunk) => {
+      body += chunk;
+      if (body.length > BODY_CAP) {
+        reject(new Error("body too large"));
+        req.destroy();
+      }
+    });
+    req.on("end", () => resolve(body));
+    req.on("error", reject);
+  });
+
+/** The two writes (08-dashboard-ux.md §2), both append-only: ratify mints a decision
+ *  claim with the HUMAN as author (gitAuthor — nothing auto-ratifies), retract appends
+ *  a tombstone record with a reason. Body: {id: <prefix ≥2 chars>, reason?}. */
+async function handleWrite(root, pathname, req, res) {
+  let body;
+  try {
+    body = JSON.parse(await readBody(req));
+  } catch {
+    return sendJson(res, 400, { error: "bad JSON body" });
+  }
+  const id = typeof body?.id === "string" ? body.id.trim() : "";
+  if (id.length < 2)
+    return sendJson(res, 400, { error: 'body must be {"id": "<claim id-prefix (≥2 chars)>"}' });
+  const dir = repoLedger(root);
+  const author = gitAuthor();
+  const t = epochDay();
+  if (pathname === "/api/ratify") {
+    const r = ratify(dir, id, { author, t });
+    return sendJson(res, r.ok ? 200 : 404, r);
+  }
+  const hit = getClaimByPrefix(dir, id);
+  if (!hit) return sendJson(res, 404, { ok: false, reason: `no claim matching ${id}` });
+  const reason = typeof body.reason === "string" ? body.reason : "";
+  const r = tombstone(dir, hit.id, { author, reason, t });
+  return sendJson(res, r.ok ? 200 : 400, { ...r, id: hit.id });
+}
+
+const WRITE_ROUTES = new Set(["/api/ratify", "/api/retract"]);
+
 /**
  * The dashboard server: GET / → the page, GET /api/data → dashData, GET
- * /api/impact?target=X → blast radius (when an atlas exists). Everything else 404.
+ * /api/impact?target=X → blast radius (when an atlas exists), POST /api/ratify and
+ * POST /api/retract → the spec's two append-only writes. Everything else 404.
  * Localhost-only by default — pass a host explicitly to expose it, on your own head.
  * @param {string} root
  * @param {{port?: number, host?: string}} [opts]
@@ -119,8 +176,16 @@ export function serve(root, { port = 4242, host = "127.0.0.1" } = {}) {
   const html = readFileSync(HTML_PATH, "utf8"); // read once at startup, self-contained
   const server = createServer((req, res) => {
     const url = new URL(req.url ?? "/", "http://localhost");
+    if (req.method === "POST" && WRITE_ROUTES.has(url.pathname)) {
+      handleWrite(root, url.pathname, req, res).catch(() =>
+        sendJson(res, 400, { error: "bad request body" }),
+      );
+      return;
+    }
     if (req.method !== "GET")
-      return sendJson(res, 404, { error: "read-only in this phase — GET only" });
+      return sendJson(res, 404, {
+        error: "GET only — the two writes are POST /api/ratify and POST /api/retract",
+      });
     if (url.pathname === "/") {
       res.writeHead(200, {
         "content-type": "text/html; charset=utf-8",
diff --git a/src/imagine.js b/src/imagine.js
index ac38b0d..6b88d2c 100644
--- a/src/imagine.js
+++ b/src/imagine.js
@@ -2,15 +2,19 @@
 // docs/plans/substrate-v2/06-faculties-and-mechanisms.md §2). The atlas gives the
 // exact-structure half: entities → blast radius → predicted breaks with confidence.
 // This module adds impacted-test SELECTION — the minimal dry-run suite that makes
-// pre-action simulation affordable at all (minutes → seconds vs "run everything").
-// The sandboxed worktree runner that EXECUTES the suite against a proposed diff is
-// the P5 follow-up (spec §2.2) — selection had to exist first, and it is useful on
-// its own as "run these, in this order, before you touch anything".
-import { statSync } from "node:fs";
+// pre-action simulation affordable at all (minutes → seconds vs "run everything") —
+// and the sandboxed worktree runner (spec §2.2) that EXECUTES that suite: dryRun()
+// checks out HEAD into an ephemeral `git worktree`, runs the suite there, parses the
+// TAP summary, and always discards the sandbox. Selection stays useful on its own as
+// "run these, in this order"; dryRun turns the prediction into measured evidence.
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { build as buildAtlas, impact, load as loadAtlas } from "./atlas.js";
 import { referencedEntities } from "./preflight.js";
 import { isTestFile, predictFailingTests } from "./substrate.js";
+import { hasBin } from "./util.js";
 
 /**
  * Weighted greedy set cover over the covers(test, source) relation: candidates are
@@ -78,6 +82,155 @@ export function selectTestsReport(root, impactedFiles) {
   return { tests, uncovered };
 }
 
+/** Strip a TAP `location: '/abs/file.js:1:2'` diagnostic down to its file path. */
+const locFile = (line) => {
+  const m = /^\s+location:\s*'(.+):\d+:\d+'/.exec(line);
+  return m ? m[1] : null;
+};
+
+/**
+ * @typedef {{ok: boolean, reason?: string, passed?: number, failed?: number,
+ *   perFile?: Record<string, "pass"|"fail">, durationMs?: number, runner?: string,
+ *   output?: string, worktree?: string}} DryRunVerdict
+ */
+
+/**
+ * Sandboxed dry-run of a selected suite — the simulation half of ĉ = g(a, C)
+ * (spec §2.2): run the tests in an EPHEMERAL `git worktree` of HEAD and discard it.
+ * The worktree is HEAD, not the working tree — worktrees share the object store,
+ * never uncommitted files — so callers MUST surface that a dirty tree dry-runs the
+ * last commit, not the in-flight proposal (the CLI refuses dirty trees by default).
+ * ok means the RUN completed and produced a verdict; failing tests are ok:true with
+ * failed>0 — that IS the imagined consequence, delivered as evidence. Never throws:
+ * unmet preconditions return { ok:false, reason }.
+ * @param {string} root
+ * @param {{tests?: string[], timeoutMs?: number}} [opts] repo-relative test paths
+ * @returns {DryRunVerdict}
+ */
+export function dryRun(root, { tests, timeoutMs = 120000 } = {}) {
+  if (!Array.isArray(tests) || tests.length === 0)
+    return { ok: false, reason: "no tests selected — nothing to dry-run" };
+  if (!hasBin("git")) return { ok: false, reason: "git not found — the sandbox is a git worktree" };
+  try {
+    execFileSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd: root, stdio: "ignore" });
+  } catch {
+    return { ok: false, reason: `not a git repository: ${root}` };
+  }
+  // mkdtemp reserves a unique parent; the worktree goes one level down because
+  // `git worktree add` wants to create its target path itself.
+  const parent = mkdtempSync(join(tmpdir(), "forge-dryrun-"));
+  const wt = join(parent, "wt");
+  const started = Date.now();
+  // The body runs in a closure so every exit path — verdict, timeout, crash — flows
+  // through the same finally-cleanup AND the same verified `worktree` stamp below.
+  /** @returns {DryRunVerdict} */
+  const body = () => {
+    try {
+      execFileSync("git", ["worktree", "add", "--detach", wt, "HEAD"], {
+        cwd: root,
+        stdio: "pipe",
+      });
+    } catch (e) {
+      const msg = /** @type {{stderr?: Buffer}} */ (e).stderr?.toString().trim() || String(e);
+      return { ok: false, reason: `git worktree add failed: ${msg}` };
+    }
+    // Runner policy: always `node --test <files...>` — a custom package test script
+    // (jest, vitest, …) is a WHOLE-SUITE command that can't be scoped per-file safely,
+    // which would defeat minimal selection. We still run node --test and say so, so a
+    // surprising verdict is attributable to the runner mismatch.
+    let runner = "node --test";
+    try {
+      const pkg = JSON.parse(readFileSync(join(wt, "package.json"), "utf8"));
+      const script = pkg?.scripts?.test;
+      if (script && !/\bnode\s+(--[\w-]+\s+)*--test\b/.test(script))
+        runner = `node --test (package.json test script is custom: ${String(script).slice(0, 60)})`;
+    } catch {} // no/unreadable package.json → default runner
+    // TAP reporter is forced: the default reporter depends on TTY-ness, and the
+    // `# pass/# fail` summary below is the contract this parser relies on. The env
+    // must NOT leak a parent test-runner's context — when dryRun itself runs under
+    // `node --test` (our own tests, or an agent's), an inherited NODE_TEST_CONTEXT
+    // makes the child speak the runner's internal protocol instead of TAP.
+    const env = { ...process.env };
+    delete env.NODE_TEST_CONTEXT;
+    const run = spawnSync(
+      process.execPath,
+      ["--test", "--test-reporter=tap", ...tests.map(String)],
+      {
+        cwd: wt,
+        env,
+        encoding: "utf8",
+        timeout: timeoutMs,
+        killSignal: "SIGKILL", // node --test forks workers; SIGKILL is the reliable stop
+        maxBuffer: 16 * 1024 * 1024,
+      },
+    );
+    const combined = `${run.stdout ?? ""}${run.stderr ? `\n${run.stderr}` : ""}`.trim();
+    const output = combined.length > 2000 ? `…${combined.slice(-2000)}` : combined;
+    const durationMs = Date.now() - started;
+    if (run.error || run.signal) {
+      const reason =
+        /** @type {{code?: string}} */ (run.error)?.code === "ETIMEDOUT" || run.signal
+          ? `dry-run timed out after ${timeoutMs}ms (killed with ${run.signal ?? "SIGKILL"})`
+          : `runner failed to start: ${run.error}`;
+      return { ok: false, reason, durationMs, runner, output };
+    }
+    const mPass = /^# pass (\d+)$/m.exec(run.stdout ?? "");
+    const mFail = /^# fail (\d+)$/m.exec(run.stdout ?? "");
+    if (!mPass || !mFail) {
+      // Non-zero exit with no TAP summary = the RUN failed (crash, bad flags), which
+      // is a different fact than "the tests failed" — report it as one.
+      return {
+        ok: false,
+        reason: `runner exited ${run.status} without a TAP summary`,
+        durationMs,
+        runner,
+        output,
+      };
+    }
+    // perFile is best-effort: node ≥20 TAP flattens per-TEST (no per-file points), but
+    // every failure block carries a `location: '<abs path>:l:c'` diagnostic — map those
+    // back to the requested files; anything never implicated passed. Omitted when a
+    // failure can't be attributed (partial attribution would misassign blame).
+    /** @type {Record<string, "pass"|"fail">} */
+    const perFile = Object.fromEntries(tests.map((t) => [String(t), "pass"]));
+    let attributable = true;
+    for (const block of (run.stdout ?? "").split(/^not ok /m).slice(1)) {
+      const file = block.split("\n").map(locFile).find(Boolean);
+      const t = file && tests.find((c) => file === join(wt, String(c)));
+      if (t) perFile[String(t)] = "fail";
+      else attributable = false;
+    }
+    return {
+      ok: true,
+      passed: Number(mPass[1]),
+      failed: Number(mFail[1]),
+      ...(attributable ? { perFile } : {}),
+      durationMs,
+      runner,
+      output,
+    };
+  };
+  let result;
+  try {
+    result = body();
+  } finally {
+    // ALWAYS discard the sandbox — a leaked worktree pins refs and litters
+    // `git worktree list` forever. remove --force, prune the bookkeeping, then
+    // belt-and-braces rm of the parent; the verdict below verifies, never assumes.
+    try {
+      execFileSync("git", ["worktree", "remove", "--force", wt], { cwd: root, stdio: "ignore" });
+    } catch {}
+    try {
+      execFileSync("git", ["worktree", "prune"], { cwd: root, stdio: "ignore" });
+    } catch {}
+    try {
+      rmSync(parent, { recursive: true, force: true });
+    } catch {}
+  }
+  result.worktree = existsSync(wt) ? "leaked" : "removed";
+  return result;
+}
+
 /**
  * Imagine the consequences of a task before acting: entities → impact() blast
  * radius → predicted breaks (per-file max confidence across targets), the minimal
@@ -117,7 +270,9 @@ export function imagineTask(root, task, { atlas, threshold = 0.1 } = {}) {
   };
 }
 
-export function renderImagine(r) {
+/** @param {ReturnType<typeof imagineTask>} r
+ *  @param {{footer?: boolean}} [opts] footer=false when the caller runs the dry-run itself */
+export function renderImagine(r, { footer = true } = {}) {
   const lines = ["Forge imagine — consequence simulation (pre-action)", ""];
   lines.push(`  targets: ${r.targets.length ? r.targets.join(", ") : "(none named)"}`);
   if (!r.found) {
@@ -140,6 +295,7 @@ export function renderImagine(r) {
       "",
       `  ! no test covers: ${r.uncovered.slice(0, 6).join(", ")}${r.uncovered.length > 6 ? " …" : ""}`,
     );
-  lines.push("", "  (sandboxed worktree dry-run of this suite lands as the P5 follow-up)");
+  if (footer)
+    lines.push("", "  (measure it: re-run with --run — sandboxed worktree dry-run of HEAD)");
   return lines.join("\n");
 }
diff --git a/src/ledger_store.js b/src/ledger_store.js
index 75316b4..2789c26 100644
--- a/src/ledger_store.js
+++ b/src/ledger_store.js
@@ -22,6 +22,7 @@ import {
   emptyState,
   liveClaims,
   mergeStates,
+  mintClaim,
   ORACLES,
   SECRET_RE,
   sealRecord,
@@ -145,6 +146,32 @@ export function tombstone(dir, id, { author = "", reason = "", t = 0 } = {}) {
   return appendRecord(dir, "tombstones", id, sealRecord({ author, reason, t }));
 }
 
+/**
+ * Ratify a claim — the fahm→ḥikma promotion (08-dashboard-ux.md §2): mint a `decision`
+ * claim pointing at the ratified claim's full id. Promotion is HUMAN-ONLY by design:
+ * the caller supplies the author (a person's identity, via gitAuthor()); nothing in the
+ * substrate ever calls this automatically. Append-only and content-addressed, so
+ * ratifying the same claim twice converges on the same decision ({existed:true}).
+ * @param {string} dir
+ * @param {string} idPrefix
+ * @param {{author?: string, t?: number}} [opts]
+ * @returns {{ok:boolean, reason?:string, decisionId?:string, ratifies?:string, existed?:boolean}}
+ */
+export function ratify(dir, idPrefix, { author = "", t = 0 } = {}) {
+  const target = getClaimByPrefix(dir, idPrefix);
+  if (!target) return { ok: false, reason: `no claim matching ${idPrefix}` };
+  const minted = mintClaim({
+    kind: "decision",
+    body: { ratifies: target.id, note: "" },
+    provenance: { agent: "dash", author },
+    t,
+  });
+  if (!minted.ok) return { ok: false, reason: "reason" in minted ? minted.reason : "mint failed" };
+  const put = putClaim(dir, minted.claim);
+  if (!put.ok) return { ok: false, reason: put.reason ?? "could not persist the decision claim" };
+  return { ok: true, decisionId: minted.claim.id, ratifies: target.id, existed: put.existed };
+}
+
 /** Load the full ledger state {claims, evidence, provenance, tombstones}. */
 export function loadState(dir) {
   const state = emptyState();
diff --git a/src/route.js b/src/route.js
index 334c2ff..047604f 100644
--- a/src/route.js
+++ b/src/route.js
@@ -7,10 +7,11 @@ import { join } from "node:path";
 import { adjudicate, asText, buildRunner, llmEnabled } from "./adjudicate.js";
 import { matchingLessons } from "./cortex.js";
 import { gitChurn, grepFanout } from "./cortex_features.js";
+import { recordRoute } from "./cost_report.js";
 import { load as loadLessons } from "./lessons_store.js";
 import { MODELS } from "./model_tiers.js";
 import { preflightRepo, referencedEntities } from "./preflight.js";
-import { clamp01 } from "./util.js";
+import { clamp01, contentHash } from "./util.js";
 
 // Weights sum to 1. Each raw signal is normalized by the point where it reads as "complex".
 
@@ -251,6 +252,25 @@ export function routeTask(
   };
 }
 
+/**
+ * Best-effort route-stage metering (05-cost-model.md) for EXPLICIT callers only — the
+ * `forge route` CLI and the explicit substrate gate call this AFTER a routing decision.
+ * Deliberately NOT called from routeTask itself: ambient hooks route on every prompt
+ * and must stay write-free, same rule as recordGate in substrate.js. One metrics line:
+ * the chosen tier + a short task hash as the ref (never the task text — metrics are
+ * telemetry, not a prompt log). No token counts here — this is an advisory routing
+ * decision, not a priced generation, and the cost report excludes unpriced events
+ * rather than estimating them.
+ * @param {string} root
+ * @param {string} task
+ * @param {{tier?: string}} rec the routeTask result (only .tier is read)
+ */
+export function meterRoute(root, task, rec) {
+  try {
+    recordRoute(root, { tier: rec?.tier, ref: contentHash(String(task)).slice(0, 12) });
+  } catch {}
+}
+
 /** Emit a LiteLLM config exposing the complexity tiers as aliases (request the one `forge route` picks). */
 export function emitGatewayConfig(root = process.cwd()) {
   const path = join(root, "litellm.config.yaml");
diff --git a/src/substrate.js b/src/substrate.js
index d510954..b988132 100644
--- a/src/substrate.js
+++ b/src/substrate.js
@@ -15,7 +15,7 @@ import { leanRepo } from "./lean.js";
 import { load as loadLessons } from "./lessons_store.js";
 import { clarifyBlock, preflightRepo, referencedEntities } from "./preflight.js";
 import { reusePeek, reuseQuery } from "./reuse.js";
-import { routeTask } from "./route.js";
+import { meterRoute, routeTask } from "./route.js";
 import { decompose } from "./scope.js";
 import { epochDay } from "./util.js";
 
@@ -205,6 +205,10 @@ export function substrateCheck(
   // Reuse the gap preflight already computed — routeTask would otherwise recompute it (and, with
   // FORGE_LLM on, fire a second, redundant assumption model call whose result it discards).
   const route = routeTask(root, text, { ...llmOpts, ambiguity: preflight.gap });
+  // P8 route metering, same write contract as recordGate above: the explicit gate
+  // meters, the ambient hook path (allowBuild:false) never appends. meterRoute is
+  // itself best-effort (try/catch inside), so measurement can never block routing.
+  if (allowBuild) meterRoute(root, text, route);
   // allowBuild:false (ambient hooks) uses the atlas only if one is already cached — never
   // builds or writes .forge/atlas.json from a hook. Impact is then best-effort.
   const atlas = loadAtlas(root) || (allowBuild ? buildAtlas({ root }) : null);
diff --git a/src/uifingerprint.js b/src/uifingerprint.js
index 1e5914b..e7a2944 100644
--- a/src/uifingerprint.js
+++ b/src/uifingerprint.js
@@ -12,6 +12,7 @@
 // the gate's job is to stop the template from ever reaching them.
 import { readFileSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
+import { BRAND } from "./brand.js";
 import { mintClaim } from "./ledger.js";
 import { loadClaims, putClaim, reindex, repoLedger } from "./ledger_store.js";
 import { gitAuthor } from "./util.js";
@@ -110,6 +111,65 @@ function parseColors(text) {
   return out;
 }
 
+// ---------------------------------------------------------------------------
+// Custom-property resolution — a token-driven stylesheet (`--s4: 16px` consumed as
+// `padding: var(--s4)`) carries its whole design system in var() indirections; the
+// extractors below only see literals, so var() must be substituted FIRST or the
+// fingerprint reads a 6-value scale as one value.
+// ---------------------------------------------------------------------------
+
+// `--name: value` declarations (value stops at `;`/`}` like every prop regex here).
+const VAR_DECL_RE = /(--[\w-]+)\s*:\s*([^;}]+)/g;
+// `var(--name)` / `var(--name, fallback)`; the fallback may contain ONE paren level
+// (rgba(...), nested var(...)) — deeper nesting stays unmatched and thus untouched.
+const VAR_USE_RE = /var\(\s*(--[\w-]+)\s*(?:,\s*([^()]*(?:\([^()]*\)[^()]*)*))?\s*\)/g;
+
+/**
+ * Substitute `var(--name[, fallback])` with the declared custom-property value
+ * (fallback when undeclared; left as-is when neither exists — the extractors ignore
+ * unresolved `var(` just as before). One level of nesting (a custom property whose
+ * value is itself a var()) resolves via a BOUNDED pass count, so declaration cycles
+ * terminate instead of recursing: cyclic values simply keep their `var(` text and
+ * stay invisible to the extractors.
+ * @param {string} text
+ * @returns {string}
+ */
+export function resolveCssVars(text) {
+  const t = String(text);
+  /** @type {Map<string,string>} */
+  const decls = new Map();
+  for (const [, name, value] of t.matchAll(VAR_DECL_RE)) decls.set(name, value.trim());
+  if (!decls.size && !t.includes("var(")) return t;
+  const substitute = (/** @type {string} */ s) =>
+    s.replace(VAR_USE_RE, (whole, name, fallback) => {
+      const v = decls.get(name);
+      if (v !== undefined) return v;
+      return fallback !== undefined ? String(fallback).trim() : whole;
+    });
+  // Resolve the declarations themselves first (--a: var(--b)); 4 passes covers the
+  // sane nesting depths and bounds a --a↔--b cycle to a fixed cost.
+  for (let i = 0; i < 4; i++) {
+    let changed = false;
+    for (const [name, value] of decls) {
+      if (!value.includes("var(")) continue;
+      const next = substitute(value);
+      if (next !== value) {
+        decls.set(name, next);
+        changed = true;
+      }
+    }
+    if (!changed) break;
+  }
+  // Then the whole text; extra passes let a fallback that is itself a var() land.
+  let out = t;
+  for (let i = 0; i < 3 && out.includes("var("); i++) {
+    const next = substitute(out);
+    if (next === out) break;
+    out = next;
+  }
+  return out;
+}
+
 // ---------------------------------------------------------------------------
 // Length parsing — spacing, radii. Everything lands in px (rem/em at the 16px root)
 // so the base-unit inference sees one scale.
@@ -207,7 +267,7 @@ const uniqSorted = (arr) => [...new Set(arr)].sort(sortNum);
  * @returns {Fingerprint}
  */
 export function fingerprintText(text) {
-  const t = String(text);
+  const t = resolveCssVars(String(text));
 
   const seen = new Set();
   /** @type {Hsl[]} */
@@ -639,6 +699,125 @@ export function scaleChecks(fingerprint, opts = {}) {
   ];
 }
 
+// ---------------------------------------------------------------------------
+// Taste profiles as constraint sets (spec §3) — each prose global/taste/<name>.md
+// keeps the *why* and steers generation; its JSON sibling is what the gate CHECKS.
+// `chroma` in the JSON is an HSL saturation/100 proxy in [0,1] (documented in each
+// profile's "why"); `ratio`/`chroma` bands steer generation but are not yet gated —
+// only the checks below are, until P8 fixtures show separation.
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {{name:string, why:string,
+ *   palette:{max_hues:number, chroma:[number,number], neutrals:string},
+ *   space:{scale:string, ratio:[number,number], base:number[]},
+ *   type:{max_families:number},
+ *   shape:{radius_levels:[number,number], shadow_levels:[number,number]},
+ *   gate:{tau_slop:number, tau_conform:number}}} TasteProfile
+ */
+
+/**
+ * Load a taste-profile constraint set from global/taste/<name>.json (located
+ * relative to the installed module via BRAND.root, same as `forge taste` finds the
+ * prose files). Null when the name has no JSON sibling or it doesn't parse.
+ * @param {string} name
+ * @returns {TasteProfile|null}
+ */
+export function loadTasteProfile(name) {
+  if (!/^[\w-]+$/.test(String(name))) return null; // a name, never a path
+  try {
+    const p = JSON.parse(readFileSync(join(BRAND.root, "global", "taste", `${name}.json`), "utf8"));
+    return p && typeof p === "object" && p.gate ? p : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The repo's pinned taste style, read from a `forge taste`-managed DESIGN.md (its
+ * header: `<!-- Forge taste: <style> — … forge:sync:<hash> -->`). Null when there is
+ * no DESIGN.md, it isn't Forge-managed, or it was written by hand.
+ * @param {string} root
+ * @returns {string|null}
+ */
+export function activeTasteStyle(root) {
+  try {
+    const head = readFileSync(join(root, "DESIGN.md"), "utf8").slice(0, 200);
+    const m = head.match(/<!--\s*Forge taste:\s*([\w-]+)\s.*forge:sync:/);
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Deterministic profile-constraint checks — same {id, pass, detail, hint} shape as
+ * scaleChecks so the CLI/hooks render them identically. Hue count is OCCUPIED
+ * 30°-hue-bins (a warm palette of 8 near-identical h≈30 tints is ONE hue decision,
+ * not eight); features the input doesn't exhibit pass vacuously, mirroring
+ * sigFeatures' "don't judge what isn't there".
+ * @param {Fingerprint} fingerprint @param {TasteProfile} profile
+ * @returns {{id:string, pass:boolean, detail:string, hint:string}[]}
+ */
+export function profileChecks(fingerprint, profile) {
+  const fp = asFp(fingerprint);
+  const name = profile.name ?? "taste";
+  const hues = fp.hueBuckets.filter((n) => n > 0).length;
+  const [rLo, rHi] = profile.shape?.radius_levels ?? [0, Infinity];
+  const [sLo, sHi] = profile.shape?.shadow_levels ?? [0, Infinity];
+  const bases = profile.space?.base ?? [];
+  const maxHues = profile.palette?.max_hues ?? Infinity;
+  const maxFam = profile.type?.max_families ?? Infinity;
+  return [
+    {
+      id: "taste-palette",
+      pass: fp.paletteSize === 0 || hues <= maxHues,
+      detail: `${hues} distinct hue bin(s) of ${fp.paletteSize} color(s) (${name} allows ≤ ${maxHues})`,
+      hint: hues > maxHues ? `collapse accents to ${maxHues} hue(s) — ${name} palettes commit` : "",
+    },
+    {
+      id: "taste-type",
+      pass: fp.fontFamilies.length <= maxFam,
+      detail: `${fp.fontFamilies.length} font family(ies) (${name} allows ≤ ${maxFam})`,
+      hint:
+        fp.fontFamilies.length > maxFam
+          ? `drop to ≤${maxFam} families — [${fp.fontFamilies.join(", ")}] is more voices than ${name} speaks in`
+          : "",
+    },
+    {
+      id: "taste-radius",
+      pass: fp.radiusLevels >= rLo && fp.radiusLevels <= rHi,
+      detail: `${fp.radiusLevels} radius level(s) (${name} wants ${rLo}–${rHi})`,
+      hint:
+        fp.radiusLevels > rHi
+          ? `flatten [${fp.radii.join(", ")}] to ≤${rHi} level(s)${rHi === 0 ? " — square corners are the style" : ""}`
+          : fp.radiusLevels < rLo
+            ? `add rounding — ${name} expects at least ${rLo} radius level(s)`
+            : "",
+    },
+    {
+      id: "taste-shadow",
+      pass: fp.shadowLevels >= sLo && fp.shadowLevels <= sHi,
+      detail: `${fp.shadowLevels} shadow level(s) (${name} wants ${sLo}–${sHi})`,
+      hint:
+        fp.shadowLevels > sHi
+          ? `flatten elevation to ≤${sHi} level(s)`
+          : fp.shadowLevels < sLo
+            ? `add soft elevation — ${name} expects at least ${sLo} shadow level(s)`
+            : "",
+    },
+    {
+      id: "taste-spacing-base",
+      pass: !fp.spacing.length || fp.spacingBase === null || bases.includes(fp.spacingBase),
+      detail: `inferred spacing base ${fp.spacingBase ?? "(none)"}px (${name} allows [${bases.join(", ")}])`,
+      hint:
+        fp.spacing.length && fp.spacingBase !== null && !bases.includes(fp.spacingBase)
+          ? `re-grid spacing onto a ${bases.join("- or ")}px base`
+          : "",
+    },
+  ];
+}
+
 // ---------------------------------------------------------------------------
 // The project fingerprint claim — v_proj lives in the PCM ledger so it is shared
 // with the team and updated by the same evidence rules as everything else.
diff --git a/test/bench.test.js b/test/bench.test.js
new file mode 100644
index 0000000..120a399
--- /dev/null
+++ b/test/bench.test.js
@@ -0,0 +1,77 @@
+// Smoke tests for bench/bench.mjs's PURE helpers only. Importing the module must not
+// start a benchmark run (it is main-module guarded), and this file never runs one —
+// the full bench is `npm run bench`, on demand, never in CI's test pass.
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  fmtMs,
+  fmtRate,
+  formatTable,
+  makeSpec,
+  median,
+  mulberry32,
+  p95,
+  timeIt,
+} from "../bench/bench.mjs";
+
+test("median: odd, even, single, empty", () => {
+  assert.equal(median([3, 1, 2]), 2);
+  assert.equal(median([4, 1, 2, 3]), 2.5);
+  assert.equal(median([7]), 7);
+  assert.ok(Number.isNaN(median([])));
+  const xs = [3, 1, 2];
+  median(xs);
+  assert.deepEqual(xs, [3, 1, 2], "input is not mutated");
+});
+
+test("p95: nearest-rank — max for small n, 95th value at n=100", () => {
+  assert.equal(p95([5, 1, 9]), 9, "n<20 → the max, not a smoothed estimate");
+  const hundred = Array.from({ length: 100 }, (_, i) => i + 1);
+  assert.equal(p95(hundred), 95);
+  assert.ok(Number.isNaN(p95([])));
+});
+
+test("fmtMs/fmtRate: precision scales with magnitude", () => {
+  assert.equal(fmtMs(0.042), "0.042 ms");
+  assert.equal(fmtMs(1.234), "1.23 ms");
+  assert.equal(fmtMs(42.1), "42.1 ms");
+  assert.equal(fmtMs(1503.4), "1503 ms");
+  assert.equal(fmtMs(Number.NaN), "n/a");
+  assert.equal(fmtRate(7121.4), "7,121/s");
+  assert.equal(fmtRate(Number.POSITIVE_INFINITY), "n/a");
+});
+
+test("formatTable: aligned columns, markdown separator variant", () => {
+  const t = formatTable(["a", "long-header"], [["x", "1"]], { markdown: true });
+  const lines = t.split("\n");
+  assert.equal(lines.length, 3);
+  assert.ok(lines[1].startsWith("|---"), "markdown separator row");
+  assert.ok(
+    lines.every((l) => l.length === lines[0].length),
+    "all rows share one width",
+  );
+  assert.ok(lines[2].includes("| x "), "cells padded to column width");
+});
+
+test("timeIt: runs warmup + measured runs, reports median/p95 of samples", () => {
+  let calls = 0;
+  const r = timeIt(
+    () => {
+      calls += 1;
+    },
+    { runs: 4, warmup: 2 },
+  );
+  assert.equal(calls, 6, "2 warmup + 4 measured");
+  assert.equal(r.samples.length, 4);
+  assert.equal(r.median, median(r.samples));
+  assert.equal(r.p95, p95(r.samples));
+});
+
+test("mulberry32/makeSpec: deterministic fixtures — same seed, same spec, every run", () => {
+  const a = makeSpec(mulberry32(42), 40);
+  const b = makeSpec(mulberry32(42), 40);
+  assert.equal(a, b);
+  assert.equal(a.split(" ").length, 40);
+  assert.notEqual(a, makeSpec(mulberry32(43), 40), "different seed diverges");
+  assert.match(a, /^[a-z ]+$/, "prose-only tokens (no idents/paths/numbers/secrets)");
+});
diff --git a/test/bump.test.js b/test/bump.test.js
new file mode 100644
index 0000000..6f6fcaa
--- /dev/null
+++ b/test/bump.test.js
@@ -0,0 +1,232 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { test } from "node:test";
+import {
+  applyBump,
+  collectVersions,
+  computeNext,
+  extractUnreleased,
+  inferKindFromChangelog,
+  inferKindFromCommits,
+  parseVersion,
+  rotateChangelog,
+  setJsonVersionText,
+} from "../scripts/bump.mjs";
+
+// ---------------------------------------------------------------------------
+// version math
+// ---------------------------------------------------------------------------
+
+test("parseVersion parses X.Y.Z and rejects garbage", () => {
+  assert.deepEqual(parseVersion("0.4.0"), { major: 0, minor: 4, patch: 0 });
+  assert.deepEqual(parseVersion("12.34.56"), { major: 12, minor: 34, patch: 56 });
+  assert.throws(() => parseVersion("1.2"), /unsupported version format/);
+  assert.throws(() => parseVersion("1.2.3-beta.1"), /unsupported version format/);
+  assert.throws(() => parseVersion("v1.2.3"), /unsupported version format/);
+});
+
+test("computeNext bumps patch/minor/major with correct resets", () => {
+  assert.equal(computeNext("0.4.0", "patch"), "0.4.1");
+  assert.equal(computeNext("0.4.9", "minor"), "0.5.0");
+  assert.equal(computeNext("0.4.9", "major"), "1.0.0");
+  assert.equal(computeNext("1.2.3", "minor"), "1.3.0");
+  assert.equal(computeNext("1.2.3", "major"), "2.0.0");
+});
+
+test("computeNext rejects unknown kinds", () => {
+  assert.throws(() => computeNext("1.0.0", "auto"), /unknown bump kind/);
+  assert.throws(() => computeNext("1.0.0", ""), /unknown bump kind/);
+});
+
+// ---------------------------------------------------------------------------
+// auto heuristic: conventional commits
+// ---------------------------------------------------------------------------
+
+test("inferKindFromCommits: feat -> minor, fix/docs/chore -> patch", () => {
+  assert.equal(inferKindFromCommits([{ subject: "fix: a" }, { subject: "docs: b" }]), "patch");
+  assert.equal(inferKindFromCommits([{ subject: "chore(deps): bump x" }]), "patch");
+  assert.equal(inferKindFromCommits([{ subject: "fix: a" }, { subject: "feat: b" }]), "minor");
+  assert.equal(inferKindFromCommits([{ subject: "feat(cli): add flag" }]), "minor");
+});
+
+test("inferKindFromCommits: BREAKING wins over everything", () => {
+  assert.equal(inferKindFromCommits([{ subject: "feat!: drop node 18" }]), "major");
+  assert.equal(inferKindFromCommits([{ subject: "refactor(core)!: rename" }]), "major");
+  assert.equal(
+    inferKindFromCommits([{ subject: "feat: x", body: "BREAKING CHANGE: config renamed" }]),
+    "major",
+  );
+});
+
+test("inferKindFromCommits: non-conventional commits default to patch, none -> null", () => {
+  assert.equal(inferKindFromCommits([{ subject: "Merge pull request #30" }]), "patch");
+  assert.equal(inferKindFromCommits([]), null);
+  assert.equal(inferKindFromCommits(null), null);
+});
+
+// ---------------------------------------------------------------------------
+// auto heuristic: CHANGELOG fallback
+// ---------------------------------------------------------------------------
+
+test("inferKindFromChangelog: BREAKING -> major, Added -> minor, other -> patch, empty -> null", () => {
+  assert.equal(inferKindFromChangelog("### Changed\n\n- BREAKING: renamed the config"), "major");
+  assert.equal(inferKindFromChangelog("### Added\n\n- new command"), "minor");
+  assert.equal(inferKindFromChangelog("### Fixed\n\n- a bug"), "patch");
+  assert.equal(inferKindFromChangelog("\n\n"), null);
+  assert.equal(inferKindFromChangelog(""), null);
+});
+
+// ---------------------------------------------------------------------------
+// CHANGELOG rotation
+// ---------------------------------------------------------------------------
+
+const CHANGELOG = `# Changelog
+
+## [Unreleased]
+
+### Added
+
+- shiny new thing
+
+## [0.4.0] - 2026-07-06
+
+### Added
+
+- old thing
+
+[Unreleased]: https://github.com/o/r/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/o/r/compare/v0.3.1...v0.4.0
+`;
+
+test("extractUnreleased returns only the [Unreleased] body", () => {
+  const body = extractUnreleased(CHANGELOG);
+  assert.match(body, /shiny new thing/);
+  assert.doesNotMatch(body, /old thing/);
+  assert.equal(extractUnreleased("# nope\n"), null);
+});
+
+test("rotateChangelog moves [Unreleased] under a dated heading and rewrites links", () => {
+  const out = rotateChangelog(CHANGELOG, "0.5.0", "0.4.0", "2026-07-07");
+  assert.match(
+    out,
+    /## \[Unreleased\]\n\n## \[0\.5\.0\] - 2026-07-07\n\n### Added\n\n- shiny new thing/,
+  );
+  assert.match(out, /\[Unreleased\]: https:\/\/github\.com\/o\/r\/compare\/v0\.5\.0\.\.\.HEAD/);
+  assert.match(out, /\[0\.5\.0\]: https:\/\/github\.com\/o\/r\/compare\/v0\.4\.0\.\.\.v0\.5\.0/);
+  assert.match(out, /\[0\.4\.0\]: https:\/\/github\.com\/o\/r\/compare\/v0\.3\.1\.\.\.v0\.4\.0/);
+  // the old section is untouched
+  assert.match(out, /## \[0\.4\.0\] - 2026-07-06/);
+});
+
+test("rotateChangelog refuses an already-released version and a missing [Unreleased]", () => {
+  assert.throws(() => rotateChangelog(CHANGELOG, "0.4.0", "0.3.1", "2026-07-07"), /already has/);
+  assert.throws(
+    () => rotateChangelog("# empty\n", "0.5.0", "0.4.0", "2026-07-07"),
+    /no ## \[Unreleased\]/,
+  );
+});
+
+// ---------------------------------------------------------------------------
+// JSON text surgery
+// ---------------------------------------------------------------------------
+
+test("setJsonVersionText replaces only the first version field and keeps formatting", () => {
+  const text =
+    '{\n  "name": "x \\u2014 y",\n  "version": "0.4.0",\n  "dep": { "version": "0.4.0" }\n}\n';
+  const out = setJsonVersionText(text, "0.4.0", "0.5.0");
+  assert.match(out, /"version": "0\.5\.0"/);
+  assert.match(out, /"dep": \{ "version": "0\.4\.0" \}/); // second occurrence untouched
+  assert.match(out, /\\u2014/); // unicode escape preserved (no JSON round-trip)
+  assert.throws(() => setJsonVersionText(text, "9.9.9", "1.0.0"), /no "version"/);
+});
+
+// ---------------------------------------------------------------------------
+// file mutation against a tmp fixture
+// ---------------------------------------------------------------------------
+
+function makeFixture() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "bump-fixture-"));
+  const w = (rel, text) => {
+    fs.mkdirSync(path.dirname(path.join(dir, rel)), { recursive: true });
+    fs.writeFileSync(path.join(dir, rel), text);
+  };
+  w("package.json", '{\n  "name": "fixture",\n  "version": "0.4.0"\n}\n');
+  const lock = {
+    name: "fixture",
+    version: "0.4.0",
+    lockfileVersion: 3,
+    packages: { "": { name: "fixture", version: "0.4.0", engines: { node: ">=20" } } },
+  };
+  w("package-lock.json", `${JSON.stringify(lock, null, 2)}\n`);
+  w(".claude-plugin/plugin.json", '{\n  "name": "fixture",\n  "version": "0.4.0"\n}\n');
+  w(".codex-plugin/plugin.json", '{\n  "name": "fixture",\n  "version": "0.4.0"\n}\n');
+  w("CITATION.cff", 'cff-version: 1.2.0\nversion: 0.4.0\ndate-released: "2026-07-06"\n');
+  w("landing/index.html", '<div class="mono">forgekit v0.4.0 · MIT</div>\n');
+  w("CHANGELOG.md", CHANGELOG);
+  return dir;
+}
+
+test("applyBump updates every version field in a fixture tree", () => {
+  const dir = makeFixture();
+  try {
+    const changed = applyBump(dir, "0.4.0", "0.5.0", "2026-07-07");
+    assert.deepEqual(
+      changed.sort(),
+      [
+        ".claude-plugin/plugin.json",
+        ".codex-plugin/plugin.json",
+        "CHANGELOG.md",
+        "CITATION.cff",
+        "landing/index.html",
+        "package-lock.json",
+        "package.json",
+      ].sort(),
+    );
+    const read = (rel) => fs.readFileSync(path.join(dir, rel), "utf8");
+    assert.equal(JSON.parse(read("package.json")).version, "0.5.0");
+    const lock = JSON.parse(read("package-lock.json"));
+    assert.equal(lock.version, "0.5.0");
+    assert.equal(lock.packages[""].version, "0.5.0");
+    assert.equal(lock.packages[""].engines.node, ">=20"); // untouched fields survive
+    assert.equal(JSON.parse(read(".claude-plugin/plugin.json")).version, "0.5.0");
+    assert.equal(JSON.parse(read(".codex-plugin/plugin.json")).version, "0.5.0");
+    assert.match(read("CITATION.cff"), /^version: 0\.5\.0$/m);
+    assert.match(read("CITATION.cff"), /^date-released: "2026-07-07"$/m);
+    assert.match(read("landing/index.html"), /forgekit v0\.5\.0/);
+    assert.match(read("CHANGELOG.md"), /## \[0\.5\.0\] - 2026-07-07/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("applyBump skips files a fixture does not have", () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "bump-partial-"));
+  try {
+    fs.writeFileSync(path.join(dir, "package.json"), '{\n  "version": "1.0.0"\n}\n');
+    const changed = applyBump(dir, "1.0.0", "1.0.1", "2026-07-07");
+    assert.deepEqual(changed, ["package.json"]);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("collectVersions reports every field and exposes drift", () => {
+  const dir = makeFixture();
+  try {
+    let found = collectVersions(dir);
+    assert.equal(new Set(Object.values(found)).size, 1);
+    // introduce drift
+    fs.writeFileSync(
+      path.join(dir, ".claude-plugin/plugin.json"),
+      '{\n  "name": "fixture",\n  "version": "0.4.1"\n}\n',
+    );
+    found = collectVersions(dir);
+    assert.equal(new Set(Object.values(found)).size, 2);
+    assert.equal(found[".claude-plugin/plugin.json"], "0.4.1");
+    assert.equal(found['package-lock.json (packages."")'], "0.4.0");
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
diff --git a/test/cost_report.test.js b/test/cost_report.test.js
index 3c77f4e..c641b5e 100644
--- a/test/cost_report.test.js
+++ b/test/cost_report.test.js
@@ -207,6 +207,12 @@ test("substrateCheck meters the gate on the explicit path only — ambient hooks
   const gate = readMetrics(explicit, { stage: "gate" });
   assert.equal(gate.length, 1);
   assert.equal(gate[0].outcome, "pass");
+  // P8 route metering rides the same explicit-only contract: the routing decision
+  // lands as one "route" event carrying the chosen tier and a short task-hash ref.
+  const routed = readMetrics(explicit, { stage: "route" });
+  assert.equal(routed.length, 1);
+  assert.ok(["simple", "medium", "complex", "extreme"].includes(routed[0].tier));
+  assert.match(routed[0].ref, /^[0-9a-f]{12}$/);
 
   const ambient = tmp();
   writeFileSync(join(ambient, "math.js"), "export function computeTax(x){ return x * 0.2 }\n");
diff --git a/test/dash.test.js b/test/dash.test.js
index 8b4e8b8..18ae2d0 100644
--- a/test/dash.test.js
+++ b/test/dash.test.js
@@ -5,7 +5,13 @@ import { join } from "node:path";
 import { test } from "node:test";
 import { dashData, serve } from "../src/dash.js";
 import { mintClaim, outcomeRecord } from "../src/ledger.js";
-import { appendEvidence, putClaim, repoLedger, tombstone } from "../src/ledger_store.js";
+import {
+  appendEvidence,
+  loadClaims,
+  putClaim,
+  repoLedger,
+  tombstone,
+} from "../src/ledger_store.js";
 import { record } from "../src/metrics.js";
 
 const tmp = () => mkdtempSync(join(tmpdir(), "forge-dash-"));
@@ -134,12 +140,71 @@ test("serve: / is the page, /api/data is the payload, unknown routes 404, GET-on
     assert.equal((await fetch(`${base}/api/impact`)).status, 400, "missing target");
     assert.equal((await fetch(`${base}/api/impact?target=x`)).status, 404, "no atlas yet");
     assert.equal((await fetch(`${base}/nope`)).status, 404);
+    // The ONLY writes are POST /api/ratify and /api/retract — POST anywhere else is 404,
+    // as is any other method on the write routes.
     assert.equal(
       (await fetch(`${base}/api/data`, { method: "POST" })).status,
       404,
-      "no writes in this phase",
+      "POST to a read route stays 404",
     );
+    assert.equal((await fetch(`${base}/nope`, { method: "POST" })).status, 404);
+    assert.equal(
+      (await fetch(`${base}/api/ratify`, { method: "PUT", body: "{}" })).status,
+      404,
+      "the write routes are POST-only",
+    );
+  } finally {
+    server.close();
+  }
+});
+
+test("serve: POST /api/ratify and /api/retract are the two append-only writes", async () => {
+  process.env.FORGE_AUTHOR = "dash-tester"; // deterministic identity for gitAuthor()
+  const { root, trusted, contested } = fixture();
+  const server = serve(root, { port: 0 });
+  await new Promise((resolve) => server.on("listening", resolve));
+  const addr = /** @type {import("node:net").AddressInfo} */ (server.address());
+  const base = `http://127.0.0.1:${addr.port}`;
+  const post = (path, body) =>
+    fetch(`${base}${path}`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: typeof body === "string" ? body : JSON.stringify(body),
+    });
+  try {
+    // ratify → a decision claim, minted with the human author, linked by full id.
+    const r1 = await post("/api/ratify", { id: trusted.id.slice(0, 8) });
+    assert.equal(r1.status, 200);
+    const out = await r1.json();
+    assert.equal(out.ok, true);
+    assert.equal(out.ratifies, trusted.id);
+    const decision = loadClaims(repoLedger(root)).find((c) => c.kind === "decision");
+    assert.deepEqual(decision.body, { ratifies: trusted.id, note: "" });
+    assert.equal(decision.provenance.author, "dash-tester");
+    // …and the new decision shows up in the read payload.
+    const d = await (await fetch(`${base}/api/data`)).json();
+    assert.equal(d.ledger.stats.byKind.decision, 1);
+    assert.ok(d.ledger.claims.some((c) => c.kind === "decision"));
+
+    // retract → the claim reads as tombstoned in the payload, reason preserved on disk.
+    const r2 = await post("/api/retract", { id: contested.id.slice(0, 8), reason: "wrong port" });
+    assert.equal(r2.status, 200);
+    assert.equal((await r2.json()).ok, true);
+    const d2 = await (await fetch(`${base}/api/data`)).json();
+    const row = d2.ledger.claims.find((c) => c.id8 === contested.id.slice(0, 8));
+    assert.equal(row.tombstoned, true);
+    const onDisk = loadClaims(repoLedger(root)).find((c) => c.id === contested.id);
+    assert.equal(onDisk.tombstone.reason, "wrong port");
+    assert.equal(onDisk.tombstone.author, "dash-tester");
+
+    // Bad bodies → 400; unknown prefixes → 404. Nothing else was written.
+    assert.equal((await post("/api/ratify", "{nope")).status, 400, "bad JSON");
+    assert.equal((await post("/api/ratify", {})).status, 400, "missing id");
+    assert.equal((await post("/api/retract", { id: "x" })).status, 400, "1-char prefix refused");
+    assert.equal((await post("/api/ratify", { id: "zz" })).status, 404, "unknown prefix");
+    assert.equal((await post("/api/retract", { id: "zz", reason: "r" })).status, 404);
   } finally {
+    delete process.env.FORGE_AUTHOR;
     server.close();
   }
 });
diff --git a/test/imagine.test.js b/test/imagine.test.js
index b091061..c0180bd 100644
--- a/test/imagine.test.js
+++ b/test/imagine.test.js
@@ -1,10 +1,17 @@
 import assert from "node:assert/strict";
-import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { test } from "node:test";
 import { build } from "../src/atlas.js";
-import { imagineTask, renderImagine, selectTests, selectTestsReport } from "../src/imagine.js";
+import {
+  dryRun,
+  imagineTask,
+  renderImagine,
+  selectTests,
+  selectTestsReport,
+} from "../src/imagine.js";
 
 const fixture = () => mkdtempSync(join(tmpdir(), "forge-imagine-"));
 
@@ -123,5 +130,93 @@ test("renderImagine prints breaks, the suite, and the sandbox follow-up note", (
   assert.match(out, /minimal dry-run suite/);
   assert.match(out, /src\/app\.test\.js/);
   assert.match(out, /risk score/);
-  assert.match(out, /P5 follow-up/);
+  assert.match(out, /--run/, "footer points at the sandboxed dry-run flag");
+});
+
+// ---------------------------------------------------------------------------
+// dryRun — the sandboxed worktree runner (spec §2.2). One tiny fixture repo,
+// ONE commit: the sandbox is a worktree of HEAD, so everything must be committed.
+// ---------------------------------------------------------------------------
+
+function gitFixture() {
+  const root = fixture();
+  const git = (...args) =>
+    execFileSync("git", args, { cwd: root, stdio: ["ignore", "pipe", "pipe"] });
+  git("init", "-q");
+  git("config", "user.email", "forge@test.invalid");
+  git("config", "user.name", "forge-test");
+  // type:module so `import` in .js is unambiguous across node versions (no reliance
+  // on syntax detection); no test script → dryRun reports the default runner.
+  put(root, "package.json", '{ "name": "fx", "type": "module" }\n');
+  put(root, "src/val.js", "export const val = 1;\n");
+  put(
+    root,
+    "test/pass.test.js",
+    'import assert from "node:assert/strict";\n' +
+      'import { test } from "node:test";\n' +
+      'import { val } from "../src/val.js";\n' +
+      'test("val is 1", () => assert.equal(val, 1));\n',
+  );
+  put(
+    root,
+    "test/fail.test.js",
+    'import assert from "node:assert/strict";\n' +
+      'import { test } from "node:test";\n' +
+      'import { val } from "../src/val.js";\n' +
+      'test("val is 2", () => assert.equal(val, 2));\n',
+  );
+  git("add", "-A");
+  git("-c", "commit.gpgsign=false", "commit", "-qm", "fixture");
+  return { root, git };
+}
+
+const dryrunTmpEntries = () =>
+  new Set(readdirSync(tmpdir()).filter((d) => d.startsWith("forge-dryrun-")));
+
+test("dryRun executes the suite in an ephemeral worktree and removes it (pass + fail)", () => {
+  const { root, git } = gitFixture();
+  const before = dryrunTmpEntries();
+
+  const green = dryRun(root, { tests: ["test/pass.test.js"] });
+  assert.equal(green.ok, true, `dry-run should produce a verdict: ${green.reason ?? ""}`);
+  assert.equal(green.failed, 0);
+  assert.ok(green.passed >= 1, "the passing test actually ran");
+  assert.match(green.runner, /^node --test/);
+  assert.equal(green.worktree, "removed");
+  assert.ok(Number.isFinite(green.durationMs));
+  assert.deepEqual(green.perFile, { "test/pass.test.js": "pass" });
+
+  // ok:true with failed>0 is deliberate: the RUN succeeded — the sandbox built, the
+  // suite executed to a verdict — and the verdict is "these tests fail". ok:false is
+  // reserved for the run itself failing (no repo, timeout, runner crash).
+  const red = dryRun(root, { tests: ["test/pass.test.js", "test/fail.test.js"] });
+  assert.equal(red.ok, true, "a failing SUITE is still a successful RUN");
+  assert.ok(red.failed > 0, "the failure is measured, not hidden");
+  assert.equal(red.passed, 1);
+  assert.equal(red.worktree, "removed");
+  assert.deepEqual(red.perFile, {
+    "test/pass.test.js": "pass",
+    "test/fail.test.js": "fail",
+  });
+  assert.match(red.output, /# fail 1/, "TAP tail is preserved as evidence");
+
+  // The sandbox must actually be gone: no new forge-dryrun-* dirs in tmp, and the
+  // fixture repo's worktree bookkeeping is back to just the main checkout.
+  for (const d of dryrunTmpEntries())
+    assert.ok(before.has(d), `ephemeral worktree dir leaked: ${d}`);
+  const list = git("worktree", "list", "--porcelain").toString();
+  const count = (list.match(/^worktree /gm) || []).length;
+  assert.equal(count, 1, `git worktree list shows leftovers:\n${list}`);
+});
+
+test("dryRun refuses gracefully outside a git repo and on an empty suite", () => {
+  const plain = fixture(); // mkdtemp dir, never git-init'ed
+  const notRepo = dryRun(plain, { tests: ["test/pass.test.js"] });
+  assert.equal(notRepo.ok, false);
+  assert.match(notRepo.reason, /not a git repository/);
+
+  const { root } = gitFixture();
+  assert.equal(dryRun(root, { tests: [] }).ok, false);
+  assert.equal(dryRun(root).ok, false, "missing opts is a precondition failure, not a throw");
+  assert.ok(!existsSync(join(root, ".forge")), "refusal writes nothing into the repo");
 });
diff --git a/test/ledger_store.test.js b/test/ledger_store.test.js
index 967f5bf..76f6de2 100644
--- a/test/ledger_store.test.js
+++ b/test/ledger_store.test.js
@@ -21,6 +21,7 @@ import {
   mergeDirs,
   pruneToAttic,
   putClaim,
+  ratify,
   readEvidence,
   reindex,
   stats,
@@ -170,6 +171,44 @@ test("tombstone: append-only records; concurrent retractions coexist; stats refl
   assert.equal(stats(dir).tombstoned, 1);
 });
 
+test("ratify: mints a decision claim linked to the ratified claim, with the human as author", () => {
+  const dir = tmp();
+  const c = fact("promote-me", "a fahm claim the team decided to stand behind");
+  putClaim(dir, c);
+  const r = ratify(dir, c.id.slice(0, 8), { author: "alice", t: 7 });
+  assert.equal(r.ok, true);
+  assert.equal(r.ratifies, c.id, "the decision points at the FULL resolved id");
+  assert.equal(r.existed, false);
+  const decision = getClaimByPrefix(dir, r.decisionId.slice(0, 8));
+  assert.equal(decision.kind, "decision");
+  assert.deepEqual(decision.body, { ratifies: c.id, note: "" });
+  assert.equal(decision.provenance.author, "alice", "human-only promotion — the caller's identity");
+  assert.equal(decision.provenance.agent, "dash");
+  assert.equal(decision.provenance.t, 7);
+  assert.equal(loadClaims(dir).length, 2, "append-only: the ratified claim is untouched");
+});
+
+test("ratify: refuses an unknown prefix instead of minting a dangling decision", () => {
+  const dir = tmp();
+  putClaim(dir, fact("only", "claim"));
+  const r = ratify(dir, "zz", { author: "alice", t: 7 });
+  assert.equal(r.ok, false);
+  assert.match(r.reason, /no claim matching zz/);
+  assert.equal(loadClaims(dir).length, 1, "nothing was minted");
+});
+
+test("ratify: idempotent — the same content converges on the same decision (existed)", () => {
+  const dir = tmp();
+  const c = fact("stable", "ratify me twice");
+  putClaim(dir, c);
+  const first = ratify(dir, c.id.slice(0, 8), { author: "alice", t: 7 });
+  const again = ratify(dir, c.id.slice(0, 8), { author: "alice", t: 7 });
+  assert.equal(again.ok, true);
+  assert.equal(again.decisionId, first.decisionId, "content-addressed → same decision id");
+  assert.equal(again.existed, true);
+  assert.equal(loadClaims(dir).filter((x) => x.kind === "decision").length, 1);
+});
+
 test("getClaimByPrefix: finds one claim via its shard without scanning the ledger", () => {
   const dir = tmp();
   const c = fact("needle", "in a stack of shards");
diff --git a/test/route.test.js b/test/route.test.js
index 2dadcab..4b1842a 100644
--- a/test/route.test.js
+++ b/test/route.test.js
@@ -3,10 +3,12 @@ import { existsSync, mkdtempSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { test } from "node:test";
+import { read as readMetrics } from "../src/metrics.js";
 import {
   complexity,
   complexityLLM,
   emitGatewayConfig,
+  meterRoute,
   recommend,
   routeTask,
 } from "../src/route.js";
@@ -155,6 +157,19 @@ test("routeTask (llm on): fires exactly ONE model call — no redundant inner as
   assert.equal(calls, 1, "routeTask must not also run an assumption model call");
 });
 
+test("meterRoute: one route metrics event lands with the chosen tier; routeTask itself never writes", () => {
+  const root = mkdtempSync(join(tmpdir(), "forge-route-"));
+  const task = "write a function to check if a number is prime";
+  const rec = routeTask(root, task);
+  assert.deepEqual(readMetrics(root, { stage: "route" }), [], "routing alone is write-free");
+  meterRoute(root, task, rec);
+  const events = readMetrics(root, { stage: "route" });
+  assert.equal(events.length, 1, "the explicit caller meters exactly once");
+  assert.equal(events[0].tier, rec.tier, "the event carries the chosen tier");
+  assert.match(events[0].ref, /^[0-9a-f]{12}$/, "ref is a short task hash, not the task text");
+  assert.ok(!JSON.stringify(events[0]).includes("prime"), "task text never leaks into metrics");
+});
+
 test("routeTask: a precomputed ambiguity matches computing it internally", () => {
   const root = mkdtempSync(join(tmpdir(), "forge-route-"));
   const task = "add a validation helper";
diff --git a/test/uifingerprint.test.js b/test/uifingerprint.test.js
index 6a36abc..c11a893 100644
--- a/test/uifingerprint.test.js
+++ b/test/uifingerprint.test.js
@@ -8,15 +8,19 @@ import { fileURLToPath } from "node:url";
 import { loadClaims, repoLedger } from "../src/ledger_store.js";
 import { ASSERTABLE_CHECKS } from "../src/uicheck.js";
 import {
+  activeTasteStyle,
   conformance,
   fingerprintFiles,
   fingerprintText,
   GENERIC_SIGNATURES,
   inferSpacingBase,
   loadProjectFingerprint,
+  loadTasteProfile,
   mintProjectFingerprint,
   nearestGeneric,
   onScaleFraction,
+  profileChecks,
+  resolveCssVars,
   scaleChecks,
   slopDistance,
   UI_GATE_DEFAULTS,
@@ -97,6 +101,54 @@ test("fingerprintText is deterministic (same text → deep-equal vector)", () =>
   assert.deepEqual(fingerprintText(CUSTOM_CSS), fingerprintText(CUSTOM_CSS));
 });
 
+// A token-driven stylesheet: the whole 4px scale lives in custom properties and is
+// only ever consumed through var() — extraction must see the full scale anyway.
+const TOKEN_CSS = `
+:root { --s1: 4px; --s2: 8px; --s3: 12px; --s4: 16px; --s6: 24px; --s8: 32px;
+  --r: var(--s1); --accent: #e63946; }
+.card { padding: var(--s3) var(--s6); margin: var(--s2); gap: var(--s4);
+  border-radius: var(--r); color: var(--accent); }
+.hero { padding: var(--s8); margin-bottom: var(--s1); }
+`;
+
+test("resolveCssVars: declared tokens substitute into their var() uses", () => {
+  const out = resolveCssVars(":root { --pad: 12px; } .a { padding: var(--pad); }");
+  assert.match(out, /padding: 12px/);
+});
+
+test("fingerprintText: a var()-consumed 4px token scale fingerprints as the FULL scale", () => {
+  const fp = fingerprintText(TOKEN_CSS);
+  assert.deepEqual(fp.spacing, [4, 8, 12, 16, 24, 32], "all six token values extracted");
+  assert.equal(fp.spacingBase, 4);
+  assert.equal(fp.spacingOnScale, 1);
+  assert.deepEqual(fp.radii, [4], "one level of nesting: --r: var(--s1) resolves");
+  assert.ok(
+    fp.palette.some((c) => c.h === 355),
+    "the accent hex reaches color extraction through var()",
+  );
+});
+
+test("resolveCssVars: var() fallback used when undeclared; declared value beats fallback", () => {
+  const fp = fingerprintText(
+    ":root { --gap: 24px; } .a { padding: var(--nope, 12px); margin: var(--gap, 99px); }",
+  );
+  assert.deepEqual(fp.spacing, [12, 24]);
+  // A nested-var fallback resolves too (bounded extra text passes).
+  const nested = fingerprintText(":root { --s: 20px; } .a { gap: var(--nope, var(--s, 2px)); }");
+  assert.deepEqual(nested.spacing, [20]);
+});
+
+test("resolveCssVars: unresolvable var() left as-is and ignored by extractors", () => {
+  const fp = fingerprintText(".a { padding: var(--ghost); margin: 8px; }");
+  assert.deepEqual(fp.spacing, [8], "the unresolved var contributes nothing");
+});
+
+test("resolveCssVars: a custom-property cycle terminates (bounded loop, no hang)", () => {
+  const cyclic = ":root { --a: var(--b); --b: var(--a); } .x { padding: var(--a); gap: 16px; }";
+  const fp = fingerprintText(cyclic); // returning at all IS the test
+  assert.deepEqual(fp.spacing, [16], "cyclic values stay invisible to extraction");
+});
+
 test("inferSpacingBase: largest base that fits wins; off-scale falls back to argmin", () => {
   assert.equal(inferSpacingBase([8, 16, 32]), 8);
   assert.equal(inferSpacingBase([4, 12, 20]), 4, "multiples of 4 but not 8 → 4, not 2");
@@ -228,6 +280,108 @@ test("cli: `uicheck design` exits 1 on the generic fixture, names the fixes", ()
   assert.match(r.stdout, /FAIL/);
 });
 
+test("loadTasteProfile: all five profiles load with full constraint sets; unknown → null", () => {
+  for (const name of ["brutalist", "corporate", "editorial", "minimalist", "playful"]) {
+    const p = loadTasteProfile(name);
+    assert.ok(p, `${name}.json loads`);
+    assert.ok(p.why.length > 40, `${name} documents its rationale`);
+    assert.ok(p.palette.max_hues >= 1);
+    assert.ok(p.palette.chroma[0] >= 0 && p.palette.chroma[1] <= 1, "chroma is a 0-1 s-proxy");
+    assert.ok(p.space.base.every((b) => [4, 8].includes(b)));
+    assert.ok(p.type.max_families >= 1);
+    assert.ok(p.shape.radius_levels[0] <= p.shape.radius_levels[1]);
+    assert.ok(p.shape.shadow_levels[0] <= p.shape.shadow_levels[1]);
+    assert.ok(p.gate.tau_slop > 0 && p.gate.tau_conform > 0);
+  }
+  assert.equal(loadTasteProfile("nope"), null);
+  assert.equal(loadTasteProfile("../brand"), null, "a name, never a path");
+});
+
+test("taste profiles encode their prose: brutalist is square+strict, playful is rounder+looser", () => {
+  const brutalist = loadTasteProfile("brutalist");
+  const playful = loadTasteProfile("playful");
+  const corporate = loadTasteProfile("corporate");
+  assert.deepEqual(brutalist.shape.radius_levels, [0, 0], "DON'T round corners");
+  assert.ok(
+    brutalist.gate.tau_slop > UI_GATE_DEFAULTS.tauSlop,
+    "brutalist demands MORE distance from generic",
+  );
+  assert.ok(playful.palette.max_hues > brutalist.palette.max_hues, "playful allows more hues");
+  assert.ok(playful.shape.radius_levels[0] >= 1, "playful REQUIRES rounding");
+  assert.ok(
+    corporate.gate.tau_slop < UI_GATE_DEFAULTS.tauSlop,
+    "corporate deliberately sits near convention",
+  );
+});
+
+test("profileChecks: brutalist flags rounded/shadowed output; the custom fixture fits editorial", () => {
+  const generic = fingerprintText(GENERIC_CSS); // rounded-12, one shadow, 8px base
+  const byId = Object.fromEntries(
+    profileChecks(generic, loadTasteProfile("brutalist")).map((c) => [c.id, c]),
+  );
+  assert.equal(byId["taste-radius"].pass, false, "12px radius breaks radius_levels [0,0]");
+  assert.match(byId["taste-radius"].hint, /square corners/);
+  assert.equal(byId["taste-spacing-base"].pass, true, "8 is in brutalist's base list");
+  const custom = fingerprintText(CUSTOM_CSS); // ink/paper + one accent, 4-base, 2 faces
+  assert.ok(
+    profileChecks(custom, loadTasteProfile("editorial")).every((c) => c.pass),
+    "the editorial-ish fixture passes the editorial constraint set",
+  );
+  // playful REQUIRES elevation the flat custom fixture lacks — lower bounds bind too.
+  const playful = Object.fromEntries(
+    profileChecks(custom, loadTasteProfile("playful")).map((c) => [c.id, c]),
+  );
+  assert.equal(playful["taste-shadow"].pass, false);
+  assert.match(playful["taste-shadow"].hint, /at least 1/);
+});
+
+test("uiGate: taste thresholds override the defaults (same vector, different verdict)", () => {
+  const custom = fingerprintText(CUSTOM_CSS);
+  const slop = slopDistance(custom);
+  assert.equal(uiGate(custom).pass, true, "passes the default tau");
+  const strict = uiGate(custom, { tauSlop: slop + 0.01 });
+  assert.equal(strict.pass, false, "a stricter profile tau flips the verdict");
+  assert.ok(strict.violations.length > 0, "and still names the driving features");
+});
+
+test("cli: `uicheck design --taste <name>` uses the profile's thresholds and checks", () => {
+  const cwd = tmp();
+  writeFileSync(join(cwd, "app.css"), CUSTOM_CSS);
+  const r = runCli(["uicheck", "design", "app.css", "--taste", "editorial", "--json"], cwd);
+  assert.equal(r.status, 0, r.stdout + r.stderr);
+  const out = JSON.parse(r.stdout);
+  assert.equal(out.taste, "editorial");
+  assert.equal(out.tauSlop, loadTasteProfile("editorial").gate.tau_slop);
+  assert.ok(
+    out.checks.some((c) => c.id === "taste-radius"),
+    "profile checks ride along",
+  );
+  // brutalist's [0,0] radius bound fails the same file (it has a 2px radius).
+  const b = runCli(["uicheck", "design", "app.css", "--taste", "brutalist", "--json"], cwd);
+  assert.equal(b.status, 1);
+  const bout = JSON.parse(b.stdout);
+  assert.equal(bout.checks.find((c) => c.id === "taste-radius").pass, false);
+  // An unknown explicit profile is an error, not a silent default.
+  const bad = runCli(["uicheck", "design", "app.css", "--taste", "nope"], cwd);
+  assert.equal(bad.status, 1);
+  assert.match(bad.stderr, /unknown taste profile/);
+});
+
+test("cli: a forge-taste-managed DESIGN.md auto-picks the profile when --taste is absent", () => {
+  const cwd = tmp();
+  writeFileSync(join(cwd, "app.css"), CUSTOM_CSS);
+  const applied = runCli(["taste", "editorial"], cwd);
+  assert.equal(applied.status, 0, applied.stderr);
+  assert.equal(activeTasteStyle(cwd), "editorial");
+  const r = runCli(["uicheck", "design", "app.css", "--json"], cwd);
+  const out = JSON.parse(r.stdout);
+  assert.equal(out.taste, "editorial", "the pinned style is picked up");
+  assert.equal(out.tauSlop, loadTasteProfile("editorial").gate.tau_slop);
+  // A hand-written (unmanaged) DESIGN.md pins nothing.
+  writeFileSync(join(cwd, "DESIGN.md"), "# my own design notes\n");
+  assert.equal(activeTasteStyle(cwd), null);
+});
+
 test("cli: fingerprint --mint stores the project claim; design then gates against it", () => {
   const cwd = tmp();
   writeFileSync(join(cwd, "app.css"), CUSTOM_CSS);
diff --git a/tsconfig.json b/tsconfig.json
index ff09581..c0d6f1d 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -13,5 +13,5 @@
     "noUnusedLocals": true,
     "types": ["node"]
   },
-  "include": ["src/**/*.js"]
+  "include": ["src/**/*.js", "scripts/**/*.mjs"]
 }