@mindrian_os/cli 2.0.0-beta.3 → 2.0.0-beta.33

package/lib/render/ROOM.md

@@ -0,0 +1,111 @@
+# lib/render/ -- Universal Renderer
+
+> ICM Layer 0 identity for the renderer module.
+
+## Purpose
+
+The universal renderer translates a 4-zone payload + render mode + conversation operator + tier into the actual on-screen output. Owns the `render(zones, mode, operator, tier)` contract.
+
+## Phase status
+
+- **Phase 99-03 (shipped):** contract surface + no-op pass-through stub. Callers can import `{ render }` today; envelope returns `rendered: false` + `_stub: 'phase-99-03'` provenance tag. Operator validation against the 5 canonical values (JUST_TALK / EXPLORE_CAPTURE / BUILD_ROOM / METHODOLOGY / DECISION_GATE) ships now so Phase 102 inherits the fence.
+- **Phase 102 (shipped):** replaces the stub internals with real rendering logic per Phase 99 CONTEXT.md D-16. Same import surface; no caller changes. The destructured `render({ zones, mode, operator, tier, jtbd, tokenBudget, roomDir, provenance })` API ships; the legacy 4-arg signature stays alive at `lib/render/render.cjs` as a thin shim that forwards to v2.
+- **Phase 121.5-04 (shipped, Sub-plan E):** the long-open question of whether render-v2 should be wired into the ordinary Larry prose path is resolved -- see **Disposition** below.
+
+## Disposition (Sub-plan E, 2026-05-16)
+
+> **render-v2 stays agent-surface-only by design.** SKILL.md remains the canonical prose contract for Larry's main conversation path. The v2 destructured `render()` entry is reserved for /mos:* command surfaces and the Shape F decision-gate output side that route through `lib/hmi/selector-dispatcher.cjs`.
+
+This is the disposition that Phase 121.5 commits to for v1.13.0 final. The verdict was locked at plan-phase after the 2026-05-16 dual-graph review. Sub-plan E (this plan, 121.5-04) closes the open question; Sub-plan E ALSO closes the Phase 102 release loop by shipping `102-VERIFICATION.md` and flipping `102-VALIDATION.md` out of `status: draft`.
+
+### Allowed render-v2 consumers (current production set)
+
+| Consumer | Role | Why allowed |
+|----------|------|-------------|
+| `lib/render/render.cjs` | v1 legacy-signature shim | Reuses v2 muscle for the 4-arg positional API per Phase 102 CONTEXT D-10. One renderer, two entry points (Canon Part 7). |
+| `lib/hmi/selector-dispatcher.cjs` | Shape F / Shape E agentic dispatcher | The /mos:* command output side -- Canon Part 3 tri-context decision-gate enforcement surface. NOT the ordinary prose path. |
+
+CI gate: `lib/memory/render-v2-disposition.test.cjs` asserts the allowlist matches this table on every test run. The operator-facing audit lives at `scripts/disposition-render-v2.cjs` (`--json` for machine-readable, default for human summary; exit 1 on any prose-path import).
+
+### Why not wire it into the prose path
+
+Three reasons, in priority order:
+
+1. **Canon Part 7 (Reuse Before Build).** SKILL.md is the canonical prose contract today; it ships, it is exercised on every Larry turn, and the 4-zone format is enforced by skill instruction. Replacing instruction-side enforcement with code-side enforcement would be a parallel implementation rather than reuse, which is the bar the canon explicitly raises against.
+2. **Canon Part 3 (the gate output side).** The v2 destructured signature was designed for Shape F.x gate surfaces -- decision-gate output, not free prose. The compaction layer (102-02), JTBD-aware Zone 4 (102-03), provenance envelope (102-04), and color overlay (102-05) all assume gate-bounded payloads. Wrapping them around ordinary prose would silently change Larry's conversational shape -- a regression risk against Phase 88.1 + 88.2 + the Part 10 capstone work.
+3. **Phase 121.5 capstone scope.** Sub-plan C reconciles SKILL.md v2 with the shipped Shape F set + dual palette + the 🎯/JTBD disambiguation. After 121.5 lands, SKILL.md IS the source of truth -- a separate v1.14.0 phase can revisit whether code-side prose rendering still earns its keep against a freshly-reconciled SKILL.md.
+
+### Current rankable input signal types (additive expansion reserved)
+
+The render-v2 entry today consumes a closed-by-version-but-open-by-future set of typed inputs:
+
+| Signal | Source | Phase shipped |
+|--------|--------|----------------|
+| `operator` (5 canonical: JUST_TALK / EXPLORE_CAPTURE / BUILD_ROOM / METHODOLOGY / DECISION_GATE) | Phase 99 conversation operator state machine | 99-03 |
+| `mode` ('A' / 'B' / 'tier-0') | Phase 90 brain-derivation tier-awareness | 102-04 |
+| `tier` (0/1/2/3) | Phase 90 brain-derivation gating | 102-04 |
+| `jtbd` (one of 13 canonical Phase 100 handles or null) | Phase 100 JTBD inference engine | 102-03 |
+| `tokenBudget` ({used, total}) | Phase 102-02 compaction layer | 102-02 |
+| `provenance` (caller-supplied; NOT folded into `_provenance`) | Phase 90 brain-derived inputs | 102-04 |
+
+These are the input signal types render-v2 accepts **as of Phase 121.5-04** (additive expansion is reserved for future lens-aware variants once the dual-graph proposal lands -- ASSOCIATION_LENS + TRANSITION_LENS lens classes may add lens-derived signals). The set is current; it is not closed for all time. Per Canon Part 7 language discipline: "current" / "as of" / "today" framing is the convention -- never "final" / "complete" / "closed set" framing.
+
+## Files
+
+| File | Role |
+|------|------|
+| render-v2.cjs | Contract surface + Phase 102 implementation. Exports `{ render, OPERATORS, composeZones, isCompact, applyCompaction, JTBD_CLI_COLOR, ANSI }`. |
+| render.cjs | v1 legacy-signature shim. Forwards to render-v2 with defensive defaults; returns just the `rendered` string. |
+| render-v2.test.cjs | Contract regression fence: 8 IIFE scenarios (5-operator round-trip, JUST_TALK default for undefined and null, unknown-operator tolerated, envelope shape stable, mode passthrough, tier passthrough, OPERATORS frozen). Registered in lib/memory/run-feynman-tests.cjs. |
+| JTBD-PALETTES.md | CLI + Mondrian dual-palette tables for the 13 canonical JTBDs (Phase 102-05). |
+| ROOM.md | This file -- ICM Layer 0 identity per CLAUDE.md Decision #15. |
+
+## Render contract (Phase 99 CONTEXT.md D-16, refined in Phase 102)
+
+```
+render({ zones, mode, operator, tier, jtbd, tokenBudget, roomDir, provenance })
+  -> { rendered: string, contract: object, _provenance: <non-enumerable, frozen> }
+
+operator == JUST_TALK        -> emit prose only; suppress envelope             (Phase 102-01)
+operator == EXPLORE_CAPTURE  -> prose; Shape E only on crystallization         (Phase 102)
+operator == BUILD_ROOM       -> full 4-zone anatomy + JTBD-aware Zone 4        (Phase 102-03)
+operator == METHODOLOGY      -> no Zone 4 mid-session; Shape E at gate         (Phase 102-01)
+operator == DECISION_GATE    -> Shape F.x; keyboard only                       (Phase 102-03)
+```
+
+The legacy 4-arg signature lives at `lib/render/render.cjs`:
+
+```
+render(zones, mode, operator, tier) -> string
+```
+
+## Canon refs
+
+- **Part 3 (Tri-Context Decision Gate):** DECISION_GATE locks Shape F.x; the renderer enforces this at output time. The v2 entry is reserved for this gate-output side.
+- **Part 4 (Every Choice Is Graph Data):** operator transitions written by Phase 99-01 are read by this renderer to pick shape.
+- **Part 7 (Reuse Before Build):** the v1 shim wraps v2 -- one renderer, two entry points. The Sub-plan E disposition (this section) is itself a Canon Part 7 decision: don't add a parallel prose-side renderer when SKILL.md is the canonical prose contract.
+- **Part 8 (Graph Boundary):** the renderer is pure formatting; no Brain calls anywhere in the chain (D-09).
+
+## Downstream consumers
+
+- **lib/render/render.cjs (v1 shim):** the legacy 4-arg positional signature surface. Reuses v2 muscle by construction.
+- **lib/hmi/selector-dispatcher.cjs:** the Shape F / Shape E agent-surface dispatcher; the /mos:* command output side. This is the canonical gate-output consumer.
+
+Any consumer outside this set is a violation of the Sub-plan E disposition. The CI gate at `lib/memory/render-v2-disposition.test.cjs` catches drift; the operator-facing audit at `scripts/disposition-render-v2.cjs` answers the question at any moment.
+
+## Constraints
+
+- Zero new runtime dependencies (Phase 87 invariant).
+- CJS only (Phase 87 invariant).
+- `render()` import surface MUST remain byte-stable across the Phase 102 swap (RENDER-102-06 fence).
+- Operator vocabulary frozen at 5 canonical values; any 6th operator requires a Gate 1 review per Phase 99 CONTEXT.md D-03.
+- Disposition: agent-surface-only. Adding a new consumer requires updating the allowlist in `scripts/disposition-render-v2.cjs` AND this ROOM.md in the same commit -- the CI gate enforces parity.
+
+## See also
+
+- `.planning/phases/99-conversation-operator-state-machine/99-CONTEXT.md` -- operator taxonomy, transition table, renderer signature contract D-16, graceful degradation D-17.
+- `.planning/phases/102-context-aware-rendering/102-CONTEXT.md` -- the Phase 102 implementation spec.
+- `.planning/phases/102-context-aware-rendering/102-VALIDATION.md` -- the Phase 102 validation strategy (Sub-plan E flips this out of draft).
+- `.planning/phases/102-context-aware-rendering/102-VERIFICATION.md` -- the Phase 102 verification record (shipped by Sub-plan E).
+- `.planning/phases/121.5-terminal-coherence-capstone/121.5-CONTEXT.md` -- Sub-plan E disposition rationale.
+- `docs/MINDRIAN-CANON.md` -- North Star, Part 3 (Tri-Context Decision Gate), Part 4 (Every Choice Is Graph Data), Part 7 (Reuse Before Build), Part 8 (Graph Boundary).

