@mindrian_os/install 1.13.0-beta.11

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

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+/*
+ * Phase 101-03 - Shape H (Timeline / Roadmap) renderer.
+ * ASCII-art horizontal timeline. 4-zone anatomy. 12-glyph compliant.
+ * Glyphs: filled-square (marker), dash (axis), right-tri-fill (primary),
+ * right-tri-empty (alt). Spec: 101-RESEARCH.md Section 4.
+ */
+
+'use strict';
+
+const path = require('path');
+
+const FILLED_SQUARE = '■'; // filled-square
+const DASH = '─';          // dash
+const PRIMARY = '▶';       // right-tri-fill
+const ALT = '▷';           // right-tri-empty
+
+const DEFAULT_WIDTH = 60;
+const MIN_WIDTH = 40;
+const MAX_WIDTH = 80;
+const CROWD_THRESHOLD = 3;
+
+const DEFAULT_FOOTER = [
+  { glyph: PRIMARY, command: '/mos:act', description: 'Run methodology' },
+  { glyph: ALT, command: '/mos:add-phase', description: 'Add phase to roadmap' },
+  { glyph: ALT, command: '/mos:milestone-summary', description: 'Generate milestone summary' },
+];
+
+function parseDate(d) {
+  if (d instanceof Date) return isNaN(d.getTime()) ? null : d;
+  const p = new Date(d);
+  return isNaN(p.getTime()) ? null : p;
+}
+
+function fmtDate(d) {
+  const m = ['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec'];
+  return m[d.getUTCMonth()] + ' ' + d.getUTCDate();
+}
+
+function err(line1, line2, line3) {
+  return { error: 'x ' + line1 + '\nWhy: ' + line2 + '\nFix: ' + line3 };
+}
+
+function clampWidth(w) {
+  if (typeof w !== 'number' || !isFinite(w)) return DEFAULT_WIDTH;
+  return Math.min(MAX_WIDTH, Math.max(MIN_WIDTH, Math.round(w)));
+}
+
+function buildHeader(jtbd, title, start, end) {
+  const tag = jtbd || 'plan-execution';
+  const subtitle = title || (fmtDate(start) + ' to ' + fmtDate(end));
+  return '-- mindrianOS -- ' + tag + ' -- timeline (' + subtitle + ') --';
+}
+
+function buildAxis(width, start, end) {
+  const a = fmtDate(start), b = fmtDate(end);
+  const middle = width - a.length - b.length - 2;
+  if (middle <= 0) return DASH.repeat(Math.max(width, 1));
+  return a + ' ' + DASH.repeat(middle) + ' ' + b;
+}
+
+function placeMarkers(milestones, start, end, width) {
+  const span = end.getTime() - start.getTime();
+  const pixelsPerMs = (width - 2) / span;
+  return milestones.map((m, idx) => {
+    const at = parseDate(m.at);
+    let col = Math.round((at.getTime() - start.getTime()) * pixelsPerMs);
+    if (col < 0) col = 0;
+    if (col > width - 1) col = width - 1;
+    return { idx, col, label: String(m.label || ''), at };
+  });
+}
+
+function markerLine(marks, width) {
+  const arr = new Array(width).fill(' ');
+  for (const m of marks) arr[m.col] = FILLED_SQUARE;
+  return arr.join('').replace(/\s+$/, '');
+}
+
+function isCrowded(marks) {
+  if (marks.length < 2) return false;
+  const s = marks.slice().sort((a, b) => a.col - b.col);
+  for (let i = 1; i < s.length; i++) {
+    if (s[i].col - s[i - 1].col < CROWD_THRESHOLD) return true;
+  }
+  return false;
+}
+
+function stampLabel(arr, col, label, room) {
+  let lab = label;
+  if (lab.length > room) lab = lab.slice(0, Math.max(1, room - 1)) + '.';
+  for (let k = 0; k < lab.length && (col + k) < arr.length; k++) {
+    arr[col + k] = lab[k];
+  }
+}
+
+function labelRowsUncrowded(marks, width) {
+  const sorted = marks.slice().sort((a, b) => a.col - b.col);
+  const arr = new Array(width).fill(' ');
+  for (let i = 0; i < sorted.length; i++) {
+    const m = sorted[i];
+    const nextCol = (i + 1 < sorted.length) ? sorted[i + 1].col : width;
+    stampLabel(arr, m.col, m.label, Math.max(1, nextCol - m.col - 1));
+  }
+  return [arr.join('').replace(/\s+$/, '')];
+}
+
+function labelRowsCrowded(marks, width) {
+  const sorted = marks.slice().sort((a, b) => a.col - b.col);
+  return sorted.map((m) => {
+    const arr = new Array(width).fill(' ');
+    stampLabel(arr, m.col, m.label, Math.max(1, width - m.col));
+    return arr.join('').replace(/\s+$/, '');
+  });
+}
+
+function buildBody(start, end, marks, width, title) {
+  const lines = [];
+  if (title) { lines.push(FILLED_SQUARE + ' ' + title); lines.push(''); }
+  lines.push(buildAxis(width, start, end));
+  lines.push(markerLine(marks, width));
+  const rows = isCrowded(marks)
+    ? labelRowsCrowded(marks, width)
+    : labelRowsUncrowded(marks, width);
+  for (const r of rows) lines.push(r);
+  return lines.join('\n');
+}
+
+/**
+ * Phase 101-05: Mode-aware footer marker selection.
+ *
+ * Per Canon Part 3 "Option generation tier-awareness":
+ *   Mode A (tier >= 2)  -> first verb may carry RECOMMENDED ▶ marker (Brain-derived).
+ *   Mode B (tier === 1) -> all verbs use the empty triangle ▷ marker; ▶ NEVER renders.
+ *
+ * Defense-in-depth: this guard lives inside the renderer regardless of whether
+ * the dispatcher already gated the call.
+ */
+function buildFooter(footerVerbs, mode) {
+  const verbs = (Array.isArray(footerVerbs) && footerVerbs.length > 0)
+    ? footerVerbs : DEFAULT_FOOTER;
+  const isModeB = (mode === 'B');
+  return verbs.map((v, i) => {
+    const defaultGlyph = (i === 0 && !isModeB) ? PRIMARY : ALT;
+    const rawGlyph = v.glyph || defaultGlyph;
+    const g = isModeB ? ALT : rawGlyph;
+    const cmd = v.command || '';
+    const desc = v.description ? ('  ' + v.description) : '';
+    return g + ' ' + cmd + desc;
+  }).join('\n');
+}
+
+/**
+ * renderShapeH({ start, end, milestones, title?, width?, jtbd?, tier?,
+ *                footerVerbs? }) -> { zones, contract } | { error }
+ */
+function renderShapeH(opts) {
+  const o = opts || {};
+  const start = parseDate(o.start);
+  const end = parseDate(o.end);
+  if (!start || !end) {
+    return err('Invalid timeline dates',
+      'start or end could not be parsed as ISO date',
+      '/mos:plan-execution add-milestone');
+  }
+  if (end.getTime() <= start.getTime()) {
+    return err('Timeline end is not after start',
+      'Shape H needs end > start to compute scale',
+      '/mos:plan-execution add-milestone');
+  }
+  const milestones = Array.isArray(o.milestones) ? o.milestones : [];
+  if (milestones.length === 0) {
+    return err('No milestones in scope',
+      'Shape H needs at least one milestone',
+      '/mos:plan-execution add-milestone');
+  }
+  for (const m of milestones) {
+    if (!parseDate(m && m.at)) {
+      return err('Milestone date invalid',
+        'one or more milestones lack a parseable at: field',
+        '/mos:plan-execution add-milestone');
+    }
+  }
+  const width = clampWidth(o.width);
+  const marks = placeMarkers(milestones, start, end, width);
+
+  // Phase 101-05: derive mode from explicit `mode` arg or fall back to `tier`.
+  // Mode A renders RECOMMENDED ▶ on first footer verb; Mode B suppresses across the footer.
+  let mode;
+  if (o.mode === 'A' || o.mode === 'B') {
+    mode = o.mode;
+  } else if (typeof o.tier === 'number') {
+    mode = o.tier >= 2 ? 'A' : 'B';
+  } else {
+    mode = 'A'; // back-compat: pre-101-05 callers default to Mode A
+  }
+
+  return {
+    zones: {
+      header: buildHeader(o.jtbd, o.title, start, end),
+      body: buildBody(start, end, marks, width, o.title),
+      footer: buildFooter(o.footerVerbs, mode),
+    },
+    contract: {
+      shape: 'H',
+      width: width,
+      milestoneCount: marks.length,
+      crowded: isCrowded(marks),
+      tier: o.tier == null ? null : o.tier,
+      jtbd: o.jtbd || null,
+      mode: mode,
+    },
+  };
+}
+
+module.exports = {
+  renderShapeH: renderShapeH,
+  __glyphs: { FILLED_SQUARE, DASH, PRIMARY, ALT },
+  __defaults: { DEFAULT_WIDTH, MIN_WIDTH, MAX_WIDTH, CROWD_THRESHOLD },
+};
+
+void path;

