@mindrian_os/cli 2.0.0-beta.3 → 2.0.0-beta.31

package/lib/hmi/voice-color-mark.cjs

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 182-01 SIGNAL-02 -- the voice-color-mark module (the Part 12 Voice Signature, CLI half)
+ * =============================================================================================
+ * Part 12 (The Pedagogy Constitution) makes the Voice Signature a HARD requirement: MindrianOS
+ * must, on every surface, make VISIBLE BY COLOR whether the navigator is hearing LARRY or the
+ * native host (Claude Code). A product the navigator cannot tell apart from the generic host is
+ * not a product (Part 10). This module is the deterministic detector + the frozen move->color
+ * map that encodes the convention. It mirrors the Phase 179 check-card-fire.cjs exported-predicate
+ * idiom (classifyCardFire): a pure, deterministic classifier the rest of the system reads.
+ *
+ * The mark names the pedagogical MOVE, reusing the Part 3 De Stijl palette (no new color minted).
+ * Phase 182.1: the mark is delivered as a colored EMOJI SQUARE (the PRIMARY mark), because this host
+ * strips ANSI (truecolor + 256 + basic-16) to literal text but renders emoji in color. The palette is
+ * UNCHANGED -- the same 5 primaries, no sixth color; only the DELIVERY moves from bracketed color-word
+ * to colored glyph. ANSI is progressive-enhancement-only. The bracketed color-word stays a recognized
+ * SECONDARY form (additive), so older fixtures and progressive-enhancement hosts still classify.
+ *   U+1F7E6 blue square    = building with you (scaffolding the next node; ASK-leaning)
+ *   U+1F7E5 red square      = challenging (devil's advocate, the reframe, pushing back)
+ *   U+1F7E8 yellow square   = contradiction surfaced (a caution: "you said X here and not-X there")
+ *   U+2B1B  black square    = the frame (a Decision Gate; a structural choice for the navigator)
+ *   U+2B1C  white square    = getting out of the way (handing the deliverable over; invisibility)
+ *
+ * Invisibility becomes a STATE WITH A COLOR: the badge ends on white the moment the insight lands.
+ *
+ * The mark is ONE of the 5 EXISTING De Stijl Mondrian primaries, anchored at
+ * references/visual/palette.json (base.mondrian_red / _blue / _yellow / _black / _white). A sixth
+ * color is structurally impossible: MARK_COLORS is a frozen 5-member Set, MARK_PALETTE_KEYS maps
+ * each to its palette.json anchor, and detectVoiceMark rejects any non-De-Stijl bracketed tag.
+ *
+ * HONEST RESIDUAL (D3, mirroring the Phase 178 R15 / Phase 179 R-1 terminal-tool-call residual):
+ * enforcement is the DECLARED CONVENTION (the doctrine in skills/larry-personality + skills/ui-system)
+ * plus the missing-mark / declaration test (Plan 182-02), NOT a per-token runtime recolor. There is
+ * NO hook that recolors every literal assistant token at runtime, so the guarantee is the declared
+ * convention plus the missing-mark test, not a per-token runtime guarantee. This module is the
+ * deterministic substrate the doctrine and that test both read; it does not claim to recolor live
+ * model output.
+ *
+ * Canon Part 8 (The Graph Boundary): LOCAL-only. The detector reads a LOCAL turn string and
+ * returns a color enum + scalar flags; it makes ZERO Brain reads/writes and ZERO network calls,
+ * carries no user data, and mints no reach / posture / edge / node (D4). The optional palette
+ * anchor reads only the LOCAL references/visual/palette.json file.
+ *
+ * Additive only: the frozen Part 3 contracts (the 12-glyph vocabulary, the 4-zone anatomy, the 5
+ * colors, MAX_K=3, DIAL_REACH_K=6, the 0.70/0.15 gate, the 6-reach bank, R15 render coverage) are
+ * UNTOUCHED (D2). The mark is additive legibility only.
+ *
+ * House rule: hyphens only, no em-dashes. CJS module, Node built-ins only.
+ *
+ * License: BSL 1.1.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const PLUGIN_ROOT = path.resolve(__dirname, '..', '..');
+
+// references/visual/palette.json is the canonical De Stijl source of truth (Phase 121.5-03). The
+// 5 marks anchor to its base.mondrian_* primaries so a sixth color is structurally impossible.
+const PALETTE_PATH = path.join(PLUGIN_ROOT, 'references', 'visual', 'palette.json');
+
+// ---------------------------------------------------------------------------
+// VOICE_COLOR_MARKS -- the frozen move->color map (Part 12 semantics). Each of the 5 canonical
+// pedagogical moves maps to exactly one of the 5 De Stijl colors. Frozen so a phase cannot
+// silently re-point a move to a new color.
+// ---------------------------------------------------------------------------
+const VOICE_COLOR_MARKS = Object.freeze({
+  building: 'blue',
+  challenging: 'red',
+  contradiction: 'yellow',
+  gate: 'black',
+  invisibility: 'white',
+});
+
+// ---------------------------------------------------------------------------
+// MARK_COLORS -- the frozen 5-member set of De Stijl colors. Equal to the 5 Mondrian primaries in
+// references/visual/palette.json (no sixth color, no non-palette color). This is the closed enum
+// that makes "no new color minted" a structural guarantee.
+// ---------------------------------------------------------------------------
+const MARK_COLORS = Object.freeze(new Set(['blue', 'red', 'yellow', 'black', 'white']));
+
+// ---------------------------------------------------------------------------
+// MARK_PALETTE_KEYS -- the no-new-color anchor: each mark color maps to its base.mondrian_* key in
+// references/visual/palette.json. The literal `mondrian_(red|blue|yellow|black|white)` strings make
+// the link from this module to the palette source greppable and auditable.
+// ---------------------------------------------------------------------------
+const MARK_PALETTE_KEYS = Object.freeze({
+  blue: 'mondrian_blue',
+  red: 'mondrian_red',
+  yellow: 'mondrian_yellow',
+  black: 'mondrian_black',
+  white: 'mondrian_white',
+});
+
+// ---------------------------------------------------------------------------
+// MARK_GLYPHS -- the PRIMARY Voice Signature marks (Phase 182.1). The host strips ANSI (truecolor,
+// 256, and basic-16) to LITERAL TEXT but renders EMOJI in color, so the De Stijl color must be
+// carried by a colored emoji square, never by an ANSI escape (ANSI is progressive-enhancement only).
+// Each of the 5 De Stijl Mondrian primaries is delivered as its colored square; the palette is
+// UNCHANGED (the same 5 colors, no sixth) -- only the DELIVERY mechanism moves from bracketed
+// color-word to colored glyph. Frozen so a phase cannot re-point a glyph to a new color.
+//   U+1F7E6 blue square    -> blue   (building)
+//   U+1F7E5 red square      -> red    (challenging)
+//   U+1F7E8 yellow square   -> yellow (contradiction)
+//   U+2B1B  black square    -> black  (gate)
+//   U+2B1C  white square    -> white  (invisibility)
+// ---------------------------------------------------------------------------
+const MARK_GLYPHS = Object.freeze({
+  '\u{1F7E6}': 'blue',
+  '\u{1F7E5}': 'red',
+  '\u{1F7E8}': 'yellow',
+  '\u{2B1B}': 'black',
+  '\u{2B1C}': 'white',
+});
+
+// COLOR_GLYPHS -- the inverse map (color -> glyph), so a consumer (the statusline Tier-1 voice glyph,
+// the dial) can render the same 5-primary mark from a color name. Derived from MARK_GLYPHS, frozen.
+const COLOR_GLYPHS = Object.freeze({
+  blue: '\u{1F7E6}',
+  red: '\u{1F7E5}',
+  yellow: '\u{1F7E8}',
+  black: '\u{2B1B}',
+  white: '\u{2B1C}',
+});
+
+// NON_DESTIJL_GLYPHS -- colored block / circle emoji that are NOT De Stijl primaries. A turn that
+// OPENS with one of these is a spoof / new-color attempt and is rejected (valid:false), the glyph
+// counterpart of the rejected bracketed `[GREEN]` / `[PURPLE]` word. No sixth color enters via the
+// detector. (Green / orange / purple / brown squares + the green/orange/red status circles the
+// statusline uses for its OWN thresholds, which are not voice marks.)
+const NON_DESTIJL_GLYPHS = Object.freeze(new Set([
+  '\u{1F7E9}', // green square
+  '\u{1F7E7}', // orange square
+  '\u{1F7EA}', // purple square
+  '\u{1F7EB}', // brown square
+  '\u{1F7E2}', // green circle
+  '\u{1F7E0}', // orange circle
+  '\u{1F534}', // red circle
+  '\u{1F535}', // blue circle
+]));
+
+// ---------------------------------------------------------------------------
+// paletteAnchorOk() -- a build-time / load-time confirmation that the 5 anchors exist in
+// references/visual/palette.json. Defensive: a missing / unreadable palette returns false (the
+// detector still works; this is an audit helper, not a hard dependency). Pure LOCAL file read; no
+// network, no Brain (Part 8).
+// ---------------------------------------------------------------------------
+function paletteAnchorOk() {
+  try {
+    const raw = fs.readFileSync(PALETTE_PATH, 'utf8');
+    const pal = JSON.parse(raw);
+    const base = pal && typeof pal === 'object' && pal.base && typeof pal.base === 'object'
+      ? pal.base
+      : {};
+    return Object.values(MARK_PALETTE_KEYS).every(function (k) {
+      return typeof base[k] === 'string' && base[k].length > 0;
+    });
+  } catch (_e) {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// markForMove(move) -- the move->color lookup. Returns one of the 5 De Stijl colors for a known
+// move, or null for an unknown move (never throws, never invents a color).
+// ---------------------------------------------------------------------------
+function markForMove(move) {
+  const key = typeof move === 'string' ? move.toLowerCase().trim() : '';
+  return Object.prototype.hasOwnProperty.call(VOICE_COLOR_MARKS, key)
+    ? VOICE_COLOR_MARKS[key]
+    : null;
+}
+
+// ---------------------------------------------------------------------------
+// glyphForColor(color) -- the color->glyph lookup. Returns the De Stijl emoji square for one of the
+// 5 colors, or null for a non-De-Stijl color (never throws, never invents a glyph).
+// ---------------------------------------------------------------------------
+function glyphForColor(color) {
+  const key = typeof color === 'string' ? color.toLowerCase().trim() : '';
+  return Object.prototype.hasOwnProperty.call(COLOR_GLYPHS, key)
+    ? COLOR_GLYPHS[key]
+    : null;
+}
+
+// glyphForMove(move) -- the move->glyph convenience (markForMove composed with glyphForColor).
+function glyphForMove(move) {
+  const color = markForMove(move);
+  return color ? glyphForColor(color) : null;
+}
+
+// leadCodePoint(text) -- the first non-whitespace Unicode code point as a string, or null. Astral
+// safe (emoji squares are surrogate pairs for U+1F7E6/5/8): codePointAt + fromCodePoint round-trips
+// the full code point, never a lone surrogate.
+function leadCodePoint(text) {
+  const s = typeof text === 'string' ? text.replace(/^\s+/, '') : '';
+  if (s.length === 0) return null;
+  return String.fromCodePoint(s.codePointAt(0));
+}
+
+// countDeStijlGlyphs(text) -- how many of the 5 De Stijl glyph marks appear anywhere in the turn
+// (the exactly-one contract, glyph side). Iterates by code point so astral squares count once.
+function countDeStijlGlyphs(text) {
+  if (typeof text !== 'string' || text.length === 0) return 0;
+  let n = 0;
+  for (const ch of text) {
+    if (Object.prototype.hasOwnProperty.call(MARK_GLYPHS, ch)) n++;
+  }
+  return n;
+}
+
+// A bracketed color-tag anywhere in the text: `[BLUE]`, `[ red ]`, etc. The capture is the color
+// word; case and inner whitespace are tolerated.
+const TAG_RE = /\[\s*([A-Za-z]+)\s*\]/g;
+// The same shape anchored at turn START (leading whitespace tolerated). The mark must open the turn.
+const LEAD_TAG_RE = /^\s*\[\s*([A-Za-z]+)\s*\]/;
+
+// ---------------------------------------------------------------------------
+// detectVoiceMark(turnText) -- THE deterministic classifier (mirrors classifyCardFire's shape).
+//
+// Returns { hasMark, count, color, isNativeHost, valid }:
+//   - A turn opening with exactly ONE valid De Stijl mark:
+//       { hasMark:true, count:1, color:<one of 5>, isNativeHost:false, valid:true }
+//   - A turn with NO bracketed tag at all (the absence IS the native-host signal):
+//       { hasMark:false, count:0, color:null, isNativeHost:true, valid:true }
+//   - A turn carrying MORE THAN ONE De Stijl mark (the exactly-one contract broken):
+//       { hasMark:true, count:<n>, color:<lead>, isNativeHost:false, valid:false }
+//   - A turn whose leading tag is a NON-De-Stijl color (a spoof / a new color attempt):
+//       { hasMark:false, count:0, color:null, isNativeHost:false, valid:false }
+//   - A turn with bracketed tags present but NONE anchored at turn start:
+//       { hasMark:false, count:0, color:null, isNativeHost:false, valid:false }
+//
+// The mark is anchored at turn start (case-insensitive); exactly one is accepted; zero marks is
+// native-host. Pure, deterministic, no network, no clock, no random. Never throws (Part 8 LOCAL).
+// ---------------------------------------------------------------------------
+function detectVoiceMark(turnText) {
+  const text = typeof turnText === 'string' ? turnText : '';
+
+  // ---- PRIMARY path (Phase 182.1): the leading De Stijl emoji GLYPH ----
+  // The glyph is the primary mark because the host strips ANSI to literal text but paints emoji.
+  const lead = leadCodePoint(text);
+  if (lead && Object.prototype.hasOwnProperty.call(MARK_GLYPHS, lead)) {
+    const color = MARK_GLYPHS[lead];
+    const glyphCount = countDeStijlGlyphs(text);
+    if (glyphCount !== 1) {
+      // More than one De Stijl glyph breaks the exactly-one contract.
+      return { hasMark: true, count: glyphCount, color, isNativeHost: false, valid: false };
+    }
+    return { hasMark: true, count: 1, color, isNativeHost: false, valid: true };
+  }
+  // A leading NON-De-Stijl colored block / circle is a spoof / new-color attempt -> reject.
+  if (lead && NON_DESTIJL_GLYPHS.has(lead)) {
+    return { hasMark: false, count: 0, color: null, isNativeHost: false, valid: false };
+  }
+
+  // ---- SECONDARY path (kept additive): the bracketed color-name word ([BLUE]) ----
+  // Gather every bracketed tag in the text.
+  const tags = [];
+  let m;
+  TAG_RE.lastIndex = 0;
+  while ((m = TAG_RE.exec(text)) !== null) {
+    tags.push(m[1].toLowerCase());
+  }
+
+  // No bracketed tag at all -> native host. The absence is the signal (Part 12 D1).
+  if (tags.length === 0) {
+    return { hasMark: false, count: 0, color: null, isNativeHost: true, valid: true };
+  }
+
+  // Is the FIRST non-whitespace token a bracketed tag (the anchored mark)?
+  const leadTag = text.match(LEAD_TAG_RE);
+  const leadColor = leadTag ? leadTag[1].toLowerCase() : null;
+
+  // A bracketed tag exists but none anchors the turn start -> not a valid anchored mark.
+  if (!leadColor) {
+    return { hasMark: false, count: 0, color: null, isNativeHost: false, valid: false };
+  }
+
+  // The leading tag is a NON-De-Stijl color (e.g. green / purple) -> reject. No new color minted.
+  if (!MARK_COLORS.has(leadColor)) {
+    return { hasMark: false, count: 0, color: null, isNativeHost: false, valid: false };
+  }
+
+  // Count the valid De Stijl marks across the turn (the exactly-one contract).
+  const deStijlCount = tags.filter(function (t) { return MARK_COLORS.has(t); }).length;
+
+  if (deStijlCount !== 1) {
+    // More than one De Stijl mark on one turn breaks the exactly-one contract.
+    return { hasMark: true, count: deStijlCount, color: leadColor, isNativeHost: false, valid: false };
+  }
+
+  // Exactly one anchored De Stijl mark: a legible Larry turn.
+  return { hasMark: true, count: 1, color: leadColor, isNativeHost: false, valid: true };
+}
+
+module.exports = {
+  VOICE_COLOR_MARKS,
+  MARK_COLORS,
+  MARK_PALETTE_KEYS,
+  MARK_GLYPHS,
+  COLOR_GLYPHS,
+  NON_DESTIJL_GLYPHS,
+  markForMove,
+  glyphForColor,
+  glyphForMove,
+  detectVoiceMark,
+  paletteAnchorOk,
+  // Phase 250-03 (HONEST-03): exported so the provenance fence's live
+  // collision guard (tests/test-250-provenance-fence.cjs) can call the real
+  // detector instead of re-deriving glyph-counting logic. Pure function,
+  // already used internally by detectVoiceMark; this export adds zero new
+  // behavior, zero new glyph, zero new color -- it only makes an existing
+  // pure function externally callable.
+  countDeStijlGlyphs,
+};

package/lib/hmi/voice-style-log.cjs

@@ -0,0 +1,276 @@
+'use strict';
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * lib/hmi/voice-style-log.cjs -- Phase 298-07 (R-08, rung 2: LOGGED)
+ * =====================================================================
+ * WHAT IT IS: the append-only evidence log for the voice policies (currently
+ * `voice-hyphens-only` and `voice-glyph-present`). Rung 2 of the harness's
+ * three-rung ladder (declared -> LOGGED -> blocking) means a violation is
+ * recorded, never enforced. `scripts/check-voice-style.cjs` is the sole
+ * writer; a human, or `evaluatePromotion` (plan 298-08), is the sole reader
+ * that matters for a promotion decision.
+ *
+ * ROW SHAPE, exactly these keys in this order: `ts` (epoch ms, the freshness
+ * key a doctor module reads, mirroring `card-fire-health-module.cjs:79`),
+ * `timestamp` (ISO string), `policy_id`, `version` (from
+ * `lib/core/repo-version.cjs::readRepoVersion()`, or the string `unknown` if
+ * that call fails), `result` (`fire` on write; a human later relabels a row
+ * to `true_positive` or `false_positive`), `detail` (a capped excerpt, never
+ * a whole turn), `session_id`.
+ *
+ * RETENTION DECISION (Pitfall 4, `298-RESEARCH.md`): this log carries no
+ * time-based TTL of any kind. A `promotion_rule` names a `window_runs`
+ * measured in RELEASES (e.g. 200 runs across a multi-week promotion
+ * window). Card-fire's own 24-hour age-based eviction
+ * (`scripts/check-card-fire.cjs:244`) prunes on every write -- copying that
+ * here would silently evict evidence before a multi-release promotion
+ * window could ever see it, making the `promotion_rule` structurally
+ * unsatisfiable. This log is instead rotated by SIZE ONLY (see
+ * ROTATE_THRESHOLD_BYTES below), never by age.
+ *
+ * APPEND-ONLY (not read-prune-rewrite): `appendVoiceStyleRow` always
+ * `fs.appendFileSync`s one line. It never reads the whole file back in order
+ * to rewrite it (contrast `card-fire`'s `appendInterceptLog`, which DOES
+ * read-prune-rewrite for its own age-based eviction). A rewrite would
+ * clobber a human's `result` relabelling the moment the next Stop hook
+ * fires -- append-only is what makes that relabelling survive.
+ *
+ * Canon Part 8 (Graph Boundary): this module does LOCAL FILE WRITES ONLY,
+ * under `$MINDRIAN_HOME` (default `~/.mindrian`). It never makes a network
+ * call and never egresses anything. `detail` is capped (VOICE_STYLE_DETAIL_CAP
+ * below) rather than storing a whole turn, so an untrusted model turn cannot
+ * write an unbounded amount of its own text to local disk.
+ *
+ * NEVER-BLOCK CONTRACT: a diagnostic log write must NEVER block or throw the
+ * Stop hook that calls it. Every exported write path is wrapped in a
+ * swallow-all try/catch; every exported read path degrades to an empty
+ * array rather than throwing. Both return plain values (never a rejected
+ * promise, never a thrown error) so a caller never needs its own wrapper.
+ *
+ * `evaluatePromotion(policy, lines)` -- Phase 298-08 (D-02, R-03). ONE evaluator,
+ * two printers (the future runner printer and the doctor module printer,
+ * plan 298-08): the 2026-07-11 printer-must-match-counter lesson
+ * (`card-fire-health-module.cjs:8-10`) applies here exactly -- a verdict is
+ * computed ONCE, by this function, and every caller formats it, never
+ * recomputes it. PURE and side-effect free: it reads its two arguments and
+ * returns a plain object; it opens no file, writes no file, and never
+ * assigns a rung anywhere (promotion stays a human edit to one policy
+ * file). The load-bearing counting rule (Pitfall 5, `298-RESEARCH.md`):
+ * `false_positive_rate` is computed over LABELED rows only
+ * (`result` is `true_positive` or `false_positive`); a row whose `result`
+ * is still the default `fire` counts toward `fires` only, never toward
+ * either positive count, so an unreviewed log can never read as a fake
+ * zero percent false-positive rate and auto-qualify for promotion.
+ */
+
+// RUNG_LADDER: the harness's three-rung promotion ladder (declared -> logged
+// -> blocking). evaluatePromotion never assigns to this ladder; it only
+// reads a policy's current position on it to compute `next_rung`.
+const RUNG_LADDER = ['declared', 'logged', 'blocking'];
+
+function nextRungOnLadder(currentRung) {
+  const idx = RUNG_LADDER.indexOf(currentRung);
+  if (idx === -1 || idx === RUNG_LADDER.length - 1) return null;
+  return RUNG_LADDER[idx + 1];
+}
+
+// evaluatePromotion(policy, lines) -- see the header comment above for the
+// full contract. Returns exactly nine keys on every input, including empty
+// input: window_runs, fires, true_positives, false_positives,
+// false_positive_rate, met, reasons, next_rung, edit_line.
+function evaluatePromotion(policy, lines) {
+  const p = policy && typeof policy === 'object' ? policy : {};
+  const rows = Array.isArray(lines) ? lines : [];
+  const rule = p.promotion_rule && typeof p.promotion_rule === 'object' ? p.promotion_rule : null;
+  const ruleIsWellFormed =
+    !!rule &&
+    Number.isFinite(rule.window_runs) &&
+    Number.isFinite(rule.max_false_positive_rate) &&
+    Number.isFinite(rule.min_true_positives);
+
+  const fires = rows.length;
+  let truePositives = 0;
+  let falsePositives = 0;
+  for (const row of rows) {
+    const result = row && typeof row === 'object' ? row.result : undefined;
+    if (result === 'true_positive') truePositives += 1;
+    else if (result === 'false_positive') falsePositives += 1;
+    // A default/unlabeled 'fire' row (or any other value) counts only
+    // toward `fires`, never toward either labeled count -- the load-bearing
+    // rule above.
+  }
+  const labeledCount = truePositives + falsePositives;
+  // Never a fake zero: with zero labeled rows the rate is null, not 0.
+  const falsePositiveRate = labeledCount > 0 ? falsePositives / labeledCount : null;
+  const windowRuns = ruleIsWellFormed ? rule.window_runs : 0;
+
+  function buildVerdict(met, reasons) {
+    const next = met ? nextRungOnLadder(p.rung) : null;
+    const editLine = next ? '"rung": "' + next + '",' : '';
+    return {
+      window_runs: windowRuns,
+      fires: fires,
+      true_positives: truePositives,
+      false_positives: falsePositives,
+      false_positive_rate: falsePositiveRate,
+      met: met,
+      reasons: reasons,
+      next_rung: next,
+      edit_line: editLine,
+    };
+  }
+
+  if (!ruleIsWellFormed) {
+    return buildVerdict(false, [
+      'promotion_rule missing or malformed: window_runs, max_false_positive_rate and min_true_positives must all be finite numbers',
+    ]);
+  }
+  if (rows.length === 0) {
+    return buildVerdict(false, ['no evidence rows: the log has zero rows for this policy']);
+  }
+  if (p.rung === 'blocking') {
+    return buildVerdict(false, ['already at rung "blocking": there is no further rung to promote to']);
+  }
+  if (labeledCount < rule.min_true_positives) {
+    return buildVerdict(false, [
+      'labeled rows (' + labeledCount + ') below min_true_positives (' + rule.min_true_positives + '): an unreviewed log cannot auto-qualify for promotion',
+    ]);
+  }
+  if (falsePositiveRate !== null && falsePositiveRate > rule.max_false_positive_rate) {
+    return buildVerdict(false, [
+      'false_positive_rate (' + falsePositiveRate.toFixed(4) + ') exceeds max_false_positive_rate (' + rule.max_false_positive_rate + ')',
+    ]);
+  }
+  return buildVerdict(true, []);
+}
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+// VOICE_STYLE_DETAIL_CAP: the `detail` field is a short excerpt plus an
+// offset, never a whole turn (Canon Part 8, T-298-02 information-disclosure
+// mitigation). Follows card-fire's INTERCEPT_LOG_TEXT_CAP precedent
+// (scripts/check-card-fire.cjs:251), sized smaller since `detail` is a
+// diagnostic excerpt, not the whole captured turn text.
+const VOICE_STYLE_DETAIL_CAP = 500;
+
+// ROTATE_THRESHOLD_BYTES: when voice-style.jsonl exceeds this size, it is
+// renamed to voice-style.jsonl.1 (overwriting any prior .1) before the new
+// row is appended to a fresh file. SIZE-based only, never time-based (see
+// the retention decision above) -- 5 MiB comfortably holds many thousands
+// of rows before rotation, and rotation never deletes evidence outright,
+// it only moves the older half out of the active file.
+const ROTATE_THRESHOLD_BYTES = 5 * 1024 * 1024;
+
+// mindrianHome() / voiceStyleLogPath() -- the MINDRIAN_HOME resolver,
+// inlined exactly as the four shipped sites do (lib/core/doctor/card-fire-
+// health-module.cjs:41-46 is the canonical one). Exported for hermetic
+// tests so tests/test-298-voice-log.cjs can point MINDRIAN_HOME at a
+// scratch directory and never touch the real ~/.mindrian.
+function mindrianHome() {
+  return process.env.MINDRIAN_HOME || path.join(os.homedir(), '.mindrian');
+}
+function voiceStyleLogPath() {
+  return path.join(mindrianHome(), 'voice-style.jsonl');
+}
+
+// resolveVersion() -- best-effort read of the repo version stamp. Never
+// throws; a failed read (e.g. this module running from a worktree checkout
+// that repo-version.cjs itself refuses, per its own contamination guard)
+// writes the string 'unknown' rather than blocking the log write.
+function resolveVersion() {
+  try {
+    // Lazy require: keeps this module loadable even in a context where
+    // repo-version.cjs's own root-resolution would throw (e.g. a scratch
+    // test directory with no plugin.json/package.json pair).
+    const { readRepoVersion } = require('../core/repo-version.cjs');
+    const result = readRepoVersion();
+    return typeof result.version === 'string' ? result.version : 'unknown';
+  } catch (_e) {
+    return 'unknown';
+  }
+}
+
+// rotateIfNeeded(fp) -- size-based rotation only (never time-based). Renames
+// the current log to `<fp>.1` (overwriting any prior `.1`) when it exceeds
+// ROTATE_THRESHOLD_BYTES, immediately before the new row is appended. Best-
+// effort: any rotation failure is swallowed and the write proceeds against
+// the (possibly oversized) existing file rather than blocking the hook.
+function rotateIfNeeded(fp) {
+  try {
+    const st = fs.statSync(fp);
+    if (st.size >= ROTATE_THRESHOLD_BYTES) {
+      fs.renameSync(fp, fp + '.1');
+    }
+  } catch (_e) {
+    /* missing file (nothing to rotate) or a rename fault; either way, proceed */
+  }
+}
+
+// appendVoiceStyleRow(row) -- fills defaults, ensures the home directory
+// exists, rotates by size if needed, then appends exactly one JSONL line.
+// Never throws (a diagnostic write must never block the calling Stop hook).
+// Returns true on a successful append, false on any failure (for testability
+// only -- no caller is required to check the return value).
+function appendVoiceStyleRow(row) {
+  try {
+    const r = row && typeof row === 'object' ? row : {};
+    const now = Date.now();
+    const detail = typeof r.detail === 'string' ? r.detail.slice(0, VOICE_STYLE_DETAIL_CAP) : '';
+    const record = {
+      ts: now,
+      timestamp: new Date(now).toISOString(),
+      policy_id: typeof r.policy_id === 'string' ? r.policy_id : '',
+      version: resolveVersion(),
+      result: typeof r.result === 'string' ? r.result : 'fire',
+      detail: detail,
+      session_id: typeof r.session_id === 'string' ? r.session_id : '',
+    };
+    const fp = voiceStyleLogPath();
+    fs.mkdirSync(path.dirname(fp), { recursive: true });
+    rotateIfNeeded(fp);
+    fs.appendFileSync(fp, JSON.stringify(record) + '\n', 'utf8');
+    return true;
+  } catch (_e) {
+    // Swallow-all: a diagnostic write must never block or throw the hook.
+    return false;
+  }
+}
+
+// readVoiceStyleRows(logPathOrNull) -- reads the log (or the given path, the
+// hermetic-test seam), splitting on newlines and JSON.parsing each line. A
+// malformed line is dropped; the surrounding rows still parse. A missing
+// file returns an empty array. Never throws.
+function readVoiceStyleRows(logPathOrNull) {
+  const fp = typeof logPathOrNull === 'string' ? logPathOrNull : voiceStyleLogPath();
+  const out = [];
+  try {
+    const raw = fs.readFileSync(fp, 'utf8');
+    const lines = raw.split('\n');
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        out.push(JSON.parse(trimmed));
+      } catch (_eLine) {
+        continue; // drop the malformed line, never throw
+      }
+    }
+  } catch (_e) {
+    /* missing / unreadable log -> empty array */
+  }
+  return out;
+}
+
+module.exports = {
+  appendVoiceStyleRow,
+  readVoiceStyleRows,
+  evaluatePromotion,
+  VOICE_STYLE_DETAIL_CAP,
+  ROTATE_THRESHOLD_BYTES,
+  // exported for hermetic tests:
+  mindrianHome,
+  voiceStyleLogPath,
+};

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.