@mindrian_os/install 1.13.0-beta.17 → 1.13.0-beta.21

package/lib/core/breakthrough/voice-scaffold.test.cjs

@@ -0,0 +1,251 @@
+'use strict';
+/*
+ * Phase 120-03 Wave 2 Task 1 -- voice-scaffold unit tests (Tests 1-14).
+ *
+ * Per CONTEXT.md D-17 LOCKED VERBATIM 4-rule voice scaffold:
+ *   Rule 1: Evidence requirement   -- artifact ids OR graph edges cited
+ *   Rule 2: Mechanism clause       -- "by Y" user action
+ *   Rule 3: Time anchor            -- "in the last N hours/days" / "this week" / etc.
+ *   Rule 4: No unbacked superlatives -- 6 forbidden + 3 frequency words guarded
+ *
+ * The auditor IS the structural enforcement (D-20 meta-principle).
+ */
+
+const test = require('node:test');
+const { strict: assert } = require('node:assert');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const SCAFFOLD_PATH = path.resolve(__dirname, 'voice-scaffold.cjs');
+const voiceScaffold = require('./voice-scaffold.cjs');
+const {
+  composeBreakthroughVoiceLine,
+  auditVoiceLine,
+  citeEvidence,
+  includeMechanism,
+  anchorTime,
+  noUnbackedSuperlatives,
+  formatTimeAnchor,
+  VOICE_RULE_NAMES,
+  FORBIDDEN_SUPERLATIVES,
+  FREQUENCY_WORDS,
+  KIND_DISPLAY,
+} = voiceScaffold;
+
+// --- T1: VOICE_RULE_NAMES verbatim ---
+test('T1: VOICE_RULE_NAMES verbatim + Object.freeze invariant', () => {
+  assert.deepEqual(VOICE_RULE_NAMES, [
+    'evidence_requirement',
+    'mechanism_clause',
+    'time_anchor',
+    'no_unbacked_superlatives',
+  ]);
+  assert.equal(VOICE_RULE_NAMES.length, 4);
+  // Object.freeze invariant
+  const before = VOICE_RULE_NAMES.slice();
+  try { VOICE_RULE_NAMES.push('extra'); } catch (_e) { /* strict mode throws */ }
+  assert.deepEqual(VOICE_RULE_NAMES.slice(0, 4), before);
+});
+
+// --- T2: FORBIDDEN_SUPERLATIVES verbatim ---
+test('T2: FORBIDDEN_SUPERLATIVES contains the 6 D-17 rule 4 words verbatim', () => {
+  assert.deepEqual(FORBIDDEN_SUPERLATIVES, [
+    'breakthrough', 'biggest', 'first', 'unprecedented', 'major', 'massive',
+  ]);
+  assert.equal(FORBIDDEN_SUPERLATIVES.length, 6);
+});
+
+// --- T3: composeBreakthroughVoiceLine happy path -- convergence ---
+test('T3: composeBreakthroughVoiceLine produces D-17-compliant line for convergence', () => {
+  const twoDaysAgoMs = Date.now() - 2 * 86400 * 1000;
+  const bk = {
+    kind: 'convergence',
+    theme: 'operator-state machines',
+    artifact_ids: ['art:1', 'art:2', 'art:3', 'art:4'],
+    detected_at: twoDaysAgoMs,
+  };
+  const roomState = {
+    mechanism_phrase: 'by uploading the four notes on Mode A and Mode B',
+  };
+  const line = composeBreakthroughVoiceLine(bk, roomState);
+  assert.match(
+    line,
+    /^You're seeing a convergence on operator-state machines \(artifacts art:1, art:2, art:3, art:4\) -- by uploading the four notes on Mode A and Mode B -- in the last two days\.$/,
+  );
+});
+
+// --- T4: composeBreakthroughVoiceLine default mechanism when roomState absent ---
+test('T4: composeBreakthroughVoiceLine uses structural default mechanism when roomState absent', () => {
+  const bk = {
+    kind: 'convergence',
+    theme: 'X',
+    artifact_ids: ['a1', 'a2', 'a3'],
+    detected_at: Date.now(),
+  };
+  const line = composeBreakthroughVoiceLine(bk, null);
+  // Default: "by adding N artifacts to this section"
+  assert.ok(/by adding 3 artifacts/.test(line),
+    'expected default mechanism with artifact count, got: ' + line);
+  // The default must still pass auditor (rule 2 satisfied)
+  const audit = auditVoiceLine(line);
+  assert.equal(audit.ok, true, 'default-mechanism line must pass auditor, violations: ' + JSON.stringify(audit.violations));
+});
+
+// --- T5: auditVoiceLine -- D-17 rule 1 violation -- no evidence cite ---
+test('T5: auditVoiceLine catches D-17 rule 1 violation (no evidence cite)', () => {
+  const bad = "You're seeing a convergence on X -- by uploading -- in the last two days.";
+  const r = auditVoiceLine(bad);
+  assert.equal(r.ok, false);
+  assert.ok(r.violations.indexOf('evidence_requirement') >= 0,
+    'expected evidence_requirement violation, got: ' + JSON.stringify(r.violations));
+});
+
+// --- T6: auditVoiceLine -- D-17 rule 2 violation -- no mechanism ---
+test('T6: auditVoiceLine catches D-17 rule 2 violation (no mechanism)', () => {
+  const bad = "You're seeing a convergence on X (artifacts a1, a2, a3) -- in the last two days.";
+  const r = auditVoiceLine(bad);
+  assert.equal(r.ok, false);
+  assert.ok(r.violations.indexOf('mechanism_clause') >= 0,
+    'expected mechanism_clause violation, got: ' + JSON.stringify(r.violations));
+});
+
+// --- T7: auditVoiceLine -- D-17 rule 3 violation -- no time anchor ---
+test('T7: auditVoiceLine catches D-17 rule 3 violation (no time anchor)', () => {
+  const bad = "You're seeing a convergence on X (artifacts a1, a2, a3) -- by uploading the notes.";
+  const r = auditVoiceLine(bad);
+  assert.equal(r.ok, false);
+  assert.ok(r.violations.indexOf('time_anchor') >= 0,
+    'expected time_anchor violation, got: ' + JSON.stringify(r.violations));
+});
+
+// --- T8: auditVoiceLine -- D-17 rule 4 violation -- unbacked superlative ---
+test('T8: auditVoiceLine catches D-17 rule 4 violation (unbacked superlative)', () => {
+  const bad = "You're seeing the BIGGEST breakthrough on X (artifacts a1, a2, a3) -- by uploading -- in the last hour.";
+  const r = auditVoiceLine(bad);
+  assert.equal(r.ok, false);
+  assert.ok(r.violations.indexOf('no_unbacked_superlatives') >= 0,
+    'expected no_unbacked_superlatives violation, got: ' + JSON.stringify(r.violations));
+});
+
+// --- T9: auditVoiceLine -- D-17 rule 4 SATISFIED with numeric backing ---
+test('T9: auditVoiceLine accepts D-17 rule 4 when superlative has numeric backing', () => {
+  const good = "You're seeing a convergence on X (artifacts a1, a2, a3) -- by uploading -- in the last hour. This is the highest differential score (0.78) in this room's history.";
+  const r = auditVoiceLine(good);
+  assert.equal(r.ok, true,
+    'expected no violations, got: ' + JSON.stringify(r.violations));
+});
+
+// --- T10: auditVoiceLine happy path passes all 4 rules ---
+test('T10: auditVoiceLine passes for T3-composed convergence line', () => {
+  const twoDaysAgoMs = Date.now() - 2 * 86400 * 1000;
+  const bk = {
+    kind: 'convergence',
+    theme: 'operator-state machines',
+    artifact_ids: ['art:1', 'art:2', 'art:3', 'art:4'],
+    detected_at: twoDaysAgoMs,
+  };
+  const roomState = {
+    mechanism_phrase: 'by uploading the four notes on Mode A and Mode B',
+  };
+  const line = composeBreakthroughVoiceLine(bk, roomState);
+  const r = auditVoiceLine(line);
+  assert.equal(r.ok, true,
+    'composer + auditor must be aligned, violations: ' + JSON.stringify(r.violations));
+  assert.deepEqual(r.violations, []);
+});
+
+// --- T11: auditVoiceLine -- multiple violations reported ---
+test('T11: auditVoiceLine reports multiple violations on maximally bad line', () => {
+  const veryBad = "You're seeing a convergence on X.";
+  const r = auditVoiceLine(veryBad);
+  assert.equal(r.ok, false);
+  // expect at least 3 violations: evidence, mechanism, time_anchor (no superlative present so rule 4 OK)
+  assert.ok(r.violations.indexOf('evidence_requirement') >= 0);
+  assert.ok(r.violations.indexOf('mechanism_clause') >= 0);
+  assert.ok(r.violations.indexOf('time_anchor') >= 0);
+  assert.ok(r.violations.length >= 3);
+});
+
+// --- T12: composeBreakthroughVoiceLine for EVERY kind passes auditor ---
+test('T12: composeBreakthroughVoiceLine output passes auditor for every kind', () => {
+  const kinds = [
+    'convergence',
+    'contradiction_resolved',
+    'cross_domain_analogy',
+    'reverse_salient_closed',
+  ];
+  for (const kind of kinds) {
+    const bk = {
+      kind: kind,
+      theme: 'sample-theme',
+      artifact_ids: ['art:1', 'art:2', 'art:3'],
+      detected_at: Date.now() - 6 * 3600 * 1000, // 6 hours ago
+    };
+    const line = composeBreakthroughVoiceLine(bk, null);
+    const r = auditVoiceLine(line);
+    assert.equal(r.ok, true,
+      'kind ' + kind + ': composer output failed audit, line: ' + line + ', violations: ' + JSON.stringify(r.violations));
+  }
+});
+
+// --- T13: Canon Part 8 source-grep -- zero Brain coupling ---
+test('T13: Canon Part 8 source-grep -- voice-scaffold.cjs has zero Brain coupling', () => {
+  const src = fs.readFileSync(SCAFFOLD_PATH, 'utf8');
+  // brain-client require
+  assert.ok(!/require\(.+brain-client/.test(src),
+    'voice-scaffold must not require brain-client');
+  // direct fetch to brain.mindrian
+  assert.ok(!/fetch.+brain\.mindrian/.test(src),
+    'voice-scaffold must not fetch brain.mindrian');
+  // cross-room aggregation
+  assert.ok(!/cross-room/i.test(src.split('\n').filter(l => !l.match(/^\s*\/\//)).join('\n')) ||
+    src.indexOf('Canon Part 8') >= 0,
+    'cross-room mentions require Canon Part 8 context comment');
+});
+
+// --- T14: em-dash invariant ---
+test('T14: zero U+2014 em-dashes in voice-scaffold.cjs', () => {
+  const src = fs.readFileSync(SCAFFOLD_PATH, 'utf8');
+  const idx = src.indexOf('—');
+  assert.equal(idx, -1, 'em-dash found at index ' + idx);
+});
+
+// --- Bonus: formatTimeAnchor buckets ---
+test('T15: formatTimeAnchor returns expected buckets', () => {
+  const now = Date.now();
+  assert.equal(formatTimeAnchor(now - 30 * 60 * 1000, now), 'in the last hour');
+  assert.equal(formatTimeAnchor(now - 4 * 3600 * 1000, now), 'in the last 4 hours');
+  assert.equal(formatTimeAnchor(now - 12 * 3600 * 1000, now), 'today');
+  assert.equal(formatTimeAnchor(now - 36 * 3600 * 1000, now), 'in the last day');
+  assert.equal(formatTimeAnchor(now - 2 * 86400 * 1000, now), 'in the last two days');
+  assert.equal(formatTimeAnchor(now - 5 * 86400 * 1000, now), 'this week');
+  assert.equal(formatTimeAnchor(now - 10 * 86400 * 1000, now), 'in the last two weeks');
+});
+
+// --- Bonus: rule predicates exposed ---
+test('T16: rule predicates exposed individually for unit-level testing', () => {
+  assert.equal(typeof citeEvidence, 'function');
+  assert.equal(typeof includeMechanism, 'function');
+  assert.equal(typeof anchorTime, 'function');
+  assert.equal(typeof noUnbackedSuperlatives, 'function');
+  // citeEvidence positive cases
+  assert.equal(citeEvidence('foo (artifacts a1, a2)'), true);
+  assert.equal(citeEvidence('foo [[wiki-link]]'), true);
+  assert.equal(citeEvidence('foo (see edges X, Y)'), true);
+  // citeEvidence negative
+  assert.equal(citeEvidence('foo bar baz'), false);
+});
+
+// --- Bonus: FREQUENCY_WORDS exposed ---
+test('T17: FREQUENCY_WORDS exposed verbatim', () => {
+  assert.deepEqual(FREQUENCY_WORDS, ['consistent', 'repeated', 'always']);
+});
+
+// --- Bonus: KIND_DISPLAY exposed ---
+test('T18: KIND_DISPLAY exposed with the 4 detector kinds', () => {
+  assert.equal(typeof KIND_DISPLAY, 'object');
+  assert.ok(KIND_DISPLAY.convergence);
+  assert.ok(KIND_DISPLAY.contradiction_resolved);
+  assert.ok(KIND_DISPLAY.cross_domain_analogy);
+  assert.ok(KIND_DISPLAY.reverse_salient_closed);
+});

package/lib/core/directive-envelope.cjs

@@ -0,0 +1,175 @@
+'use strict';
+
+/*
+ * Phase 127-00 (Task 1) -- DirectiveEnvelope wrapper module.
+ *
+ * Builds the typed packet returned by `brain_ask` (via the stdio shim) and
+ * consumed by Larry's surface. CANONICAL DEFAULT mode: GUIDED.
+ *
+ * Default: GUIDED per feedback_larry_pedagogical_guided_first.md (HARD RULE).
+ * AUTONOMOUS only on explicit user invitation, non-judgment prep, or explicit
+ * "run" command. Cold start ALWAYS forces GUIDED. Mature-room commit-phase
+ * gates default to HYBRID.
+ *
+ * Canon parts: 2 (Larry pedagogy intrinsic, not Brain-dependent),
+ *   3 (Decision Gate F-shape next_gate handoff), 7 (pure data shaping,
+ *   zero network surface; envelope wrapper sits ABOVE brain-client).
+ *
+ * Constraints: CJS, Node built-ins only, zero new runtime deps, ZERO network
+ * surface (no fetch/http/brain-client require). HARD RULE: no em-dashes.
+ */
+
+const DEFAULT_MODE = 'GUIDED';
+
+/**
+ * Mode classifier. Signal precedence (first match wins; explicit user signals
+ * beat heuristic context):
+ *   1. user_said_just_tell_me | user_said_bottom_line -> AUTONOMOUS
+ *   2. is_first_material | is_cold_start              -> GUIDED (forced)
+ *   3. session_count>=8 + room_mature + in_commit_phase -> HYBRID
+ *   4. is_prep_work && !requires_judgment             -> AUTONOMOUS
+ *   5. user_explicitly_said_run                       -> AUTONOMOUS
+ *   6. default                                        -> GUIDED
+ *
+ * Non-object input is coerced to empty signals (default GUIDED applies).
+ * @param {object} signals
+ * @returns {{mode: string, rationale: string}}
+ */
+function selectMode(signals) {
+  const s = (signals && typeof signals === 'object') ? signals : {};
+
+  // 1. Explicit user invitation (highest precedence).
+  if (s.user_said_just_tell_me || s.user_said_bottom_line) {
+    return { mode: 'AUTONOMOUS', rationale: 'explicit_user_invitation' };
+  }
+
+  // 2. Cold start FORCES GUIDED (per feedback_larry_pedagogical_guided_first.md).
+  if (s.is_first_material || s.is_cold_start) {
+    return { mode: 'GUIDED', rationale: 'cold_start_never_autonomous' };
+  }
+
+  // 3. Mature-room commit-phase: HYBRID for non-trivial methodology run.
+  if (typeof s.session_count === 'number' && s.session_count >= 8
+      && s.room_mature && s.in_commit_phase) {
+    return { mode: 'HYBRID', rationale: 'mature_room_commit_gate' };
+  }
+
+  // 4. Non-judgment prep work.
+  if (s.is_prep_work && !s.requires_judgment) {
+    return { mode: 'AUTONOMOUS', rationale: 'non_judgment_prep_work' };
+  }
+
+  // 5. Explicit execute command.
+  if (s.user_explicitly_said_run) {
+    return { mode: 'AUTONOMOUS', rationale: 'explicit_execute_command' };
+  }
+
+  // 6. Default: GUIDED (Larry pedagogical canon).
+  return { mode: 'GUIDED', rationale: 'default_guided_pedagogical_canon' };
+}
+
+// The 3 documented user-override keys. Frozen template; envelope build
+// shallow-copies so caller mutations do not leak across envelopes.
+const USER_OVERRIDE_TEMPLATE = Object.freeze({
+  'just tell me': 'switch to AUTONOMOUS, run framework end-to-end',
+  'let me think': 'switch to GUIDED, ask the next reframing question',
+  'stop': 'halt, return control',
+});
+
+/**
+ * Build directive body. Pass through Brain-supplied `directive` when present;
+ * otherwise produce a mode-appropriate empty scaffold.
+ * @param {object|null} brainResponse
+ * @param {string} mode
+ * @returns {object}
+ */
+function buildDirective(brainResponse, mode) {
+  // Pass-through if Brain already supplied a typed directive payload.
+  if (brainResponse && typeof brainResponse === 'object'
+      && brainResponse.directive && typeof brainResponse.directive === 'object') {
+    return brainResponse.directive;
+  }
+
+  if (mode === 'AUTONOMOUS') {
+    return { autonomous: { plan: [], framework: null } };
+  }
+  if (mode === 'HYBRID') {
+    return {
+      hybrid: {
+        autonomous_prep: [],
+        guided_commit: { questions: [] },
+        framework: null,
+      },
+    };
+  }
+  // GUIDED default scaffold.
+  return { guided: { questions: [], framework: null, stage: null } };
+}
+
+/**
+ * Build next_gate handoff. Brain-supplied next_gate passes through when its
+ * sub_shape matches F.[1-5]; otherwise defaults to F.1 Next Move (Canon Part 3).
+ * @param {object|null} brainResponse
+ * @returns {{sub_shape: string, options: Array}}
+ */
+function buildNextGate(brainResponse) {
+  if (brainResponse && typeof brainResponse === 'object'
+      && brainResponse.next_gate && typeof brainResponse.next_gate === 'object') {
+    const ng = brainResponse.next_gate;
+    if (typeof ng.sub_shape === 'string' && /^F\.[1-5]$/.test(ng.sub_shape)) {
+      return {
+        sub_shape: ng.sub_shape,
+        options: Array.isArray(ng.options) ? ng.options : [],
+      };
+    }
+  }
+  return { sub_shape: 'F.1', options: [] };
+}
+
+/**
+ * Wrap a Brain response (or null) in a typed DirectiveEnvelope.
+ * brainResponse null/undefined => Tier-0 sentinel (mode GUIDED, rationale
+ * "brain_unreachable", directive.guided.stage "tier_0_brain_unreachable").
+ * Otherwise selectMode applies + directive/next_gate pass through when supplied.
+ * @param {object|null} brainResponse
+ * @param {object} signals
+ * @returns {object} DirectiveEnvelope per CAPABILITY-MAP spec.
+ */
+function wrapDirective(brainResponse, signals) {
+  if (brainResponse === null || brainResponse === undefined) {
+    // Tier-0 sentinel.
+    return {
+      packet_version: '1.0',
+      packet_type: 'DirectiveEnvelope',
+      mode: 'GUIDED',
+      mode_rationale: 'brain_unreachable',
+      directive: {
+        guided: {
+          questions: [],
+          framework: null,
+          stage: 'tier_0_brain_unreachable',
+        },
+      },
+      user_override: Object.assign({}, USER_OVERRIDE_TEMPLATE),
+      next_gate: { sub_shape: 'F.1', options: [] },
+    };
+  }
+
+  const { mode, rationale } = selectMode(signals || {});
+
+  return {
+    packet_version: '1.0',
+    packet_type: 'DirectiveEnvelope',
+    mode: mode,
+    mode_rationale: rationale,
+    directive: buildDirective(brainResponse, mode),
+    user_override: Object.assign({}, USER_OVERRIDE_TEMPLATE),
+    next_gate: buildNextGate(brainResponse),
+  };
+}
+
+module.exports = {
+  DEFAULT_MODE,
+  selectMode,
+  wrapDirective,
+};

package/lib/core/directive-envelope.test.cjs

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 127-00 (Task 1 RED) -- DirectiveEnvelope wrapper tests.
+ *
+ * 9 behavior tests covering:
+ *   - Tier-0 sentinel (null brainResponse)
+ *   - Default GUIDED mode for ordinary responses
+ *   - Explicit AUTONOMOUS via "just tell me" / "bottom line"
+ *   - HYBRID for mature-room commit-phase signals
+ *   - Cold-start FORCES GUIDED (never autonomous)
+ *   - user_override map present + the 3 documented keys
+ *   - next_gate sub_shape regex + options array
+ *   - selectMode default invariant
+ *   - DEFAULT_MODE constant exported and locked
+ *
+ * Canon parts: 2 (Larry pedagogy), 3 (Decision Gate F-shape next_gate),
+ *   7 (Reuse Before Build: pure data shaping, zero network surface).
+ *
+ * Constraints (Phase 87 invariant):
+ *   - Node built-ins only (node:assert/strict).
+ *   - CJS only.
+ *   - Zero new runtime dependencies.
+ *
+ * HARD RULE: no em-dashes (hyphens only).
+ */
+
+const assert = require('node:assert/strict');
+
+let passed = 0;
+let failed = 0;
+
+function ok(name) {
+  passed += 1;
+  process.stdout.write('  ok ' + name + '\n');
+}
+
+function fail(name, err) {
+  failed += 1;
+  process.stdout.write('  FAIL ' + name + '\n');
+  if (err) process.stdout.write('    ' + (err.message || String(err)) + '\n');
+}
+
+const mod = require('./directive-envelope.cjs');
+const { wrapDirective, selectMode, DEFAULT_MODE } = mod;
+
+// ---------------------------------------------------------------------------
+// Test 1: wrapDirective(null, {}) returns Tier-0 sentinel envelope.
+// ---------------------------------------------------------------------------
+(function test1_tier0Sentinel() {
+  const label = 'wrapDirective(null, {}) returns Tier-0 sentinel envelope';
+  try {
+    const env = wrapDirective(null, {});
+    assert.equal(env.packet_version, '1.0', 'packet_version must be "1.0"');
+    assert.equal(env.packet_type, 'DirectiveEnvelope', 'packet_type must be "DirectiveEnvelope"');
+    assert.equal(env.mode, 'GUIDED', 'Tier-0 mode must be GUIDED');
+    assert.equal(env.mode_rationale, 'brain_unreachable',
+      'Tier-0 mode_rationale must be "brain_unreachable"; got ' + env.mode_rationale);
+    assert.ok(env.directive && typeof env.directive === 'object', 'directive must be an object');
+    assert.ok(env.directive.guided && typeof env.directive.guided === 'object',
+      'Tier-0 directive.guided must be present');
+    assert.ok(Array.isArray(env.directive.guided.questions),
+      'Tier-0 directive.guided.questions must be an array');
+    ok(label);
+  } catch (err) { fail(label, err); }
+})();
+
+// ---------------------------------------------------------------------------
+// Test 2: ordinary brainResponse with empty signals defaults to GUIDED.
+// ---------------------------------------------------------------------------
+(function test2_defaultGuided() {
+  const label = 'wrapDirective({text:"..."}, {}) defaults to mode=GUIDED';
+  try {
+    const env = wrapDirective({ text: 'raw brain response' }, {});
+    assert.equal(env.mode, 'GUIDED', 'default mode must be GUIDED');
+    assert.ok(typeof env.mode_rationale === 'string' && env.mode_rationale.length > 0,
+      'mode_rationale must be a non-empty string');
+    assert.ok(env.mode_rationale.includes('guided') || env.mode_rationale.includes('pedagogical')
+      || env.mode_rationale.includes('default'),
+      'mode_rationale for default GUIDED should reference guided/pedagogical/default; got ' + env.mode_rationale);
+    ok(label);
+  } catch (err) { fail(label, err); }
+})();
+
+// ---------------------------------------------------------------------------
+// Test 3: explicit AUTONOMOUS via "just tell me" signal.
+// ---------------------------------------------------------------------------
+(function test3_explicitAutonomous() {
+  const label = 'wrapDirective(resp, {user_said_just_tell_me:true}) returns AUTONOMOUS';
+  try {
+    const env = wrapDirective({ text: 'r' }, { user_said_just_tell_me: true });
+    assert.equal(env.mode, 'AUTONOMOUS', 'mode must be AUTONOMOUS');
+    assert.equal(env.mode_rationale, 'explicit_user_invitation',
+      'mode_rationale must be "explicit_user_invitation"; got ' + env.mode_rationale);
+    ok(label);
+  } catch (err) { fail(label, err); }
+})();
+
+// ---------------------------------------------------------------------------
+// Test 4: HYBRID for mature-room commit-phase.
+// ---------------------------------------------------------------------------
+(function test4_hybridMatureCommit() {
+  const label = 'wrapDirective(resp, {session_count:9, room_mature:true, in_commit_phase:true}) returns HYBRID';
+  try {
+    const env = wrapDirective({ text: 'r' }, {
+      session_count: 9,
+      room_mature: true,
+      in_commit_phase: true,
+    });
+    assert.equal(env.mode, 'HYBRID', 'mode must be HYBRID; got ' + env.mode);
+    assert.equal(env.mode_rationale, 'mature_room_commit_gate',
+      'mode_rationale must be "mature_room_commit_gate"; got ' + env.mode_rationale);
+    ok(label);
+  } catch (err) { fail(label, err); }
+})();
+
+// ---------------------------------------------------------------------------
+// Test 5: cold start FORCES GUIDED (never autonomous on first material).
+// ---------------------------------------------------------------------------
+(function test5_coldStartForcesGuided() {
+  const label = 'wrapDirective(resp, {is_first_material:true}) returns GUIDED (never autonomous on cold start)';
+  try {
+    const env = wrapDirective({ text: 'r' }, { is_first_material: true });
+    assert.equal(env.mode, 'GUIDED', 'cold-start mode must be GUIDED; got ' + env.mode);
+    assert.ok(env.mode_rationale.includes('cold_start'),
+      'cold-start mode_rationale must include "cold_start"; got ' + env.mode_rationale);
+    ok(label);
+  } catch (err) { fail(label, err); }
+})();
+
+// ---------------------------------------------------------------------------
+// Test 6: every envelope contains user_override with the 3 documented keys.
+// ---------------------------------------------------------------------------
+(function test6_userOverrideMap() {
+  const label = 'every envelope contains user_override map with the 3 documented overrides';
+  try {
+    const envs = [
+      wrapDirective(null, {}),
+      wrapDirective({ text: 'r' }, {}),
+      wrapDirective({ text: 'r' }, { user_said_just_tell_me: true }),
+      wrapDirective({ text: 'r' }, { is_first_material: true }),
+    ];
+    for (const env of envs) {
+      assert.ok(env.user_override && typeof env.user_override === 'object',
+        'user_override must be an object');
+      assert.ok(Object.prototype.hasOwnProperty.call(env.user_override, 'just tell me'),
+        'user_override must have "just tell me" key');
+      assert.ok(Object.prototype.hasOwnProperty.call(env.user_override, 'let me think'),
+        'user_override must have "let me think" key');
+      assert.ok(Object.prototype.hasOwnProperty.call(env.user_override, 'stop'),
+        'user_override must have "stop" key');
+    }
+    ok(label);
+  } catch (err) { fail(label, err); }
+})();
+
+// ---------------------------------------------------------------------------
+// Test 7: every envelope contains next_gate.sub_shape F.[1-5] + options array.
+// ---------------------------------------------------------------------------
+(function test7_nextGateShape() {
+  const label = 'every envelope contains next_gate.sub_shape matching /^F\\.[1-5]$/ and options array';
+  try {
+    const re = /^F\.[1-5]$/;
+    const envs = [
+      wrapDirective(null, {}),
+      wrapDirective({ text: 'r' }, {}),
+      wrapDirective({ text: 'r' }, { user_said_just_tell_me: true }),
+      wrapDirective({ text: 'r' }, { session_count: 9, room_mature: true, in_commit_phase: true }),
+    ];
+    for (const env of envs) {
+      assert.ok(env.next_gate && typeof env.next_gate === 'object', 'next_gate must be an object');
+      assert.ok(re.test(env.next_gate.sub_shape),
+        'next_gate.sub_shape must match F.[1-5]; got ' + env.next_gate.sub_shape);
+      assert.ok(Array.isArray(env.next_gate.options),
+        'next_gate.options must be an array');
+    }
+    ok(label);
+  } catch (err) { fail(label, err); }
+})();
+
+// ---------------------------------------------------------------------------
+// Test 8: selectMode returns GUIDED by default with no signals.
+// ---------------------------------------------------------------------------
+(function test8_selectModeDefault() {
+  const label = 'selectMode({}) returns mode=GUIDED by default (DEFAULT_MODE invariant)';
+  try {
+    const r = selectMode({});
+    assert.ok(r && typeof r === 'object', 'selectMode must return an object');
+    assert.equal(r.mode, 'GUIDED', 'default selectMode mode must be GUIDED; got ' + r.mode);
+    assert.ok(typeof r.rationale === 'string' && r.rationale.length > 0,
+      'rationale must be a non-empty string');
+    // Non-object input must be treated as empty signals (closed vocabulary).
+    const r2 = selectMode(null);
+    assert.equal(r2.mode, 'GUIDED', 'selectMode(null) must default to GUIDED');
+    const r3 = selectMode(undefined);
+    assert.equal(r3.mode, 'GUIDED', 'selectMode(undefined) must default to GUIDED');
+    const r4 = selectMode('string');
+    assert.equal(r4.mode, 'GUIDED', 'selectMode(non-object) must default to GUIDED');
+    ok(label);
+  } catch (err) { fail(label, err); }
+})();
+
+// ---------------------------------------------------------------------------
+// Test 9: DEFAULT_MODE constant exported and locked to 'GUIDED'.
+// ---------------------------------------------------------------------------
+(function test9_defaultModeConstant() {
+  const label = 'DEFAULT_MODE constant exported and === "GUIDED" (Larry pedagogical canon lock)';
+  try {
+    assert.equal(DEFAULT_MODE, 'GUIDED',
+      'DEFAULT_MODE must be exported and equal "GUIDED"; got ' + DEFAULT_MODE);
+    assert.equal(typeof DEFAULT_MODE, 'string', 'DEFAULT_MODE must be a string');
+    ok(label);
+  } catch (err) { fail(label, err); }
+})();
+
+// ---------------------------------------------------------------------------
+// Summary.
+// ---------------------------------------------------------------------------
+process.stdout.write('\n');
+process.stdout.write('PASSED: ' + passed + '\n');
+process.stdout.write('FAILED: ' + failed + '\n');
+process.exit(failed === 0 ? 0 : 1);