@mindrian_os/install 1.13.0-beta.11

package/lib/hmi/shape-f6-plan-review-renderer.cjs

@@ -0,0 +1,312 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 88.2-06 -- Shape F.6 Plan Review Round renderer (UISEL-88.2-08 part 2).
+ *
+ * NAMING NOTE (R1 collision mitigation): this file is shape-f6-PLAN-REVIEW-renderer.cjs.
+ * lib/hmi/shape-f6-renderer.cjs is Phase 101-01 JTBD-aware Next Move and is byte-stable
+ * (sha256 baseline 1792535860abc791222bf0ecf59599d66e49ad9cc1606b3d8679fca2922150cf).
+ * The umbrella 'F' branch in selector-dispatcher.cjs continues to route to the Phase
+ * 101-01 module via JTBD logic; ONLY explicit requestedShape:'F.6' (string) routes
+ * to this plan-review renderer.
+ *
+ * Replaces the 88.2-00 Wave-0 stub. Implements F.6 per CONTEXT.md amendment
+ * 2026-04-29 + D-AMEND-01 (F.6 in scope of Phase 88.2 finish) + D-AMEND-04
+ * (open-vocab parent shape with optional personaContext suffix) + D-AMEND-05
+ * (Tier 2 persona-aware decoys via lib/hmi/decoy-tier.cjs dispatcher).
+ *
+ * F.6 invariants (CONTEXT.md spec body 2026-04-29):
+ *   - Round size 15-30 questions (default 20). Real:decoy ratio 4:1 (16 + 4 at 20).
+ *   - Real questions sourced from artifact's structural decomposition (tasks, gates,
+ *     dependencies, acceptance criteria, success metrics).
+ *   - Decoys NOT disclosed during round; debrief Shape A action report at round-end
+ *     discloses (decoy-ethics contract, room/decisions/decision-decoy-ethics.md).
+ *   - Each response writes ONE REVIEWED typed edge with properties
+ *     { round_id, position, latency_ms, was_decoy, response, confidence_self_report }.
+ *     Position-aware so debrief identifies decoys-caught vs decoys-missed.
+ *   - Round can be paused via 'q' keystroke; resumes from same position; persists
+ *     across session restarts (round-state graph node survives).
+ *   - Cowork: parallel actor responses captured per actor_id (Cowork concurrency
+ *     contract, room/decisions/decision-cowork-round-locking.md).
+ *   - Double-line border (parent shape -- structural distinction from F.0 single-line).
+ *
+ * Three exports:
+ *   1. renderShapeF6PlanReview({ tier, round_id?, position, totalQuestions, claim,
+ *                                counts, header?, personaContext? })
+ *      -> { zones, contract }
+ *      Renders one question of N. The renderer is PURE (no FS reads, no DB writes);
+ *      caller composes the round (decoy interleaving, real-question sourcing) by
+ *      pairing this renderer with lib/hmi/decoy-tier.cjs and a per-position invocation.
+ *
+ *   2. buildReviewedEdge({ roomDir, round_id, position, latency_ms, was_decoy,
+ *                          response, confidence_self_report?, reason?, actor_id? })
+ *      -> { ok, reason?, eventId? }
+ *      Writes one REVIEWED edge to room.db via Phase 109 logEvent with eventType
+ *      'selector_response'. Closed-vocab response: confirm | reject | discuss |
+ *      free-text. Graceful-fail envelope -- never throws.
+ *
+ *   3. emitRoundCompleted({ roomDir, round_id, real_count, decoy_count, tier })
+ *      -> { ok, reason?, eventId? }
+ *      Writes one f6_round_completed event at round close. Surfaces summary
+ *      counts so the debrief Shape A action report can render without re-querying.
+ *      Graceful-fail envelope -- never throws.
+ *
+ * Persona suffix (per D-AMEND-04 / 88.2-03 DISCRETION-AMEND-01 RESOLVED PATTERN):
+ *   When personaContext is a non-empty string, the header gets ' ({personaContext} lens)'
+ *   suffix. Cold-start (omitted/null/empty) preserves the persona-agnostic header
+ *   byte-for-byte. The renderer stays PURE; the caller (dispatcher per 88.2-04) supplies
+ *   the pre-computed string from readUserMd().role_blend per Phase 115 D-12.
+ *
+ * Glyph audit (12-glyph vocabulary per skills/ui-system/SKILL.md):
+ *   ALLOWED: triangle (filled) / triangle (open) / square / dot / arrow.
+ *   FORBIDDEN: rounded box corners, heavy horizontals/verticals, error/warn glyphs.
+ *   The progress bar uses '=' and '-' ASCII (not heavy horizontal); count chips use plain text.
+ *
+ * Pure CJS, node built-ins only, zero deps (Phase 87 invariant).
+ * Canon Part 4: every response produces a typed REVIEWED edge -- no silent dismiss.
+ * Canon Part 8: all writes are LOCAL room.db; zero Brain egress.
+ */
+'use strict';
+
+const F6_VERBS = ['Confirm', 'Reject', 'Discuss'];
+
+// Closed-vocab response taxonomy. The renderer surfaces 3 verbs; the
+// 'free-text' branch is reachable when a downstream prompt captures a
+// reject reason (the reason becomes a property on the REVIEWED edge,
+// not a separate response token).
+const VALID_RESPONSES = ['confirm', 'reject', 'discuss', 'free-text'];
+
+const RESPONSE_EVENT_TYPE = 'selector_response';
+const ROUND_COMPLETED_EVENT_TYPE = 'f6_round_completed';
+
+const MARKER_ROW = '▷';            // 12-glyph row marker (matches 88.2-01 + F.0)
+const MARKER_PROGRESS = '▶';       // 12-glyph progress chevron
+const DEFAULT_HEADER_PREFIX = '-- mindrianOS -- plan review --';
+
+// Progress bar geometry: 20 cells, 5% each. Filled cells use '='; empty
+// cells use '-'. ASCII only -- no heavy-horizontal box-drawing chars
+// (forbidden in the 12-glyph audit; project-wide convention).
+const PROGRESS_BAR_CELLS = 20;
+
+/**
+ * Render one question of a F.6 plan-review round.
+ *
+ * Returns { zones, contract } where:
+ *   - zones.header carries 'ROUND {position} of {totalQuestions}' + optional
+ *     ' ({personaContext} lens)' suffix
+ *   - zones.body carries the user-story claim + 3 verb rows + progress bar +
+ *     count chips
+ *   - contract.shape === 'F.6'; freeTextOffered === false; verbs frozen at
+ *     ['Confirm', 'Reject', 'Discuss']; recommended === null in both modes
+ *     (closed-vocab; no Brain confidence marker on F.6 itself)
+ */
+function renderShapeF6PlanReview(input) {
+  const opts = (input && typeof input === 'object') ? input : {};
+  const tier = (typeof opts.tier === 'number') ? opts.tier : 0;
+  const mode = (tier >= 2) ? 'A' : 'B';
+  const position = (Number.isInteger(opts.position) && opts.position >= 1) ? opts.position : 1;
+  const totalQuestions = (Number.isInteger(opts.totalQuestions) && opts.totalQuestions >= 1)
+    ? opts.totalQuestions : 20;
+  const claim = (typeof opts.claim === 'string') ? opts.claim : '';
+  const counts = (opts.counts && typeof opts.counts === 'object') ? opts.counts : {};
+  const personaContext = (typeof opts.personaContext === 'string' && opts.personaContext.length > 0)
+    ? opts.personaContext : null;
+  const roundId = (typeof opts.round_id === 'string' && opts.round_id.length > 0)
+    ? opts.round_id : null;
+
+  // Header: caller override OR canonical 'ROUND N of M -- PLAN REVIEW' format.
+  const headerBase = (typeof opts.header === 'string' && opts.header.length > 0)
+    ? opts.header
+    : DEFAULT_HEADER_PREFIX + ' ROUND ' + position + ' of ' + totalQuestions;
+  const composedHeader = personaContext
+    ? (headerBase + ' (' + personaContext + ' lens)')
+    : headerBase;
+
+  // Body: user-story scaffold + 3 verb rows.
+  const verbRows = F6_VERBS.map((v, i) => MARKER_ROW + ' ' + (i + 1) + ') ' + v);
+
+  // Progress bar: 20 cells, 5% each. Filled = '=' / Empty = '-'.
+  const pct = Math.floor((position / totalQuestions) * 100);
+  const filledCells = Math.max(0, Math.min(PROGRESS_BAR_CELLS, Math.floor(pct / 5)));
+  let bar = '[';
+  for (let i = 0; i < PROGRESS_BAR_CELLS; i++) {
+    bar += (i < filledCells) ? '=' : '-';
+  }
+  bar += ']';
+
+  // Count chips: 'reject N   discuss N   confirm N' (plain text -- no decorative
+  // glyphs). The order matches the CONTEXT.md spec body sample box.
+  const cReject = Number.isInteger(counts.reject) ? counts.reject : 0;
+  const cDiscuss = Number.isInteger(counts.discuss) ? counts.discuss : 0;
+  const cConfirm = Number.isInteger(counts.confirm) ? counts.confirm : 0;
+  const countLine = 'reject ' + cReject + '   discuss ' + cDiscuss + '   confirm ' + cConfirm;
+
+  const claimBlock = claim
+    ? 'As a navigator, I confirm:\n  "' + claim + '"\n\n'
+    : '';
+  const body = claimBlock +
+               verbRows.join('\n') + '\n\n' +
+               MARKER_PROGRESS + ' progress  ' + bar + '  ' + pct + '%\n' +
+               countLine;
+
+  return {
+    zones: {
+      header: composedHeader,
+      body: body,
+      signals: '',
+      footer: null,
+    },
+    contract: {
+      shape: 'F.6',
+      keyboard: 'askuserquestion',
+      verbs: F6_VERBS.slice(),     // defensive copy
+      freeTextOffered: false,      // closed-vocab; reject reason captured via downstream prompt
+      mode: mode,
+      recommended: null,           // F.6 carries no RECOMMENDED (closed-vocab parent shape)
+      border_style: 'double',      // parent shape; distinct from F.0's single-line
+      personaContext: personaContext,
+      round_id: roundId,
+      position: position,
+      total_questions: totalQuestions,
+    },
+  };
+}
+
+/**
+ * Build and emit a REVIEWED typed edge to room.db via Phase 109.
+ * Graceful-fail envelope -- never throws.
+ *
+ * Closed-vocab response: confirm | reject | discuss | free-text.
+ * was_decoy is required boolean (per F.6 spec position-aware debrief).
+ * confidence_self_report is optional 1-5 integer.
+ * reason is optional free-text (carries reject reason when response === 'reject').
+ * actor_id is optional Cowork scalar handle (parallel-actor disambiguation).
+ */
+function buildReviewedEdge(args) {
+  try {
+    const a = (args && typeof args === 'object') ? args : {};
+
+    if (typeof a.round_id !== 'string' || a.round_id.length === 0) {
+      return { ok: false, reason: 'invalid_round_id' };
+    }
+    if (!Number.isInteger(a.position) || a.position < 1) {
+      return { ok: false, reason: 'invalid_position' };
+    }
+    if (typeof a.was_decoy !== 'boolean') {
+      return { ok: false, reason: 'invalid_was_decoy' };
+    }
+    if (VALID_RESPONSES.indexOf(a.response) === -1) {
+      return { ok: false, reason: 'invalid_response' };
+    }
+    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(RESPONSE_EVENT_TYPE)) {
+      return { ok: false, reason: 'event_type_not_registered' };
+    }
+
+    // Project standard: node:sqlite DatabaseSync per lib/core/lazygraph-ops.cjs.
+    // better-sqlite3 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 = {
+        round_id: a.round_id,
+        position: a.position,
+        latency_ms: (typeof a.latency_ms === 'number') ? a.latency_ms : null,
+        was_decoy: a.was_decoy,
+        response: a.response,
+      };
+      if (a.confidence_self_report !== undefined) props.confidence_self_report = a.confidence_self_report;
+      if (typeof a.reason === 'string' && a.reason.length > 0) props.reason = a.reason;
+      if (typeof a.actor_id === 'string' && a.actor_id.length > 0) props.actor_id = a.actor_id;
+      return logEvent(db, RESPONSE_EVENT_TYPE, props);
+    } finally {
+      db.close();
+    }
+  } catch (_e) {
+    return { ok: false, reason: 'edge_build_threw_caught' };
+  }
+}
+
+/**
+ * Emit the f6_round_completed event at round close. Carries summary counts
+ * + tier label so debrief Shape A action report can render without
+ * re-querying the per-response edges.
+ *
+ * Graceful-fail envelope -- never throws.
+ */
+function emitRoundCompleted(args) {
+  try {
+    const a = (args && typeof args === 'object') ? args : {};
+    if (typeof a.round_id !== 'string' || a.round_id.length === 0) {
+      return { ok: false, reason: 'invalid_round_id' };
+    }
+
+    const { EVENT_TYPES, logEvent } = require('../core/navigation/memory-events.cjs');
+    if (!EVENT_TYPES.has(ROUND_COMPLETED_EVENT_TYPE)) {
+      return { ok: false, reason: 'event_type_not_registered' };
+    }
+
+    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 = {
+        round_id: a.round_id,
+        real_count: (typeof a.real_count === 'number') ? a.real_count : null,
+        decoy_count: (typeof a.decoy_count === 'number') ? a.decoy_count : null,
+        tier: (typeof a.tier === 'string') ? a.tier : null,
+        ended_at: new Date().toISOString(),
+      };
+      return logEvent(db, ROUND_COMPLETED_EVENT_TYPE, props);
+    } finally {
+      db.close();
+    }
+  } catch (_e) {
+    return { ok: false, reason: 'round_completion_threw_caught' };
+  }
+}
+
+module.exports = {
+  renderShapeF6PlanReview: renderShapeF6PlanReview,
+  buildReviewedEdge: buildReviewedEdge,
+  emitRoundCompleted: emitRoundCompleted,
+  F6_VERBS: F6_VERBS.slice(),
+  VALID_RESPONSES: VALID_RESPONSES.slice(),
+  _internal: {
+    RESPONSE_EVENT_TYPE: RESPONSE_EVENT_TYPE,
+    ROUND_COMPLETED_EVENT_TYPE: ROUND_COMPLETED_EVENT_TYPE,
+    PROGRESS_BAR_CELLS: PROGRESS_BAR_CELLS,
+  },
+};

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

