@mindrian_os/install 1.13.0-beta.16 → 1.13.0-beta.19

package/lib/core/venture-shape-nudge.test.cjs

@@ -0,0 +1,161 @@
+'use strict';
+
+/*
+ * Phase 119-00 Wave 1 -- venture-shape-nudge module tests.
+ *
+ * Mirrors the lib/memory/selector-decisions.test.cjs fixture pattern
+ * (fs.mkdtempSync + openRoomDb). Tests are allowed to require room-db.cjs
+ * directly per the Phase 109-06 pre-commit chokepoint allow-list for tests/.
+ *
+ * Covers the 7 behavior axes from 119-00-PLAN.md Task 1:
+ *   Test 1 -- cold-start floor (Test 5 in plan: no room.db -> surface false)
+ *   Test 2 -- venture-shape accumulation to threshold (Test 6)
+ *   Test 3 -- D-01 invariant: auto_explore_fired short-circuits (Test 7)
+ *   Test 4 -- venture_classification_unavailable safe-default (Test 7b)
+ *   Test 5 -- venture_classified present happy-path (Test 7c)
+ *   Test 6 -- no Brain client require (Test 8; source-grep audit)
+ *   Test 7 -- no-room-dir guard
+ */
+
+const { test } = require('node:test');
+const { strict: assert } = require('node:assert');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const { openRoomDb } = require(path.join(REPO_ROOT, 'lib', 'core', 'room-db.cjs'));
+const navigation = require(path.join(REPO_ROOT, 'lib', 'core', 'navigation.cjs'));
+const ventureShapeNudge = require(path.join(REPO_ROOT, 'lib', 'core', 'venture-shape-nudge.cjs'));
+
+function freshRoom() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'p119-00-nudge-'));
+  fs.mkdirSync(path.join(dir, '.mindrian'), { recursive: true });
+  const db = openRoomDb(dir);
+  return { dir, db };
+}
+
+function closeQuiet(db) {
+  try { db.close(); } catch (_e) { /* graceful */ }
+}
+
+test('Test 1: cold-start floor -- no events in db returns surface:false with venture_classification_unavailable', () => {
+  const { dir, db } = freshRoom();
+  closeQuiet(db);
+  const r = ventureShapeNudge.shouldSurfaceNudge(dir, {});
+  assert.equal(r.surface, false);
+  assert.equal(r.turn_count, 0);
+  assert.equal(r.threshold, 3);
+  assert.equal(r.skip_reason, 'venture_classification_unavailable');
+});
+
+test('Test 2: 3 venture_classified=true events reach threshold (surface=true)', () => {
+  const { dir, db } = freshRoom();
+  for (let i = 0; i < 3; i++) {
+    const result = navigation.logMemoryEvent(db, 'f_selector_decision', {
+      venture_classified: true,
+      classification_source: 'haiku-4-5',
+      source_path: 'test:venture-shape-nudge',
+      created_by: 'system',
+    });
+    assert.equal(result.ok, true, 'logMemoryEvent should accept f_selector_decision; got reason=' + (result.reason || ''));
+  }
+  closeQuiet(db);
+  const r = ventureShapeNudge.shouldSurfaceNudge(dir, {});
+  assert.equal(r.surface, true);
+  assert.equal(r.turn_count, 3);
+  assert.equal(r.threshold, 3);
+  assert.equal(r.skip_reason, undefined);
+});
+
+test('Test 3: D-01 invariant -- auto_explore_fired short-circuits regardless of turn count', () => {
+  const { dir, db } = freshRoom();
+  // Seed 5 venture-shaped turns AND one auto_explore_fired event.
+  for (let i = 0; i < 5; i++) {
+    navigation.logMemoryEvent(db, 'f_selector_decision', {
+      venture_classified: true,
+      classification_source: 'haiku-4-5',
+      source_path: 'test:venture-shape-nudge',
+    });
+  }
+  navigation.logMemoryEvent(db, 'auto_explore_fired', {
+    material_id: 'abcd1234',
+    relative_file_path: 'docs/sample.md',
+    room_slug: 'test-room',
+    tier: 1,
+    surfacing_count: 0,
+    brain_baseline_present: false,
+    source_path: 'test:venture-shape-nudge',
+  });
+  closeQuiet(db);
+  const r = ventureShapeNudge.shouldSurfaceNudge(dir, {});
+  assert.equal(r.surface, false);
+  assert.equal(r.skip_reason, 'upload_path_active');
+});
+
+test('Test 4: venture_classification_unavailable safe-default when field absent', () => {
+  const { dir, db } = freshRoom();
+  // Seed events without venture_classified field at all.
+  for (let i = 0; i < 5; i++) {
+    navigation.logMemoryEvent(db, 'f_selector_decision', {
+      command: 'mos:test',
+      framework: 'test-framework',
+      source_path: 'test:venture-shape-nudge',
+    });
+  }
+  closeQuiet(db);
+  const r = ventureShapeNudge.shouldSurfaceNudge(dir, {});
+  assert.equal(r.surface, false);
+  assert.equal(r.skip_reason, 'venture_classification_unavailable');
+  assert.equal(r.turn_count, 0);
+});
+
+test('Test 5: mixed venture_classified true/false -- only true counts toward threshold', () => {
+  const { dir, db } = freshRoom();
+  // 3 true + 1 false; threshold=3 met.
+  for (let i = 0; i < 3; i++) {
+    navigation.logMemoryEvent(db, 'f_selector_decision', {
+      venture_classified: true,
+      classification_source: 'haiku-4-5',
+      source_path: 'test:venture-shape-nudge',
+    });
+  }
+  navigation.logMemoryEvent(db, 'f_selector_decision', {
+    venture_classified: false,
+    classification_source: 'haiku-4-5',
+    source_path: 'test:venture-shape-nudge',
+  });
+  closeQuiet(db);
+  const r = ventureShapeNudge.shouldSurfaceNudge(dir, {});
+  assert.equal(r.surface, true);
+  assert.equal(r.turn_count, 3);
+});
+
+test('Test 6: no Brain client require -- source-grep audit', () => {
+  const src = fs.readFileSync(path.join(REPO_ROOT, 'lib', 'core', 'venture-shape-nudge.cjs'), 'utf8');
+  // Canon Part 8: zero brain-client require, zero mcp-server-brain require,
+  // zero fetch to brain.mindrian.
+  assert.equal(/require\([^)]*brain-client/.test(src), false, 'brain-client require detected');
+  assert.equal(/require\([^)]*mcp-server-brain/.test(src), false, 'mcp-server-brain require detected');
+  assert.equal(/brain\.mindrian/.test(src), false, 'brain.mindrian fetch reference detected');
+  // Canon Part 9: zero direct room-db.cjs require.
+  assert.equal(/require\([^)]*room-db\.cjs/.test(src), false, 'direct room-db.cjs require detected');
+});
+
+test('Test 7: no-room-dir guard returns safe default', () => {
+  const r = ventureShapeNudge.shouldSurfaceNudge('', {});
+  assert.equal(r.surface, false);
+  assert.equal(r.skip_reason, 'no_room_dir');
+
+  const r2 = ventureShapeNudge.shouldSurfaceNudge(null, {});
+  assert.equal(r2.surface, false);
+
+  // Non-existent path -> no_room_db.
+  const r3 = ventureShapeNudge.shouldSurfaceNudge('/tmp/p119-nonexistent-' + Date.now(), {});
+  assert.equal(r3.surface, false);
+  assert.equal(r3.skip_reason, 'no_room_db');
+});
+
+test('Test 8: VENTURE_NUDGE_THRESHOLD constant exported and equals 3', () => {
+  assert.equal(ventureShapeNudge.VENTURE_NUDGE_THRESHOLD, 3);
+});

