CodeWithJuber · CodeWithJuber · Jul 17, 2026 · Jul 17, 2026 · Jul 17, 2026
@@ -231,15 +231,18 @@ parses) swept against every doc artifact → UPDATED / STALE (file:line hits) /
 VERIFIED-UNAFFECTED with the reason recorded. Pure reporter; the gate provides the teeth.
 
 **Docs-check now guards more than names (`src/docs_check.js`).** Beyond
-commands/env/MCP-tools/CHANGELOG, five reconcilers close the blind spots behind recurring
+commands/env/MCP-tools/CHANGELOG, six reconcilers close the blind spots behind recurring
 "docs rot" complaints: `checkDiagrams` scans every `mermaid` block across all Markdown for
 the branded `%%{init` theme and literal-`\n` node breaks; `checkModelTiers` reconciles doc
 prose prices against `src/model_tiers.json`; `checkBenchmarks` reconciles bolded `N ms`
 README claims against the measured table in `reports/benchmarks.md`; `checkLinks` resolves
 every intra-repo Markdown anchor (`#x` and `path.md#x`) against the target's real headings
 (GitHub-exact slugs — em-dashes yield `--`, never collapsed), killing the dead-anchor class;
-and `checkRoadmap` fails when the ROADMAP's "Now" marker trails the shipped `package.json`
-version. The two public pages
+`checkRoadmap` fails when the ROADMAP's "Now" marker trails the shipped `package.json`
+version; and `checkCrosswalk` resolves every `.js`/`.sh` binding the research paper's
+crosswalk (`research/formal-synthesis/crosswalk.json`) claims for this repo against the
+files that actually exist in `src/`, `global/guards/`, and `hooks/` (kit-only names opt
+out with a `kit:` prefix), so the paper's stated bindings can no longer trail the code. The two public pages
 (`landing/index.html` + the `build-pages.mjs` status page) derive from ONE color source —
 `brand.json.colors` (full dark + light palettes), emitted as CSS by `src/brand.js`
 (`rootTokensCss()`). `test/pages.test.js` enforces full-palette parity: every hex in

@@ -6,6 +6,26 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Added
+
+- **Color-aware CLI output.** New zero-dep `src/fmt.js`: `supportsColor` honoring the
+  `FORCE_COLOR` > `NO_COLOR` > `TERM=dumb` > TTY precedence, brand-token painting
+  (24-bit from `brand.json` when `COLORTERM` declares truecolor, portable 16-color
+  fallback otherwise), visible-width-aligned `table`, and `bar` confidence meters —
+  adopted across `ledger` (stats/blame/query), `cortex`, `route`, `doctor`, and
+  `cost` output plus the `--verbose` title line. Piped output stays escape-free.
+
+### Fixed
+
+- **Research crosswalk reconciled with the code.** The formal-synthesis paper's
+  crosswalk (rows 5/6/12/14 and the README §11 binding paragraph) cited hooks that
+  no longer exist (`docs-guard.sh`, `session-context.sh`, `intent-router.sh`); the
+  bindings now name the real system (`cortex.sh` → `src/gate.js` stopGate,
+  `src/session.js` rehydrationBlock, `src/intent.js` exemplar k-NN), with kit-only
+  names marked by a `kit:` prefix. A new `crosswalk` docs-check reconciler fails CI
+  when any non-`kit:` `.js`/`.sh` binding in `crosswalk.json` names a file that does
+  not exist in `src/`, `global/guards/`, or `hooks/`.
+
 ## [0.18.0] - 2026-07-16
 
 ### Changed

@@ -169,6 +169,10 @@ Advisory by default. Set `FORGE_ENFORCE=1` to turn the substrate into a hard blo
 strongest signals (vacuous prompt, un-assemblable required context, blast radius over the
 default 25-file threshold).
 
+Output is plain text when piped; on a TTY it adds brand-palette color and confidence
+meters. `NO_COLOR` turns color off, `FORCE_COLOR=1` forces it on (e.g. in CI, `0`
+forces off), and `TERM`/`COLORTERM` follow the usual terminal conventions.
+
 | Group                      | Command           | Does                                                                                                               |
 | -------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------ |
 | **Config layer**           | `forge init`      | emit every tool's native config from one source                                                                    |

@@ -1075,6 +1075,9 @@ code reads but this table misses fails CI on the forge repo):
 | `FORGE_STOPGATE`                                               | `0` disables the Stop completion gate (code-without-docs block)                                               |
 | `FORGE_INTENT`                                                 | `0` disables intent protocol cards on prompts                                                                 |
 | `FORGE_VERBOSE`                                                | `1` restores the `Forge <cmd>` title line on command output (also `--verbose`)                                |