@@ -0,0 +1,144 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 101-01 -- Shape F.6 (JTBD-aware Next Move) renderer.
+ *
+ * Renders the Phase 100 JTBD signal into a Shape F selector body whose
+ * verb vocabulary is drawn from `entries[i].next_move_verbs[]` of the
+ * canonical taxonomy. Free-Text is appended last (D-10 hardcoded).
+ * Mode A (tier >= 2) marks `recommendedVerb` with `▶`; Mode B suppresses
+ * the marker (D-05). Falls through to F.1 if the taxonomy entry is
+ * degenerate (verb set < 3 entries) or missing -- per D-04 + RESEARCH §8
+ * pitfall 4. Keyboard contract delegates to F.1 (D-01).
+ *
+ * Allowed glyphs in body (per 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:
+ *   renderShapeF6({ jtbd, tier, recommendedVerb, header? })
+ *     -> { zones, contract }
+ *      | { error: string }                     // taxonomy missing
+ *      | { fallthrough: true, reason: string } // degenerate verb set
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const TAXONOMY_PATH = path.join(__dirname, 'jtbd-taxonomy.json');
+const FREE_TEXT = 'Free-Text';
+const MIN_VERBS = 3; // D-04 + RESEARCH §8 pitfall 4: < 3 verbs = degenerate
+const MARKER_RECOMMENDED = '▶';
+const MARKER_ROW = '▷';
+
+function loadTaxonomy() {
+  // Taxonomy-missing graceful branch (D-12, CONTEXT). Out-of-order execution
+  // (Phase 101 before Phase 100 Wave 1) returns 3-line error per Canon Part 3
+  // Rule 2 instead of crashing.
+  if (!fs.existsSync(TAXONOMY_PATH)) return null;
+  try {
+    const raw = fs.readFileSync(TAXONOMY_PATH, 'utf8');
+    return JSON.parse(raw);
+  } catch (e) {
+    return null;
+  }
+}
+
+function entriesOf(taxonomy) {
+  if (!taxonomy) return [];
+  if (Array.isArray(taxonomy.entries)) return taxonomy.entries;
+  if (Array.isArray(taxonomy.jtbds)) return taxonomy.jtbds;
+  return [];
+}
+
+function findEntry(taxonomy, jtbdId) {
+  const list = entriesOf(taxonomy);
+  if (!Array.isArray(list) || typeof jtbdId !== 'string') return null;
+  return list.find(e => e && e.id === jtbdId) || null;
+}
+
+function defaultHeader(jtbdId) {
+  // Zone 1 default per RESEARCH §2 step 6.
+  return '-- mindrianOS -- ' + jtbdId + ' -- next move --';
+}
+
+function renderShapeF6(input) {
+  const opts = (input && typeof input === 'object') ? input : {};
+  const jtbd = typeof opts.jtbd === 'string' ? opts.jtbd : null;
+  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;
+
+  // Step 0: taxonomy-missing graceful branch (Canon Part 3 Rule 2 + D-12).
+  const taxonomy = loadTaxonomy();
+  if (!taxonomy) {
+    return {
+      error:
+        'x lib/hmi/jtbd-taxonomy.json not found\n' +
+        'Why: Phase 100 Wave 1 must ship before F.6 can render\n' +
+        'Fix: complete Phase 100 plans 100-01 first',
+    };
+  }
+
+  // Null-jtbd is dispatcher's job (D-02); F.6 expects non-null. Treat as
+  // fallthrough so the dispatcher routes to F.1.
+  if (!jtbd) {
+    return { fallthrough: true, reason: 'jtbd_null' };
+  }
+
+  const entry = findEntry(taxonomy, jtbd);
+  if (!entry) {
+    return { fallthrough: true, reason: 'jtbd_unknown' };
+  }
+
+  const rawVerbs = Array.isArray(entry.next_move_verbs) ? entry.next_move_verbs.slice() : [];
+
+  // Step 2: degenerate verb set (D-04 + RESEARCH §8 pitfall 4). Per the plan,
+  // count is on raw taxonomy verbs (Free-Text is appended later).
+  if (rawVerbs.length < MIN_VERBS) {
+    return { fallthrough: true, reason: 'degenerate_verb_set' };
+  }
+
+  // Step 3: Free-Text always last (D-10 hardcoded). Caller cannot omit.
+  // Defensive de-dup if taxonomy already lists Free-Text (current taxonomy
+  // does for the explore JTBD; explore is < 3 anyway, but be safe).
+  const verbsNoFree = rawVerbs.filter(v => v !== FREE_TEXT);
+  const verbs = verbsNoFree.concat([FREE_TEXT]);
+
+  // Step 4: Mode A (tier >= 2) renders recommendation; Mode B suppresses.
+  const mode = tier >= 2 ? 'A' : 'B';
+  const recInList = (mode === 'A' && recommendedVerb && verbs.indexOf(recommendedVerb) !== -1)
+    ? recommendedVerb : null;
+
+  // Step 6: render zones.
+  const zone1 = header || defaultHeader(jtbd);
+  const zone2Lines = verbs.map((verb, i) => {
+    const prefix = (verb === recInList) ? MARKER_RECOMMENDED : MARKER_ROW;
+    const num = String(i + 1);
+    return prefix + ' ' + num + '. ' + verb;
+  });
+
+  const zones = {
+    header: zone1,
+    body: zone2Lines.join('\n'),
+    signals: '',
+    footer: null, // F.x is itself the selector; no separate Zone 4 footer.
+  };
+
+  // Step 7: contract -- keyboard inheritance from F.1 (D-01).
+  const contract = {
+    keyboard: 'f1-inheritance',
+    verbs: verbs.slice(),
+    mode: mode,
+    recommended: recInList,
+  };
+
+  return { zones, contract };
+}
+
+module.exports = { renderShapeF6 };

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

@@ -0,0 +1,219 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 101-02 -- lib/hmi/shape-g-renderer.cjs
+ * Shape G (Comparison Matrix). Render-only in v1; interactive table picking
+ * is v1.15.x. Produces a 4-zone block whose Zone 2 body is a comparison
+ * matrix: rows = options, columns = criteria.
+ *
+ * Contract (RESEARCH section 3 + PLAN must_haves):
+ *   - options.length >= 3 AND criteria.length >= 2 (D-08); else fallthrough to E
+ *   - cells clamped to CELL_CLAMP (12) chars + ellipsis; criteria to CRITERION_CLAMP (10)
+ *   - 4-zone wrapping with Zone 4 footer (>= 2 /mos: references)
+ *   - 12-glyph compliance + ASCII pipe column separator (allowed for table use)
+ *
+ * Source uses String.fromCharCode(0x2500) for U+2500 so the file contains
+ * zero literal forbidden box-drawing chars per scripts/doctor.cjs scan.
+ *
+ * Canon Part 8 (LOCAL ONLY): pure function. License: BSL 1.1.
+ */
+
+'use strict';
+
+// path + fs reserved for forward-compat (PLAN names them as imports).
+require('node:path');
+require('node:fs');
+
+const G_FILLED_SQUARE = '■';        // U+25A0
+const G_RIGHT_TRI_FILLED = '▶';     // U+25B6
+const G_RIGHT_TRI_EMPTY = '▷';      // U+25B7
+const G_DASH = String.fromCharCode(0x2500); // U+2500 (avoid literal in source)
+
+const CRITERION_CLAMP = 10;
+const CELL_CLAMP = 12;
+const ELLIPSIS = '...';
+
+const DEFAULT_FOOTER_VERBS = [
+  { glyph: G_RIGHT_TRI_FILLED, command: '/mos:scenario-plan', hint: 'Branch into futures' },
+  { glyph: G_RIGHT_TRI_EMPTY, command: '/mos:deep-grade', hint: 'Score each option' },
+  { glyph: G_RIGHT_TRI_EMPTY, command: '/mos:jtbd set decide-pursue', hint: 'Move to commit gate' },
+];
+
+function clamp(s, maxLen) {
+  const str = (s === null || s === undefined) ? '' : String(s);
+  if (str.length <= maxLen) return str;
+  if (maxLen <= ELLIPSIS.length) return str.slice(0, maxLen);
+  return str.slice(0, maxLen - ELLIPSIS.length) + ELLIPSIS;
+}
+
+function pad(s, width) {
+  const str = (s === null || s === undefined) ? '' : String(s);
+  if (str.length >= width) return str;
+  return str + ' '.repeat(width - str.length);
+}
+
+function repeatChar(ch, width) {
+  return width <= 0 ? '' : ch.repeat(width);
+}
+
+function validateDimensions(options, criteria) {
+  if (!Array.isArray(options) || options.length < 3) {
+    return { fallthrough: true, fallthroughTo: 'E', reason: 'degenerate_matrix' };
+  }
+  if (!Array.isArray(criteria) || criteria.length < 2) {
+    return { fallthrough: true, fallthroughTo: 'E', reason: 'degenerate_matrix' };
+  }
+  return null;
+}
+
+function computeWidths(options, criteriaClamped, cellsClamped) {
+  let optionColWidth = 0;
+  for (const opt of options) {
+    const len = String(opt || '').length;
+    if (len > optionColWidth) optionColWidth = len;
+  }
+  const criterionWidths = new Array(criteriaClamped.length);
+  for (let c = 0; c < criteriaClamped.length; c++) {
+    let maxCell = criteriaClamped[c].length;
+    for (const opt of options) {
+      const cell = (cellsClamped[opt] && cellsClamped[opt][criteriaClamped[c]]) || '';
+      if (cell.length > maxCell) maxCell = cell.length;
+    }
+    criterionWidths[c] = maxCell;
+  }
+  return { optionColWidth: optionColWidth, criterionWidths: criterionWidths };
+}
+
+function renderHeader(options, criteria, opts) {
+  const room = (opts && opts.room) ? opts.room : 'mindrianOS';
+  const middle = opts && opts.title
+    ? opts.title
+    : (opts && opts.jtbd ? opts.jtbd : 'compare');
+  const dims = options.length + ' options x ' + criteria.length + ' criteria';
+  return '-- ' + room + ' -- ' + middle + ' -- ' + dims + ' --';
+}
+
+function renderBody(options, criteriaClamped, cellsClamped) {
+  const widths = computeWidths(options, criteriaClamped, cellsClamped);
+  const optW = widths.optionColWidth;
+  const critW = widths.criterionWidths;
+  const lines = [];
+  lines.push(G_FILLED_SQUARE + ' Comparison Matrix');
+
+  let headerRow = '  ' + pad('', optW);
+  for (let c = 0; c < criteriaClamped.length; c++) {
+    headerRow += ' | ' + pad(criteriaClamped[c], critW[c]);
+  }
+  lines.push(headerRow);
+
+  let sepRow = '  ' + repeatChar(G_DASH, optW);
+  for (let c = 0; c < criteriaClamped.length; c++) {
+    sepRow += ' ' + G_DASH + ' ' + repeatChar(G_DASH, critW[c]);
+  }
+  lines.push(sepRow);
+
+  for (const opt of options) {
+    let row = '  ' + pad(String(opt), optW);
+    for (let c = 0; c < criteriaClamped.length; c++) {
+      const cell = (cellsClamped[opt] && cellsClamped[opt][criteriaClamped[c]]) || '';
+      row += ' | ' + pad(cell, critW[c]);
+    }
+    lines.push(row);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Phase 101-05: Mode-aware footer marker selection.
+ *
+ * Per Canon Part 3 "Option generation tier-awareness":
+ *   Mode A (tier >= 2)  -> first verb may carry RECOMMENDED ▶ marker (Brain-derived).
+ *   Mode B (tier === 1) -> all verbs use the empty triangle ▷ marker; ▶ NEVER renders.
+ *
+ * Defense-in-depth: this guard lives inside the renderer regardless of whether
+ * the dispatcher already gated the call. A buggy caller forgetting to pass mode
+ * still cannot leak a ▶ marker in Mode B.
+ */
+function renderFooter(footerVerbs, mode) {
+  const verbs = (Array.isArray(footerVerbs) && footerVerbs.length >= 2)
+    ? footerVerbs
+    : DEFAULT_FOOTER_VERBS;
+  const isModeB = (mode === 'B');
+  const lines = [];
+  for (let i = 0; i < verbs.length; i++) {
+    const v = verbs[i];
+    const defaultGlyph = (i === 0 && !isModeB) ? G_RIGHT_TRI_FILLED : G_RIGHT_TRI_EMPTY;
+    // In Mode B, hard-override any caller-supplied ▶ glyph to ▷ (Canon Part 3).
+    const rawGlyph = v.glyph || defaultGlyph;
+    const glyph = isModeB ? G_RIGHT_TRI_EMPTY : rawGlyph;
+    const cmd = v.command || '/mos:status';
+    const hint = v.hint || '';
+    const hintSuffix = hint ? '# ' + hint : '';
+    lines.push('  ' + glyph + ' ' + pad(cmd, 28) + hintSuffix);
+  }
+  return lines.join('\n');
+}
+
+function renderShapeG(input) {
+  const opts = input || {};
+  const options = opts.options;
+  const criteria = opts.criteria;
+  const cells = opts.cells || {};
+
+  // Phase 101-05: derive mode from explicit `mode` arg or fall back to `tier`.
+  // Mode A (Brain reachable + tier >= 2) renders RECOMMENDED ▶ on first footer verb.
+  // Mode B (tier 1 / Brain unreachable) suppresses ▶ across the entire footer.
+  let mode;
+  if (opts.mode === 'A' || opts.mode === 'B') {
+    mode = opts.mode;
+  } else if (typeof opts.tier === 'number') {
+    mode = opts.tier >= 2 ? 'A' : 'B';
+  } else {
+    mode = 'A'; // back-compat: pre-101-05 callers default to Mode A behavior
+  }
+
+  const dimErr = validateDimensions(options, criteria);
+  if (dimErr) return dimErr;
+
+  const criteriaClamped = criteria.map((c) => clamp(c, CRITERION_CLAMP));
+  const cellsClamped = {};
+  for (const opt of options) {
+    cellsClamped[opt] = {};
+    const optCells = (cells[opt] && typeof cells[opt] === 'object') ? cells[opt] : {};
+    for (let c = 0; c < criteria.length; c++) {
+      const origKey = criteria[c];
+      const clampedKey = criteriaClamped[c];
+      const raw = optCells[origKey] !== undefined ? optCells[origKey] : optCells[clampedKey];
+      cellsClamped[opt][clampedKey] = clamp(raw, CELL_CLAMP);
+    }
+  }
+
+  return {
+    zones: {
+      header: renderHeader(options, criteria, opts),
+      body: renderBody(options, criteriaClamped, cellsClamped),
+      signals: '',
+      footer: renderFooter(opts.footerVerbs, mode),
+    },
+    contract: {
+      shape: 'G',
+      passthrough: false,
+      options_count: options.length,
+      criteria_count: criteria.length,
+      mode: mode,
+    },
+  };
+}
+
+module.exports = {
+  renderShapeG: renderShapeG,
+  _internal: {
+    clamp: clamp,
+    pad: pad,
+    validateDimensions: validateDimensions,
+    computeWidths: computeWidths,
+    CRITERION_CLAMP: CRITERION_CLAMP,
+    CELL_CLAMP: CELL_CLAMP,
+    ELLIPSIS: ELLIPSIS,
+  },
+};