@mindrian_os/install 1.13.0-beta.11

package/lib/hmi/selector-telemetry.cjs

@@ -0,0 +1,263 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 88.2-03 -- selector telemetry emitter (UISEL-88.2-06 part 1).
+ *
+ * Substrate that every Phase 88.2 sub-shape (F.1-F.5) calls into when a
+ * selector is presented and when the navigator responds.
+ *
+ * Three event surfaces (all LOCAL):
+ *
+ *   recordPresentation(roomDir, record) -- called when a Shape F selector
+ *     is rendered. Emits one JSONL line with {ts, event:'presentation',
+ *     room_slug_sha256, sub_shape, mode, options_count, recommended_present,
+ *     operator?}.
+ *
+ *   recordResponse(roomDir, record) -- called when the navigator picks an
+ *     option. Emits one JSONL line with {ts, event:'response',
+ *     room_slug_sha256, sub_shape, mode, response_index,
+ *     response_was_free_text, latency_ms}.
+ *
+ *   recordSelectorMirror(roomDir, eventType, payload)  -- Phase 88.2-03
+ *     D-AMEND-02 Option B dual-surface mirror. Writes a memory_event row
+ *     in <roomDir>/.mindrian/room.db via the Phase 109 navigation chokepoint
+ *     (lib/core/navigation/memory-events.cjs logEvent). Mirror failure is
+ *     graceful (returns {ok:false, reason}); never throws; never blocks
+ *     the JSONL primary surface. Both surfaces are LOCAL per Canon Part 8.
+ *
+ * Canon Part 8 contract (LOCAL only -- zero Brain or network IO):
+ *   - Primary JSONL target: ~/.mindrian/telemetry/selector.jsonl (per-user
+ *     LOCAL ledger; never crosses any network boundary).
+ *   - Mirror target: <roomDir>/.mindrian/room.db (LOCAL SQLite, Phase 109
+ *     SQL spine). Filesystem-local. Zero LOCAL -> BRAIN egress.
+ *   - room_slug_sha256 = first 16 hex chars of sha256(path.basename(roomDir)).
+ *     The literal room slug NEVER touches disk.
+ *   - All scalar fields are integers, ISO timestamps, booleans, or
+ *     fixed-vocabulary enum strings (sub_shape in {F.1..F.5}, mode in
+ *     {A, B}, operator in the 5 frozen Phase 105 operators).
+ *   - Zero references to Brain MCP, network calls, or remote endpoints.
+ *
+ * FIFO bound: at most MAX_LINES (10000) lines retained; on overflow, the
+ * oldest are dropped. Atomic write via mktemp + rename in same directory.
+ *
+ * Graceful failure: every public entry point is wrapped in try/catch.
+ * Telemetry NEVER fails Larry's turn -- a write error returns silently.
+ *
+ * Three-surface compatibility: identical behavior on CLI, Desktop MCP, and
+ * Cowork. The home directory ($HOME/.mindrian/telemetry) is per-user, so
+ * Cowork actors each get their own ledger.
+ *
+ * Pure CJS, node built-ins only, zero new runtime deps.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
+
+// Env override exists so tests can redirect to a tmp file without touching
+// the real ~/.mindrian ledger. Production callers never set this var.
+const TELEMETRY_PATH = process.env.MINDRIAN_SELECTOR_TELEMETRY_PATH ||
+  path.join(os.homedir(), '.mindrian', 'telemetry', 'selector.jsonl');
+
+// Env override for MAX_LINES exists so the FIFO truncation test can use
+// a tiny bound (e.g. 50) without rewriting a 10000-entry file repeatedly.
+// Production callers never set this var; the constant remains 10000.
+const _envMax = parseInt(process.env.MINDRIAN_SELECTOR_TELEMETRY_MAX_LINES, 10);
+const MAX_LINES = (Number.isFinite(_envMax) && _envMax > 0) ? _envMax : 10000;
+const SLUG_HASH_LEN = 16;
+
+function hashRoomSlug(roomDir) {
+  // Hash the basename only -- never the full path. This means the ledger
+  // contains a stable per-room handle (so aggregation can group events)
+  // without ever persisting the literal user-chosen room name.
+  const slug = path.basename(roomDir || 'unknown');
+  return crypto.createHash('sha256').update(String(slug)).digest('hex').slice(0, SLUG_HASH_LEN);
+}
+
+function ensureDir() {
+  const dir = path.dirname(TELEMETRY_PATH);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+function appendLineAtomic(line) {
+  // Read existing -> push -> FIFO-truncate -> atomic write via mktemp +
+  // rename in the same directory. Same-directory tmp is required so the
+  // rename is atomic on any POSIX filesystem.
+  ensureDir();
+  let lines = [];
+  if (fs.existsSync(TELEMETRY_PATH)) {
+    try {
+      const raw = fs.readFileSync(TELEMETRY_PATH, 'utf8');
+      lines = raw.split('\n').filter(Boolean);
+    } catch (_e) {
+      // Unreadable -- start fresh rather than crash.
+      lines = [];
+    }
+  }
+  lines.push(line);
+  if (lines.length > MAX_LINES) {
+    lines = lines.slice(lines.length - MAX_LINES);
+  }
+  const dir = path.dirname(TELEMETRY_PATH);
+  const rand = crypto.randomBytes(6).toString('hex');
+  const tmp = path.join(dir, '.selector.jsonl.' + rand);
+  fs.writeFileSync(tmp, lines.join('\n') + '\n', 'utf8');
+  fs.renameSync(tmp, TELEMETRY_PATH);
+}
+
+function recordPresentation(roomDir, record) {
+  try {
+    const r = (record && typeof record === 'object') ? record : {};
+    const obj = {
+      ts: new Date().toISOString(),
+      event: 'presentation',
+      room_slug_sha256: hashRoomSlug(roomDir),
+      sub_shape: typeof r.sub_shape === 'string' ? r.sub_shape : null,
+      mode: typeof r.mode === 'string' ? r.mode : null,
+      options_count: typeof r.options_count === 'number' ? r.options_count : null,
+      recommended_present: r.recommended_present === true,
+    };
+    if (typeof r.operator === 'string') {
+      obj.operator = r.operator;
+    }
+    appendLineAtomic(JSON.stringify(obj));
+  } catch (_e) {
+    // Graceful -- never fail Larry's turn on a telemetry I/O hiccup.
+  }
+}
+
+function recordResponse(roomDir, record) {
+  try {
+    const r = (record && typeof record === 'object') ? record : {};
+    const obj = {
+      ts: new Date().toISOString(),
+      event: 'response',
+      room_slug_sha256: hashRoomSlug(roomDir),
+      sub_shape: typeof r.sub_shape === 'string' ? r.sub_shape : null,
+      mode: typeof r.mode === 'string' ? r.mode : null,
+      response_index: typeof r.response_index === 'number' ? r.response_index : null,
+      response_was_free_text: r.response_was_free_text === true,
+      latency_ms: typeof r.latency_ms === 'number' ? r.latency_ms : null,
+    };
+    appendLineAtomic(JSON.stringify(obj));
+  } catch (_e) {
+    // Graceful.
+  }
+}
+
+/**
+ * Phase 88.2-03 D-AMEND-02 Option B -- dual-surface mirror.
+ *
+ * Mirrors selector telemetry events to the Phase 109 SQL spine
+ * (room.db memory_event row) IN ADDITION TO the JSONL primary surface.
+ *
+ * Both surfaces are LOCAL per Canon Part 8:
+ *   - Primary JSONL: ~/.mindrian/telemetry/selector.jsonl (filesystem-local).
+ *   - Mirror memory_event: <roomDir>/.mindrian/<roomName>.db (LOCAL SQLite).
+ *
+ * The mirror writes scalar enum strings + sha256 hashes + numeric scalars.
+ * NO user content. NO meeting transcripts. NO artifact bodies. Zero
+ * LOCAL -> BRAIN data flow introduced.
+ *
+ * Resilience contract (D-AMEND-02):
+ *   - JSONL primary surface NEVER depends on the mirror succeeding.
+ *   - Mirror failure modes are returned as a structured envelope; never throws.
+ *   - When MINDRIAN_DISABLE_MEMORY_EVENT=1 is set, mirror returns
+ *     {ok:false, reason:'mirror_disabled_env'} without touching the DB.
+ *   - When the room has no .db (pre-Phase-109 user), mirror returns
+ *     {ok:false, reason:'db_not_initialized'} and the JSONL primary
+ *     emit -- typically called separately by the caller -- still succeeds.
+ *
+ * @param {string} roomDir   Absolute path to the room directory.
+ * @param {string} eventType One of EVENT_TYPES (validated against the
+ *                           memory-events Set; must be one of the 4 new
+ *                           strings landed by 88.2-00:
+ *                           selector_presentation, selector_response,
+ *                           selector_rejection_captured, f6_round_completed).
+ * @param {object} payload   Event payload merged into the memory_event
+ *                           row's properties JSON. event_type is merged in
+ *                           by logEvent (overrides any caller value).
+ * @returns {{ok: boolean, reason?: string, eventId?: string}}
+ */
+function recordSelectorMirror(roomDir, eventType, payload) {
+  try {
+    if (process.env.MINDRIAN_DISABLE_MEMORY_EVENT === '1') {
+      return { ok: false, reason: 'mirror_disabled_env' };
+    }
+
+    // Lazy-require navigation/memory-events.cjs so a missing Phase 109
+    // substrate (or a stripped-down install) cannot crash callers at load.
+    let EVENT_TYPES;
+    let logEvent;
+    try {
+      const memMod = require('../core/navigation/memory-events.cjs');
+      EVENT_TYPES = memMod.EVENT_TYPES;
+      logEvent = memMod.logEvent;
+    } catch (_e) {
+      return { ok: false, reason: 'memory_events_module_unavailable' };
+    }
+
+    if (!EVENT_TYPES || typeof EVENT_TYPES.has !== 'function' || !EVENT_TYPES.has(eventType)) {
+      return { ok: false, reason: 'invalid_event_type' };
+    }
+    if (typeof logEvent !== 'function') {
+      return { ok: false, reason: 'memory_events_module_unavailable' };
+    }
+
+    if (typeof roomDir !== 'string' || roomDir.length === 0) {
+      return { ok: false, reason: 'invalid_room_dir' };
+    }
+
+    // Project sqlite binding: node:sqlite DatabaseSync (per
+    // lib/core/lazygraph-ops.cjs). NOT better-sqlite3.
+    let DatabaseSync;
+    try {
+      DatabaseSync = require('node:sqlite').DatabaseSync;
+    } catch (_e) {
+      return { ok: false, reason: 'sqlite_unavailable' };
+    }
+    if (typeof DatabaseSync !== 'function') {
+      return { ok: false, reason: 'sqlite_unavailable' };
+    }
+
+    const dbPath = path.join(roomDir, '.mindrian', 'room.db');
+    if (!fs.existsSync(dbPath)) {
+      return { ok: false, reason: 'db_not_initialized' };
+    }
+
+    let db;
+    try {
+      db = new DatabaseSync(dbPath);
+    } catch (_e) {
+      return { ok: false, reason: 'db_open_failed' };
+    }
+    try {
+      const safePayload = (payload && typeof payload === 'object' && !Array.isArray(payload))
+        ? payload
+        : {};
+      const result = logEvent(db, eventType, safePayload);
+      // logEvent returns { ok, eventId } | { ok:false, reason }; pass through.
+      return result;
+    } catch (_e) {
+      return { ok: false, reason: 'mirror_threw_caught' };
+    } finally {
+      try { db.close(); } catch (_e) { /* best-effort */ }
+    }
+  } catch (_e) {
+    return { ok: false, reason: 'mirror_threw_caught' };
+  }
+}
+
+module.exports = {
+  recordPresentation: recordPresentation,
+  recordResponse: recordResponse,
+  recordSelectorMirror: recordSelectorMirror,
+  TELEMETRY_PATH: TELEMETRY_PATH,
+  MAX_LINES: MAX_LINES,
+  _internal: { hashRoomSlug: hashRoomSlug },
+};

package/lib/hmi/shape-f0-renderer.cjs

@@ -0,0 +1,139 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 88.2-05 -- Shape F.0 Mini Decision Gate renderer (UISEL-88.2-07).
+ *
+ * Implements F.0 per CONTEXT.md amendment 2026-04-29 + D-AMEND-01.
+ * EXACTLY 3 verbs: Approve / Reject (with reason) / Defer.
+ * NO Free-Text slot (Reject reason captured as REJECTED_BECAUSE typed edge property).
+ * Single-line ASCII border (visual sub-decision cue per spec).
+ * persona-AGNOSTIC visually (D-AMEND-04).
+ * F.0 ALWAYS produces a typed edge -- no silent dismiss path (Canon Part 4).
+ *
+ * REJECTED_BECAUSE edge schema (DISCRETION-AMEND-03 RESOLVED):
+ *   { reason, rejected_at, parent_decision_id, actor_id?, confidence_self_report? }
+ *   - Edge label: REJECTED_BECAUSE
+ *   - Edge written via Phase 109 lib/core/navigation/memory-events logEvent
+ *   - eventType: 'selector_rejection_captured' (one of 4 new strings from 88.2-00)
+ *
+ * Pure CJS, node built-ins only, zero new runtime deps (Phase 87 invariant).
+ * Canon Part 8: zero Brain egress; reason text is graph-local only.
+ */
+'use strict';
+
+const F0_VERBS = ['Approve', 'Reject', 'Defer'];
+const DEFAULT_HEADER = '-- mindrianOS -- mini -- pick --';
+const MARKER_ROW = '▷';      // 12-glyph vocab triangle marker (matches 88.2-01 ▷)
+const REJECTION_EVENT_TYPE = 'selector_rejection_captured';
+
+/**
+ * Render F.0 Mini Decision Gate.
+ * @param {object} [input]
+ * @param {number} [input.tier]                 0/1/2/3 (mode A if >=2, B otherwise)
+ * @param {string} [input.header]               Optional override header
+ * @param {string} [input.body]                 The WHAT being decided (claim/question text)
+ * @param {string} [input.parent_decision_id]   Surfaced in contract for downstream edge wiring
+ * @returns {{zones, contract}}
+ */
+function renderShapeF0(input) {
+  const opts = (input && typeof input === 'object') ? input : {};
+  const tier = (typeof opts.tier === 'number') ? opts.tier : 0;
+  const mode = (tier >= 2) ? 'A' : 'B';
+  const header = (typeof opts.header === 'string' && opts.header.length > 0) ? opts.header : DEFAULT_HEADER;
+  const bodyText = (typeof opts.body === 'string' && opts.body.length > 0) ? opts.body : '';
+  const parentDecisionId = (typeof opts.parent_decision_id === 'string' && opts.parent_decision_id.length > 0)
+    ? opts.parent_decision_id : null;
+
+  // Compose body rows. Each verb gets a triangle marker (Mode A and Mode B both -- F.0 carries no RECOMMENDED).
+  const rows = F0_VERBS.map((v, i) => {
+    const suffix = (v === 'Approve') ? '  -- cascade now'
+                 : (v === 'Reject')  ? '   -- capture reason -> graph data'
+                 :                     '    -- queue for milestone audit';
+    return MARKER_ROW + ' ' + (i + 1) + ') ' + v + suffix;
+  });
+  const body = (bodyText ? bodyText + '\n\n' : '') + rows.join('\n');
+
+  return {
+    zones: { header: header, body: body, signals: '', footer: null },
+    contract: {
+      shape: 'F.0',
+      keyboard: 'askuserquestion',
+      verbs: F0_VERBS.slice(),    // defensive copy
+      freeTextOffered: false,     // closed-vocab carve-out (dispatcher respects)
+      mode: mode,
+      recommended: null,          // F.0 carries no RECOMMENDED (sub-decision shape)
+      border_style: 'single',     // visual cue scalar
+      parent_decision_id: parentDecisionId,
+    },
+  };
+}
+
+/**
+ * Build and emit a REJECTED_BECAUSE typed edge to room.db via Phase 109.
+ * Graceful-fail envelope -- never throws.
+ *
+ * @param {object} args
+ * @param {string} args.roomDir
+ * @param {string} args.reason                 Required, non-empty.
+ * @param {string} args.parent_decision_id     Required, non-empty.
+ * @param {string} [args.actor_id]             Optional Cowork scalar handle.
+ * @param {number} [args.confidence_self_report] Optional 1-5 integer.
+ * @returns {{ok:boolean, reason?:string, eventId?:string}}
+ */
+function buildRejectedBecauseEdge(args) {
+  try {
+    const a = (args && typeof args === 'object') ? args : {};
+    if (typeof a.reason !== 'string' || a.reason.length === 0) {
+      return { ok: false, reason: 'invalid_reason' };
+    }
+    if (typeof a.parent_decision_id !== 'string' || a.parent_decision_id.length === 0) {
+      return { ok: false, reason: 'invalid_parent_decision_id' };
+    }
+    if (a.confidence_self_report !== undefined) {
+      const c = a.confidence_self_report;
+      if (!Number.isInteger(c) || c < 1 || c > 5) {
+        return { ok: false, reason: 'invalid_confidence' };
+      }
+    }
+    const { EVENT_TYPES, logEvent } = require('../core/navigation/memory-events.cjs');
+    if (!EVENT_TYPES.has(REJECTION_EVENT_TYPE)) {
+      return { ok: false, reason: 'event_type_not_registered' };
+    }
+    // Project standard: node:sqlite DatabaseSync per lib/core/lazygraph-ops.cjs.
+    // better-sqlite3 is documented as broken in lib/import/PRECONDITIONS.md.
+    let DatabaseSync;
+    try { ({ DatabaseSync } = require('node:sqlite')); }
+    catch (_e) { return { ok: false, reason: 'sqlite_unavailable' }; }
+    const fs = require('node:fs');
+    const path = require('node:path');
+    if (typeof a.roomDir !== 'string' || a.roomDir.length === 0) {
+      return { ok: false, reason: 'invalid_room_dir' };
+    }
+    const dbPath = path.join(a.roomDir, '.mindrian', 'room.db');
+    if (!fs.existsSync(dbPath)) {
+      return { ok: false, reason: 'db_not_initialized' };
+    }
+    const db = new DatabaseSync(dbPath);
+    try {
+      const props = {
+        reason: a.reason,
+        rejected_at: new Date().toISOString(),
+        parent_decision_id: a.parent_decision_id,
+      };
+      if (typeof a.actor_id === 'string' && a.actor_id.length > 0) props.actor_id = a.actor_id;
+      if (a.confidence_self_report !== undefined) props.confidence_self_report = a.confidence_self_report;
+      return logEvent(db, REJECTION_EVENT_TYPE, props);
+    } finally {
+      db.close();
+    }
+  } catch (_e) {
+    return { ok: false, reason: 'edge_build_threw_caught' };
+  }
+}
+
+module.exports = {
+  renderShapeF0,
+  buildRejectedBecauseEdge,
+  F0_VERBS: F0_VERBS.slice(),
+  _internal: { REJECTION_EVENT_TYPE },
+};

package/lib/hmi/shape-f1-fallback.cjs

@@ -0,0 +1,80 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 101-04 Task 1 -- Shape F.1 fallback renderer (HMI-101-06).
+ *
+ * Mirrors the F.1 contract from skills/ui-system/SKILL.md Section 2 Shape F.1.
+ * Used by selector-dispatcher.cjs ONLY when Phase 88.2's
+ * shape-f1-renderer.cjs is absent. The 10-verb canonical vocabulary is
+ * hardcoded so the F+null-JTBD path stays alive whether or not Phase 88.2
+ * has shipped.
+ *
+ * Free-Text is hardcoded as the last verb (Canon Part 3 + D-10).
+ * Mode A (tier >= 2): RECOMMENDED marker (▶) on matching verb.
+ * Mode B (tier < 2): no RECOMMENDED marker -- empty triangle (▷) on every row.
+ *
+ * Allowed glyphs (Canon Part 3 + skills/ui-system/SKILL.md 12-glyph
+ * vocabulary): ▶ ▷. No box characters.
+ *
+ * Pure CJS, node built-ins only, zero deps (Phase 87 invariant).
+ *
+ * API:
+ *   renderShapeF1({ tier, recommendedVerb, header? }) -> { zones, contract }
+ */
+
+'use strict';
+
+const CANONICAL_VERBS = [
+  'Run Methodology',
+  'Reformulate',
+  'Spawn Sub-Agent',
+  'Navigate Graph',
+  "Devil's Advocate",
+  'Scenario Plan',
+  'Synthesize',
+  'Bank Opportunity',
+  'Defer',
+  'Free-Text',
+];
+
+const MARKER_RECOMMENDED = '▶';
+const MARKER_ROW = '▷';
+
+function renderShapeF1(input) {
+  const opts = (input && typeof input === 'object') ? input : {};
+  const tier = typeof opts.tier === 'number' ? opts.tier : 0;
+  const recommendedVerb = typeof opts.recommendedVerb === 'string' && opts.recommendedVerb.length > 0
+    ? opts.recommendedVerb : null;
+  const header = typeof opts.header === 'string' && opts.header.length > 0
+    ? opts.header : null;
+
+  const mode = tier >= 2 ? 'A' : 'B';
+  const recInList = (mode === 'A' && recommendedVerb && CANONICAL_VERBS.indexOf(recommendedVerb) !== -1)
+    ? recommendedVerb : null;
+
+  const lines = CANONICAL_VERBS.map((verb, i) => {
+    const prefix = (verb === recInList) ? MARKER_RECOMMENDED : MARKER_ROW;
+    return prefix + ' ' + String(i + 1) + '. ' + verb;
+  });
+
+  return {
+    zones: {
+      header: header || '-- mindrianOS -- next move -- pick a verb --',
+      body: lines.join('\n'),
+      signals: '',
+      footer: null,
+    },
+    contract: {
+      shape: 'F.1',
+      keyboard: 'f1-fallback',
+      verbs: CANONICAL_VERBS.slice(),
+      mode: mode,
+      recommended: recInList,
+    },
+  };
+}
+
+module.exports = {
+  renderShapeF1: renderShapeF1,
+  CANONICAL_VERBS: CANONICAL_VERBS.slice(),
+};

package/lib/hmi/shape-f1-renderer.cjs

@@ -0,0 +1,138 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 88.2-01 -- Shape F.1 canonical renderer (UISEL-88.2-01).
+ *
+ * Implements the open-vocabulary Shape F.1 (Next Move) selector per
+ * skills/ui-system/SKILL.md Section 2 Shape F.1 and docs/MINDRIAN-CANON.md
+ * Part 3 (the 10 canonical verbs + Free-Text-always-last invariant).
+ *
+ * Drop-in replacement for lib/hmi/shape-f1-fallback.cjs. The dispatcher
+ * (lib/hmi/selector-dispatcher.cjs) prefers this module via safeRequire;
+ * fallback is preserved per CONTEXT.md "no breaking changes" invariant.
+ *
+ * Differences from the fallback:
+ *   1. Accepts optional `verbs` arg; user-supplied verbs are capped at 5
+ *      and Free-Text is appended last (de-duplicated, hardcoded).
+ *   2. contract.shape === 'F.1' (fallback omitted this).
+ *   3. contract.keyboard === 'askuserquestion' (the canonical primitive
+ *      per Phase 88.2 invariant; fallback used 'f1-fallback').
+ *
+ * Mode A (tier >= 2): Brain reachable, RECOMMENDED marker (▶) rendered on
+ * matching `recommendedVerb` row when it appears in the verb list.
+ * Mode B (tier < 2):  no RECOMMENDED marker; every row prefixed with ▷.
+ *
+ * Allowed glyphs in body (Canon Part 3 + skills/ui-system/SKILL.md
+ * 12-glyph vocabulary): ▶ ▷ ■ • →. No box characters.
+ *
+ * Pure CJS, node built-ins only, zero runtime deps (Phase 87 invariant).
+ *
+ * API:
+ *   renderShapeF1({ tier, recommendedVerb?, verbs?, header?, personaContext? })
+ *     -> { zones, contract }
+ *
+ * personaContext (optional, Phase 88.2-03): when a non-empty string is
+ * supplied, the header is suffixed with ' ({personaContext} lens)' and
+ * contract.personaContext surfaces the value back to the dispatcher for
+ * telemetry. Cold-start (omitted/null/empty) preserves the prior
+ * behavior byte-for-byte (no suffix; contract.personaContext === null).
+ */
+
+'use strict';
+
+const CANONICAL_VERBS = [
+  'Run Methodology',
+  'Reformulate',
+  'Spawn Sub-Agent',
+  'Navigate Graph',
+  "Devil's Advocate",
+  'Scenario Plan',
+  'Synthesize',
+  'Bank Opportunity',
+  'Defer',
+  'Free-Text',
+];
+
+const FREE_TEXT = 'Free-Text';
+const USER_VERB_CAP = 5; // Phase 88.2 invariant: 3-5 options + Free-Text appended.
+const MARKER_RECOMMENDED = '▶';
+const MARKER_ROW = '▷';
+const DEFAULT_HEADER = '-- mindrianOS -- next move -- pick a verb --';
+
+/**
+ * Normalize the verb list:
+ *   - if user-supplied: cap at USER_VERB_CAP, drop all Free-Text instances,
+ *     then append exactly one trailing Free-Text.
+ *   - if not: return the canonical 10-verb vocabulary as-is (already ends
+ *     with Free-Text).
+ *
+ * Free-Text-always-last is hardcoded; callers cannot omit it.
+ */
+function normalizeVerbs(rawVerbs) {
+  if (!Array.isArray(rawVerbs)) {
+    return CANONICAL_VERBS.slice();
+  }
+  const userOnly = rawVerbs
+    .filter(v => typeof v === 'string' && v.length > 0 && v !== FREE_TEXT)
+    .slice(0, USER_VERB_CAP);
+  userOnly.push(FREE_TEXT);
+  return userOnly;
+}
+
+function renderShapeF1(input) {
+  const opts = (input && typeof input === 'object') ? input : {};
+  const tier = typeof opts.tier === 'number' ? opts.tier : 0;
+  const recommendedVerb = typeof opts.recommendedVerb === 'string' && opts.recommendedVerb.length > 0
+    ? opts.recommendedVerb : null;
+  const header = typeof opts.header === 'string' && opts.header.length > 0
+    ? opts.header : null;
+  // Phase 88.2-03 D-AMEND-04 / DISCRETION-AMEND-01 option (a): optional
+  // personaContext suffix. Cold-start (omitted, null, undefined, or empty
+  // string): NO suffix; existing behavior preserved. Renderer stays PURE
+  // (no FS reads); the dispatcher supplies the pre-computed string from
+  // readUserMd().role_blend per Phase 115 D-12.
+  const personaContext = (typeof opts.personaContext === 'string' && opts.personaContext.length > 0)
+    ? opts.personaContext
+    : null;
+
+  const verbs = normalizeVerbs(opts.verbs);
+
+  const mode = tier >= 2 ? 'A' : 'B';
+  // RECOMMENDED only when Mode A AND verb is in list AND not Free-Text.
+  const recInList = (mode === 'A' && recommendedVerb
+      && verbs.indexOf(recommendedVerb) !== -1
+      && recommendedVerb !== FREE_TEXT)
+    ? recommendedVerb : null;
+
+  const lines = verbs.map((verb, i) => {
+    const prefix = (verb === recInList) ? MARKER_RECOMMENDED : MARKER_ROW;
+    return prefix + ' ' + String(i + 1) + '. ' + verb;
+  });
+
+  let composedHeader = header || DEFAULT_HEADER;
+  if (personaContext) {
+    composedHeader = composedHeader + ' (' + personaContext + ' lens)';
+  }
+
+  return {
+    zones: {
+      header: composedHeader,
+      body: lines.join('\n'),
+      signals: '',
+      footer: null,
+    },
+    contract: {
+      shape: 'F.1',
+      keyboard: 'askuserquestion',
+      verbs: verbs.slice(),
+      mode: mode,
+      recommended: recInList,
+      personaContext: personaContext,
+    },
+  };
+}
+
+module.exports = {
+  renderShapeF1: renderShapeF1,
+  CANONICAL_VERBS: CANONICAL_VERBS.slice(),
+};