package/lib/hmi/tier-check.cjs

@@ -0,0 +1,63 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 101-05 Task 1 -- tier-check helper (v1 stub).
+ *
+ * Per Canon Part 3 (docs/MINDRIAN-CANON.md "Option generation tier-awareness"):
+ *
+ *   Tier 0  (no Brain, no usable local graph)  -> hardcoded minimal option set
+ *   Tier 1  (Local Only / Mode B)              -> Navigation Engine; no RECOMMENDED
+ *   Tier >= 2 (Full Loop / Mode A)             -> Brain-derived options + RECOMMENDED >= 0.7
+ *
+ * docs/CANON-PHASE-MAP.md Part 3 row "Option generation tier-awareness shipped"
+ * points at Phase 90 Plan 90-09 + .planning/research/navigation-engine-brain-interface.md.
+ * No standalone tier-check helper landed in main as of 2026-05-01; the contract
+ * is currently inferred from `lib/core/brain-client.cjs#isAvailable()` plus
+ * BRAIN.md presence checks scattered across `scripts/brain-derive-command.cjs`
+ * and `lib/memory/*`.
+ *
+ * v1 stub semantics (PLAN 101-05 Task 1, autonomous execution, no Phase 90
+ * follow-on hard-blocking us):
+ *   - tier 2  if `process.env.MINDRIAN_BRAIN_KEY` is set (Brain reachable)
+ *   - tier 1  otherwise (Local Only)
+ *   - tier 0  is currently never returned by getTier(); callers may pass
+ *             `tier: 0` explicitly to exercise the dispatcher refuse path.
+ *
+ * Real Phase 90 wiring (Brain ping + reachability cache + BRAIN.md presence
+ * audit) is deferred. When Phase 90's full helper lands, this stub becomes
+ * the back-compat shim.
+ *
+ * Pure CJS, node built-ins only, zero deps (Phase 87 invariant).
+ */
+
+'use strict';
+
+/**
+ * Return current tier based on Brain key presence.
+ *
+ * @returns {0|1|2|3} tier
+ */
+function getTier() {
+  // v1 stub: env var is the only signal. Phase 90 follow-on will replace
+  // with a Brain-ping + cache + BRAIN.md presence audit.
+  if (process.env.MINDRIAN_BRAIN_KEY) return 2;
+  return 1;
+}
+
+/**
+ * Map a tier integer to a Mode A / Mode B / Tier 0 string per Canon Part 3.
+ *
+ * @param {number} tier
+ * @returns {'A'|'B'|'0'}
+ */
+function modeForTier(tier) {
+  const t = (typeof tier === 'number' && Number.isFinite(tier)) ? tier : 0;
+  if (t >= 2) return 'A';
+  if (t === 1) return 'B';
+  return '0';
+}
+
+module.exports = {
+  getTier: getTier,
+  modeForTier: modeForTier,
+};

