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

package/lib/memory/help-coverage.test.cjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 121.5-07 Task 2 -- help-coverage CI guard tests.
+ *
+ * Test map (4 cases, PLAN Task 2 <behavior> Tests 10-13):
+ *
+ *   10. scripts/check-help-coverage.cjs exits 0 against live repo.
+ *   11. Synthetic fixture: temp command without help_jtbd -> exit 1.
+ *   12. Synthetic fixture: command file exists but NOT in help-groups.json
+ *       (and not admin) -> exit 1.
+ *   13. Infrastructure group contains "doctor" (closes Cluster 5 audit
+ *       finding -- doctor was previously silently absent from help.md).
+ *
+ * Canon Part 3 (UI Ruling System), Part 7 (Reuse Before Build), Part 8
+ * (Graph Boundary).
+ */
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const REPO = path.resolve(__dirname, '..', '..');
+const CHECKER = path.join(REPO, 'scripts', 'check-help-coverage.cjs');
+const GROUPS_PATH = path.join(REPO, 'data', 'help-groups.json');
+const COMMANDS_DIR = path.join(REPO, 'commands');
+
+let passed = 0;
+let failed = 0;
+const failures = [];
+
+function run(name, fn) {
+  try {
+    fn();
+    console.log('  PASS  ' + name);
+    passed++;
+  } catch (err) {
+    console.error('  FAIL  ' + name);
+    console.error('        ' + (err.message || err));
+    failed++;
+    failures.push(name);
+  }
+}
+
+// --- Test 10: live repo passes ---
+run('Test 10: check-help-coverage.cjs exits 0 against live repo', () => {
+  assert.ok(fs.existsSync(CHECKER), 'scripts/check-help-coverage.cjs must exist');
+  const r = spawnSync('node', [CHECKER], { encoding: 'utf8' });
+  assert.equal(r.status, 0, 'expected exit 0, got ' + r.status + '\nstdout:' + r.stdout + '\nstderr:' + r.stderr);
+});
+
+// --- Test 11: synthetic fixture without help_jtbd -> exit 1 ---
+run('Test 11: command without help_jtbd causes exit 1', () => {
+  // Create a temp commands/foo.md without help_jtbd; the checker exits 1.
+  const tmpName = '___coverage_tmp_no_jtbd.md';
+  const tmpPath = path.join(COMMANDS_DIR, tmpName);
+  const content = '---\nname: tmp-no-jtbd\ndescription: temp fixture\n---\n# tmp\n';
+  fs.writeFileSync(tmpPath, content);
+  try {
+    const r = spawnSync('node', [CHECKER], { encoding: 'utf8' });
+    assert.notEqual(r.status, 0, 'expected non-zero exit (missing help_jtbd)');
+    assert.ok(/help_jtbd/i.test(r.stdout + r.stderr), 'expected diagnostic mentioning help_jtbd');
+  } finally {
+    fs.unlinkSync(tmpPath);
+  }
+});
+
+// --- Test 12: synthetic fixture file present but not in groups -> exit 1 ---
+run('Test 12: command file not in help-groups.json causes exit 1', () => {
+  const tmpName = '___coverage_tmp_no_group.md';
+  const tmpPath = path.join(COMMANDS_DIR, tmpName);
+  // Has help_jtbd but is NOT in data/help-groups.json AND not admin.
+  const content =
+    '---\nname: tmp-no-group\ndescription: temp fixture\nhelp_jtbd: "Test fixture command without a group."\n---\n# tmp\n';
+  fs.writeFileSync(tmpPath, content);
+  try {
+    const r = spawnSync('node', [CHECKER], { encoding: 'utf8' });
+    assert.notEqual(r.status, 0, 'expected non-zero exit (missing from groups)');
+    assert.ok(
+      /help-groups\.json|MISSING from help-groups/i.test(r.stdout + r.stderr),
+      'expected diagnostic mentioning help-groups.json'
+    );
+  } finally {
+    fs.unlinkSync(tmpPath);
+  }
+});
+
+// --- Test 13: Infrastructure group contains doctor ---
+run('Test 13: Infrastructure group contains doctor (Cluster 5 audit closed)', () => {
+  const groups = JSON.parse(fs.readFileSync(GROUPS_PATH, 'utf8'));
+  const infra = groups.groups.find((g) => g.id === 'infrastructure');
+  assert.ok(infra, 'infrastructure group must exist');
+  assert.ok(infra.commands.includes('doctor'), 'Infrastructure must contain doctor');
+});
+
+console.log('');
+console.log('passed=' + passed + ' failed=' + failed);
+if (failed > 0) {
+  console.error('Failed tests:');
+  for (const t of failures) console.error('  - ' + t);
+  process.exit(1);
+}
+process.exit(0);