package/lib/core/visual-ops.cjs

@@ -173,8 +173,19 @@ function formatSectionHeader(sectionName, entryCount, stage) {
 // MERMAID DIAGRAM GENERATORS
 // ═══════════════════════════════════════════════════════════════
 
-// De Stijl hex colors for Mermaid style directives (no ANSI in diagrams)
-const DS_HEX = {
+// De Stijl hex colors for Mermaid style directives (no ANSI in diagrams).
+//
+// Phase 121.5-03: DS_HEX is now SOURCED FROM references/visual/palette.json
+// (the canonical De Stijl source-of-truth per ODD 3 resolution + Canon Part 7).
+// The literal fallback below is graceful degradation only -- if palette.json
+// fails to load (unlikely in a properly-installed plugin), the shipping
+// values are frozen here verbatim from the pre-121.5 hardcoded DS_HEX so
+// downstream Mermaid + dashboard rendering keeps working.
+//
+// Test seam: MINDRIAN_PALETTE_PATH env var overrides the default palette
+// path. Used by lib/memory/statusline-two-row.test.cjs (test 11) to verify
+// the wiring without touching the live palette.json.
+const FALLBACK_DS_HEX = {
   red: '#A63D2F',
   blue: '#1E3A6E',
   yellow: '#C8A43C',
@@ -186,6 +197,63 @@ const DS_HEX = {
   bg: '#0D0D0D'
 };
 
+/**
+ * Compose DS_HEX from references/visual/palette.json. Preserves the legacy
+ * key names (red / blue / yellow / green / sienna / amethyst / cream / muted
+ * / bg) so existing consumers (Mermaid generators, dashboard exporters) keep
+ * working byte-identical. Also exposes the palette tier keys via dot
+ * extension for new consumers (e.g. mondrian_red, muted_green, saturated_blue).
+ */
+function loadPaletteDsHex() {
+  const path = require('path');
+  const fs = require('fs');
+  const candidate = process.env.MINDRIAN_PALETTE_PATH ||
+    path.join(__dirname, '..', '..', 'references', 'visual', 'palette.json');
+  try {
+    const palette = JSON.parse(fs.readFileSync(candidate, 'utf8'));
+    const base = palette.base || {};
+    const a = palette.palette_a_discovery || {};
+    const b = palette.palette_b_build || {};
+    const ext = palette.extended || {};
+    const composed = {
+      // Legacy DS_HEX keys (preserve backward compat for Mermaid + dashboard)
+      red:      base.mondrian_red    || FALLBACK_DS_HEX.red,
+      blue:     base.mondrian_blue   || FALLBACK_DS_HEX.blue,
+      yellow:   base.mondrian_yellow || FALLBACK_DS_HEX.yellow,
+      green:    base.success_green   || FALLBACK_DS_HEX.green,
+      sienna:   ext.sienna           || FALLBACK_DS_HEX.sienna,
+      amethyst: base.amethyst        || FALLBACK_DS_HEX.amethyst,
+      cream:    base.cream           || FALLBACK_DS_HEX.cream,
+      muted:    base.gray_meta       || FALLBACK_DS_HEX.muted,
+      bg:       ext.bg               || base.mondrian_black || FALLBACK_DS_HEX.bg,
+      // Tier-keyed mirrors (new consumers can use the explicit names)
+      mondrian_red:    base.mondrian_red,
+      mondrian_blue:   base.mondrian_blue,
+      mondrian_yellow: base.mondrian_yellow,
+      mondrian_black:  base.mondrian_black,
+      mondrian_white:  base.mondrian_white,
+      gray_meta:       base.gray_meta,
+      success_green:   base.success_green,
+      muted_red:       a.muted_red,
+      muted_green:     a.muted_green,
+      teal_accent:     a.teal_accent,
+      saturated_red:    b.saturated_red,
+      saturated_blue:   b.saturated_blue,
+      saturated_yellow: b.saturated_yellow,
+    };
+    return composed;
+  } catch (e) {
+    // Graceful degradation per Canon Part 7. One warning to stderr, then
+    // fall back to the frozen literal.
+    if (process.env.MINDRIAN_PALETTE_DEBUG) {
+      try { process.stderr.write('[visual-ops] palette.json load failed: ' + e.message + '\n'); } catch (_) {}
+    }
+    return Object.assign({}, FALLBACK_DS_HEX);
+  }
+}
+
+const DS_HEX = loadPaletteDsHex();
+
 // Map stage names to hex colors for Mermaid
 const STAGE_HEX = {
   preopportunity: DS_HEX.muted,

package/lib/hmi/selector-dispatcher.cjs

@@ -70,6 +70,14 @@
 
 'use strict';
 
+// Phase 121-02 D-04: unified-stream selector_pick emit chokepoint.
+// require()-loaded lazily inside emitSelectorPickUnified() so a missing writer
+// module (or a stripped-down install) cannot crash the dispatcher at load.
+const crypto = require('node:crypto');
+function _sha256(s) {
+  return crypto.createHash('sha256').update(String(s || '')).digest('hex');
+}
+
 const FREE_TEXT = 'Free-Text';
 const MODE_B_ZONE1_PREFIX = '⚠ Brain unreachable; running on local graph only.';
 
@@ -79,7 +87,12 @@ const MODE_B_ZONE1_PREFIX = '⚠ Brain unreachable; running on local graph only.
 //   collision-safe lib/hmi/shape-f6-plan-review-renderer.cjs path; the umbrella 'F'
 //   branch continues to route to Phase 101-01's lib/hmi/shape-f6-renderer.cjs via
 //   JTBD logic preserved byte-stable per R1 invariant).
-const F_SUBSHAPES = ['F.0', 'F.1', 'F.2', 'F.3', 'F.4', 'F.5', 'F.6'];
+// Phase 120-01: 'F.7' Breakthrough Surface appended (CONTEXT.md D-07..D-10 + D-20). Closed-vocab
+//   5 verbs verbatim [Explore deeper]/[Confirm]/[File as decision]/[Dismiss]/[Back]; mandatory
+//   [Dismiss] guard (D-10). Routes to lib/hmi/shape-f7-breakthrough-renderer.cjs via the
+//   explicit requestedShape:'F.7' branch in dispatchShapeFSubShape. The umbrella 'F' branch
+//   does NOT resolve to F.7 -- breakthrough surfacing is opt-in via explicit dispatch.
+const F_SUBSHAPES = ['F.0', 'F.1', 'F.2', 'F.3', 'F.4', 'F.5', 'F.6', 'F.7'];
 const F_UMBRELLA = 'F';
 const JUST_TALK = 'JUST_TALK';
 const COMPACTION_VIOLATION_CODE = 'render_v2_compaction_violation';
@@ -175,6 +188,58 @@ function justTalkRefuse(requestedShape) {
   };
 }
 
+/**
+ * Phase 121-02 D-04: emit selector_pick event into the unified
+ * ~/.mindrian/telemetry/v1.13/events-YYYY-WNN.jsonl stream (Plan 121-00
+ * writer chokepoint). Wrapped in try/catch -- telemetry NEVER fails Larry's
+ * turn. Canon Part 8: room slug is sha256-hashed; payload fields are scalar
+ * enums / numbers / booleans only. The emit is gated by validateEventPayload
+ * inside writer.emit() so adversarial fixtures (Cypher in verb_chosen, etc.)
+ * cannot leak. Non-blocking: any thrown error is swallowed so the pickShape
+ * dispatch resolution still returns to the caller.
+ */
+function emitSelectorPickUnified(roomDir, subShape, rendered, payloadIn) {
+  try {
+    let writer;
+    try {
+      writer = require('../core/telemetry/writer.cjs');
+    } catch (_e) {
+      return; // missing writer module -- soft skip, do not crash dispatch
+    }
+    if (!writer || typeof writer.emit !== 'function') return;
+    const contract = (rendered && rendered.contract) ? rendered.contract : {};
+    const verbs = Array.isArray(contract.verbs) ? contract.verbs : [];
+    const mode = (typeof contract.mode === 'string') ? contract.mode : 'A';
+    const recommended = contract.recommended;
+    const payload = (payloadIn && typeof payloadIn === 'object') ? payloadIn : {};
+    const rankerConfidence = (typeof payload.rankerConfidence === 'number')
+      ? payload.rankerConfidence
+      : 0;
+    const recommendedRendered = (recommended !== null && recommended !== undefined)
+      ? true
+      : Boolean(payload.recommendedRendered);
+    const verbChosen = (typeof payload.verb_chosen === 'string' && payload.verb_chosen.length > 0)
+      ? payload.verb_chosen
+      : (typeof contract.recommended === 'string' ? contract.recommended : '');
+    const slugSource = (typeof roomDir === 'string' && roomDir.length > 0)
+      ? String(roomDir).split('/').filter(Boolean).pop() || roomDir
+      : (String(process.cwd()).split('/').filter(Boolean).pop() || 'default-room');
+    writer.emit('selector_pick', {
+      sub_shape: String(subShape || '').slice(0, 64),
+      mode: String(mode || 'A').slice(0, 64),
+      ranker_confidence: rankerConfidence,
+      recommended_rendered: Boolean(recommendedRendered),
+      options_count: Number.isInteger(verbs.length) ? verbs.length : 0,
+      room_slug_sha256: _sha256(slugSource),
+      verb_chosen: String(verbChosen || '').slice(0, 64),
+    });
+  } catch (_e) {
+    // Canon Part 8 validation failure or any other emit failure: swallow.
+    // The dispatch resolution must still return cleanly per non-blocking
+    // contract (selector-pick-capture test 3 verifies this).
+  }
+}
+
 /**
  * Phase 88.2-04: emit selector presentation telemetry. Wrapped in try/catch --
  * telemetry NEVER fails Larry's turn. Canon Part 8: LOCAL ledger only, room
@@ -354,6 +419,25 @@ function dispatchShapeFSubShape(requestedShape, args) {
       personaContext: (typeof payloadObj.personaContext === 'string' && payloadObj.personaContext.length > 0)
         ? payloadObj.personaContext : undefined,
     };
+  } else if (requestedShape === 'F.7') {
+    // Phase 120-01: F.7 Breakthrough Surface (closed-vocab; 5 verbs verbatim).
+    //   Per CONTEXT.md D-07: built NEW (not a reuse of F.4).
+    //   Per CONTEXT.md D-08: 5 verbs locked verbatim [Explore deeper]/[Confirm]/
+    //     [File as decision]/[Dismiss]/[Back].
+    //   Per CONTEXT.md D-10: [Dismiss] is MANDATORY (renderer asserts presence on
+    //     every render).
+    //   Per CONTEXT.md D-20: payload.breakthrough carries provenance.artifact_ids[] --
+    //     F.7 renderer refuses to render if artifact_ids.length === 0 (HARD FLOOR
+    //     structural enforcement at the surface layer; defense in depth on top of
+    //     writeBreakthrough's validateProvenance in lib/core/breakthrough/schema.cjs).
+    mod = safeRequire('./shape-f7-breakthrough-renderer.cjs');
+    fnName = 'renderShapeF7Breakthrough';
+    inputArgs = {
+      tier: tier,
+      header: callerHeader,
+      breakthrough: (payloadObj.breakthrough && typeof payloadObj.breakthrough === 'object') ? payloadObj.breakthrough : null,
+      more_count: (Number.isInteger(payloadObj.more_count) && payloadObj.more_count >= 0) ? payloadObj.more_count : 0,
+    };
   }
 
   if (!mod || typeof mod[fnName] !== 'function') {
@@ -496,6 +580,11 @@ function pickShape(args) {
         const payloadObj = (opts.payload && typeof opts.payload === 'object') ? opts.payload : {};
         if (payloadObj.emitTelemetry === true) {
           emitPresentationTelemetry(opts.roomDir, result.shape, result.rendered, operator);
+          // Phase 121-02 D-04: capture selector pick (88.2/125 ranker) into
+          // the unified ~/.mindrian/telemetry/v1.13/events-YYYY-WNN.jsonl
+          // stream (Plan 121-00 writer chokepoint). Non-blocking; never
+          // throws back to caller.
+          emitSelectorPickUnified(opts.roomDir, result.shape, result.rendered, payloadObj);
         }
       }
     }

package/lib/hmi/shape-f7-breakthrough-renderer.cjs

@@ -0,0 +1,222 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 120-01 -- Shape F.7 Breakthrough Surface renderer.
+ *
+ * Per CONTEXT.md D-07..D-10 (the 5 verbs LOCKED VERBATIM + closed-vocab + mandatory dismiss):
+ *   - Built NEW (D-07): F.4 maps content-to-user-actionable-observation;
+ *     F.7 maps user-actions-to-recognition-of-user-own-work. Different speech acts.
+ *   - 5 verbs LOCKED VERBATIM (D-08): [Explore deeper] / [Confirm] / [File as decision] /
+ *     [Dismiss] / [Back]. Order is structural, not stylistic.
+ *   - [File as decision] (D-09) emits breakthrough_filed_as_decision via the Plan 120-02
+ *     scanner consumer; F.7 only renders the verb -- it does NOT itself emit events.
+ *   - [Dismiss] (D-10) is MANDATORY -- the renderer asserts its presence; refuses to
+ *     render a contract without it (defense in depth against accidental drift).
+ *
+ * Per CONTEXT.md D-11..D-12 (top-1 with "More breakthroughs (N)" affordance):
+ *   - Top-1 surface; "More breakthroughs (N)" affordance for queued candidates.
+ *   - more_count is rendered in zones.footer IFF more_count > 0.
+ *
+ * Per CONTEXT.md D-20 HARD FLOOR (Cypher-provable):
+ *   - breakthrough.artifact_ids[] must be non-empty AT RENDER TIME. The renderer is
+ *     the second structural enforcement point (the first is writeBreakthrough in
+ *     Plan 120-00 schema.cjs). Defense in depth: if a caller somehow bypasses
+ *     writeBreakthrough's validateProvenance, F.7 refuses to render the surfacing.
+ *
+ * Per CONTEXT.md D-17 voice scaffold rule 3 (time anchor):
+ *   - The title line includes a human-readable time anchor (e.g., "in the last 8 hours")
+ *     derived from breakthrough.detected_at via formatTimeAnchor.
+ *
+ * Canon Part 3: F.7 IS a Decision Gate primitive instance. LOCAL context only
+ *   (the breakthrough artifact_ids + theme); BRAIN context is none (D-20 makes
+ *   breakthroughs locally Cypher-provable); SIGNAL context is none (cross-room
+ *   forbidden per Part 8).
+ *
+ * Canon Part 4: every choice is graph data. Each of the 5 verbs maps to a typed
+ *   event the Plan 120-02 scanner consumer emits at verb-dispatch time.
+ *
+ * Canon Part 8: zero Brain coupling. The renderer is pure: no FS reads, no DB
+ *   writes, no fetch calls. Mirrors the F.4 / F.6 pattern byte-for-byte.
+ *
+ * Pure CJS, node built-ins only, zero deps (Phase 87 invariant).
+ */
+'use strict';
+
+// D-08: the 5 verbs LOCKED VERBATIM. Object.freeze prevents accidental mutation
+// of the canonical array; downstream code that needs a mutable copy must call
+// F7_VERBS.slice() (the dispatcher does this in inputArgs).
+const F7_VERBS = Object.freeze([
+  'Explore deeper',
+  'Confirm',
+  'File as decision',
+  'Dismiss',
+  'Back',
+]);
+
+// D-10: structural index of 'Dismiss' in F7_VERBS. assertContractInvariants uses
+// this to surface a precise 'dismiss_required' reason when the contract drifts.
+const F7_DISMISS_INDEX = 3;
+
+// Map the four detector kinds Plan 120-00 emits to their canonical display
+// strings. Unknown kinds fall back to the raw kind string (and finally to
+// 'Pattern' if kind is falsy).
+const KIND_DISPLAY_NAMES = Object.freeze({
+  convergence: 'Convergence',
+  contradiction_resolved: 'Contradiction resolved',
+  cross_domain_analogy: 'Cross-domain analogy',
+  reverse_salient_closed: 'Reverse salient closed',
+});
+
+// D-17 rule 3: human-readable time anchor with bucket boundaries chosen to
+// match the spec examples (in the last hour / in the last N hours / today /
+// in the last day / this week / in the last two weeks / on YYYY-MM-DD).
+// D-06 ethical fence: ages > 14 days surface the calendar date verbatim so
+// the user can see exactly how stale the recognition is.
+function formatTimeAnchor(detected_at) {
+  const now = Date.now();
+  const ts = (typeof detected_at === 'number' && Number.isFinite(detected_at)) ? detected_at : now;
+  const ageMs = Math.max(0, now - ts);
+  const ageHours = ageMs / (3600 * 1000);
+  const ageDays = ageHours / 24;
+  if (ageHours < 1) return 'in the last hour';
+  if (ageHours < 8) return 'in the last ' + Math.floor(ageHours) + ' hours';
+  if (ageHours < 24) return 'today';
+  if (ageDays < 2) return 'in the last day';
+  if (ageDays < 7) return 'this week';
+  if (ageDays < 14) return 'in the last two weeks';
+  // Older than the 14-day ethical fence (D-06) -- include calendar date for transparency.
+  const d = new Date(ts);
+  const yyyy = d.getUTCFullYear();
+  const mm = String(d.getUTCMonth() + 1).padStart(2, '0');
+  const dd = String(d.getUTCDate()).padStart(2, '0');
+  return 'on ' + yyyy + '-' + mm + '-' + dd;
+}
+
+// D-10 MANDATORY-Dismiss structural guard. Returns {ok:true} when the verbs
+// array deep-equals F7_VERBS; otherwise returns {ok:false, reason} with a
+// precise reason code so consumers can surface a meaningful error envelope.
+//
+// Reason codes:
+//   verb_count_mismatch -- verbs.length !== 5
+//   dismiss_required    -- the slot at F7_DISMISS_INDEX is not literally 'Dismiss'
+//   verb_order_mismatch -- some other slot diverges from the canonical array
+function assertContractInvariants(verbs) {
+  if (!Array.isArray(verbs) || verbs.length !== F7_VERBS.length) {
+    return { ok: false, reason: 'verb_count_mismatch' };
+  }
+  for (let i = 0; i < F7_VERBS.length; i++) {
+    if (verbs[i] !== F7_VERBS[i]) {
+      return { ok: false, reason: i === F7_DISMISS_INDEX ? 'dismiss_required' : 'verb_order_mismatch' };
+    }
+  }
+  return { ok: true };
+}
+
+/**
+ * Render the F.7 Breakthrough Surface.
+ *
+ * @param {object} args
+ * @param {number} [args.tier]         tier integer; informational only -- F.7 is closed-vocab
+ *                                     in every tier (no recommended marker; no mode branch)
+ * @param {string} [args.header]       caller-supplied header line; default 'Breakthrough'
+ * @param {object} args.breakthrough   the breakthrough candidate (must carry artifact_ids[])
+ * @param {number} [args.more_count]   non-negative integer; number of queued candidates
+ *                                     surfaced via the "More breakthroughs (N)" footer
+ * @param {string} [args.voice_line]   Phase 120-03 D-17 additive slot. When present + non-empty,
+ *                                     prepended as the first line of zones.body above the title.
+ *                                     Caller (Plan 120-03 scanner.surfaceBreakthrough) audits
+ *                                     the line via voice-scaffold.auditVoiceLine before passing;
+ *                                     this renderer does NOT re-audit (single source of truth).
+ *
+ * @returns {object} { zones: {header, body, footer}, contract: {...} }  OR
+ *                   { error: 'provenance_required' | 'dismiss_required' | 'verb_count_mismatch' | 'verb_order_mismatch' }
+ */
+function renderShapeF7Breakthrough(args) {
+  const a = (args && typeof args === 'object') ? args : {};
+  const more_count = (Number.isInteger(a.more_count) && a.more_count >= 0) ? a.more_count : 0;
+  const bk = a.breakthrough;
+
+  // D-20 HARD FLOOR defense in depth -- refuse to render a provenance-less
+  // breakthrough. The Plan 120-00 schema layer rejects writes with empty
+  // artifact_ids; this is the SECOND structural enforcement point at the
+  // surface layer (in case writeBreakthrough is somehow bypassed).
+  if (!bk || typeof bk !== 'object' || !Array.isArray(bk.artifact_ids) || bk.artifact_ids.length === 0) {
+    return { error: 'provenance_required' };
+  }
+
+  // Build the locked-verbatim verbs array and assert the D-10 invariants.
+  // Defense in depth: the source-of-truth F7_VERBS is Object.freeze-d above;
+  // assertContractInvariants on the mutable copy gives a final structural
+  // assertion before composition.
+  const verbs = F7_VERBS.slice();
+  const check = assertContractInvariants(verbs);
+  if (!check.ok) {
+    return { error: check.reason };
+  }
+
+  // Row 1 (title): kind capitalized + theme + time anchor.
+  // Theme is sliced to 120 chars at the surface layer (defense in depth on top
+  // of the schema-layer 200-char sanitizer in Plan 120-00).
+  const kindKey = (typeof bk.kind === 'string') ? bk.kind : '';
+  const kindDisplay = KIND_DISPLAY_NAMES[kindKey] || kindKey || 'Pattern';
+  const themeRaw = (typeof bk.theme === 'string') ? bk.theme : '';
+  const theme = themeRaw.slice(0, 120);
+  const timeAnchor = formatTimeAnchor(bk.detected_at || Date.now());
+  const titleLine = kindDisplay + (theme ? ': ' + theme : '') + ' (' + timeAnchor + ')';
+
+  // Row 2 (verbs): the 5 verbs in [X] brackets, separated by double-space.
+  // Bracket style matches the F.4 / F.6 closed-vocab convention.
+  const verbsLine = verbs.map(function (v) { return '[' + v + ']'; }).join('  ');
+
+  // Phase 120-03 D-17 additive: optional voice_line prepend.
+  //
+  // When args.voice_line is a non-empty string, it is prepended as the FIRST line
+  // of zones.body, above the title line. This is the conversational opener
+  // composed by Plan 120-03 voice-scaffold.composeBreakthroughVoiceLine. The
+  // caller (scanner.surfaceBreakthrough) audits the line via auditVoiceLine
+  // before passing; this renderer does NOT re-audit (single source of truth, no
+  // duplicated regex logic at the surface layer).
+  //
+  // The contract.verbs / freeTextOffered / recommended / breakthrough_id /
+  // more_count fields are PRESERVED byte-stably across both branches (with-line
+  // and without-line). Plan 120-01 11-test byte-stability invariant is preserved
+  // when voice_line is absent (the without-line branch is the legacy code path).
+  const voiceLineRaw = (typeof a.voice_line === 'string') ? a.voice_line : '';
+  const voiceLine = voiceLineRaw.length > 0 ? voiceLineRaw : '';
+  const body = voiceLine
+    ? (voiceLine + '\n' + titleLine + '\n' + verbsLine)
+    : (titleLine + '\n' + verbsLine);
+
+  const header = (typeof a.header === 'string' && a.header.length > 0) ? a.header : 'Breakthrough';
+  // D-11 affordance: only surface "More breakthroughs (N)" when N > 0; empty
+  // footer otherwise so the renderer never lies about queued candidates.
+  const footer = (more_count > 0) ? ('More breakthroughs (' + more_count + ')') : '';
+
+  return {
+    zones: {
+      header: header,
+      body: body,
+      signals: '',
+      footer: footer,
+    },
+    contract: {
+      shape: 'F.7',
+      keyboard: 'askuserquestion',
+      verbs: verbs,
+      freeTextOffered: false,    // closed-vocab; mirrors F.3 / F.4 / F.6 plan-review
+      mode: 'closed',
+      recommended: null,         // closed-vocab does not mark a recommended verb
+      breakthrough_id: bk.id,
+      more_count: more_count,
+    },
+  };
+}
+
+module.exports = {
+  renderShapeF7Breakthrough: renderShapeF7Breakthrough,
+  F7_VERBS: F7_VERBS,
+  F7_DISMISS_INDEX: F7_DISMISS_INDEX,
+  formatTimeAnchor: formatTimeAnchor,
+  assertContractInvariants: assertContractInvariants,
+  KIND_DISPLAY_NAMES: KIND_DISPLAY_NAMES,
+};