package/lib/import/PRECONDITIONS.md

@@ -0,0 +1,41 @@
+# Phase 80 Preconditions
+
+## Known: bin/mindrian-tools.cjs MODULE_NOT_FOUND via lazygraph-ops (Phase 78-02 carryover)
+
+**Status:** still broken as of 2026-04-13 (Phase 80-01 execution).
+
+**Symptom:** `node bin/mindrian-tools.cjs --help` crashes at startup with:
+
+```
+Error: Cannot find module 'better-sqlite3'
+requireStack:
+  - lib/core/lazygraph-ops.cjs
+  - lib/core/graph-ops.cjs
+  - bin/mindrian-tools.cjs
+```
+
+`lib/core/lazygraph-ops.cjs` does a top-level `require('better-sqlite3')`
+and `bin/mindrian-tools.cjs` eagerly loads `graph-ops.cjs` which pulls in
+`lazygraph-ops.cjs`, so ANY subcommand (even `--help`) fails before
+argv parsing. This is the same class of issue as Phase 78-02 (lazygraph-ops
+side-effect load), just surfaced through a different native dep.
+
+**Root cause (not fixed here):** `better-sqlite3` is declared in
+package.json but is a native module that was not built against this
+Node version / WSL env. Either `npm rebuild better-sqlite3`, pin a
+pre-built version, or lazy-require better-sqlite3 inside the functions
+that actually need it.
+
+**Workaround for Phase 80:**
+
+- Plan 80-05 (command wiring) must NOT add the `vault import` subcommand to
+  `bin/mindrian-tools.cjs` via the graph-ops require chain.
+- Instead, wire `/mos:vault import` through `node scripts/vault-import.cjs`
+  directly (no import of graph-ops / lazygraph-ops in the entry path).
+- If any downstream plan wants to call mindrian-tools.cjs as a smoke test
+  (IMPORT-11), it MUST first confirm mindrian-tools.cjs runs cleanly OR
+  stub the smoke test behind this precondition until fixed.
+
+**Fix target:** separate plan (not Phase 80 scope). File as a post-Phase-80
+follow-up task against `lib/core/lazygraph-ops.cjs` to lazy-require
+better-sqlite3 at function-call time, not module-load time.