package/lib/memory/help-renderer.test.cjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 121.5-07 Task 2 -- help-renderer + help-groups.json tests.
+ *
+ * Test map (6 cases, one-to-one with PLAN Task 2 <behavior> Tests 1-6):
+ *
+ *   1. data/help-groups.json parses; groups[] has 11 entries.
+ *   2. Each group entry has {id, label, glyph, commands: []}.
+ *   3. Every commands/*.md (non-admin) appears in EXACTLY one group's commands[].
+ *   4. renderHelp({capability: 'truecolor'}) emits 24-bit ANSI escapes.
+ *   5. renderHelp({capability: 'ascii'}) emits zero \x1b escape sequences.
+ *   6. renderHelp({capability: 'ascii'}) contains sentinel glyphs for each
+ *      of the 11 groups (proves all groups render in ASCII mode).
+ *
+ * Canon Part 3 (UI Ruling System), Part 7 (Reuse Before Build), Part 8
+ * (Graph Boundary -- filesystem only, no network, no Brain, no telemetry).
+ */
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REPO = path.resolve(__dirname, '..', '..');
+const GROUPS_PATH = path.join(REPO, 'data', 'help-groups.json');
+const RENDERER_PATH = path.join(REPO, 'scripts', 'help-renderer.cjs');
+const COMMANDS_DIR = path.join(REPO, 'commands');
+
+let passed = 0;
+let failed = 0;
+const failures = [];
+
+function run(name, fn) {
+  try {
+    fn();
+    console.log('  PASS  ' + name);
+    passed++;
+  } catch (err) {
+    console.error('  FAIL  ' + name);
+    console.error('        ' + (err.message || err));
+    failed++;
+    failures.push(name);
+  }
+}
+
+// --- Test 1: data/help-groups.json parses + 11 groups ---
+run('Test 1: data/help-groups.json parses; groups[] has 11 entries', () => {
+  assert.ok(fs.existsSync(GROUPS_PATH), 'data/help-groups.json must exist');
+  const groups = JSON.parse(fs.readFileSync(GROUPS_PATH, 'utf8'));
+  assert.ok(Array.isArray(groups.groups), 'groups must be array');
+  assert.equal(groups.groups.length, 11, 'expected 11 groups, got ' + groups.groups.length);
+});
+
+// --- Test 2: each group has required keys ---
+run('Test 2: each group has {id, label, glyph, commands: []}', () => {
+  const groups = JSON.parse(fs.readFileSync(GROUPS_PATH, 'utf8'));
+  for (const g of groups.groups) {
+    assert.ok(typeof g.id === 'string' && g.id.length > 0, 'group.id missing: ' + JSON.stringify(g));
+    assert.ok(typeof g.label === 'string' && g.label.length > 0, 'group.label missing: ' + g.id);
+    assert.ok(typeof g.glyph === 'string' && g.glyph.length > 0, 'group.glyph missing: ' + g.id);
+    assert.ok(Array.isArray(g.commands), 'group.commands not array: ' + g.id);
+  }
+});
+
+// --- Test 3: every non-admin command appears in exactly one group ---
+run('Test 3: every non-admin command appears in exactly one group', () => {
+  const groups = JSON.parse(fs.readFileSync(GROUPS_PATH, 'utf8'));
+  const deprecated = new Set(
+    Object.keys(groups.deprecated_aliases || {}).filter((k) => !k.startsWith('_'))
+  );
+
+  // Build seen-count map.
+  const seen = new Map();
+  for (const g of groups.groups) {
+    for (const c of g.commands) {
+      seen.set(c, (seen.get(c) || 0) + 1);
+    }
+  }
+
+  // Every command file (non-admin) must be in exactly one group OR deprecated.
+  const files = fs.readdirSync(COMMANDS_DIR).filter((f) => f.endsWith('.md'));
+  const errors = [];
+  for (const f of files) {
+    const name = f.replace(/\.md$/, '');
+    const text = fs.readFileSync(path.join(COMMANDS_DIR, f), 'utf8');
+    const fm = text.match(/^---\n([\s\S]*?)\n---/);
+    let visibility = 'user';
+    if (fm) {
+      const vm = fm[1].match(/^visibility:\s*(\S+)/m);
+      if (vm) visibility = vm[1];
+    }
+    if (visibility === 'admin') {
+      // admin commands may be in Infrastructure group or absent; allowed either way.
+      continue;
+    }
+    if (deprecated.has(name)) continue;
+    const count = seen.get(name) || 0;
+    if (count === 0) errors.push(name + ' (missing from all groups)');
+    if (count > 1) errors.push(name + ' (appears in ' + count + ' groups)');
+  }
+  assert.deepEqual(errors, [], 'command-group violations: ' + errors.join(', '));
+});
+
+// --- Test 4: truecolor render emits ANSI ---
+run('Test 4: renderHelp({capability: truecolor}) emits 24-bit ANSI', () => {
+  assert.ok(fs.existsSync(RENDERER_PATH), 'scripts/help-renderer.cjs must exist');
+  const { renderHelp } = require(RENDERER_PATH);
+  const out = renderHelp({ capability: 'truecolor' });
+  assert.ok(out.length > 100, 'output too short');
+  // Look for 24-bit truecolor escape pattern: ESC[38;2;R;G;Bm
+  assert.ok(/\x1b\[38;2;\d+;\d+;\d+m/.test(out), 'no 24-bit ANSI escape found');
+});
+
+// --- Test 5: ascii render has zero ANSI ---
+run('Test 5: renderHelp({capability: ascii}) emits zero \\x1b escapes', () => {
+  const { renderHelp } = require(RENDERER_PATH);
+  const out = renderHelp({ capability: 'ascii' });
+  assert.ok(out.length > 100, 'output too short');
+  assert.ok(!/\x1b/.test(out), 'ASCII output contains \\x1b escape');
+});
+
+// --- Test 6: ASCII output renders all 11 group labels ---
+run('Test 6: ASCII render contains all 11 group labels', () => {
+  const { renderHelp, loadGroups } = require(RENDERER_PATH);
+  const groups = loadGroups();
+  const out = renderHelp({ capability: 'ascii', groups });
+  for (const g of groups.groups) {
+    assert.ok(
+      out.includes(g.label),
+      'ASCII output missing group label "' + g.label + '"'
+    );
+  }
+});
+
+console.log('');
+console.log('passed=' + passed + ' failed=' + failed);
+if (failed > 0) {
+  console.error('Failed tests:');
+  for (const t of failures) console.error('  - ' + t);
+  process.exit(1);
+}
+process.exit(0);

package/lib/memory/mos-status-renderer.test.cjs

@@ -37,7 +37,7 @@
  *   6.  --stale-only flag: renders only stale sections + summary.
  *   7.  <section> argument: renders that section's full triple (not truncated).
  *   8.  Missing room: prints "no active room; /mos:rooms to list" + exit 0.
- *   9.  Zero external network: no fetch/http/brain.mindrian.ai strings in the
+ *   9.  Zero external network: no fetch/http/mindrian-brain.onrender.com strings in the
  *       renderer source.
  *  10.  Shape E zones present: header + rows + summary + actions.
  *  11.  Warm-cache path: if statusline-cache has fresh data for the section,
@@ -468,7 +468,7 @@ assert.equal(
   const src = fs.readFileSync(RENDERER, 'utf8');
   // Canon Part 8: the renderer must be strictly LOCAL.
   const forbidden = [
-    'brain.mindrian.ai',
+    'mindrian-brain.onrender.com',
     'http://',
     'https://',
     'require(\'node:http\')',

package/lib/memory/navigation-engine-core.test.cjs

@@ -639,7 +639,7 @@ if (engineLoadable()) {
   run('Test 29: FORBIDDEN Brain network calls (grep)', () => {
     const src = fs.readFileSync(ENGINE_PATH, 'utf8');
     // Forbidden: brain-client.query / search / smartSearch and any direct
-    // network egress to brain.mindrian.ai or fetch/curl for Brain.
+    // network egress to mindrian-brain.onrender.com or fetch/curl for Brain.
     const reBad = /brain[-_]?client\s*\.\s*(query|search|smartSearch)\b|brain\.mindrian\.ai|\bfetch\s*\(|\bcurl\b/;
     // Allow brain-client.isAvailable and brain-client.schema (Section 9.3).
     // Strip those allowed calls before scanning.

package/lib/memory/palette-consistency.test.cjs

@@ -0,0 +1,127 @@
+// palette-consistency.test.cjs -- Phase 121.5-03 Task 1
+//
+// Tests for references/visual/palette.json + scripts/check-palette-consistency.cjs.
+//
+// 5 tests: schema, hex format, live-repo check, fixture violation, derived_files paths.
+//
+// No emoji. No em-dashes.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const REPO_ROOT = path.join(__dirname, '..', '..');
+const PALETTE_PATH = path.join(REPO_ROOT, 'references', 'visual', 'palette.json');
+const CHECKER_PATH = path.join(REPO_ROOT, 'scripts', 'check-palette-consistency.cjs');
+
+const checker = require(CHECKER_PATH);
+
+let passed = 0;
+let failed = 0;
+
+function ok(name) {
+  console.log('  ok   ' + name);
+  passed++;
+}
+function fail(name, msg) {
+  console.error('  FAIL ' + name + (msg ? ' -- ' + msg : ''));
+  failed++;
+}
+
+function assert(cond, name, msg) {
+  if (cond) ok(name);
+  else fail(name, msg);
+}
+
+console.log('test palette-consistency');
+
+// Test 1: palette.json parses; required tiers present.
+let palette;
+try {
+  palette = JSON.parse(fs.readFileSync(PALETTE_PATH, 'utf8'));
+  const hasAll = palette.base && palette.palette_a_discovery && palette.palette_b_build &&
+                 palette.ansi_5_color && Array.isArray(palette.derived_files);
+  assert(hasAll, 'test1 schema -- base, palette_a, palette_b, ansi_5, derived_files all present');
+} catch (e) {
+  fail('test1 schema -- parse error: ' + e.message);
+}
+
+// Test 2: Every hex value matches /^#[0-9a-f]{6}$/i.
+try {
+  const tiers = [palette.base, palette.palette_a_discovery, palette.palette_b_build, palette.extended || {}];
+  let bad = null;
+  for (const t of tiers) {
+    if (!t) continue;
+    for (const k of Object.keys(t)) {
+      const v = t[k];
+      if (typeof v === 'string' && !/^#[0-9a-f]{6}$/i.test(v)) {
+        bad = k + ' = ' + v;
+        break;
+      }
+    }
+    if (bad) break;
+  }
+  assert(bad === null, 'test2 hex format -- every hex matches /^#[0-9a-f]{6}$/i', bad);
+} catch (e) {
+  fail('test2 hex format', e.message);
+}
+
+// Test 3: check() exits valid against the live repo (or at least returns
+// a structured result with no stray hex from derived files that exist).
+try {
+  const result = checker.check();
+  // The check() may have violations if Task 2 hasn't wired consumers yet -- that
+  // is acceptable for Task 1 alone; we assert that the result is well-structured.
+  const ok1 = typeof result === 'object' && typeof result.valid === 'boolean' &&
+              Array.isArray(result.violations) && typeof result.canonical_count === 'number';
+  assert(ok1, 'test3 live-repo check -- check() returns structured result');
+  // Smoke test: canonical_count is at least 9 (the base tier alone has 9 keys).
+  assert(result.canonical_count >= 9, 'test3b live-repo check -- canonical_count >= 9');
+} catch (e) {
+  fail('test3 live-repo check', e.message);
+}
+
+// Test 4: Synthetic fixture with stray hex returns violations.length >= 1.
+try {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'palette-test-'));
+  const fakeFile = path.join(tmpDir, 'fake-consumer.css');
+  fs.writeFileSync(fakeFile, ':root { --not-canon: #abcdef; }');
+  // Build synthetic palette referencing this fake file via absolute path
+  // (relative-to-repo trick: place fixture under a known subpath).
+  // Instead use the in-process checker on a synthesized text directly.
+  const hexes = checker.hexesFromText(':root { --not-canon: #abcdef; --canon: #A63D2F; }');
+  const found1 = hexes.has('#abcdef');
+  const found2 = hexes.has('#a63d2f');
+  assert(found1 && found2, 'test4 fixture -- hexesFromText finds both canonical + non-canonical');
+  // Build a canonical set + check membership directly.
+  const canon = checker.collectCanonical(palette);
+  assert(canon.has('#a63d2f') && !canon.has('#abcdef'),
+    'test4b fixture -- canonical set contains shipped red, not the synthetic non-canon hex');
+  // Clean up tmp dir
+  try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch (_) {}
+} catch (e) {
+  fail('test4 fixture', e.message);
+}
+
+// Test 5: derived_files entries point to files (or skip gracefully).
+try {
+  const derived = palette.derived_files;
+  assert(Array.isArray(derived) && derived.length > 0,
+    'test5 derived_files -- non-empty array');
+  // At least one of the derived files must exist on disk.
+  const existCount = derived.filter(function(e) {
+    return fs.existsSync(path.join(REPO_ROOT, e.path));
+  }).length;
+  assert(existCount > 0,
+    'test5b derived_files -- at least one file exists on disk');
+} catch (e) {
+  fail('test5 derived_files', e.message);
+}
+
+// Summary
+console.log('');
+console.log('palette-consistency.test: ' + passed + ' passed, ' + failed + ' failed');
+if (failed > 0) process.exit(1);
+process.exit(0);

package/lib/memory/pending-tension-store.cjs

@@ -37,6 +37,29 @@ const crypto = require('node:crypto');
 // ---------- Constants ----------
 
 const PENDING_TENSIONS_DIR = path.join(os.homedir(), '.mindrian', 'pending-tensions');
+
+// Phase 121-02 D-05: tension_engagement emit support. Maps the local Phase 116
+// last_response vocabulary {RESOLVE, LATER, SKIP, DROPPED} -> the unified
+// telemetry user_response enum {resolve, defer, ignore}. DROPPED is system-
+// driven (3-strikes decay or explicit drop) and is intentionally excluded so
+// only user-initiated transitions ever land in the unified stream.
+const USER_RESPONSE_MAP = Object.freeze({
+  RESOLVE: 'resolve',
+  LATER: 'defer',
+  SKIP: 'ignore',
+});
+
+// Map Phase 116 tension_type vocabulary -> unified telemetry enum.
+//   contradiction   -> contradicts
+//   convergence     -> converges
+//   stale_decision  -> invalidates  (a stale decision invalidates its premise)
+//   open_question   -> invalidates  (an open question invalidates closure)
+const TENSION_TYPE_MAP = Object.freeze({
+  contradiction: 'contradicts',
+  convergence: 'converges',
+  stale_decision: 'invalidates',
+  open_question: 'invalidates',
+});
 const VALID_STATES = Object.freeze(new Set(['queued', 'surfaced', 'resolved', 'dropped']));
 const VALID_TYPES = Object.freeze(new Set([
   'contradiction',
@@ -220,6 +243,58 @@ function markSurfaced(roomSlug, tension_id) {
   return { ok: true, surfacing_count: next.surfacing_count };
 }
 
+/**
+ * Phase 121-02 D-05: capture user engagement with surfaced tensions into the
+ * unified ~/.mindrian/telemetry/v1.13/events-YYYY-WNN.jsonl stream (Plan 121-00
+ * writer chokepoint). Emit ONLY on user-initiated state transitions
+ * (RESOLVE -> resolve, LATER -> defer, SKIP -> ignore). Decayed tensions
+ * (system-driven 3-strikes via evaluateAndDecay or explicit markDropped) are
+ * NOT engagement events and intentionally do NOT emit.
+ *
+ * Non-blocking: try/catch wraps every step. A Canon Part 8 forbidden-pattern
+ * rejection in the writer never crashes the markResolved transition; the
+ * JSONL state append has already succeeded by the time we emit.
+ *
+ * TTR: time from last_surfaced_at -> now. Floor at 0; integer seconds.
+ * Context hash: 16-char sha256 of context_signature.focus_node_id (or empty).
+ */
+function emitTensionEngagementUnified(roomSlug, prev, response) {
+  try {
+    if (!USER_RESPONSE_MAP[response]) return; // system-driven; do not emit
+    let writer;
+    try {
+      writer = require('../core/telemetry/writer.cjs');
+    } catch (_e) {
+      return; // missing writer module; soft skip
+    }
+    if (!writer || typeof writer.emit !== 'function') return;
+    const tensionType = TENSION_TYPE_MAP[prev && prev.type] || 'invalidates';
+    const surfacedAt = (prev && Number.isFinite(prev.last_surfaced_at))
+      ? Number(prev.last_surfaced_at)
+      : 0;
+    const ttrSeconds = surfacedAt > 0
+      ? Math.max(0, Math.round((Date.now() - surfacedAt) / 1000))
+      : 0;
+    // Hash the focus node id (or any context_signature field) to a 16-char
+    // sha256 prefix; never the raw scalar.
+    let contextSrc = '';
+    if (prev && isPlainObject(prev.context_signature)) {
+      contextSrc = String(prev.context_signature.focus_node_id || prev.context_signature.context_id || '');
+    }
+    const contextHash = crypto.createHash('sha256').update(contextSrc).digest('hex').slice(0, 16);
+    const slugHash = crypto.createHash('sha256').update(String(roomSlug || '')).digest('hex');
+    writer.emit('tension_engagement', {
+      tension_type: String(tensionType).slice(0, 64),
+      user_response: USER_RESPONSE_MAP[response],
+      ttr_seconds: ttrSeconds,
+      room_slug_sha256: slugHash,
+      context_hash: contextHash,
+    });
+  } catch (_e) {
+    // Swallow: telemetry MUST never crash the tension transition.
+  }
+}
+
 /**
  * Mark a tension as resolved with a user response. State -> 'resolved'.
  *
@@ -239,6 +314,11 @@ function markResolved(roomSlug, tension_id, response) {
   });
   const r = appendTension(roomSlug, next);
   if (!r.ok) return r;
+  // Phase 121-02 D-05: emit only AFTER the JSONL state append succeeds. The
+  // emit is gated on USER_RESPONSE_MAP (RESOLVE/LATER/SKIP) so DROPPED falls
+  // through silently. This is the load-bearing exclusion: decayed tensions
+  // are system-driven and must not count as engagement.
+  emitTensionEngagementUnified(roomSlug, prev, response);
   return { ok: true };
 }