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

package/lib/core/mva-progressive-renderer.cjs

@@ -0,0 +1,194 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 118-03 Plan 03 -- mva-progressive-renderer.
+ *
+ * Pure-function renderer that turns AgentResult shapes into Larry-voiced
+ * GUIDED text blocks. Zero I/O. Zero process / console / fs references.
+ *
+ * Larry voice (per feedback_larry_pedagogical_guided_first.md):
+ *   GUIDED, not AUTONOMOUS. The renderer never says "I've analyzed your
+ *   venture and found:" -- it surfaces what shows up in the graph and
+ *   invites the navigator to chew on it.
+ *
+ * Canon Part 8: this module receives ONLY structured AgentResult objects
+ * (which themselves only carry agent-supplied summary_line / payload).
+ * The renderer does not read the raw sentence; it does not know it exists.
+ *
+ * Em-dash discipline (per feedback_no_emdashes.md): every string emitted
+ * by this module uses `--` and `-` ONLY. The hardcoded footer text is a
+ * module-level constant (NOT loaded from any source markdown at runtime;
+ * source spec contains em-dashes and is not a runtime input).
+ *
+ * The 6 per-agent labels (verbatim from plan task 1 step 3):
+ *   brain_similar       -> [brain]
+ *   brain_cross_domain  -> [analogy]
+ *   brain_classic_traps -> [traps]
+ *   tavily_funding      -> [funding]
+ *   six_hats_red_black  -> [worth chewing on]
+ *   dashboard_graph     -> [your room]
+ *
+ * Pure CJS, no requires (zero deps).
+ */
+'use strict';
+
+// ---------- Frozen invariants ----------
+
+const AGENT_LABELS = Object.freeze({
+  brain_similar: 'brain',
+  brain_cross_domain: 'analogy',
+  brain_classic_traps: 'traps',
+  tavily_funding: 'funding',
+  six_hats_red_black: 'worth chewing on',
+  dashboard_graph: 'your room',
+});
+
+// Verbatim from source spec line 111 + binding decision B7.
+// Note the apostrophe in "didn't" stays as a literal apostrophe; the em-dash
+// in the source spec is rewritten as `--` per feedback_no_emdashes.md.
+const SHARP_QUESTION_FALLBACK = [
+  "I didn't find precedents for this in 30 seconds.",
+  "That's either a gap in my data or a signal that you're in a genuinely unexplored space.",
+  "Which do you think it is?",
+  ''
+].join('\n');
+
+// Hardcoded module-level constant for the 3-option footer (CRITICAL-6).
+// MUST use `--`, NEVER `—`. Plan 118-03 Test 8b asserts both invariants.
+const FOOTER_TEXT = [
+  '',
+  'What now?',
+  '  [1] Just tell me what\'s new         (stay in "tell me" mode)',
+  '  [2] Build a room around this        (invest)',
+  '  [3] Challenge me -- Devil\'s Advocate (go deeper cognitively)',
+  ''
+].join('\n');
+
+// Hebrew refusal block (per LD1). English first, Hebrew second. No em-dashes.
+const HEBREW_REFUSAL = [
+  'MindrianOS does not yet support Hebrew in v1.13.0. Please try in English.',
+  'MindrianOS לא תומך בעברית ב-v1.13.0; אנא נסה באנגלית.',
+  ''
+].join('\n');
+
+// ---------- Pure helpers ----------
+
+function _label(agent_id) {
+  return AGENT_LABELS[agent_id] || agent_id;
+}
+
+function _summaryLine(payload) {
+  if (!payload || typeof payload !== 'object') return '';
+  if (typeof payload.summary_line === 'string') return payload.summary_line;
+  return '';
+}
+
+// ---------- Public exports ----------
+
+/**
+ * renderHeader(sha8) -> 2-line GUIDED opener.
+ *
+ * "Scanning for precedents... (sentence <sha8>)"
+ * "[progress: 0s / 45s, 0 of 6 returned]"
+ */
+function renderHeader(sha8) {
+  const safeSha8 = (typeof sha8 === 'string' && sha8.length > 0) ? sha8 : 'unknown';
+  return [
+    `Scanning for precedents... (sentence ${safeSha8})`,
+    '[progress: 0s / 45s, 0 of 6 returned]',
+    ''
+  ].join('\n');
+}
+
+/**
+ * renderProgressIndicator(elapsedMs, budgetMs, returnedCount) -> single line.
+ *
+ * "  [progress: 12s / 45s, 3 of 6 returned]"
+ */
+function renderProgressIndicator(elapsedMs, budgetMs, returnedCount) {
+  const elapsed = Math.max(0, Math.round((elapsedMs || 0) / 1000));
+  const budget = Math.max(0, Math.round((budgetMs || 0) / 1000));
+  const returned = Math.max(0, returnedCount | 0);
+  return `  [progress: ${elapsed}s / ${budget}s, ${returned} of 6 returned]\n`;
+}
+
+/**
+ * renderAgentResult(result) -> 1-3 line Larry-voiced block based on status.
+ *
+ * Dispatches on result.status:
+ *   ok       -> "  [<label>] <summary_line>"
+ *   empty    -> contextualized placeholder (special-case tavily_unavailable)
+ *   timeout  -> "  [<label>] (still in progress at 45s)"
+ *   error    -> "  [<label>] (skipped)"  (raw error NEVER included verbatim)
+ */
+function renderAgentResult(result) {
+  if (!result || typeof result !== 'object') return '';
+  const id = result.agent_id || 'agent';
+  const label = _label(id);
+  const status = result.status;
+
+  if (status === 'ok') {
+    const line = _summaryLine(result.payload);
+    if (line) {
+      return `  [${label}] ${line}\n`;
+    }
+    return `  [${label}] (no summary returned)\n`;
+  }
+
+  if (status === 'empty') {
+    const reason = result.payload && typeof result.payload === 'object' ? result.payload.reason : null;
+    if (id === 'tavily_funding' && reason === 'tavily_unavailable') {
+      return `  [${label}] Live funding scan: not configured (add TAVILY_API_KEY to ~/.mindrian.env)\n`;
+    }
+    return `  [${label}] (no findings this pass)\n`;
+  }
+
+  if (status === 'timeout') {
+    return `  [${label}] (still in progress at 45s)\n`;
+  }
+
+  if (status === 'error') {
+    // CRITICAL: do NOT include the raw error string verbatim. Canon Part 8.
+    return `  [${label}] (skipped)\n`;
+  }
+
+  return `  [${label}] (unknown status)\n`;
+}
+
+/**
+ * renderSharpQuestionFallback() -> verbatim sharp question from source spec
+ * line 111. Em-dash-free (the source spec's em-dash is rewritten to `--`
+ * by hardcoding the text here).
+ */
+function renderSharpQuestionFallback() {
+  return SHARP_QUESTION_FALLBACK;
+}
+
+/**
+ * renderHebrewRefusal() -> bilingual refusal block. English first, Hebrew
+ * second. No em-dashes. Per LD1 (Locked Decision 1).
+ */
+function renderHebrewRefusal() {
+  return HEBREW_REFUSAL;
+}
+
+/**
+ * renderFooter() -> the 3-option footer block (binding decision B4).
+ *
+ * VERBATIM hardcoded text. MUST use `--`, NEVER `—`. Tested by Test 8b
+ * in mva-progressive-renderer.test.cjs.
+ */
+function renderFooter() {
+  return FOOTER_TEXT;
+}
+
+module.exports = {
+  renderHeader,
+  renderProgressIndicator,
+  renderAgentResult,
+  renderSharpQuestionFallback,
+  renderHebrewRefusal,
+  renderFooter,
+  // Exported for adversarial/golden-fixture tests in Plan 118-06
+  AGENT_LABELS,
+};