package/lib/import/branding.cjs

@@ -0,0 +1,210 @@
+'use strict';
+
+/**
+ * Phase 80 Plan 80-06 Task 1 (IMPORT-10) -- Branding injection.
+ *
+ * Applied by Stage 04 enricher AFTER wikilink injection. For every routed
+ * artifact this module:
+ *
+ *   1. normalizeFrontmatter -- rewrites frontmatter to the De Stijl canonical
+ *      shape (title, section, status, imported_from, imported_at, import_id,
+ *      source_wikilinks, tags). Non-canonical source fields are preserved
+ *      under _source_frontmatter so nothing is lost.
+ *   2. promoteCalloutFields -- promotes known source frontmatter fields
+ *      (author, attendees, date, tags) into Obsidian-style callout blocks
+ *      ([!author], [!attendees], [!date], [!tags]) at the top of the body.
+ *      These render via the De Stijl .callout / .callout-blue / .callout-teal
+ *      / .callout-red CSS classes shipped by scripts/generate-hub.cjs (v1.9.7).
+ *   3. injectBrandedFooter -- appends a MindrianOS branded footer using the
+ *      same FOOTER_MARKER string as scripts/vault-footer-injector.cjs (Phase
+ *      76) so idempotency checks cover both paths.
+ *
+ * Phase 76 discovery (scripts/vault-footer-injector.cjs):
+ *   - Exports buildFooter, hasExistingFooter, appendFooter, processFile.
+ *   - FOOTER_MARKER = '> MindrianOS |', FOOTER_BRAND = '> [SQUARE] MindrianOS |'
+ *     (the square glyph is intentionally preserved verbatim from that file).
+ *   - Uses enrichFrontmatter from lib/vault/frontmatter-schema.cjs.
+ *   - The Phase 76 module is CLI-first but exports are reusable; however the
+ *     80-06 branding flow needs a per-file, per-import-context API that
+ *     Phase 76 does not expose (it walks a whole room and computes its own
+ *     import context from roomName). So this module reimplements the thin
+ *     per-file footer pathway while reusing the SAME marker so the two
+ *     paths are mutually idempotent.
+ *
+ * Idempotent: running applyBranding twice on the same file produces no
+ * second-pass changes (footer not doubled, callouts not duplicated,
+ * frontmatter already canonical).
+ *
+ * Zero em-dashes in this file and in branding.test.cjs (hyphens only).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const matter = require('gray-matter');
+
+// FOOTER_MARKER must match scripts/vault-footer-injector.cjs (Phase 76).
+const FOOTER_MARKER = '> MindrianOS |';
+// The branded prefix uses a bracketed token instead of a box glyph so the
+// source file stays plain ASCII and is trivially greppable across platforms.
+const FOOTER_BRAND = '> [MOS] MindrianOS |';
+
+const CALLOUT_MARKER = '<!-- destijl-callout -->';
+const CALLOUT_FIELDS = ['author', 'attendees', 'date', 'tags'];
+
+const CANONICAL_KEYS = new Set([
+  'title',
+  'section',
+  'status',
+  'imported_from',
+  'imported_at',
+  'import_id',
+  'source_wikilinks',
+  'tags'
+]);
+
+// ---------------------------------------------------------------------------
+// Footer injection
+// ---------------------------------------------------------------------------
+
+function hasExistingFooter(content) {
+  return /^>\s*(?:\[MOS\]\s*)?MindrianOS\s*\|/m.test(content);
+}
+
+function injectBrandedFooter(artifactPath, importContext) {
+  const content = fs.readFileSync(artifactPath, 'utf8');
+  if (hasExistingFooter(content)) return false;
+
+  const importedAt = (importContext && importContext.imported_at) || new Date().toISOString();
+  const sourceVault = (importContext && importContext.source_vault) || 'unknown';
+  const importId = (importContext && importContext.import_id) || 'unknown';
+
+  const footer = [
+    '',
+    '---',
+    '',
+    FOOTER_BRAND + ' imported ' + importedAt + ' | from ' + sourceVault + ' | import_id: ' + importId,
+    ''
+  ].join('\n');
+
+  const trimmed = content.replace(/\s+$/, '');
+  // Avoid doubling an existing horizontal rule at the tail of the body.
+  const endsWithHr = /(^|\n)---\s*$/.test(trimmed);
+  const out = endsWithHr
+    ? trimmed + '\n\n' + FOOTER_BRAND + ' imported ' + importedAt + ' | from ' + sourceVault + ' | import_id: ' + importId + '\n'
+    : trimmed + footer;
+
+  fs.writeFileSync(artifactPath, out);
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Frontmatter normalization
+// ---------------------------------------------------------------------------
+
+function normalizeFrontmatter(artifactPath, classification, importContext) {
+  const raw = fs.readFileSync(artifactPath, 'utf8');
+  const parsed = matter(raw);
+  const src = parsed.data || {};
+
+  const importedAt = (importContext && importContext.imported_at) || new Date().toISOString();
+
+  // Preserve any previously-seeded _source_frontmatter so re-runs do not
+  // nest it recursively on every invocation.
+  const previouslyPreserved = (src._source_frontmatter && typeof src._source_frontmatter === 'object')
+    ? src._source_frontmatter
+    : {};
+
+  const canonical = {};
+  canonical.title = src.title || path.basename(artifactPath, '.md');
+  canonical.section = (classification && classification.section) || src.section || '';
+  canonical.status = 'imported';
+  canonical.imported_from = (importContext && importContext.source_path) || src.imported_from || '';
+  canonical.imported_at = src.imported_at || importedAt;
+  canonical.import_id = (importContext && importContext.import_id) || src.import_id || '';
+
+  if (Array.isArray(src.source_wikilinks)) {
+    canonical.source_wikilinks = src.source_wikilinks;
+  } else if (importContext && Array.isArray(importContext.source_wikilinks)) {
+    canonical.source_wikilinks = importContext.source_wikilinks;
+  } else {
+    canonical.source_wikilinks = [];
+  }
+
+  if (Array.isArray(src.tags)) canonical.tags = src.tags;
+  else if (src.tags) canonical.tags = [src.tags];
+  else canonical.tags = [];
+
+  // Everything else goes under _source_frontmatter so it round-trips.
+  const preserved = Object.assign({}, previouslyPreserved);
+  for (const [k, v] of Object.entries(src)) {
+    if (CANONICAL_KEYS.has(k)) continue;
+    if (k === '_source_frontmatter') continue;
+    preserved[k] = v;
+  }
+  if (Object.keys(preserved).length > 0) canonical._source_frontmatter = preserved;
+
+  const out = matter.stringify(parsed.content, canonical);
+  fs.writeFileSync(artifactPath, out);
+  return canonical;
+}
+
+// ---------------------------------------------------------------------------
+// Callout promotion
+// ---------------------------------------------------------------------------
+
+function formatCalloutValue(v) {
+  if (Array.isArray(v)) return v.map(formatCalloutValue).join(', ');
+  if (v instanceof Date) return v.toISOString().slice(0, 10);
+  return String(v);
+}
+
+function promoteCalloutFields(artifactPath) {
+  const raw = fs.readFileSync(artifactPath, 'utf8');
+  if (raw.includes(CALLOUT_MARKER)) return false; // idempotent
+
+  const parsed = matter(raw);
+  const fm = parsed.data || {};
+  const src = (fm._source_frontmatter && typeof fm._source_frontmatter === 'object') ? fm._source_frontmatter : {};
+
+  const callouts = [];
+  for (const key of CALLOUT_FIELDS) {
+    let v = src[key];
+    if (v == null || v === '') v = fm[key];
+    if (v == null || v === '') continue;
+    if (Array.isArray(v) && v.length === 0) continue;
+    callouts.push('> [!' + key + '] ' + formatCalloutValue(v));
+  }
+  if (callouts.length === 0) return false;
+
+  // Block uses De Stijl callout rendering (scripts/generate-hub.cjs .callout
+  // classes). The marker comment makes the block detectable on re-runs and
+  // also acts as a hint for the hub renderer to wrap with callout-blue.
+  const block = [CALLOUT_MARKER, ...callouts, ''].join('\n');
+  const newBody = block + '\n' + parsed.content.replace(/^\s+/, '');
+  const out = matter.stringify(newBody, fm);
+  fs.writeFileSync(artifactPath, out);
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Orchestrator
+// ---------------------------------------------------------------------------
+
+function applyBranding(artifactPath, classification, importContext) {
+  normalizeFrontmatter(artifactPath, classification, importContext);
+  promoteCalloutFields(artifactPath);
+  injectBrandedFooter(artifactPath, importContext);
+}
+
+module.exports = {
+  injectBrandedFooter: injectBrandedFooter,
+  normalizeFrontmatter: normalizeFrontmatter,
+  promoteCalloutFields: promoteCalloutFields,
+  applyBranding: applyBranding,
+  hasExistingFooter: hasExistingFooter,
+  FOOTER_MARKER: FOOTER_MARKER,
+  FOOTER_BRAND: FOOTER_BRAND,
+  CALLOUT_MARKER: CALLOUT_MARKER,
+  CALLOUT_FIELDS: CALLOUT_FIELDS,
+  CANONICAL_KEYS: CANONICAL_KEYS
+};