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

package/lib/memory/doctor-deprecation-surface.test.cjs

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+/*
+ * Phase 121.5-08 Plan Task 2 -- doctor class I (deprecated-usage surface)
+ * + F.1 selector wiring on onboard Step 6 + diagnose recommendation.
+ *
+ * Behavior contract (per plan):
+ *   T1: scripts/doctor.cjs --deprecated-usage detects synthetic usage in temp
+ *       transcript fixtures (a temp ~/.claude/projects/.../session.jsonl-like
+ *       fixture mentioning "/mos:heal" -- the class I detector picks it up).
+ *   T2: Class I returns {class: 'I', status, action, deprecated_uses: []}.
+ *   T3: --deprecated-usage exits 0 when no deprecated commands used; exits 1
+ *       when violations found.
+ *   T4: doctor --all includes class I in the cascade.
+ *   T5: commands/onboard.md Step 6 body contains the canonical F.1 selector
+ *       vocabulary (Run Methodology / Defer / Free-Text).
+ *   T6: commands/diagnose.md recommendation block contains the canonical F.1
+ *       selector vocabulary.
+ *   T7: CHANGELOG.md has an Unreleased / next-beta entry listing all 5
+ *       renames + the /mos:mos creation + the F.1 wiring + the class I add.
+ *
+ * Hermetic: uses fs.mkdtempSync for synthetic transcript fixture (T1). The
+ * doctor invocation spawns scripts/doctor.cjs as a subprocess with the
+ * fixture dir bound via MINDRIAN_DOCTOR_TRANSCRIPTS_DIR.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const cp = require('child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const DOCTOR_CJS = path.join(REPO_ROOT, 'scripts', 'doctor.cjs');
+
+let pass = 0;
+let fail = 0;
+const failures = [];
+
+function assert(cond, name, detail) {
+  if (cond) {
+    pass++;
+    console.log('PASS  ' + name);
+  } else {
+    fail++;
+    failures.push(name + (detail ? ' -- ' + detail : ''));
+    console.log('FAIL  ' + name + (detail ? ' -- ' + detail : ''));
+  }
+}
+
+// --- T1 + T2 + T3 (positive): synthesize a fixture transcript dir with
+// "/mos:heal" usage; --deprecated-usage detects + exits 1 + returns class I.
+{
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'doctor-deprec-'));
+  const sessionDir = path.join(tmpRoot, 'sessions', 'fake-project-hash');
+  fs.mkdirSync(sessionDir, { recursive: true });
+  const jsonlPath = path.join(sessionDir, 'session-abc.jsonl');
+  // Recent mtime (now). Per implementation contract: scan last 7 days.
+  const fixture = JSON.stringify({ role: 'user', content: 'let me run /mos:heal here' }) + '\n'
+                + JSON.stringify({ role: 'user', content: 'now /mos:query something' }) + '\n';
+  fs.writeFileSync(jsonlPath, fixture);
+  const now = Date.now();
+  fs.utimesSync(jsonlPath, new Date(now), new Date(now));
+
+  const r = cp.spawnSync('node', [DOCTOR_CJS, '--deprecated-usage', '--json'], {
+    encoding: 'utf8',
+    env: Object.assign({}, process.env, { MINDRIAN_DOCTOR_TRANSCRIPTS_DIR: tmpRoot }),
+    timeout: 30000,
+  });
+  // Parse JSON envelope
+  let envelope = null;
+  if (r.stdout) {
+    const start = r.stdout.indexOf('{');
+    if (start >= 0) {
+      try { envelope = JSON.parse(r.stdout.slice(start)); } catch (_) { envelope = null; }
+    }
+  }
+  assert(envelope !== null, 'T1: --deprecated-usage emits parseable JSON', (r.stdout || '').slice(0, 300));
+  const cls = envelope && envelope.checks && envelope.checks['deprecated-usage'];
+  assert(cls !== undefined && cls !== null, 'T1: report.checks["deprecated-usage"] exists', JSON.stringify(envelope && envelope.checks));
+  if (cls) {
+    assert(cls.class === 'L', 'T2: class==="L"', cls.class);
+    assert(typeof cls.status === 'string', 'T2: status is a string', cls.status);
+    assert(typeof cls.action === 'string', 'T2: action is a string', cls.action);
+    assert(Array.isArray(cls.deprecated_uses), 'T2: deprecated_uses is array', JSON.stringify(cls.deprecated_uses));
+    assert(cls.deprecated_uses.length >= 2, 'T1: detected at least 2 deprecated uses (heal + query)', JSON.stringify(cls.deprecated_uses));
+    const found = cls.deprecated_uses.map(function (x) { return x.deprecated; }).sort();
+    assert(found.indexOf('/mos:heal') >= 0, 'T1: /mos:heal detected', JSON.stringify(found));
+    assert(found.indexOf('/mos:query') >= 0, 'T1: /mos:query detected', JSON.stringify(found));
+    assert(cls.status === 'DEPRECATED_USAGE' || cls.status === 'warn', 'T2: status flags violation', cls.status);
+  }
+  // Cleanup
+  try { fs.rmSync(tmpRoot, { recursive: true, force: true }); } catch (_) {}
+}
+
+// --- T3 negative: no transcripts -> --deprecated-usage clean.
+{
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'doctor-deprec-clean-'));
+  const r = cp.spawnSync('node', [DOCTOR_CJS, '--deprecated-usage', '--json'], {
+    encoding: 'utf8',
+    env: Object.assign({}, process.env, { MINDRIAN_DOCTOR_TRANSCRIPTS_DIR: tmpRoot }),
+    timeout: 30000,
+  });
+  let envelope = null;
+  if (r.stdout) {
+    const start = r.stdout.indexOf('{');
+    if (start >= 0) { try { envelope = JSON.parse(r.stdout.slice(start)); } catch (_) {} }
+  }
+  const cls = envelope && envelope.checks && envelope.checks['deprecated-usage'];
+  assert(cls && cls.status === 'OK', 'T3: status === OK with no deprecated usage', cls && cls.status);
+  assert(cls && cls.deprecated_uses && cls.deprecated_uses.length === 0, 'T3: deprecated_uses is empty array');
+  // Per spec: --deprecated-usage exits 0 when clean.
+  assert(r.status === 0, 'T3: exit 0 when clean', String(r.status));
+  try { fs.rmSync(tmpRoot, { recursive: true, force: true }); } catch (_) {}
+}
+
+// --- T4: --all activates --deprecated-usage in the cascade.
+{
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'doctor-deprec-all-'));
+  const r = cp.spawnSync('node', [DOCTOR_CJS, '--all', '--json'], {
+    encoding: 'utf8',
+    env: Object.assign({}, process.env, { MINDRIAN_DOCTOR_TRANSCRIPTS_DIR: tmpRoot }),
+    timeout: 60000,
+  });
+  let envelope = null;
+  if (r.stdout) {
+    const start = r.stdout.indexOf('{');
+    if (start >= 0) { try { envelope = JSON.parse(r.stdout.slice(start)); } catch (_) {} }
+  }
+  const cls = envelope && envelope.checks && envelope.checks['deprecated-usage'];
+  assert(cls !== undefined && cls !== null, 'T4: --all includes deprecated-usage in cascade', JSON.stringify(envelope && envelope.checks ? Object.keys(envelope.checks) : null));
+  try { fs.rmSync(tmpRoot, { recursive: true, force: true }); } catch (_) {}
+}
+
+// --- T5: commands/onboard.md Step 6 has F.1 selector vocabulary.
+{
+  const onboardPath = path.join(REPO_ROOT, 'commands', 'onboard.md');
+  const body = fs.readFileSync(onboardPath, 'utf8');
+  // Locate Step 6 region for verification (the test asserts the F.1 lives
+  // inside or in the vicinity of Step 6, not just anywhere in the file).
+  const step6Idx = body.indexOf('## Step 6');
+  assert(step6Idx > 0, 'T5: Step 6 section exists', String(step6Idx));
+  // The whole step-6 region (from Step 6 to end of file or next ##)
+  const rest = body.slice(step6Idx);
+  const nextStep = rest.indexOf('\n## ', 5);
+  const step6Region = nextStep > 0 ? rest.slice(0, nextStep) : rest;
+  assert(/F\.1/.test(step6Region), 'T5: Step 6 mentions F.1', step6Region.slice(0, 400));
+  assert(/Run Methodology/.test(step6Region), 'T5: Step 6 has "Run Methodology" verb');
+  assert(/Defer/.test(step6Region), 'T5: Step 6 has "Defer" verb');
+  assert(/Free-Text/.test(step6Region), 'T5: Step 6 has "Free-Text" verb');
+  assert(step6Region.indexOf('—') < 0, 'T5: Step 6 region has no em-dash');
+}
+
+// --- T6: commands/diagnose.md recommendation has F.1 selector vocabulary.
+{
+  const diagPath = path.join(REPO_ROOT, 'commands', 'diagnose.md');
+  const body = fs.readFileSync(diagPath, 'utf8');
+  assert(/F\.1/.test(body), 'T6: diagnose.md mentions F.1');
+  assert(/Run Methodology/.test(body), 'T6: diagnose.md has "Run Methodology" verb');
+  assert(/Defer/.test(body), 'T6: diagnose.md has "Defer" verb');
+  assert(/Free-Text/.test(body), 'T6: diagnose.md has "Free-Text" verb');
+  assert(body.indexOf('—') < 0, 'T6: diagnose.md has no em-dash');
+}
+
+// --- T7: CHANGELOG.md entry for Phase 121.5-08 covers all 5 renames + /mos:mos + F.1.
+{
+  const cl = fs.readFileSync(path.join(REPO_ROOT, 'CHANGELOG.md'), 'utf8');
+  assert(/Phase 121\.5-08/.test(cl), 'T7: CHANGELOG mentions Phase 121.5-08');
+  assert(/heal/i.test(cl), 'T7: CHANGELOG mentions heal rename');
+  assert(/query/i.test(cl), 'T7: CHANGELOG mentions query rename');
+  assert(/organize/i.test(cl), 'T7: CHANGELOG mentions organize rename');
+  assert(/hmi-status/i.test(cl), 'T7: CHANGELOG mentions hmi-status rename');
+  assert(/visualize/i.test(cl), 'T7: CHANGELOG mentions visualize rename');
+  assert(/\/mos:mos/.test(cl), 'T7: CHANGELOG mentions /mos:mos creation');
+  // F.1 selector wiring announcement
+  assert(/F\.1/.test(cl) || /F.1 selector/.test(cl), 'T7: CHANGELOG mentions F.1 selector wiring');
+}
+
+console.log('');
+console.log('doctor-deprecation-surface.test.cjs: ' + pass + ' passed, ' + fail + ' failed');
+if (fail > 0) {
+  console.log('FAILURES:');
+  for (const f of failures) console.log('  - ' + f);
+  process.exit(1);
+}
+process.exit(0);

package/lib/memory/first-touch-version.test.cjs

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * lib/memory/first-touch-version.test.cjs
+ * ---------------------------------------
+ * Phase 121.5-05 Sub-plan F Task 1 acceptance tests.
+ *
+ * 8 tests covering the first-touch-version-stamper module:
+ *
+ *   1. stampVersion('banner', '1.13.0-beta.15') contains "MindrianOS v1.13.0-beta.15"
+ *   2. stampVersion('splash', '1.13.0') starts with "MindrianOS v1.13.0"
+ *   3. stampVersion('onboard', '1.14.0') embeds "MindrianOS v1.14.0"
+ *   4. stampVersion(<unknown_surface>, version) throws Error('unknown_surface: ...')
+ *   5. stampVersion called without version arg auto-resolves from plugin.json
+ *   6. data/first-touch-surfaces.json parses; surfaces[] length >= 6
+ *   7. hasEmDash(text) returns true on U+2014, false otherwise
+ *   8. scripts/banner output contains "MindrianOS v" + live plugin.json version
+ *
+ * Pure CJS, node built-ins only. No emoji. No em-dashes.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const stamperPath = path.join(REPO_ROOT, 'lib', 'core', 'first-touch-version-stamper.cjs');
+const stamper = require(stamperPath);
+
+let passed = 0;
+let failed = 0;
+const failures = [];
+
+function assert(name, cond, detail) {
+  if (cond) {
+    passed++;
+    console.log('  PASS  ' + name);
+  } else {
+    failed++;
+    failures.push({ name, detail });
+    console.log('  FAIL  ' + name + (detail ? ' :: ' + detail : ''));
+  }
+}
+
+// --- Test 1: banner stamp contains MindrianOS v<version> ----------------
+{
+  const out = stamper.stampVersion('banner', '1.13.0-beta.15');
+  assert(
+    'Test 1: stampVersion(banner, "1.13.0-beta.15") contains "MindrianOS v1.13.0-beta.15"',
+    out.indexOf('MindrianOS v1.13.0-beta.15') >= 0,
+    'got: ' + out,
+  );
+}
+
+// --- Test 2: splash stamp starts with MindrianOS v<version> -------------
+{
+  const out = stamper.stampVersion('splash', '1.13.0');
+  assert(
+    'Test 2: stampVersion(splash, "1.13.0") starts with "MindrianOS v1.13.0"',
+    out.indexOf('MindrianOS v1.13.0') === 0,
+    'got: ' + out,
+  );
+}
+
+// --- Test 3: onboard stamp embeds MindrianOS v<version> -----------------
+{
+  const out = stamper.stampVersion('onboard', '1.14.0');
+  assert(
+    'Test 3: stampVersion(onboard, "1.14.0") embeds "MindrianOS v1.14.0"',
+    out.indexOf('MindrianOS v1.14.0') >= 0,
+    'got: ' + out,
+  );
+}
+
+// --- Test 4: unknown surface throws -------------------------------------
+{
+  let threw = false;
+  let msg = '';
+  try {
+    stamper.stampVersion('not-a-real-surface', '1.0.0');
+  } catch (e) {
+    threw = true;
+    msg = e.message;
+  }
+  assert(
+    'Test 4: stampVersion(unknown_surface) throws Error(unknown_surface: ...)',
+    threw && /^unknown_surface:/.test(msg),
+    'threw=' + threw + ' msg=' + msg,
+  );
+}
+
+// --- Test 5: no version arg -> auto-resolve from plugin.json ------------
+{
+  const pluginJsonPath = path.join(REPO_ROOT, '.claude-plugin', 'plugin.json');
+  const liveVersion = JSON.parse(fs.readFileSync(pluginJsonPath, 'utf8')).version;
+  const out = stamper.stampVersion('banner');
+  assert(
+    'Test 5: stampVersion(banner) auto-resolves version from plugin.json (' + liveVersion + ')',
+    out.indexOf(liveVersion) >= 0,
+    'got: ' + out + ' live=' + liveVersion,
+  );
+}
+
+// --- Test 6: surfaces JSON parses + has >= 6 entries --------------------
+{
+  const surfaces = stamper.readSurfaces();
+  assert(
+    'Test 6: data/first-touch-surfaces.json parses; surfaces[].length >= 6',
+    Array.isArray(surfaces.surfaces) && surfaces.surfaces.length >= 6,
+    'length=' + (surfaces.surfaces ? surfaces.surfaces.length : 'undefined'),
+  );
+
+  // Sanity: each surface has the required keys.
+  const requiredKeys = ['id', 'file', 'kind', 'version_stamp_required', 'em_dash_check'];
+  let allOk = true;
+  let missingDetail = '';
+  for (const s of surfaces.surfaces) {
+    for (const k of requiredKeys) {
+      if (!(k in s)) {
+        allOk = false;
+        missingDetail = 'surface ' + (s.id || '?') + ' missing key ' + k;
+        break;
+      }
+    }
+    if (!allOk) break;
+  }
+  assert(
+    'Test 6b: every surface has id / file / kind / version_stamp_required / em_dash_check',
+    allOk,
+    missingDetail,
+  );
+}
+
+// --- Test 7: hasEmDash detects U+2014 -----------------------------------
+{
+  // U+2014 EM DASH, written via escape so this source stays ASCII-clean.
+  const withDash = 'this has an \u2014 em dash';
+  const withoutDash = 'this has a - hyphen';
+  assert(
+    'Test 7a: hasEmDash returns true on U+2014',
+    stamper.hasEmDash(withDash) === true,
+  );
+  assert(
+    'Test 7b: hasEmDash returns false on plain hyphen',
+    stamper.hasEmDash(withoutDash) === false,
+  );
+  assert(
+    'Test 7c: hasEmDash returns false on non-string',
+    stamper.hasEmDash(null) === false && stamper.hasEmDash(42) === false,
+  );
+}
+
+// --- Test 8: scripts/banner emits "MindrianOS v" + live version ---------
+{
+  const bannerPath = path.join(REPO_ROOT, 'scripts', 'banner');
+  let bannerOut = '';
+  let bannerErr = null;
+  try {
+    bannerOut = execSync('bash ' + JSON.stringify(bannerPath), {
+      cwd: REPO_ROOT,
+      encoding: 'utf8',
+      env: Object.assign({}, process.env, { COLUMNS: '120' }),
+    });
+  } catch (e) {
+    bannerErr = e.message;
+  }
+  const liveVersion = stamper.resolveCurrentVersion();
+  assert(
+    'Test 8a: scripts/banner runs without error',
+    bannerErr === null,
+    bannerErr || '',
+  );
+  assert(
+    'Test 8b: banner output contains "MindrianOS v"',
+    bannerOut.indexOf('MindrianOS v') >= 0,
+    'first 200 chars: ' + bannerOut.slice(0, 200),
+  );
+  assert(
+    'Test 8c: banner output contains the live plugin.json version (' + liveVersion + ')',
+    bannerOut.indexOf(liveVersion) >= 0,
+    'live=' + liveVersion,
+  );
+}
+
+// --- Summary ------------------------------------------------------------
+console.log('');
+console.log('first-touch-version.test.cjs: ' + passed + ' passed, ' + failed + ' failed');
+if (failed > 0) {
+  for (const f of failures) {
+    console.log('  - ' + f.name + (f.detail ? ' :: ' + f.detail : ''));
+  }
+  process.exit(1);
+}
+process.exit(0);

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);