@mindrian_os/install 1.13.0-beta.11

package/lib/core/framework-chain-composer.cjs

@@ -0,0 +1,411 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 91-08 -- Framework Chain Composer (FEEDS_INTO chain proposal)
+ * ====================================================================
+ * Pure module. Parses BRAIN.md framework_chain_predictions section bodies
+ * authored by Phase 90-01 deriveSection and proposes the next framework
+ * to run when the user just completed framework A. The proposal becomes
+ * an engine.offer_next_step candidate consumed by the navigation engine
+ * (Plan 91-00) and rendered through the offer presenter (Plan 91-04).
+ *
+ * Canon Part 2 Engine 1 + Appendix E:
+ *   Framework chains power Act 1 -> BONO Orchestration handoffs.
+ *   FEEDS_INTO is the Brain-flagged graph infrastructure (~40 edges in
+ *   the curriculum graph as of v1.10.18). This plan converts that
+ *   infrastructure into a user-facing capability per locked decision
+ *   D-09 (Composable Methodology Adapters).
+ *
+ * Canon Part 3 Section 6 RECOMMENDED gate:
+ *   The composer marks a proposal as recommended_eligible when its
+ *   confidence is >= 0.7 (RECOMMENDED_FLOOR). The presenter respects
+ *   this flag only when Mode A holds (brain reachable + fresh) -- the
+ *   engine writes both flags into decision_trace and the presenter
+ *   renders the marker only when both are true.
+ *
+ * Canon Part 7 (Reuse Before Build):
+ *   FEEDS_INTO edges are existing graph infrastructure. Phase 90-01
+ *   wrote them into BRAIN.md framework_chain_predictions sections via
+ *   deriveSection. This module CONSUMES that representation without
+ *   inventing a new chain format.
+ *
+ * Canon Part 8 (Graph Boundary):
+ *   The composer reads ONLY the LOCAL BRAIN.md body via the section
+ *   shape passed in by callers (readQuadruple.brain.sections). It NEVER
+ *   queries Brain at engine time. The pre-derivation ran in Phase 90-01
+ *   inside the buildBrainQueryContext chokepoint. Zero network. Zero
+ *   shell-out. Zero brain-client touches.
+ *
+ * Pure module: zero throws, minimal fs touches (only detectCompleted-
+ * Framework's mtime fallback uses fs.readdir + fs.stat, both wrapped in
+ * try/catch).
+ *
+ * License: BSL 1.1.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// ---------- Frozen constants ----------
+
+// Confidence gates per locked decision in PLAN frontmatter:
+//   < 0.5  -> null (noise floor; proposal suppressed)
+//   >= 0.5 -> proposal returned (no RECOMMENDED marker eligibility)
+//   >= 0.7 -> proposal returned + recommended_eligible:true
+const NOISE_FLOOR = 0.5;
+const RECOMMENDED_FLOOR = 0.7;
+
+// Recent-write window for mtime fallback completion detection. Five
+// minutes per PLAN frontmatter (Wave 3 acceptable heuristic; future
+// plans may layer richer signal on top).
+const RECENT_WRITE_WINDOW_MS = 5 * 60 * 1000;
+
+// Bootstrap KNOWN_FRAMEWORKS list. Order is preservation-friendly with
+// existing /mos:* commands. The list is conservative; Brain-derived
+// FEEDS_INTO edges may reference frameworks outside this set (in which
+// case completion detection falls through to the mtime slug fallback,
+// and command mapping falls through to /mos:beautiful-question). The
+// list is extensible; future plans may pull from the Brain frameworks
+// catalog directly.
+const KNOWN_FRAMEWORKS = Object.freeze([
+  'SWOT Analysis',
+  'Porter Five Forces',
+  'Value Chain Analysis',
+  'Business Model Canvas',
+  'Lean Canvas',
+  'Jobs-to-be-Done',
+  'Value Proposition Canvas',
+  '5 Whys',
+  'First Principles',
+  'Design Thinking',
+  'Blue Ocean Strategy',
+  "Innovator's Dilemma",
+  '7 S Framework',
+  'Balanced Scorecard',
+  'Mullins',
+  'Beautiful Question',
+  'Soft Systems',
+  'Rich Pictures',
+]);
+
+// Map known framework names to canonical /mos: command slugs. This is a
+// best-effort table; unknown frameworks fall back to the
+// /mos:beautiful-question guide command per plan locked decisions.
+// The map is intentionally case-insensitive at lookup time so a Brain
+// edge "Lean Canvas" or "lean canvas" resolves identically.
+const FRAMEWORK_TO_COMMAND_SLUG = Object.freeze({
+  'swot analysis': 'beautiful-question', // No dedicated /mos:swot today; bypass to BQ guide.
+  'porter five forces': 'beautiful-question',
+  'value chain analysis': 'beautiful-question',
+  'business model canvas': 'beautiful-question',
+  'lean canvas': 'lean-canvas',
+  'jobs-to-be-done': 'beautiful-question',
+  'value proposition canvas': 'beautiful-question',
+  '5 whys': 'beautiful-question',
+  'first principles': 'beautiful-question',
+  'design thinking': 'beautiful-question',
+  'blue ocean strategy': 'beautiful-question',
+  "innovator's dilemma": 'beautiful-question',
+  '7 s framework': 'beautiful-question',
+  'balanced scorecard': 'beautiful-question',
+  'mullins': 'mullins',
+  'beautiful question': 'beautiful-question',
+  'soft systems': 'beautiful-question',
+  'rich pictures': 'beautiful-question',
+});
+
+// Default fallback command when the next framework has no known mapping.
+const FALLBACK_COMMAND_SLUG = 'beautiful-question';
+
+// ---------- Section parser ----------
+
+/**
+ * parseFrameworkChainSection(section) -> edges[]
+ *
+ * Parses BRAIN.md framework_chain_predictions section body into an array
+ * of FEEDS_INTO edges. Returns [] on null / undefined / empty / no-signal.
+ *
+ * Tolerant of two body formats:
+ *   1. "Framework A FEEDS_INTO Framework B (confidence: 0.85, phase: x)"
+ *   2. "Framework A -> Framework B (confidence: 0.85)"
+ *
+ * Confidence may be omitted; the resulting edge.confidence is null
+ * (preserved per plan Test 4 -- the structural relationship survives so
+ * downstream gating can decide).
+ *
+ * Each line that does not match either pattern is silently skipped.
+ *
+ * @param {object|null} section -- {body, tokens_estimate} or null
+ * @returns {Array<{from:string, to:string, confidence:number|null, phase_indicator:string|null}>}
+ */
+function parseFrameworkChainSection(section) {
+  if (section === null || section === undefined) return [];
+  if (typeof section !== 'object') return [];
+  const body = section.body;
+  if (typeof body !== 'string' || body.length === 0) return [];
+  if (/^\s*\(no\s*signal\)\s*$/i.test(body)) return [];
+
+  const out = [];
+  const lines = body.split(/\r?\n/);
+
+  // Primary pattern: FEEDS_INTO with optional (confidence: ..., phase: ...) tail.
+  // Tolerates leading bullet/whitespace and forms with no confidence.
+  // Captures: from, to, confidence (optional), phase (optional).
+  // We extract in two passes (with-tail then bare) to keep the regex simple.
+  const reFeedsWithTail = /^[\s\-*]*(.+?)\s+FEEDS_INTO\s+(.+?)\s*\(\s*(?:confidence|conf)\s*:\s*([01](?:\.\d+)?|0?\.\d+)(?:\s*,\s*phase\s*:\s*([^)]+?))?\s*\)\s*$/i;
+  const reFeedsBare = /^[\s\-*]*(.+?)\s+FEEDS_INTO\s+(.+?)\s*$/i;
+  const reArrowWithTail = /^[\s\-*]*(.+?)\s*->\s*(.+?)\s*\(\s*(?:confidence|conf)\s*:\s*([01](?:\.\d+)?|0?\.\d+)(?:\s*,\s*phase\s*:\s*([^)]+?))?\s*\)\s*$/i;
+
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/\s+$/u, ''); // rtrim
+    if (line.length === 0) continue;
+
+    let m = reFeedsWithTail.exec(line);
+    if (m) {
+      const from = m[1].trim();
+      const to = m[2].trim();
+      const conf = parseConfidenceOrNull(m[3]);
+      const phase = m[4] !== undefined && m[4] !== null ? m[4].trim() : null;
+      if (from.length > 0 && to.length > 0) {
+        out.push({ from: from, to: to, confidence: conf, phase_indicator: phase });
+      }
+      continue;
+    }
+
+    m = reArrowWithTail.exec(line);
+    if (m) {
+      const from = m[1].trim();
+      const to = m[2].trim();
+      const conf = parseConfidenceOrNull(m[3]);
+      const phase = m[4] !== undefined && m[4] !== null ? m[4].trim() : null;
+      if (from.length > 0 && to.length > 0) {
+        out.push({ from: from, to: to, confidence: conf, phase_indicator: phase });
+      }
+      continue;
+    }
+
+    // FEEDS_INTO bare (no parenthetical) -- preserve edge with null
+    // confidence per Test 4.
+    m = reFeedsBare.exec(line);
+    if (m) {
+      const from = m[1].trim();
+      const to = m[2].trim();
+      if (from.length > 0 && to.length > 0) {
+        out.push({ from: from, to: to, confidence: null, phase_indicator: null });
+      }
+      continue;
+    }
+    // No match -> silent skip (forward-compat with future formats).
+  }
+
+  return out;
+}
+
+function parseConfidenceOrNull(s) {
+  if (typeof s !== 'string') return null;
+  const v = parseFloat(s);
+  if (!Number.isFinite(v)) return null;
+  if (v < 0 || v > 1) return null;
+  return v;
+}
+
+// ---------- Completion detection ----------
+
+/**
+ * detectCompletedFramework(roomDir, sectionPath, reasoning) -> string|null
+ *
+ * Detects which framework the user just completed via two cascading paths:
+ *   1. Primary: governing_thought substring match against KNOWN_FRAMEWORKS
+ *      (case-insensitive). Returns the canonical framework name from
+ *      KNOWN_FRAMEWORKS (preserves canonical capitalization).
+ *   2. Fallback: scan section_path for files whose basename slug matches
+ *      a known framework slug, with mtime within the recent-write window
+ *      (5 minutes). Returns the canonical framework name on match.
+ *
+ * Returns null on no signal. Never throws.
+ *
+ * @param {string} roomDir
+ * @param {string} sectionPath -- absolute path to active section dir
+ * @param {object|null} reasoning -- quadruple.reasoning shape (may be null)
+ * @returns {string|null}
+ */
+function detectCompletedFramework(roomDir, sectionPath, reasoning) {
+  // Primary path: governing_thought match.
+  if (reasoning && typeof reasoning === 'object') {
+    const gt = reasoning.governing_thought;
+    if (typeof gt === 'string' && gt.length > 0) {
+      const lc = gt.toLowerCase();
+      // Case-insensitive substring match against canonical framework
+      // names. Iterate KNOWN_FRAMEWORKS in declaration order so longer/
+      // more-specific names that contain shorter names (e.g. "Lean
+      // Canvas" vs "Canvas") get matched correctly. We do NOT need to
+      // dedupe; first match wins.
+      for (const fw of KNOWN_FRAMEWORKS) {
+        if (lc.indexOf(fw.toLowerCase()) !== -1) {
+          return fw;
+        }
+      }
+    }
+  }
+
+  // Fallback: mtime scan of section directory.
+  if (typeof sectionPath === 'string' && sectionPath.length > 0) {
+    try {
+      const stat = fs.statSync(sectionPath);
+      if (stat.isDirectory()) {
+        const now = Date.now();
+        const entries = fs.readdirSync(sectionPath, { withFileTypes: true });
+        for (const entry of entries) {
+          if (!entry.isFile()) continue;
+          const filePath = path.join(sectionPath, entry.name);
+          let fileStat;
+          try {
+            fileStat = fs.statSync(filePath);
+          } catch (_) {
+            continue;
+          }
+          if (now - fileStat.mtimeMs > RECENT_WRITE_WINDOW_MS) continue;
+          // Slug-match the basename (without extension) against known
+          // framework slugs.
+          const base = entry.name.replace(/\.[^.]+$/u, '').toLowerCase();
+          const baseSlug = base.replace(/[\s_]+/g, '-');
+          for (const fw of KNOWN_FRAMEWORKS) {
+            const fwSlug = fw.toLowerCase().replace(/[\s_]+/g, '-');
+            if (baseSlug === fwSlug || baseSlug.indexOf(fwSlug) !== -1) {
+              return fw;
+            }
+          }
+        }
+      }
+    } catch (_) {
+      // missing dir / permission denied / etc -> fall through to null
+    }
+  }
+
+  return null;
+}
+
+// ---------- Chain proposal ----------
+
+/**
+ * proposeNextFramework(completedFramework, edges) -> proposal|null
+ *
+ * Filters edges by edge.from === completedFramework (case-insensitive),
+ * sorts by confidence descending (null confidence sorts last), takes the
+ * top edge, applies the noise gate (< 0.5 -> null), maps the next
+ * framework to a /mos: command, and returns the proposal.
+ *
+ * Output:
+ *   {
+ *     next: string,                  // canonical "next" framework name
+ *     confidence: number,
+ *     source: 'FEEDS_INTO',
+ *     phase_indicator: string|null,
+ *     command: string,               // '/mos:<slug>'
+ *     reason: string,                // grounding text (FEEDS_INTO + Brain + confidence)
+ *     recommended_eligible: boolean, // true when confidence >= 0.7
+ *   }
+ *
+ * Returns null when:
+ *   - completedFramework is null/empty
+ *   - edges is null/empty
+ *   - no edge has matching from
+ *   - top edge confidence < 0.5
+ *
+ * Never throws.
+ *
+ * @param {string|null} completedFramework
+ * @param {Array} edges
+ * @returns {object|null}
+ */
+function proposeNextFramework(completedFramework, edges) {
+  if (typeof completedFramework !== 'string' || completedFramework.length === 0) return null;
+  if (!Array.isArray(edges) || edges.length === 0) return null;
+
+  const targetLc = completedFramework.toLowerCase();
+
+  // Filter: edge.from must match completedFramework (case-insensitive).
+  const matching = [];
+  for (const e of edges) {
+    if (!e || typeof e !== 'object') continue;
+    const f = typeof e.from === 'string' ? e.from : null;
+    const t = typeof e.to === 'string' ? e.to : null;
+    if (f === null || t === null) continue;
+    if (f.toLowerCase() !== targetLc) continue;
+    matching.push(e);
+  }
+  if (matching.length === 0) return null;
+
+  // Sort by confidence descending (null sorts last).
+  matching.sort(function (a, b) {
+    const ac = (typeof a.confidence === 'number') ? a.confidence : -Infinity;
+    const bc = (typeof b.confidence === 'number') ? b.confidence : -Infinity;
+    return bc - ac;
+  });
+
+  const top = matching[0];
+  const conf = (typeof top.confidence === 'number') ? top.confidence : null;
+
+  // Noise gate: < 0.5 -> null. null confidence is ALSO suppressed by
+  // the noise gate (we cannot certify a confidenceless edge).
+  if (conf === null || conf < NOISE_FLOOR) return null;
+
+  // Map next to /mos: command.
+  const slug = mapFrameworkToCommandSlug(top.to);
+  const command = '/mos:' + slug;
+
+  // Grounding-rule reason: must contain FEEDS_INTO + Brain + the
+  // confidence number per Plan 91-04 presenter contract + Test 13.
+  const confStr = conf.toFixed(2);
+  const reason =
+    completedFramework + ' FEEDS_INTO ' + top.to +
+    ' (Brain confidence ' + confStr + '). Continuing the chain keeps pedagogical flow.';
+
+  return {
+    next: top.to,
+    confidence: conf,
+    source: 'FEEDS_INTO',
+    phase_indicator: (typeof top.phase_indicator === 'string') ? top.phase_indicator : null,
+    command: command,
+    reason: reason,
+    recommended_eligible: conf >= RECOMMENDED_FLOOR,
+  };
+}
+
+/**
+ * mapFrameworkToCommandSlug(name) -> slug
+ *
+ * Maps a framework name (in any case) to a /mos: command slug via the
+ * frozen FRAMEWORK_TO_COMMAND_SLUG table. Falls back to FALLBACK_COMMAND_
+ * SLUG ('beautiful-question') when no entry matches. Pure: no I/O.
+ *
+ * @param {string} name
+ * @returns {string}
+ */
+function mapFrameworkToCommandSlug(name) {
+  if (typeof name !== 'string' || name.length === 0) return FALLBACK_COMMAND_SLUG;
+  const lc = name.toLowerCase();
+  if (Object.prototype.hasOwnProperty.call(FRAMEWORK_TO_COMMAND_SLUG, lc)) {
+    return FRAMEWORK_TO_COMMAND_SLUG[lc];
+  }
+  return FALLBACK_COMMAND_SLUG;
+}
+
+// ---------- Exports ----------
+
+module.exports = {
+  parseFrameworkChainSection: parseFrameworkChainSection,
+  detectCompletedFramework: detectCompletedFramework,
+  proposeNextFramework: proposeNextFramework,
+  // Frozen tables exposed for downstream introspection + test invariants.
+  KNOWN_FRAMEWORKS: KNOWN_FRAMEWORKS,
+  FRAMEWORK_TO_COMMAND_SLUG: FRAMEWORK_TO_COMMAND_SLUG,
+  // Constants exposed for invariant tests + downstream callers.
+  NOISE_FLOOR: NOISE_FLOOR,
+  RECOMMENDED_FLOOR: RECOMMENDED_FLOOR,
+  RECENT_WRITE_WINDOW_MS: RECENT_WRITE_WINDOW_MS,
+  FALLBACK_COMMAND_SLUG: FALLBACK_COMMAND_SLUG,
+};