+| `NO_COLOR`                                                     | set (non-empty) disables ANSI color in CLI output — the [no-color.org](https://no-color.org) convention       |
+| `FORCE_COLOR`                                                  | forces CLI color on even when piped, e.g. in CI (`0` forces off) — takes precedence over `NO_COLOR`           |
+| `TERM` / `COLORTERM`                                           | `TERM=dumb` disables color; `COLORTERM=truecolor`/`24bit` upgrades to the brand palette's 24-bit hues         |
 | `FORGE_NO_UPDATE_CHECK`                                        | `1` silences the `forge doctor` update notice                                                                 |
 | `FORGE_DEBUG`                                                  | `1` writes fail-safe error details to stderr instead of swallowing them                                       |
 

@@ -8,7 +8,7 @@ frozen language model reliable at coding:
    (memory, learning, imagination, self-correction, impact-awareness) and six
    operating mechanisms M1–M6, with two runnable prototypes.
 2. **The End-to-End Agent Reliability Framework** (`FRAMEWORK.md`) — failure modes
-   F1 (partial work) and F2 (session amnesia), the change-closure fixpoint Δ*,
+   F1 (partial work) and F2 (session amnesia), the change-closure fixpoint Δ\*,
    invariants I1–I4, algorithms A1–A7, and correctness theorems T1–T6.
 3. **forgekit / claude-e2e-kit** — the deployed implementation: committed-file
    memory, deterministic lifecycle hooks, and auto-invoked skills.
@@ -20,39 +20,39 @@ The synthesis proves these are **one object in three vocabularies**.
 > **Reliability = a probabilistic instruction layer × a deterministic interception
 > layer. Neither layer alone suffices.**
 
-Instructions (`CLAUDE.md`, rules, skills) *raise* the probability `p < 1` that the
+Instructions (`CLAUDE.md`, rules, skills) _raise_ the probability `p < 1` that the
 model behaves correctly, but can never reach `p = 1` — so the residual silent-miss
 rate over `n` tasks is `1 − pⁿ → 1`. A deterministic layer (hooks that execute
 regardless of the model's choice) multiplies that residual down by a factor
-`(1 − cⱼ)` per check — but cannot catch the *semantic* class (undecidable, by Rice's
+`(1 − cⱼ)` per check — but cannot catch the _semantic_ class (undecidable, by Rice's
 theorem), so it needs the soft layer to shrink what reaches it. The paper states this
 as **Theorem D** and proves it. It is the formal content of the practitioner's rule:
-*never trust the output of a probability engine; earn trust with an external check.*
+_never trust the output of a probability engine; earn trust with an external check._
 
 ## Three anchor identities (not analogies — the same mathematics)
 
-| Substrate | Framework | Relationship |
-|---|---|---|
-| Impact-Oracle blast-radius | change-closure `Δ*` (least fixpoint of `X ↦ X ∪ N(X)`) | **identical** — reverse reachability, run to fixpoint ⇒ perfect recall |
-| M2 assumption gate | amnesia equation `assumption ≈ argmax P(convention \| training)` | **identical** — the gate supplies missing context or halts, never guesses |
-| substrate's two layers | design law "Π₃ probabilistic, Π₂ deterministic" | **identical** — Theorem D |
+| Substrate                  | Framework                                                        | Relationship                                                              |
+| -------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| Impact-Oracle blast-radius | change-closure `Δ*` (least fixpoint of `X ↦ X ∪ N(X)`)           | **identical** — reverse reachability, run to fixpoint ⇒ perfect recall    |
+| M2 assumption gate         | amnesia equation `assumption ≈ argmax P(convention \| training)` | **identical** — the gate supplies missing context or halts, never guesses |
+| substrate's two layers     | design law "Π₃ probabilistic, Π₂ deterministic"                  | **identical** — Theorem D                                                 |
 
 ## Contents
 
-| File | What it is |
-|---|---|
-| `substrate_synthesis.pdf` | The formal synthesis paper (42 pp): definitions, Theorem D + proof, the unified A1–A7 TASK loop, invariants I1–I4, theorems T1–T6 with proofs, the 16-row crosswalk, the full 14-mapping Qur'anic epistemology, both prototypes with honest metrics. |
-| `substrate_synthesis.html` | Same paper, self-contained HTML. |
-| `crosswalk.json` / `crosswalk.md` | The three-way term-by-term correspondence (substrate ↔ framework ↔ forgekit), with the P1/P2/P3 → Π₁/Π₂/Π₃ notation reconciliation. |
-| `graded_reference_set.json` / `.md` | The 15 new sources independently verified and graded (9 confirmed, 6 traceable, 0 unverifiable), including the disambiguation of the two future-dated arXiv IDs. |
-| `merged_references.json` | Full 47-entry bibliography (32 original + 15 new, deduped). |
-| `figures/schematic_duality.png` | The two-layer duality architecture. |
-| `figures/schematic_taskloop.png` | The unified 7-stage TASK loop (each stage bound to faculty · algorithm · Qur'anic anchor). |
+| File                                | What it is                                                                                                                                                                                                                                           |
+| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `substrate_synthesis.pdf`           | The formal synthesis paper (42 pp): definitions, Theorem D + proof, the unified A1–A7 TASK loop, invariants I1–I4, theorems T1–T6 with proofs, the 16-row crosswalk, the full 14-mapping Qur'anic epistemology, both prototypes with honest metrics. |
+| `substrate_synthesis.html`          | Same paper, self-contained HTML.                                                                                                                                                                                                                     |
+| `crosswalk.json` / `crosswalk.md`   | The three-way term-by-term correspondence (substrate ↔ framework ↔ forgekit), with the P1/P2/P3 → Π₁/Π₂/Π₃ notation reconciliation.                                                                                                                  |
+| `graded_reference_set.json` / `.md` | The 15 new sources independently verified and graded (9 confirmed, 6 traceable, 0 unverifiable), including the disambiguation of the two future-dated arXiv IDs.                                                                                     |
+| `merged_references.json`            | Full 47-entry bibliography (32 original + 15 new, deduped).                                                                                                                                                                                          |
+| `figures/schematic_duality.png`     | The two-layer duality architecture.                                                                                                                                                                                                                  |
+| `figures/schematic_taskloop.png`    | The unified 7-stage TASK loop (each stage bound to faculty · algorithm · Qur'anic anchor).                                                                                                                                                           |
 
 The **two runnable prototypes** referenced throughout the paper already live in this
 repo and are not duplicated here:
 
-- `../python-prototypes/impact_oracle/` — Prototype I, the impact oracle (A1 / Δ*).
+- `../python-prototypes/impact_oracle/` — Prototype I, the impact oracle (A1 / Δ\*).
   Runnable, 36 tests. Perfect recall on impacted files.
 - `../python-prototypes/router_gate/` — Prototype II, complexity-router +
   assumption-gate (A7 + A6 / M1 + M2). Runnable, 19 tests. 62.1% real cost saved,
@@ -62,22 +62,24 @@ repo and are not duplicated here:
 
 - **The prototypes are demonstrations, not benchmarks.** The router/gate's perfect
   accuracy is on a 30-task hand-labelled set whose thresholds were tuned against it —
-  it shows the rubric *can separate* the cases. The cost figures, by contrast, are
+  it shows the rubric _can separate_ the cases. The cost figures, by contrast, are
   exact arithmetic on **real measured token counts** from live model calls, and the
   correctness sub-experiment actually executed the cheaper models' code against tests.
 - **The impact oracle does not win on F1** (0.75 vs grep's 0.79). Its property is
   **perfect recall** — the safety guarantee for "what will my edit break?".
 - **Every future-dated / recent citation was verified by direct fetch, not inferred.**
-  Both 2026 arXiv IDs resolve to real preprints; one (`2601.05111`) is a *different*
+  Both 2026 arXiv IDs resolve to real preprints; one (`2601.05111`) is a _different_
   paper from the founding Agent-as-a-Judge work (`2410.10934`), and both are recorded.
 - **The Qur'anic lens is framing, never technical authority.** It supplies the
-  vocabulary of epistemic obligation — *lā taqfu*, *tabayyun*, *al-amāna* — that names
-  *why* each safeguard is mandatory; the engineering stands on its own merits.
+  vocabulary of epistemic obligation — _lā taqfu_, _tabayyun_, _al-amāna_ — that names
+  _why_ each safeguard is mandatory; the engineering stands on its own merits.
 
 ## Relationship to forgekit
 
 `forgekit` is one binding of this theory (and `claude-e2e-kit` is its Claude-specific
 reference realization). The paper's §11 gives the exact object-by-object mapping:
-`Π₁` = the committed `docs/*.md` store, `Π₂` = the `session-context` / `docs-guard` /
-`intent-router` hooks, `Π₃` = `CLAUDE.md` + `.claude/rules/`. The two prototypes here
+`Π₁` = the committed `docs/*.md` store, `Π₂` = the `cortex.sh` hook chain
+(`src/cortex_hook_main.js` dispatching `src/gate.js` stopGate, `src/session.js`
+rehydrationBlock, and `src/intent.js` intent routing; kit: `session-context` /
+`docs-guard` / `intent-router`), `Π₃` = `CLAUDE.md` + `.claude/rules/`. The two prototypes here
 are the mechanical cores of the `/impact` skill and the effort-router.
@@ -46,14 +46,14 @@
       "concept": "Self-correction / verification",
       "substrate": "M6 inline verification; Prototype-II verify step; self-correction faculty",
       "framework": "Algorithm A6 COMPLETION-GATE (deterministic Stop-hook floor); Hoare postcondition Done(t); the verification operator in A3 (verified-unaffected requires an actual grep, not an assumption)",
-      "forgekit": "docs-guard.sh Stop hook (blocks finish if code changed but no doc/state artifact did); reviewer agent verdict",
+      "forgekit": "src/gate.js stopGate Stop hook via cortex.sh (blocks finish if code changed but no doc/state artifact did; kit: docs-guard.sh); reviewer agent verdict",
       "relation": "Same verify-gate. Substrate framed it as a mechanism; framework proves it terminates (T1) and is sound (T3) and makes it the deterministic layer of the duality."
     },
     {
       "concept": "Complexity routing",
       "substrate": "M1 complexity-aware router (transparent additive rubric); Prototype-II router",
       "framework": "Algorithm A7 KNOWLEDGE-ROUTER (where every fact lives, keeps always-loaded context bounded); System 1/System 2 effort routing; intent DFA",
-      "forgekit": "intent-router.sh (UserPromptSubmit hook, keyword DFA, <10ms, zero-token); effort-routing rule in CLAUDE.md; per-agent model: fields",
+      "forgekit": "src/intent.js exemplar k-NN intent classifier (UserPromptSubmit via cortex.sh, zero-token; kit: intent-router.sh keyword DFA); effort-routing rule in CLAUDE.md; per-agent model: fields",
       "relation": "Two facets of one routing principle. Substrate M1 routes by TASK COMPLEXITY -> model tier (cost). Framework A7 routes by KNOWLEDGE TYPE -> storage home (context budget). Both are transparent/deterministic, both reject an opaque-LLM classifier for the same reason."
     },
     {
@@ -95,7 +95,7 @@
       "concept": "Rehydration (session start)",
       "substrate": "closed-loop write-back/read-back band in the substrate architecture",
       "framework": "Algorithm A5 CONTEXT-REHYDRATE; loader L; records git baseline for the gate",
-      "forgekit": "session-context.sh SessionStart hook; /catchup skill (deep variant)",
+      "forgekit": "src/session.js rehydrationBlock SessionStart injection via cortex.sh (kit: session-context.sh); /catchup skill (deep variant)",
       "relation": "The read side of the substrate's memory loop, made deterministic (inject, don't hope the agent reads)."
     },
     {
@@ -109,7 +109,7 @@
       "concept": "The two-layer duality (THE central new insight)",
       "substrate": "implicit: the substrate wraps a probabilistic core with deterministic external structure, but v2 never states it as a law",
       "framework": "DESIGN LAW: instructions (Pi3) are PROBABILISTIC (raise p); interception (Pi2) is DETERMINISTIC (guarantee a floor c->1). P(silent miss) = (1-p)\u00b7prod_j(1-c_j). Since p<1 always, neither layer alone suffices.",
-      "forgekit": "the split itself: CLAUDE.md/rules/skills = soft layer; hooks (docs-guard, session-context, intent-router) = hard layer",
+      "forgekit": "the split itself: CLAUDE.md/rules/skills = soft layer; hooks (cortex.sh -> src/gate.js, src/session.js, src/intent.js; kit: docs-guard, session-context, intent-router) = hard layer",
       "relation": "THIS is what the kit gives the substrate theory: the reason the substrate must be TWO layers, stated as a theorem. The user's own discipline ('never trust AI output \u2014 it is calculated probability') is exactly (1-p)>0, which forces the deterministic layer."
     },
     {
@@ -127,4 +127,4 @@
       "relation": "The ethical frame the substrate draws from the lens is realized as concrete safety properties in the framework (fail-open, reversibility) and kit (auditable hooks)."
     }
   ]
-}
+}