package/lib/core/mva-progressive-renderer.test.cjs

@@ -0,0 +1,157 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 118-03 Plan 03 Task 1 -- mva-progressive-renderer tests.
+ *
+ * Verifies that the renderer is a pure-function module (no I/O), emits Larry-voiced
+ * GUIDED text blocks per AgentResult status, hardcodes the 3-option footer with
+ * `--` (not `—`), and complies with Canon Part 8 (zero raw-content access).
+ *
+ * Pure CJS, node built-ins only. Run via `node --test`.
+ */
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const {
+  renderAgentResult,
+  renderSharpQuestionFallback,
+  renderHebrewRefusal,
+  renderHeader,
+  renderProgressIndicator,
+  renderFooter,
+} = require('./mva-progressive-renderer.cjs');
+
+test('renderer Test 1 -- ok agent renders Larry-voiced 1-line summary, em-dash-free', () => {
+  const out = renderAgentResult({
+    agent_id: 'brain_similar',
+    status: 'ok',
+    duration_ms: 12,
+    payload: { summary_line: 'Found 3 ventures in this space: Honeydue (dead), Zeta (alive), Monarch (alive)' }
+  });
+  assert.ok(typeof out === 'string', 'must return a string');
+  assert.ok(out.includes('[brain]'), 'must include brain prefix');
+  assert.ok(out.includes('Found 3 ventures'), 'must include summary_line content');
+  assert.equal(out.match(/—/), null, 'must have no em-dashes');
+  assert.ok(out.endsWith('\n'), 'must end with newline');
+});
+
+test('renderer Test 2 -- timeout status renders progress placeholder', () => {
+  const out = renderAgentResult({
+    agent_id: 'brain_similar',
+    status: 'timeout',
+    duration_ms: 45000,
+  });
+  assert.ok(out.includes('[brain]'), 'must include label');
+  assert.ok(/still/i.test(out), 'must indicate still-in-progress');
+  assert.equal(out.match(/—/), null, 'no em-dashes');
+});
+
+test('renderer Test 3 -- error status renders skipped placeholder, sanitized', () => {
+  const out = renderAgentResult({
+    agent_id: 'brain_classic_traps',
+    status: 'error',
+    duration_ms: 50,
+    error: 'this is a very long error message that should never reach the user via the rendered output and certainly not unsanitized for very long lengths'
+  });
+  assert.ok(out.includes('[traps]'), 'must include label');
+  assert.ok(/skipped/i.test(out), 'must indicate skipped');
+  // The raw error should NOT appear verbatim in the rendered output.
+  assert.equal(out.includes('this is a very long error message'), false, 'must not include raw error verbatim');
+  assert.equal(out.match(/—/), null, 'no em-dashes');
+});
+
+test('renderer Test 4 -- empty status with tavily_unavailable shows configuration hint', () => {
+  const out = renderAgentResult({
+    agent_id: 'tavily_funding',
+    status: 'empty',
+    duration_ms: 5,
+    payload: { reason: 'tavily_unavailable' }
+  });
+  assert.ok(out.includes('[funding]'), 'must include funding label');
+  assert.ok(out.includes('TAVILY_API_KEY') || out.includes('not configured'), 'must hint at configuration');
+  assert.equal(out.match(/—/), null, 'no em-dashes');
+});
+
+test('renderer Test 5 -- sharp-question fallback is verbatim from source spec, em-dash-free', () => {
+  const out = renderSharpQuestionFallback();
+  assert.ok(typeof out === 'string', 'must return a string');
+  assert.ok(out.includes("I didn't find precedents for this in 30 seconds"), 'must include opener');
+  assert.ok(out.includes('gap in my data'), 'must include data gap clause');
+  assert.ok(out.includes('genuinely unexplored space'), 'must include unexplored clause');
+  assert.ok(out.includes('Which do you think it is?'), 'must include the closing question');
+  assert.equal(out.match(/—/), null, 'must have no em-dashes');
+});
+
+test('renderer Test 6 -- Hebrew refusal is bilingual, em-dash-free', () => {
+  const out = renderHebrewRefusal();
+  assert.ok(typeof out === 'string', 'must return a string');
+  assert.ok(out.includes('English'), 'must include English instruction');
+  assert.ok(out.includes('v1.13.0'), 'must mention version');
+  // Hebrew characters must appear
+  assert.ok(/[֐-׿]/.test(out), 'must include Hebrew characters');
+  assert.equal(out.match(/—/), null, 'no em-dashes');
+});
+
+test('renderer Test 7 -- renderHeader produces 2-line opener with sha8 and progress', () => {
+  const out = renderHeader('abcd1234');
+  assert.ok(typeof out === 'string', 'must return a string');
+  assert.ok(out.includes('abcd1234'), 'must include sha8');
+  assert.ok(/scanning/i.test(out), 'must include scanning verb');
+  const lines = out.split('\n').filter((l) => l.length > 0);
+  assert.ok(lines.length >= 2, `must be at least 2 lines, got ${lines.length}`);
+  assert.equal(out.match(/—/), null, 'no em-dashes');
+});
+
+test('renderer Test 8 -- renderProgressIndicator shows progress with elapsed/budget/returned', () => {
+  const out = renderProgressIndicator(12000, 45000, 3);
+  assert.ok(typeof out === 'string', 'must return a string');
+  assert.ok(out.includes('12') || out.includes('12s'), 'must include elapsed seconds');
+  assert.ok(out.includes('45'), 'must include budget seconds');
+  assert.ok(out.includes('3'), 'must include returned count');
+  assert.equal(out.match(/—/), null, 'no em-dashes');
+
+  // Edge cases
+  const zero = renderProgressIndicator(0, 45000, 0);
+  assert.ok(zero.includes('0'), 'edge: 0 elapsed');
+  const full = renderProgressIndicator(45000, 45000, 6);
+  assert.ok(full.includes('45'), 'edge: full elapsed');
+  assert.equal(zero.match(/—/), null);
+  assert.equal(full.match(/—/), null);
+});
+
+test('renderer Test 8b (CRITICAL-6) -- renderFooter returns hardcoded 3-option footer, em-dash-free', () => {
+  const out = renderFooter();
+  assert.ok(typeof out === 'string', 'must return a string');
+  assert.ok(out.includes('What now?'), 'must include question opener');
+  assert.ok(out.includes('[1] Just tell me'), 'must include option 1');
+  assert.ok(out.includes('[2] Build a room'), 'must include option 2');
+  assert.ok(out.includes('[3] Challenge me'), 'must include option 3');
+  // CRITICAL invariant: em-dash-free
+  assert.equal(out.match(/—/), null, 'footer must have no em-dashes');
+  // CRITICAL invariant: literal `--` substring present
+  assert.ok(out.includes("Challenge me -- Devil's Advocate"), "must contain literal 'Challenge me -- Devil's Advocate' with `--`");
+});
+
+test('renderer Test 9 -- renderer source is pure (no fs/process/console)', () => {
+  const src = fs.readFileSync(path.join(__dirname, 'mva-progressive-renderer.cjs'), 'utf8');
+
+  // Strip block comments to avoid false-positives in the "pure" assertion.
+  // The renderer documents its purity in comments; tokens inside /* ... */ are not
+  // executable references and must not trip the source-scan.
+  const noBlockComments = src.replace(/\/\*[\s\S]*?\*\//g, '');
+  // Also strip line comments so the documentation that explicitly names
+  // forbidden tokens (e.g. "// no fs.* / no process.* / no console.*") does
+  // not trip the scan. These are intentional self-documentation, not refs.
+  const code = noBlockComments.replace(/\/\/[^\n]*/g, '');
+
+  // Allow `require('fs')` to be absent; verify there is no actual fs.* call.
+  assert.equal(/\brequire\s*\(\s*['"]node:fs['"]\s*\)/.test(code), false, 'must not require node:fs');
+  assert.equal(/\brequire\s*\(\s*['"]fs['"]\s*\)/.test(code), false, 'must not require fs');
+  assert.equal(/\bfs\./.test(code), false, 'must not call fs.*');
+  assert.equal(/\bprocess\./.test(code), false, 'must not access process.*');
+  assert.equal(/\bconsole\./.test(code), false, 'must not call console.*');
+});

package/lib/core/mva-rule-linter.cjs

@@ -0,0 +1,213 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 118-06 Plan 06 -- mva-rule-linter.
+ *
+ * The reward-before-investment rule linter (per docs/reward-before-investment
+ * -rule.md). Scans commands/*.md frontmatter, validates that every interactive
+ * command declares an `interactive_first_reward` field, classifies into three
+ * buckets:
+ *
+ *   compliant -> field present with an allowed REWARD_TYPES value
+ *   missing   -> file has no frontmatter, OR no `interactive_first_reward` key
+ *   invalid   -> field present but value not in REWARD_TYPES enum
+ *
+ * REWARD_TYPES is the v1.13.0 canonical closed vocabulary. Future additions
+ * are canon amendments, not command-level inventions (per rule doc + Canon
+ * Part 7 reuse-before-build).
+ *
+ * Per binding decision B5: this library is the enforcement mechanism the
+ * universal rule needs. Per-command actual remediations are out-of-scope
+ * follow-up phases. This file only validates the DECLARATION.
+ *
+ * Canon Part 8: zero network, zero Brain calls, zero user-content egress.
+ * Reads only plugin-source command files (fs.readdirSync + fs.readFileSync).
+ *
+ * Pure CJS, node built-ins only.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// ---------- The closed vocabulary (v1.13.0) ----------
+
+// Per docs/reward-before-investment-rule.md + WARN-5 audit (plan-checker
+// iteration 2):
+//   reframe_question                -- Larry reframes the user's sentence
+//                                      into a beautiful question (onboard).
+//   instant_brief                   -- the 30-second MVA pipeline output
+//                                      (new-project; this phase's deliverable).
+//   schema_preview                  -- structural preview of what would be
+//                                      extracted before the full ask.
+//   calibration_distribution_preview-- anonymized score distribution from the
+//                                      calibration set (grade).
+//   paragraph_preview               -- partial extraction from the first
+//                                      paragraph alone (file-meeting).
+//   --none (scripting only)         -- explicit opt-out, per rule doc line 81
+//                                      (scripting override).
+const REWARD_TYPES = Object.freeze(new Set([
+  'reframe_question',
+  'instant_brief',
+  'schema_preview',
+  'calibration_distribution_preview',
+  'paragraph_preview',
+  '--none (scripting only)',
+]));
+
+// ---------- Frontmatter parser (mirrors scripts/build-command-registry.cjs) ----------
+
+// Hand-rolled YAML-ish slice parser. Handles:
+//   key: value
+//   key: ["a","b"]    (JSON.parse)
+//   key:              + indented `- item` dash list
+//   strips surrounding quotes
+//   key: null         -> null
+//   key: true|false   -> boolean
+//
+// Returns:
+//   - parsed frontmatter object on success
+//   - null if no `---` block found (caller flags as "missing")
+function parseFrontmatter(md) {
+  if (typeof md !== 'string') return null;
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(md);
+  if (!m) return null;
+  const out = {};
+  let key = null;
+  for (const rawLine of m[1].split(/\r?\n/)) {
+    const line = rawLine.replace(/\s+$/, '');
+    // Skip comments and blank lines
+    if (line === '' || /^\s*#/.test(line)) {
+      continue;
+    }
+    const kv = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
+    if (kv) {
+      key = kv[1];
+      const v = kv[2].trim();
+      if (v === '') {
+        out[key] = [];
+      } else if (v === 'null' || v === '~') {
+        out[key] = null;
+      } else if (v === 'true' || v === 'false') {
+        out[key] = v === 'true';
+      } else if (v.startsWith('[')) {
+        try {
+          out[key] = JSON.parse(v);
+        } catch (_e) {
+          out[key] = v.replace(/^["']|["']$/g, '');
+        }
+      } else {
+        // Strip trailing inline comment ("value  # comment") -- the linter
+        // only cares about the scalar; the comment is metadata.
+        const noComment = v.replace(/\s+#.*$/, '');
+        out[key] = noComment.replace(/^["']|["']$/g, '');
+      }
+    } else if (key && /^\s*-\s+/.test(line)) {
+      if (!Array.isArray(out[key])) out[key] = [];
+      out[key].push(line.replace(/^\s*-\s+/, '').replace(/^["']|["']$/g, ''));
+    }
+  }
+  return out;
+}
+
+// ---------- validateFrontmatter ----------
+
+/**
+ * validateFrontmatter(fm) -> { ok: boolean, reason?: string, value?: string }
+ *
+ *   - fm = null               -> { ok: false, reason: 'no_frontmatter' }
+ *   - missing interactive_first_reward field -> { ok: false, reason: 'missing_field' }
+ *   - value not in REWARD_TYPES               -> { ok: false, reason: 'invalid_value', value }
+ *   - else                                    -> { ok: true, value }
+ *
+ * The `--none (scripting only)` literal is accepted verbatim per rule doc
+ * line 81. Whitespace-trim before lookup so trailing-space typos don't
+ * falsely fail.
+ */
+function validateFrontmatter(fm) {
+  if (fm === null || typeof fm !== 'object') {
+    return { ok: false, reason: 'no_frontmatter' };
+  }
+  if (!Object.prototype.hasOwnProperty.call(fm, 'interactive_first_reward')) {
+    return { ok: false, reason: 'missing_field' };
+  }
+  const raw = fm.interactive_first_reward;
+  if (typeof raw !== 'string') {
+    return { ok: false, reason: 'invalid_value', value: String(raw) };
+  }
+  const value = raw.trim();
+  if (!REWARD_TYPES.has(value)) {
+    return { ok: false, reason: 'invalid_value', value };
+  }
+  return { ok: true, value };
+}
+
+// ---------- scanCommands ----------
+
+/**
+ * scanCommands(commandsDir) -> { ok, compliant[], missing[], invalid[] }
+ *
+ * Reads every *.md in commandsDir (non-recursive), parses frontmatter, runs
+ * validateFrontmatter, classifies into one of three buckets. Each entry is
+ * { path, reason?, value? }.
+ *
+ * ok === true iff missing.length === 0 AND invalid.length === 0.
+ *
+ * Graceful: a file without a frontmatter block is reported in `missing`
+ * (does NOT throw). A file that fs.readFileSync cannot read is reported in
+ * `missing` with reason='read_error'. The function never throws.
+ */
+function scanCommands(commandsDir) {
+  const compliant = [];
+  const missing = [];
+  const invalid = [];
+
+  let entries;
+  try {
+    entries = fs.readdirSync(commandsDir);
+  } catch (e) {
+    return {
+      ok: false,
+      compliant,
+      missing: [{ path: commandsDir, reason: 'commands_dir_read_error', error: e.message }],
+      invalid,
+    };
+  }
+
+  const mdFiles = entries.filter((f) => f.endsWith('.md')).sort();
+
+  for (const f of mdFiles) {
+    const full = path.join(commandsDir, f);
+    let raw;
+    try {
+      raw = fs.readFileSync(full, 'utf8');
+    } catch (_e) {
+      missing.push({ path: full, reason: 'read_error' });
+      continue;
+    }
+    const fm = parseFrontmatter(raw);
+    const v = validateFrontmatter(fm);
+    if (v.ok) {
+      compliant.push({ path: full, value: v.value });
+    } else if (v.reason === 'invalid_value') {
+      invalid.push({ path: full, reason: v.reason, value: v.value });
+    } else {
+      // no_frontmatter OR missing_field -- both count as "missing"
+      missing.push({ path: full, reason: v.reason });
+    }
+  }
+
+  return {
+    ok: missing.length === 0 && invalid.length === 0,
+    compliant,
+    missing,
+    invalid,
+  };
+}
+
+module.exports = {
+  scanCommands,
+  validateFrontmatter,
+  parseFrontmatter, // exposed for tests
+  REWARD_TYPES,
+};