@mindrian_os/cli 1.13.0-beta.10 → 1.13.0-beta.44

package/lib/core/folder-memory-shared.cjs

@@ -1,890 +0,0 @@
-/*
- * Copyright (c) 2026 Mindrian. BSL 1.1.
- *
- * Phase 88-01 -- folder-memory shared pure logic
- * ===============================================
- * Pure parsers + score/staleness logic for the per-folder memory triple
- * (ROOM.md + STATE.md + MINTO.md). Accepts pre-loaded buffers; performs
- * zero fs I/O. Consumed by both lib/core/folder-memory.cjs (sync entry
- * point) and lib/core/folder-memory-async.cjs (async entry point) so the
- * two surfaces emit identical shapes by construction.
- *
- * The read contract is documented in
- *   .planning/phases/88-feynman-minto-memory-layer/88-CONTEXT.md
- *     lines 99-132
- * and mirrored in the PLAN <interfaces> block. Changing the exported
- * shape here is a cross-plan-breaking change: 88-06 on-stop snapshot,
- * 88-07 session-start TRIPLE_CONTEXT injection, 88-08/88-09 compaction
- * re-injection, 88-10 decision-capture, 88-13 guardian, and the eventual
- * Phase 91 Navigation Engine all read through this module.
- *
- * Pure CJS, zero npm dependencies, node built-ins only. Mirrors Phase
- * 87-04 shared-module pattern (room-ops-shared.cjs).
- *
- * API:
- *   parseRoomMd(buf, mtimeMs) -> { exists:true, identity_text, references, last_updated_at }
- *   parseStateMd(buf)         -> { exists:true, artifact_count, gap_status,
- *                                   completeness_score, minto_health:'--',
- *                                   last_activity_at }
- *   parseMintoMd(buf, opts)   -> { exists:true, governing_thought,
- *                                   arguments_count, evidence_density,
- *                                   mece_status, decision_log,
- *                                   last_generated_at,
- *                                   last_artifact_write_seen_at,
- *                                   flagged_weaknesses,
- *                                   _parsed_ok:bool }
- *   computeStale(reasoning, artifactMtimes, mintoMtimeMs, invariantSeverity)
- *                              -> { is_stale, stale_reason }
- *   computeHealthScore(r)      -> number in [0,1]
- *   emptyRoom()/emptyState()/emptyReasoning()
- *                              -> default exists:false shells
- *
- * License: BSL 1.1.
- */
-
-'use strict';
-
-const fs = require('node:fs');
-
-// ---------- Helpers ----------
-
-const ROOM_BEGIN_MARKER = '<!-- BEGIN REFERENCES -->';
-const ROOM_END_MARKER = '<!-- END REFERENCES -->';
-// Wikilink: [[target]] or [[target|label]]
-const WIKILINK_RE = /\[\[([^\]|]+)(?:\|([^\]]+))?\]\]/g;
-
-// ---------- Phase 90-04 BRAIN.md parser constants ----------
-//
-// OPTIONAL_SECTION_HEADINGS is duplicated byte-for-byte from
-// lib/core/brain-md-schema.cjs (Phase 90-00) to preserve the flat
-// lib/core dependency graph (88-01 key-decision: no cross-import from
-// sibling contract modules). A parity test in
-// lib/memory/folder-memory-quadruple.test.cjs asserts the two arrays
-// remain byte-identical across edits. Any future heading addition MUST
-// land in both files in the same commit; drift is caught at CI time.
-
-const OPTIONAL_SECTION_HEADINGS = Object.freeze([
-  '## Pattern Matches',
-  '## Cross-Domain Analogies',
-  '## Wicked Indicators',
-  '## Unfilled Opportunity Matches',
-  '## Framework Chain Predictions',
-  '## Assessment Thinking Chain Position',
-  '## ProblemType Classification',
-  '## Flagged Contradictions (cross-room)',
-  '## HSI Signals',
-]);
-
-// Heading text -> sections key mapping. The key is the canonical slug
-// used inside the returned brain.sections object (lower_snake_case).
-// Anything outside this set is ignored (forward-compat for user-extended
-// BRAIN.md variants).
-const BRAIN_SECTION_KEY_BY_HEADING = Object.freeze({
-  '## Pattern Matches': 'pattern_matches',
-  '## Cross-Domain Analogies': 'cross_domain_analogies',
-  '## Wicked Indicators': 'wicked_indicators',
-  '## Unfilled Opportunity Matches': 'unfilled_opportunity_matches',
-  '## Framework Chain Predictions': 'framework_chain_predictions',
-  '## Assessment Thinking Chain Position': 'assessment_thinking_chain_position',
-  '## ProblemType Classification': 'problemtype_classification',
-  '## Flagged Contradictions (cross-room)': 'flagged_contradictions_xroom',
-  '## HSI Signals': 'hsi_signals',
-});
-
-function classifyRefType(target) {
-  if (!target || typeof target !== 'string') return 'artifact';
-  if (target.indexOf('/team/') !== -1 || target.indexOf('team/') === 0) return 'team';
-  if (target.indexOf('/meetings/') !== -1 || target.indexOf('meetings/') === 0) return 'meeting';
-  // Pure section reference: bare section name or section/ROOM.md
-  if (/^[a-z][a-z0-9-]+\/ROOM\.md$/i.test(target)) return 'section';
-  if (/^[a-z][a-z0-9-]+$/i.test(target)) return 'section';
-  return 'artifact';
-}
-
-// ---------- Empty / default shells ----------
-
-function emptyRoom() {
-  return {
-    exists: false,
-    identity_text: '',
-    references: [],
-    last_updated_at: null,
-  };
-}
-
-function emptyState() {
-  return {
-    exists: false,
-    artifact_count: 0,
-    gap_status: 'unknown',
-    completeness_score: 0,
-    minto_health: '--',
-    last_activity_at: null,
-  };
-}
-
-function emptyReasoning() {
-  return {
-    exists: false,
-    governing_thought: null,
-    arguments_count: 0,
-    evidence_density: 0,
-    mece_status: 'fail',
-    reasoning_health_score: 0,
-    flagged_weaknesses: [],
-    decision_log: [],
-    last_generated_at: null,
-    last_artifact_write_seen_at: null,
-    is_stale: true,
-    stale_reason: 'never_generated',
-  };
-}
-
-// ---------- ROOM.md parser ----------
-
-/**
- * Parse a ROOM.md buffer. Returns identity_text (everything outside the
- * REFERENCES marker block) and references array (one entry per wikilink
- * found INSIDE the marker block).
- *
- * @param {string} buf utf8 content of ROOM.md
- * @param {number|null} mtimeMs mtime epoch ms (for last_updated_at)
- * @returns {object}
- */
-function parseRoomMd(buf, mtimeMs) {
-  if (typeof buf !== 'string') {
-    return emptyRoom();
-  }
-
-  // Split on markers. Everything outside the markers is identity_text.
-  let identityText = buf;
-  let refsBlock = '';
-
-  const beginIdx = buf.indexOf(ROOM_BEGIN_MARKER);
-  const endIdx = buf.indexOf(ROOM_END_MARKER);
-  if (beginIdx !== -1 && endIdx !== -1 && endIdx > beginIdx) {
-    refsBlock = buf.slice(beginIdx + ROOM_BEGIN_MARKER.length, endIdx);
-    identityText = (buf.slice(0, beginIdx) + buf.slice(endIdx + ROOM_END_MARKER.length)).trim();
-  } else {
-    identityText = buf.trim();
-  }
-
-  const references = [];
-  let m;
-  // Reset regex state (global regex keeps lastIndex between calls).
-  WIKILINK_RE.lastIndex = 0;
-  while ((m = WIKILINK_RE.exec(refsBlock)) !== null) {
-    const target = m[1].trim();
-    const label = (m[2] || target).trim();
-    references.push({
-      target: target,
-      type: classifyRefType(target),
-      label: label,
-    });
-  }
-
-  return {
-    exists: true,
-    identity_text: identityText,
-    references: references,
-    last_updated_at: mtimeMs ? new Date(mtimeMs).toISOString().replace(/\.\d+Z$/, 'Z') : null,
-  };
-}
-
-// ---------- STATE.md parser ----------
-//
-// NOTE (PLAN C-4 correction): STATE.md does not carry a `MINTO health:`
-// glyph. `minto_health` is a DERIVED signal, computed from the reasoning
-// branch; we return '--' here (placeholder) and the caller synthesizes
-// a check/dot/-- glyph from `reasoning.reasoning_health_score`.
-
-/**
- * Parse a STATE.md buffer. Tolerant of both bash-rendered compute-state
- * output (Markdown tables) and hand-authored key:value shapes.
- *
- * @param {string} buf utf8 content of STATE.md
- * @returns {object}
- */
-function parseStateMd(buf) {
-  if (typeof buf !== 'string') return emptyState();
-
-  const out = {
-    exists: true,
-    artifact_count: 0,
-    gap_status: 'unknown',
-    completeness_score: 0,
-    minto_health: '--',
-    last_activity_at: null,
-  };
-
-  // artifact_count: N  OR  Artifacts: N  OR  entries: N
-  const acMatch = buf.match(/^\s*(?:artifact_count|Artifacts|entries)\s*:\s*(\d+)/mi);
-  if (acMatch) {
-    out.artifact_count = parseInt(acMatch[1], 10);
-  }
-
-  // gap_status: empty|seeded|active|complete|unknown
-  const gsMatch = buf.match(/^\s*(?:gap_status|Status)\s*:\s*([a-zA-Z-]+)/m);
-  if (gsMatch) {
-    const raw = gsMatch[1].toLowerCase();
-    if (['empty', 'seeded', 'active', 'complete', 'unknown', 'well-developed'].indexOf(raw) !== -1) {
-      out.gap_status = raw === 'well-developed' ? 'active' : raw;
-    }
-  }
-
-  // completeness_score: 0..1
-  const csMatch = buf.match(/^\s*completeness_score\s*:\s*([\d.]+)/mi);
-  if (csMatch) {
-    const v = parseFloat(csMatch[1]);
-    if (Number.isFinite(v)) out.completeness_score = Math.max(0, Math.min(1, v));
-  }
-
-  // last_activity or Last activity: YYYY-MM-DD
-  const laMatch = buf.match(/^\s*(?:last_activity(?:_at)?|Last activity)\s*:\s*(\d{4}-\d{2}-\d{2}[^\n]*)/mi);
-  if (laMatch) {
-    out.last_activity_at = laMatch[1].trim();
-  }
-
-  return out;
-}
-
-// ---------- Narrow-dialect YAML frontmatter parser for MINTO.md ----------
-//
-// Scoped copy of the parser in lib/core/feynman-minto-invariants.cjs.
-// Duplicated intentionally (per 88-00 key-decision "Narrow-dialect
-// frontmatter parser duplicated in both generator and migration"): this
-// module pulls ONLY the fields it needs from the v88 schema, which is a
-// narrower dialect than the invariants parser. Keeping the copy here
-// untangles lib/core dependency graphs (no circular require on invariants
-// for its parser half).
-
-function unquote(raw) {
-  const s = raw.trim();
-  if (s.length === 0) return '';
-  if (s === 'null') return null;
-  if (s[0] === '"') {
-    if (s.length < 2 || s[s.length - 1] !== '"') return undefined; // unterminated
-    return s.slice(1, -1);
-  }
-  if (s[0] === "'") {
-    if (s.length < 2 || s[s.length - 1] !== "'") return undefined;
-    return s.slice(1, -1);
-  }
-  if (s === '[]') return [];
-  if (s[0] === '[' && s[s.length - 1] === ']') {
-    // Flow-style list; split by comma, trim, unquote elements.
-    const inner = s.slice(1, -1).trim();
-    if (inner.length === 0) return [];
-    return inner.split(',').map((x) => unquote(x));
-  }
-  return s;
-}
-
-function parseMintoFrontmatter(fmText) {
-  const lines = fmText.split(/\r?\n/);
-  const root = {};
-  let i = 0;
-
-  while (i < lines.length) {
-    const raw = lines[i];
-    if (raw.length === 0 || /^\s*$/.test(raw) || /^\s*#/.test(raw)) {
-      i += 1;
-      continue;
-    }
-    const m = raw.match(/^([A-Za-z_][A-Za-z0-9_-]*):(.*)$/);
-    if (!m) {
-      return { ok: false, error: 'bad top-level line ' + (i + 1) };
-    }
-    const key = m[1];
-    const rest = m[2];
-
-    if (rest.trim().length > 0) {
-      const v = unquote(rest);
-      if (v === undefined) {
-        return { ok: false, error: 'unterminated scalar for key ' + key };
-      }
-      root[key] = v;
-      i += 1;
-      continue;
-    }
-
-    // Block follows -- either empty, string array, or object array.
-    i += 1;
-    const items = [];
-    let isObjectArray = false;
-    let isStringArray = false;
-
-    while (i < lines.length) {
-      const next = lines[i];
-      if (next.length === 0 || /^\s*$/.test(next) || /^\s*#/.test(next)) {
-        i += 1;
-        continue;
-      }
-      // Object entry: `  - key: value`
-      const objHead = next.match(/^\s+-\s+([A-Za-z_][A-Za-z0-9_-]*):\s*(.*)$/);
-      if (objHead) {
-        isObjectArray = true;
-        const obj = {};
-        const vraw = objHead[2];
-        const v = unquote(vraw);
-        if (v === undefined) {
-          return { ok: false, error: 'unterminated scalar in object array for ' + key };
-        }
-        obj[objHead[1]] = v;
-        i += 1;
-        while (i < lines.length) {
-          const cont = lines[i];
-          if (cont.length === 0 || /^\s*$/.test(cont)) { i += 1; continue; }
-          const contMatch = cont.match(/^\s+([A-Za-z_][A-Za-z0-9_-]*):\s*(.*)$/);
-          if (/^\s+-\s/.test(cont) || !contMatch) break;
-          const cvRaw = contMatch[2];
-          const cv = unquote(cvRaw);
-          if (cv === undefined) {
-            return { ok: false, error: 'unterminated scalar in object array cont for ' + key };
-          }
-          obj[contMatch[1]] = cv;
-          i += 1;
-        }
-        items.push(obj);
-        continue;
-      }
-      const strItem = next.match(/^\s+-\s+(.*)$/);
-      if (strItem) {
-        isStringArray = true;
-        const v = unquote(strItem[1]);
-        if (v === undefined) {
-          return { ok: false, error: 'unterminated scalar in string array for ' + key };
-        }
-        items.push(v);
-        i += 1;
-        continue;
-      }
-      if (/^[A-Za-z_]/.test(next)) break;
-      i += 1;
-    }
-
-    if (isStringArray && isObjectArray) {
-      return { ok: false, error: 'mixed string/object array for ' + key };
-    }
-    root[key] = items;
-  }
-
-  return { ok: true, data: root };
-}
-
-// ---------- Body metrics (MECE + evidence density) ----------
-
-function extractBodyMetrics(body) {
-  // arguments_count: count MECE argument headers or '## ' claim-level
-  // sections in the body. We look for `### Claim N:` pattern (matches the
-  // Phase 81 generator output) and '## Key Claims' / MECE sections.
-  let argumentsCount = 0;
-  const claimMatches = body.match(/^###\s+Claim\s+\d+/gim);
-  if (claimMatches) argumentsCount = claimMatches.length;
-  if (argumentsCount === 0) {
-    // Fallback: count top-level claim bullets under "Key Claims".
-    const keyClaimsMatch = body.match(/^##\s+Key Claims[\s\S]*?(?=^##\s|\Z)/m);
-    if (keyClaimsMatch) {
-      const bullets = keyClaimsMatch[0].match(/^-\s+/gm);
-      if (bullets) argumentsCount = bullets.length;
-    }
-  }
-
-  // evidence_density: citations / claims. Citation = "Source:" marker or
-  // `[[...]]` wikilink inside an Evidence block.
-  const citations = (body.match(/Source:\s*/g) || []).length;
-  const evidenceDensity = argumentsCount === 0 ? 0 : Math.min(1, citations / Math.max(1, argumentsCount));
-
-  // mece_status: presence of "MECE Issue Tree" section + non-empty
-  const meceMatch = body.match(/^##\s+MECE (?:Issue Tree|Arguments?)[\s\S]*?(?=^##\s|\Z)/m);
-  let meceStatus = 'fail';
-  if (meceMatch) {
-    const block = meceMatch[0];
-    const bulletCount = (block.match(/^\s*-\s+/gm) || []).length;
-    if (bulletCount >= 3) meceStatus = 'pass';
-    else if (bulletCount >= 1) meceStatus = 'warn';
-  }
-
-  return { argumentsCount, evidenceDensity, meceStatus };
-}
-
-// ---------- MINTO.md parser ----------
-
-/**
- * Parse a MINTO.md buffer.
- *
- * @param {string} buf utf8 content
- * @returns {object} reasoning-branch fields (without staleness)
- */
-function parseMintoMd(buf) {
-  const out = {
-    exists: true,
-    governing_thought: null,
-    arguments_count: 0,
-    evidence_density: 0,
-    mece_status: 'fail',
-    flagged_weaknesses: [],
-    decision_log: [],
-    last_generated_at: null,
-    last_artifact_write_seen_at: null,
-    _parsed_ok: false,
-  };
-
-  if (typeof buf !== 'string' || buf.length === 0) return out;
-
-  const fmRe = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/;
-  const m = buf.match(fmRe);
-  if (!m) {
-    // No frontmatter at all -- parse failed.
-    out._parsed_ok = false;
-    return out;
-  }
-
-  const parsed = parseMintoFrontmatter(m[1]);
-  if (!parsed.ok) {
-    out._parsed_ok = false;
-    return out;
-  }
-  const fm = parsed.data;
-  const body = m[2] || '';
-
-  // governing_thought: prefer frontmatter field (v88 schema); fall back
-  // to "> [!abstract] Governing Thought\n> text" from body.
-  if (typeof fm.governing_thought === 'string' && fm.governing_thought.length > 0) {
-    out.governing_thought = fm.governing_thought;
-  } else {
-    const gtMatch = body.match(/>\s*\[!abstract\]\s+Governing Thought\s*\n>\s*([^\n]+)/);
-    if (gtMatch) out.governing_thought = gtMatch[1].trim();
-  }
-
-  if (typeof fm.last_generated_at === 'string') {
-    out.last_generated_at = fm.last_generated_at;
-  } else if (fm.last_generated_at === null) {
-    out.last_generated_at = null;
-  }
-  if (typeof fm.last_artifact_write_seen_at === 'string') {
-    out.last_artifact_write_seen_at = fm.last_artifact_write_seen_at;
-  }
-
-  if (Array.isArray(fm.flagged_weaknesses)) {
-    out.flagged_weaknesses = fm.flagged_weaknesses.filter((x) => typeof x === 'string');
-  }
-
-  if (Array.isArray(fm.decision_log)) {
-    // Preserve write order (oldest first). Guardian enforces caps; read
-    // is permissive.
-    out.decision_log = fm.decision_log
-      .filter((e) => e && typeof e === 'object')
-      .map((e) => ({
-        session_id: typeof e.session_id === 'string' ? e.session_id : '',
-        timestamp: typeof e.timestamp === 'string' ? e.timestamp : '',
-        action: typeof e.action === 'string' ? e.action : '',
-        user_response: typeof e.user_response === 'string' ? e.user_response : '',
-        reason: typeof e.reason === 'string' ? e.reason : '',
-        outcome: typeof e.outcome === 'string' ? e.outcome : undefined,
-      }));
-  }
-
-  const bm = extractBodyMetrics(body);
-  out.arguments_count = bm.argumentsCount;
-  out.evidence_density = bm.evidenceDensity;
-  out.mece_status = bm.meceStatus;
-  out._parsed_ok = true;
-
-  return out;
-}
-
-// ---------- Staleness computation ----------
-
-/**
- * Compute staleness signal for a parsed reasoning branch.
- *
- * @param {object} reasoning fields from parseMintoMd
- * @param {Array<number>} artifactMtimes ms epochs of section artifact files
- * @param {number|null} mintoMtimeMs ms epoch of MINTO.md itself
- * @param {string|null} invariantSeverity 'critical' | ... | null from 88-00-B validate
- * @returns {{is_stale:boolean, stale_reason:string|null}}
- */
-function computeStale(reasoning, artifactMtimes, mintoMtimeMs, invariantSeverity) {
-  if (invariantSeverity === 'critical') {
-    return { is_stale: true, stale_reason: 'invariant_violation' };
-  }
-  if (reasoning._parsed_ok === false) {
-    return { is_stale: true, stale_reason: 'parse_failed' };
-  }
-
-  const lga = reasoning.last_generated_at;
-  // Sentinel zero timestamp from 88-00 migration = never regenerated under v88
-  if (lga === '1970-01-01T00:00:00Z') {
-    return { is_stale: true, stale_reason: 'never_generated' };
-  }
-  // Field absent entirely -> missing_timestamps (distinguishes "never
-  // migrated under v88" sentinel from "no timestamp at all" edge case).
-  if (lga == null || lga === '') {
-    return { is_stale: true, stale_reason: 'missing_timestamps' };
-  }
-
-  const lgaMs = Date.parse(lga);
-  if (!Number.isFinite(lgaMs)) {
-    return { is_stale: true, stale_reason: 'missing_timestamps' };
-  }
-
-  // Compare artifact mtimes to MINTO generation time.
-  const referenceMs = mintoMtimeMs != null ? mintoMtimeMs : lgaMs;
-  if (Array.isArray(artifactMtimes)) {
-    for (const mt of artifactMtimes) {
-      if (Number.isFinite(mt) && mt > referenceMs + 1000) {
-        return { is_stale: true, stale_reason: 'artifacts_newer_than_minto' };
-      }
-    }
-  }
-
-  return { is_stale: false, stale_reason: null };
-}
-
-// ---------- Health score ----------
-
-/**
- * computeHealthScore(reasoning) -> number in [0,1]
- *
- * Formula (from PLAN <interfaces> block):
- *   + 0.3 if governing_thought non-empty
- *   + 0.2 * min(arguments_count / 3, 1)
- *   + 0.2 * min(evidence_density, 1)
- *   + 0.1 if mece_status == 'pass' (0.05 if warn, 0 if fail)
- *   + 0.2 if is_stale == false
- * Clamped to [0, 1].
- */
-function computeHealthScore(r) {
-  if (!r || typeof r !== 'object') return 0;
-  let s = 0;
-  if (typeof r.governing_thought === 'string' && r.governing_thought.length > 0) s += 0.3;
-  const ac = typeof r.arguments_count === 'number' ? r.arguments_count : 0;
-  s += 0.2 * Math.min(ac / 3, 1);
-  const ed = typeof r.evidence_density === 'number' ? r.evidence_density : 0;
-  s += 0.2 * Math.min(Math.max(ed, 0), 1);
-  if (r.mece_status === 'pass') s += 0.1;
-  else if (r.mece_status === 'warn') s += 0.05;
-  if (r.is_stale === false) s += 0.2;
-  return Math.max(0, Math.min(1, s));
-}
-
-// ---------- Phase 90-04 BRAIN.md parser ----------
-//
-// Pure helper that consumes a BRAIN.md file path and returns either
-// null (file absent) or a structured object:
-//
-//   {
-//     exists: true,
-//     section: string,
-//     brain_generated_at: string | null,
-//     brain_graph_version: number | null,
-//     governing_thought_hash: string | null,
-//     staleness: 'fresh' | 'stale' | 'unavailable',
-//     stale_reason: string | null,
-//     author: string,
-//     confidence_baseline: number | null,
-//     parse_failed: boolean,
-//     sections: {
-//       pattern_matches: null | {body, tokens_estimate},
-//       cross_domain_analogies: null | {body, tokens_estimate},
-//       wicked_indicators: null | {body, tokens_estimate},
-//       unfilled_opportunity_matches: null | {body, tokens_estimate},
-//       framework_chain_predictions: null | {body, tokens_estimate},
-//       assessment_thinking_chain_position: null | {body, tokens_estimate},
-//       problemtype_classification: null | {body, tokens_estimate},
-//       flagged_contradictions_xroom: null | {body, tokens_estimate},
-//       hsi_signals: null | {body, tokens_estimate},
-//     },
-//     flagged_weaknesses: string[]
-//   }
-//
-// Precedence (mirrors Phase 88-01 emptyReasoning staleness pattern):
-//   1. BRAIN.md absent                         -> null (literal)
-//   2. Empty / non-regular file                -> emptyBrain, parse_failed:true, staleness:'stale'
-//   3. Frontmatter delimiter missing           -> emptyBrain, parse_failed:true
-//   4. Narrow-dialect YAML unparseable         -> emptyBrain, parse_failed:true
-//   5. Valid                                   -> full struct, parse_failed:false
-//
-// Graceful degradation: NEVER throws. Every failure returns a struct
-// with parse_failed:true rather than propagating an exception up to
-// readQuadruple callers (session-start, Navigation Engine, dashboard).
-//
-// Pure I/O: this module owns the BRAIN.md read boundary inside shared.
-// Keeping the I/O here keeps folder-memory.cjs (sync) and
-// folder-memory-async.cjs (async) free of duplicate file-open code while
-// respecting the 88-01 pattern of "shared owns parsers, entry points own
-// orchestration."
-
-function emptyBrainSections() {
-  return {
-    pattern_matches: null,
-    cross_domain_analogies: null,
-    wicked_indicators: null,
-    unfilled_opportunity_matches: null,
-    framework_chain_predictions: null,
-    assessment_thinking_chain_position: null,
-    problemtype_classification: null,
-    flagged_contradictions_xroom: null,
-    hsi_signals: null,
-  };
-}
-
-function emptyBrain() {
-  return {
-    exists: false,
-    section: '',
-    brain_generated_at: null,
-    brain_graph_version: null,
-    governing_thought_hash: null,
-    staleness: 'unavailable',
-    stale_reason: null,
-    author: '',
-    confidence_baseline: null,
-    parse_failed: false,
-    sections: emptyBrainSections(),
-    flagged_weaknesses: [],
-  };
-}
-
-// Narrow-dialect YAML scalar parser scoped to BRAIN.md fields (flat
-// scalars only: strings, ints, floats, booleans, null). Mirrors the
-// dialect used in lib/core/brain-md-schema.cjs and
-// lib/core/brain-md-staleness.cjs; duplicated here intentionally so
-// shared keeps zero cross-import into those modules (flat dep graph).
-
-function unquoteBrainScalar(raw) {
-  const s = raw.trim();
-  if (s.length === 0) return '';
-  if (s[0] === '"') {
-    if (s.length < 2 || s[s.length - 1] !== '"') return undefined;
-    return s.slice(1, -1);
-  }
-  if (s[0] === "'") {
-    if (s.length < 2 || s[s.length - 1] !== "'") return undefined;
-    return s.slice(1, -1);
-  }
-  return s;
-}
-
-function castBrainScalar(s) {
-  if (s === 'null' || s === '~') return null;
-  if (s === 'true') return true;
-  if (s === 'false') return false;
-  if (/^-?\d+$/.test(s)) {
-    const n = parseInt(s, 10);
-    if (Number.isSafeInteger(n)) return n;
-  }
-  if (/^-?\d+\.\d+$/.test(s)) {
-    const f = parseFloat(s);
-    if (Number.isFinite(f)) return f;
-  }
-  return s;
-}
-
-function parseBrainFrontmatter(src) {
-  if (typeof src !== 'string' || src.length === 0) {
-    return { ok: false };
-  }
-  const lines = src.split(/\r?\n/);
-  const root = {};
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    if (line.length === 0 || /^\s*$/.test(line) || /^\s*#/.test(line)) continue;
-    const m = line.match(/^([A-Za-z_][A-Za-z0-9_-]*):(.*)$/);
-    if (!m) return { ok: false };
-    const key = m[1];
-    const rest = m[2];
-    if (rest.trim().length === 0) {
-      root[key] = '';
-      continue;
-    }
-    const raw = unquoteBrainScalar(rest);
-    if (raw === undefined) return { ok: false };
-    root[key] = castBrainScalar(raw);
-  }
-  return { ok: true, data: root };
-}
-
-// Walk the body for any "## " line. For each line that matches one of
-// BRAIN_SECTION_KEY_BY_HEADING, capture the body bytes until the next
-// "## " or EOF. Unknown headings are silently skipped (future-compat).
-
-function extractBrainSections(body) {
-  const sections = emptyBrainSections();
-  if (typeof body !== 'string' || body.length === 0) return sections;
-  const lines = body.split(/\r?\n/);
-
-  let currentKey = null;
-  let currentBuf = [];
-
-  function flush() {
-    if (currentKey) {
-      const bodyText = currentBuf.join('\n').replace(/^\n+/, '').replace(/\n+$/, '');
-      if (bodyText.length > 0) {
-        sections[currentKey] = {
-          body: bodyText,
-          tokens_estimate: Math.ceil(bodyText.length / 4),
-        };
-      }
-    }
-    currentKey = null;
-    currentBuf = [];
-  }
-
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    if (/^##\s+/.test(line)) {
-      flush();
-      // Heading text is the full "## Heading" line, normalized by
-      // stripping any trailing whitespace (leading '## ' preserved).
-      const headingTrim = line.replace(/\s+$/, '');
-      const key = BRAIN_SECTION_KEY_BY_HEADING[headingTrim];
-      if (key) {
-        currentKey = key;
-      } else {
-        // Unknown heading: we still flush any accumulating body but
-        // drop this block by leaving currentKey null. Bytes between
-        // this unknown heading and the next known heading are ignored
-        // (future-compat).
-        currentKey = null;
-      }
-      continue;
-    }
-    if (currentKey) currentBuf.push(line);
-  }
-  flush();
-  return sections;
-}
-
-/**
- * parseBrainMd(filePath) -> null | struct
- *
- * null  when the file is absent.
- * struct when the file is present; parse_failed reflects whether the
- * frontmatter parsed cleanly.
- *
- * Never throws.
- */
-function parseBrainMd(filePath) {
-  if (typeof filePath !== 'string' || filePath.length === 0) return null;
-
-  let stat;
-  try {
-    stat = fs.statSync(filePath);
-  } catch (_e) {
-    return null; // absent
-  }
-  if (!stat.isFile()) return null;
-
-  // Empty / non-regular -> emptyBrain parse_failed
-  if (stat.size === 0) {
-    const shell = emptyBrain();
-    shell.exists = true;
-    shell.parse_failed = true;
-    shell.staleness = 'stale';
-    return shell;
-  }
-
-  let raw;
-  try {
-    raw = fs.readFileSync(filePath, 'utf8');
-  } catch (_e) {
-    const shell = emptyBrain();
-    shell.exists = true;
-    shell.parse_failed = true;
-    shell.staleness = 'stale';
-    return shell;
-  }
-
-  const fmRe = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
-  const m = raw.match(fmRe);
-  if (!m) {
-    const shell = emptyBrain();
-    shell.exists = true;
-    shell.parse_failed = true;
-    shell.staleness = 'stale';
-    return shell;
-  }
-
-  const parsed = parseBrainFrontmatter(m[1]);
-  if (!parsed.ok) {
-    const shell = emptyBrain();
-    shell.exists = true;
-    shell.parse_failed = true;
-    shell.staleness = 'stale';
-    return shell;
-  }
-  const fm = parsed.data;
-  const body = m[2] || '';
-
-  const brain = emptyBrain();
-  brain.exists = true;
-  brain.parse_failed = false;
-
-  brain.section = typeof fm.section === 'string' ? fm.section : '';
-  brain.brain_generated_at = typeof fm.brain_generated_at === 'string' && fm.brain_generated_at.length > 0
-    ? fm.brain_generated_at
-    : null;
-  brain.brain_graph_version = typeof fm.brain_graph_version === 'number'
-    ? fm.brain_graph_version
-    : null;
-  brain.governing_thought_hash = typeof fm.governing_thought_hash === 'string' && fm.governing_thought_hash.length > 0
-    ? fm.governing_thought_hash
-    : null;
-  brain.staleness = (
-    fm.staleness === 'fresh' ||
-    fm.staleness === 'stale' ||
-    fm.staleness === 'unavailable'
-  ) ? fm.staleness : 'unavailable';
-  brain.stale_reason = (fm.stale_reason === null || fm.stale_reason === undefined || fm.stale_reason === '')
-    ? null
-    : fm.stale_reason;
-  brain.author = typeof fm.author === 'string' ? fm.author : '';
-  brain.confidence_baseline = typeof fm.confidence_baseline === 'number'
-    ? fm.confidence_baseline
-    : null;
-
-  brain.sections = extractBrainSections(body);
-  brain.flagged_weaknesses = []; // BRAIN.md schema does not populate this
-                                 // via narrow-dialect YAML arrays; the
-                                 // field stays as [] for forward-compat
-                                 // with Plan 90-05 invariants validator.
-
-  return brain;
-}
-
-/**
- * attachBrainToTriple(triple, brainStruct) -> {room, state, reasoning, brain}
- *
- * Pure assembler. Does NOT copy triple fields; the returned object
- * references the same room/state/reasoning objects as the input
- * (consistent with Phase 88-01 readTriple output -- callers treat the
- * returned object as read-only). Adds a brain field without mutating
- * the input.
- */
-function attachBrainToTriple(triple, brainStruct) {
-  const t = triple || {};
-  return {
-    room: t.room,
-    state: t.state,
-    reasoning: t.reasoning,
-    brain: brainStruct === undefined ? null : brainStruct,
-  };
-}
-
-module.exports = {
-  parseRoomMd: parseRoomMd,
-  parseStateMd: parseStateMd,
-  parseMintoMd: parseMintoMd,
-  parseBrainMd: parseBrainMd,
-  computeStale: computeStale,
-  computeHealthScore: computeHealthScore,
-  emptyRoom: emptyRoom,
-  emptyState: emptyState,
-  emptyReasoning: emptyReasoning,
-  emptyBrain: emptyBrain,
-  attachBrainToTriple: attachBrainToTriple,
-  classifyRefType: classifyRefType,
-  OPTIONAL_SECTION_HEADINGS: OPTIONAL_SECTION_HEADINGS,
-};