package/lib/render/render-v2.cjs

@@ -0,0 +1,532 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 102-01 -- universal renderer (extended signature).
+ *
+ * Replaces the Phase 99-03 stub at the same import surface. Phase 102
+ * evolves the signature to a single destructured object so we can carry
+ * the full context tuple (operator, tier, jtbd, tokenBudget, roomDir,
+ * provenance) without another signature break in 102-02..05.
+ *
+ * Phase 102-01 ships skeleton + zone composition only. Hooks:
+ *   1. Compaction     -> 102-02   3. Color overlay -> 102-05
+ *   2. JTBD-aware Z4  -> 102-03   4. Provenance    -> 102-04
+ * Numbered comment markers in render() are the insertion points.
+ *
+ * Per CONTEXT D-10, lib/render/render.cjs ships in the same wave as a
+ * thin shim around this v2 entry, preserving the legacy 4-arg
+ * positional signature for callers that have not yet migrated.
+ *
+ * Canon parts: 3 (Tri-Context Gate, output-side enforcement),
+ * 4 (operator transitions read here), 5 (evidence tier via Z3),
+ * 7 (single formatter for every /mos: command), 8 (D-09: this renderer
+ * NEVER calls Brain inline -- pure formatting layer; Canon Part 8
+ * compliant by construction).
+ *
+ * Constraints: zero new runtime deps, CJS only (Phase 87 invariant),
+ * defensive defaults so {} or undefined cannot crash the formatter.
+ */
+
+/**
+ * The 5 canonical operators (Phase 99 CONTEXT.md D-03, frozen).
+ * Re-exported for downstream consumers that want to validate operator
+ * values without re-importing from lib/conversation/operator.cjs.
+ *
+ * @type {ReadonlyArray<string>}
+ */
+const OPERATORS = Object.freeze([
+  'JUST_TALK',
+  'EXPLORE_CAPTURE',
+  'BUILD_ROOM',
+  'METHODOLOGY',
+  'DECISION_GATE',
+]);
+
+/**
+ * JTBD -> CLI semantic color map (Phase 102 D-06).
+ *
+ * Maps each of the 13 canonical Phase 100 JTBD handles to one of the 5
+ * SKILL.md §4 CLI colors (red / yellow / cyan / green / gray). NO new
+ * colors invented; the 5-color contract is the boundary.
+ *
+ * Color anchors:
+ *   - red    : commit / blocker / contradiction (high-stakes)
+ *   - yellow : questioning / challenge / warning
+ *   - cyan   : informational / cross-reference / capture
+ *   - green  : forward action / commitment / success
+ *   - gray   : meta / no specific action (the canvas)
+ *
+ * @type {Readonly<Record<string,string>>}
+ */
+const JTBD_CLI_COLOR = Object.freeze({
+  'decide-pursue': 'red',
+  'find-problem': 'yellow',
+  'understand-market': 'cyan',
+  'find-bottleneck': 'red',
+  'prepare-pitch': 'green',
+  'validate-idea': 'yellow',
+  'compare-options': 'cyan',
+  'connect-domains': 'cyan',
+  'surface-contradiction': 'red',
+  'plan-execution': 'green',
+  'file-meeting': 'cyan',
+  'audit-room': 'yellow',
+  'explore': 'gray',
+});
+
+/**
+ * Posture -> CLI semantic color map (Phase 177 BCH-12).
+ *
+ * Maps each of the 3 FROZEN posture ids (sensor-types.cjs POSTURE_IDS:
+ * push_forward / hold / pull_back) into the SAME 5-color CLI contract used by
+ * JTBD_CLI_COLOR (red / yellow / cyan / green / gray). NO 6th CLI color is
+ * invented (blue/black/white are HTML/Mondrian only). The 3 postures map:
+ *   - pull_back     -> red    : the engine held the navigator back (high-stakes)
+ *   - hold          -> yellow : the engine paused / questioned (caution)
+ *   - push_forward  -> green  : the engine drove forward (commitment / go)
+ *
+ * INVISIBILITY BY ABSENCE (the BCH-12 headline guarantee): this map has NO
+ * 'praise' key and NO 'grade' key. There is no engine state for a compliment,
+ * so there is no color to paint one. The badge structurally CANNOT flatter --
+ * you cannot color what the map does not name. The badge is driven from the
+ * COMPOSED posture (the engine's composed decision, never a model emit), so it
+ * is painted at composition and cannot lie about a later state.
+ *
+ * @type {Readonly<Record<string,string>>}
+ */
+const POSTURE_CLI_COLOR = Object.freeze({
+  pull_back: 'red',
+  hold: 'yellow',
+  push_forward: 'green',
+});
+
+/**
+ * ANSI SGR escape sequences for the 5-color contract (SKILL.md §4).
+ * Used by Zone 1 left-rail accent (D-07). TTY-gated at render time so
+ * non-TTY captures (CI logs, JSON-mode emission) stay byte-clean.
+ *
+ * @type {Readonly<Record<string,string>>}
+ */
+const ANSI = Object.freeze({
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  gray: '\x1b[90m',
+  reset: '\x1b[0m',
+});
+
+/**
+ * Render a 4-zone payload into a single output string + contract envelope.
+ *
+ * @param {object} args
+ * @param {object} [args.zones]         - { header, body, signals?, footer? }
+ * @param {string} [args.mode]          - 'A' | 'B' | 'tier-0' (default 'A')
+ * @param {string|null} [args.operator] - one of OPERATORS or null
+ * @param {number} [args.tier]          - 0|1|2|3 (default 1)
+ * @param {string|null} [args.jtbd]     - active JTBD or null (default null)
+ * @param {string|null} [args.posture]  - COMPOSED posture (pull_back|hold|
+ *                                        push_forward) or null. When present it
+ *                                        DRIVES the Zone 1 badge color (BCH-12);
+ *                                        jtbd is the fallback when posture is
+ *                                        absent. Painted at composition so it
+ *                                        cannot lie. (default null)
+ * @param {object} [args.tokenBudget]   - { used, total } (default {0,1})
+ * @param {string} [args.roomDir]       - absolute room path; used by
+ *                                        downstream plans for selector-dispatcher
+ *                                        access. Defaults to env or process.cwd().
+ * @param {object|null} [args.provenance] - optional Brain provenance object
+ * @returns {{ rendered: string, contract: object }}
+ */
+function render(args) {
+  args = args || {};
+  // Defensive defaults — every arg can be missing or null/undefined.
+  let zones = args.zones || {};
+  const mode = args.mode || 'A';
+  const operator = args.operator || null;
+  const tier = (args.tier === undefined || args.tier === null) ? 1 : args.tier;
+  const jtbd = args.jtbd || null;
+  const posture = args.posture || null;
+  const tokenBudget = args.tokenBudget || { used: 0, total: 1 };
+  const roomDir = args.roomDir || process.env.MINDRIAN_ROOM_DIR || process.cwd();
+  let provenance = args.provenance || null;
+
+  // -------------------------------------------------------------------------
+  // Algorithm steps 1-7: hooks for downstream plans (102-02..05).
+  // The numbered markers MUST stay so follow-on plans land at the right spot.
+  // -------------------------------------------------------------------------
+
+  // 1. Compaction decision (Phase 102-02 — single 80% threshold).
+  //    Source priority: explicit env var (CLAUDE_CONTEXT_USED_PCT) >
+  //    caller-supplied tokenBudget > memory heuristic. See isCompact() below.
+  //    Adaptive granularity (50/70/80/90) is v1.15.x deferred (CONTEXT D-02).
+  const compact = isCompact(tokenBudget);
+
+  // 2. JTBD-aware Zone 4 (Phase 102-03) -- dispatch for both jtbd-set and
+  //    jtbd-null+BUILD_ROOM (per CONTEXT D-04). Free-Text is forced last by
+  //    the dispatcher's ensureFreeTextLast invariant. The operator gates in
+  //    step 6 (JUST_TALK / METHODOLOGY) override this enrichment when needed
+  //    -- order matters: we set zones.footer here, step 6 may strip it.
+  const shouldFireZone4 = (zones.footer === undefined)
+    && operator !== 'JUST_TALK'
+    && operator !== 'METHODOLOGY'
+    && (jtbd || operator === 'BUILD_ROOM');
+
+  if (shouldFireZone4) {
+    try {
+      const dispatcher = require('../hmi/selector-dispatcher.cjs');
+      const result = dispatcher.pickShape({
+        requestedShape: 'F',
+        roomDir: roomDir,
+        operator: operator,
+        tier: tier,
+        payload: {},
+      });
+      // Dispatcher returns F.6 when jtbd set, F.1 (canonical 10) when jtbd null.
+      // Result envelope: { shape, rendered: { zones, contract } }. Pull verbs
+      // off contract.verbs and the pre-formatted body off zones.body so the
+      // composeZones B6 footer contract is satisfied (rendered string short
+      // path; verbs[] defense-in-depth fallback).
+      if (result && result.rendered && result.rendered.contract
+          && Array.isArray(result.rendered.contract.verbs)) {
+        zones = Object.assign({}, zones, {
+          footer: {
+            verbs: result.rendered.contract.verbs.slice(),
+            shape: result.shape,
+            rendered: (result.rendered.zones && typeof result.rendered.zones.body === 'string')
+              ? result.rendered.zones.body : null,
+          },
+        });
+      }
+    } catch (err) {
+      // Graceful fallback per Canon Part 3 Rule 2: dispatcher errors must
+      // never block the render. Surface debug info under MINDRIAN_DEBUG=1
+      // and leave zones.footer undefined for the caller / downstream default.
+      if (process.env.MINDRIAN_DEBUG === '1') {
+        process.stderr.write(
+          '[render-v2] zone4 dispatcher error: '
+          + String((err && err.message) || err).slice(0, 80) + '\n'
+        );
+      }
+    }
+  }
+
+  // 3. Zone 1 left-rail accent (Phase 102-05; D-06 + D-07).
+  //    Subtle JTBD-aware accent: a single colored ■ glyph prepended to
+  //    the existing Zone 1 header. ALL gates must hold:
+  //      (a) jtbd is non-null and present in JTBD_CLI_COLOR (D-06);
+  //      (b) compact mode is OFF (D-08; uses the unified `compact` flag
+  //          from slot 1 above, so the local env+budget gate from the
+  //          102-05 worktree's standalone build collapses out -- single
+  //          source of truth for compaction);
+  //      (c) process.stdout.isTTY is true -- non-TTY captures (CI logs,
+  //          piped output, JSON-mode emission) MUST stay byte-clean per
+  //          the RENDER-102-05 strip-ANSI invariant.
+  //    The ■ glyph itself is shape, not color -- emit it in BOTH TTY and
+  //    non-TTY modes so the strip-ANSI(TTY) === non-TTY byte-identical
+  //    invariant holds. Only the ANSI SGR bytes are gated on isTTY.
+  //    Mutate a shallow copy so we never alter the caller's zones object.
+  //
+  //    Phase 177 BCH-12: the color SOURCE is now posture-first. The COMPOSED
+  //    posture (pull_back/hold/push_forward) DRIVES the badge color when
+  //    present; jtbd is the fallback. The badge is painted from the engine's
+  //    composed posture so it cannot lie about a later state, and because
+  //    POSTURE_CLI_COLOR has NO praise/grade key the channel structurally
+  //    cannot flatter (invisibility by absence). Resolution order:
+  //      posture (if in POSTURE_CLI_COLOR) -> jtbd (if in JTBD_CLI_COLOR).
+  const postureColorName = posture && POSTURE_CLI_COLOR[posture];
+  const jtbdColorName = jtbd && JTBD_CLI_COLOR[jtbd];
+  const accentColorName = postureColorName || jtbdColorName;
+  if (!compact && accentColorName) {
+    const useColor = process.stdout.isTTY === true;
+    const color = useColor ? ANSI[accentColorName] : '';
+    const reset = useColor ? ANSI.reset : '';
+    zones = Object.assign({}, zones);
+    zones.header = color + '■' + reset + ' ' + (zones.header || '');
+  }
+
+  // 4. Provenance enrichment (Phase 102-04 -- LOCAL-only audit envelope).
+  //    Build the LOCAL-only _provenance envelope. Per RENDER-102-04 +
+  //    Canon Part 8, every render result carries:
+  //      { renderer:'render-v2', version:'102', operator, tier, mode, jtbd }
+  //    Zero Brain queries, zero network IO, zero filesystem reads outside
+  //    lib/render/JTBD-PALETTES.md. The fields are pure scalar passthroughs
+  //    of args already destructured above; no user-content strings are
+  //    embedded (operator + mode + tier + jtbd are framework-handle enums
+  //    or null), so this envelope is Canon Part 8 compliant by construction.
+  //    The 'provenance' caller arg (from upstream Brain-aware code paths)
+  //    is intentionally NOT folded into _provenance to avoid leaking caller-
+  //    supplied user content into the renderer's audit envelope; callers may
+  //    place that payload into zones.signals themselves if they want it
+  //    surfaced. Attached non-enumerably via attachProvenance() so the
+  //    Phase 99-03 byte-stability fence (Object.keys === [contract,rendered])
+  //    stays green.
+  const _provenance = Object.freeze({
+    renderer: 'render-v2',
+    version: '102',
+    operator: operator,
+    tier: tier,
+    mode: mode,
+    jtbd: jtbd,
+  });
+
+  // 5. Compact mode application (Phase 102-02). Apply AFTER any upstream
+  //    enrichment hooks (Z4 dispatcher, color overlay, provenance) so
+  //    compaction trims the final pre-compose payload. Sibling 102-05's
+  //    color-overlay block (slot 3) self-gates against compact via its
+  //    own local check; once that local gate is folded into this unified
+  //    `compact` flag (future cleanup), the redundancy drops out without
+  //    changing observable behavior.
+  if (compact) zones = applyCompaction(zones);
+
+  // 6. Operator-driven Zone 4 gates (102-01: ship this gate today).
+  //    JUST_TALK suppresses ALL output (prose-only operator); METHODOLOGY
+  //    mid-session strips Zone 4 (the methodology owns the screen).
+  if (operator === 'JUST_TALK') {
+    return attachProvenance(
+      { rendered: '', contract: { suppressed: true, reason: 'just-talk' } },
+      _provenance
+    );
+  }
+  if (operator === 'METHODOLOGY' && (!zones.body || !zones.body.endingSignal)) {
+    // Mutate a shallow copy so we never alter the caller's object.
+    zones = Object.assign({}, zones);
+    delete zones.footer;
+  }
+
+  // 7. Mode B prefix (filled by 102-04)
+  //    if (mode === 'B' && zones.header && !String(zones.header).startsWith('⚠')) {
+  //      zones.header = '⚠ Brain unreachable; running on local graph only.\n' + zones.header;
+  //    }
+
+  // -------------------------------------------------------------------------
+  // Step 8: compose 4 zones into a single string.
+  // -------------------------------------------------------------------------
+  const composed = composeZones(zones);
+
+  // Reference the not-yet-used vars so static analyzers do not warn before
+  // 102-05 wires them up. (102-03 consumed: tier, jtbd, roomDir via the Z4
+  // dispatcher. 102-04 consumed: mode + tier + jtbd into _provenance. The
+  // upstream caller-supplied `provenance` arg remains unused -- intentionally
+  // NOT folded into _provenance to avoid leaking user content per Canon
+  // Part 8; callers may put it in zones.signals themselves.)
+  void provenance;
+
+  // Surface `compact` on the contract so downstream plans can branch on it
+  // (102-05 reads it to drop the color overlay; tests inspect it to verify
+  // the compaction gate fired). The non-enumerable _provenance envelope is
+  // attached via attachProvenance() so Object.keys(env) stays
+  // ['contract','rendered'] (RENDER-102-06 byte-stability invariant).
+  return attachProvenance(
+    { rendered: composed, contract: { compact: compact } },
+    _provenance
+  );
+}
+
+/**
+ * Attach a non-enumerable, frozen `_provenance` field to a render envelope.
+ *
+ * Non-enumerable so `Object.keys(env).sort()` still equals
+ * `['contract','rendered']` (per RENDER-102-06: the Phase 99-03 -> Phase 102
+ * import-surface byte-stability fence in `lib/render/render-v2.test.cjs`
+ * scenario 5). The field is still readable as `env._provenance` for any
+ * caller that asks for it explicitly (audit, telemetry, debug surface).
+ *
+ * Configurable: false; writable: false. The whole envelope is intended to
+ * be a single-pass write -- callers that mutate it are out of contract.
+ *
+ * @param {object} envelope  - { rendered, contract } from the renderer.
+ * @param {object} provenance - frozen provenance descriptor.
+ * @returns {object} same envelope, with `_provenance` attached.
+ */
+function attachProvenance(envelope, provenance) {
+  Object.defineProperty(envelope, '_provenance', {
+    value: provenance,
+    enumerable: false,
+    configurable: false,
+    writable: false,
+  });
+  return envelope;
+}
+
+/**
+ * Compose a 4-zone payload into a single newline-delimited string.
+ *
+ * Footer shape contract (cross-plan with 102-03):
+ *   - string: emit verbatim
+ *   - { rendered: string }: emit rendered field (pre-formatted by dispatcher in 102-03)
+ *   - { verbs: string[] }: emit verbs as `▷ <verb>` lines (defense-in-depth fallback)
+ *
+ * Signals shape:
+ *   - array of strings; each prefixed with `▷ ` and joined by newlines.
+ *
+ * @param {object} zones
+ * @returns {string}
+ */
+function composeZones(zones) {
+  zones = zones || {};
+  const header = zones.header;
+  const body = zones.body;
+  const signals = zones.signals;
+  const footer = zones.footer;
+
+  const parts = [];
+
+  if (header) parts.push(String(header));
+
+  if (body) {
+    if (typeof body === 'string') {
+      parts.push(body);
+    } else if (body.text) {
+      parts.push(String(body.text));
+    } else {
+      parts.push(JSON.stringify(body));
+    }
+  }
+
+  if (Array.isArray(signals) && signals.length) {
+    parts.push(signals.map(function (s) { return '▷ ' + s; }).join('\n'));
+  }
+
+  if (footer) {
+    if (typeof footer === 'string') {
+      parts.push(footer);
+    } else if (footer.rendered) {
+      parts.push(String(footer.rendered));
+    } else if (Array.isArray(footer.verbs)) {
+      parts.push(footer.verbs.map(function (v) { return '▷ ' + v; }).join('\n'));
+    }
+  }
+
+  return parts.filter(Boolean).join('\n\n');
+}
+
+// ---------------------------------------------------------------------------
+// Phase 102-02 — token-budget-aware compaction layer.
+//
+// Single 80% threshold (CONTEXT D-02 + D-03). Adaptive granularity
+// (50% / 70% / 80% / 90%) is v1.15.x deferred. Compaction is a pure
+// function of zones; callers see the trimmed payload via composeZones.
+// ---------------------------------------------------------------------------
+
+/**
+ * Decide whether to compact based on token-budget signals.
+ *
+ * Source priority (CONTEXT D-02):
+ *   1. process.env.CLAUDE_CONTEXT_USED_PCT — explicit Claude Code signal.
+ *      Treated as a percentage in 0..100. Returns true when > 80.
+ *   2. caller-supplied tokenBudget {used, total} — explicit numbers from
+ *      the caller. Returns true when used/total > 0.80. Requires both
+ *      total > 0 AND used > 0; the defensive default {used:0, total:1}
+ *      falls through to the heuristic.
+ *   3. process.memoryUsage() heuristic — heapUsed/heapTotal > 0.95.
+ *      Rough last-resort proxy that ONLY triggers under genuine heap
+ *      pressure. Idle Node CLIs sit at ~0.70 routinely, so the original
+ *      0.60 threshold from RESEARCH §2 step 1 misfired against the 99-03
+ *      regression fence + 102-01 signature suites (both call render()
+ *      with no env var and no explicit budget; both expect non-compact
+ *      output). Raised to 0.95 here as a Rule 1 deviation; documented in
+ *      102-02-SUMMARY.md "Deviations from Plan". The function still
+ *      always returns a boolean per the plan's done-criteria 8.
+ *
+ * @param {object} tokenBudget - { used, total }
+ * @returns {boolean} true when the renderer should switch to compact mode.
+ */
+function isCompact(tokenBudget) {
+  // 1. Explicit env signal from Claude Code. Truthy + parseable wins.
+  if (process.env.CLAUDE_CONTEXT_USED_PCT) {
+    const pct = parseFloat(process.env.CLAUDE_CONTEXT_USED_PCT) / 100;
+    if (!isNaN(pct)) return pct > 0.80;
+  }
+  // 2. Caller-supplied {used, total}. Defensive: only trust positive
+  //    totals AND a positive `used` so the {0,1} default falls through.
+  if (tokenBudget && tokenBudget.total > 0 && tokenBudget.used > 0) {
+    return (tokenBudget.used / tokenBudget.total) > 0.80;
+  }
+  // 3. Memory heuristic fallback. Threshold raised from 0.60 -> 0.95 so
+  //    idle Node processes do not trip compaction. Always returns boolean.
+  const m = process.memoryUsage();
+  return (m.heapUsed / m.heapTotal) > 0.95;
+}
+
+/**
+ * Apply Phase 102-02 compaction rules to a zones payload.
+ *
+ * Returns a new shallow-copied object; never mutates the caller's zones.
+ * Compaction rules (CONTEXT D-03):
+ *   - Z1 header: single line; strip decorative dashes / box-drawing glyphs.
+ *     The `-- ... --` envelope collapses to a leading `■ ` (canonical
+ *     compact glyph from the `■ ✓ ⚠ →` allowlist).
+ *   - Z2 body: cap at 30 lines. Lines 31..N replaced by a single
+ *     `... <N more rows>` summary line. String body shape preserved.
+ *   - Z3 signals: cap at 2 (down from 3).
+ *   - Z4 footer (object form with verbs[]): cap at 2; if the verb list
+ *     ends in `Free-Text`, preserve `Free-Text` as the LAST element
+ *     (Phase 100 invariant — Free-Text is always the escape hatch).
+ *
+ * @param {object} zones
+ * @returns {object} compacted zones (shallow copy)
+ */
+function applyCompaction(zones) {
+  const out = Object.assign({}, zones || {});
+
+  // Z1: simplify header — single line, strip decorative dashes/box-drawing.
+  if (out.header) {
+    let h = String(out.header);
+    h = h.split('\n')[0]; // single line first
+    // Collapse leading "-- " into "■ " (canonical compact glyph) and drop
+    // any trailing " -- " envelope. Mid-string " -- " separators are kept
+    // (semantic between-segment dividers); only the outer envelope is
+    // decorative and strippable.
+    h = h.replace(/^-- /, '■ ').replace(/ -- $/, '');
+    // Strip box-drawing characters anywhere in the header.
+    h = h.replace(/[─━│┌┐└┘╭╮╰╯]/g, '');
+    out.header = h;
+  }
+
+  // Z2: cap body at 30 lines (string form only — object-shaped bodies are
+  // upstream's job to compact).
+  if (typeof out.body === 'string') {
+    const lines = out.body.split('\n');
+    if (lines.length > 30) {
+      const overflow = lines.length - 30;
+      out.body = lines.slice(0, 30).join('\n') + '\n... <' + overflow + ' more rows>';
+    }
+  }
+
+  // Z3: cap signals at 2.
+  if (Array.isArray(out.signals) && out.signals.length > 2) {
+    out.signals = out.signals.slice(0, 2);
+  }
+
+  // Z4: cap footer.verbs at 2; preserve Free-Text last when present.
+  if (out.footer && typeof out.footer === 'object' && Array.isArray(out.footer.verbs)) {
+    const verbs = out.footer.verbs;
+    if (verbs.length > 2) {
+      const hasFreeText = verbs[verbs.length - 1] === 'Free-Text';
+      const trimmed = hasFreeText
+        ? [verbs[0], 'Free-Text']
+        : verbs.slice(0, 2);
+      out.footer = Object.assign({}, out.footer, { verbs: trimmed });
+    }
+  }
+
+  return out;
+}
+
+module.exports = {
+  render,
+  OPERATORS,
+  composeZones,
+  // Phase 102-02 exports for test fences + downstream introspection.
+  isCompact,
+  applyCompaction,
+  // Phase 102-05 exports for test fences + downstream introspection.
+  JTBD_CLI_COLOR,
+  ANSI,
+  // Phase 177 BCH-12 export: the posture-driven badge color map.
+  POSTURE_CLI_COLOR,
+};