@mindrian_os/install 1.13.0-beta.13 → 1.13.0-beta.14

package/lib/core/navigation/packet.cjs

@@ -15,6 +15,14 @@ const crypto = require('node:crypto');
 const { getNeighborhood } = require('./neighborhood.cjs');
 const { findContradictions, findUnsupportedClaims, findRelevantOpportunities } = require('./insights.cjs');
 const { findRecentChanges } = require('./memory-events.cjs');
+// Phase 125-03 -- framework_chain_hint stitch. projections.cjs (Plan 01) gives
+// us the active framework set + hop depth from roomState; framework-chain-slice
+// (Plan 02) fetches the FEEDS_INTO Cypher slice from the Brain. Both modules
+// are pure-or-graceful: projections never throws, slice fetcher returns a
+// degraded envelope rather than throwing. Required at module top because the
+// stitch is a hot path the helper does NOT lazy-import.
+const projections = require('./projections.cjs');
+const chainSliceMod = require('../../brain/framework-chain-slice.cjs');
 
 // Phase 110-02 (D-03 + D-09): privacy-mode opt-up. local_summary_only is the default and
 // the only mode any of the 12 shipped Brain jobs ever requests (every $def.in.properties.privacy_mode
@@ -178,7 +186,57 @@ function getFocusType(db, focusNodeId) {
   return row ? row.type : null;
 }
 
-function buildBrainPacket(db, job, focusNodeId, opts) {
+// Phase 125-03 -- stitch helper. Reads roomState via projections, fetches the
+// 1-3 hop FEEDS_INTO slice via Plan 02 fetcher (or mock from opts._mocks),
+// returns the framework_chain_hint shape per CONTEXT.md Scope IN section B
+// item 5 -- OR undefined when the active set is empty (which is the "absent
+// from packet" path per Plan 04 schema: framework_chain_hint is optional on
+// LocalGraphSummary; absence is meaningful).
+//
+// Contract:
+//   - roomState null / not-an-object -> undefined  (cold-start packet ships without hint)
+//   - active frameworks empty array  -> undefined  (no anchor to fetch a slice for)
+//   - active frameworks non-empty + Brain reachable  -> hint object (5 fields)
+//   - active frameworks non-empty + Brain unreachable -> hint object with degraded
+//     shape per Plan 02 fetcher contract (edges:[], brain_snapshot_id:null,
+//     slice_rationale carrying 'brain_unreachable' or similar marker). The hint
+//     is STILL attached so the ranker can distinguish "active set non-empty but
+//     Brain failed" from "active set empty" (RESEARCH G-08 / Tier 0 invariant).
+//
+// Async because the fetcher is async. Pure read-only flow: no db writes, no fs
+// writes, no Brain writes -- only the Plan 02 read primitive (Cypher MATCH).
+async function _surfaceFrameworkChainHint(db, roomState, opts) {
+  if (!roomState || typeof roomState !== 'object') return undefined;
+  const active = projections.resolveActiveFrameworks(roomState);
+  if (!Array.isArray(active) || active.length === 0) return undefined;
+  const hopDepth = projections.resolveHopDepth(roomState);
+  const depth = (hopDepth && (hopDepth.depth === 1 || hopDepth.depth === 2 || hopDepth.depth === 3))
+    ? hopDepth.depth
+    : 3;
+  const activeNames = active.map(function (a) { return a.name; });
+  // Test seam: opts._mocks.fetchFrameworkChainSlice replaces the live fetcher
+  // for hermetic tests (no Brain network). Falls through to the shipped Plan
+  // 02 module when no mock is provided.
+  const fetcher = (opts && opts._mocks && typeof opts._mocks.fetchFrameworkChainSlice === 'function')
+    ? opts._mocks.fetchFrameworkChainSlice
+    : chainSliceMod.fetchFrameworkChainSlice;
+  // Per Plan 02 contract, fetcher NEVER throws; it returns a degraded envelope
+  // on any failure path (Brain unreachable, query throws, sanitizer rejects).
+  // Wrapping in try/catch is defensive belt-and-suspenders in case a future
+  // mock or replacement misbehaves.
+  let slice;
+  try {
+    slice = await fetcher({ active_frameworks: activeNames, max_hops: depth });
+  } catch (_e) {
+    // Defensive: even if the fetcher contract is violated, do NOT crash the
+    // packet builder. Return undefined -> hint absent for this call.
+    return undefined;
+  }
+  if (!slice || typeof slice !== 'object') return undefined;
+  return slice;
+}
+
+async function buildBrainPacket(db, job, focusNodeId, opts) {
   const options = opts || {};
   const mocks = options._mocks;
   const roomId = options.roomId || null;
@@ -217,6 +275,15 @@ function buildBrainPacket(db, job, focusNodeId, opts) {
   const recentChanges = findRecentChanges(db, Date.now() - 24 * 60 * 60 * 1000, { limit: 10 }).map(safeRecentChangeProjection);
   const bankedOpportunities = surface_banked_opportunities(db, focusNodeId, mocks);
 
+  // Phase 125-03: framework_chain_hint stitch. Reads roomState from opts (callers
+  // pass it through; Plan 05 ranker passes its own roomState when calling
+  // buildBrainPacket explicitly). When opts.roomState is absent OR resolves to an
+  // empty active framework set, the hint is ABSENT from the packet per the
+  // CONTEXT.md "absent when active set empty" invariant (Plan 04 schema accepts
+  // both shapes since framework_chain_hint is NOT in LocalGraphSummary.required[]).
+  const roomState = (options && typeof options === 'object') ? options.roomState : null;
+  const frameworkChainHint = await _surfaceFrameworkChainHint(db, roomState, options || {});
+
   return {
     packet_version: '1.0',
     job,
@@ -240,14 +307,22 @@ function buildBrainPacket(db, job, focusNodeId, opts) {
         summary: focusSummary,
       },
     },
-    local_graph_summary: {
-      nearest_claims: nearestClaims,
-      nearest_assumptions: nearestAssumptions,
-      contradictions,
-      unsupported_claims: unsupportedClaims,
-      recent_changes: recentChanges,
-      banked_opportunities: bankedOpportunities,
-    },
+    local_graph_summary: Object.assign(
+      {
+        nearest_claims: nearestClaims,
+        nearest_assumptions: nearestAssumptions,
+        contradictions,
+        unsupported_claims: unsupportedClaims,
+        recent_changes: recentChanges,
+        banked_opportunities: bankedOpportunities,
+      },
+      // Phase 125-03: conditionally include framework_chain_hint. Object.assign
+      // with an empty-object short-circuit guarantees the key is ABSENT (not
+      // present with an undefined value) when frameworkChainHint is undefined.
+      // This preserves the schema invariant in Plan 04 (the field is optional;
+      // absence is meaningful for the ranker in Plan 05).
+      (frameworkChainHint === undefined) ? {} : { framework_chain_hint: frameworkChainHint }
+    ),
     constraints: {
       privacy: 'no_raw_artifact_text',
       max_tokens: 1200,
@@ -265,4 +340,9 @@ module.exports = {
   readRoomConfigPrivacyMode,
   roomHasExcerptApproval,
   PRIVACY_MODES,
+  // Phase 125-03 test seam: surface helper exposed for fine-grained unit tests
+  // in lib/memory/packet-chain-hint.test.cjs. NOT part of the public API; Plan
+  // 05 ranker reads the assembled local_graph_summary.framework_chain_hint
+  // directly off the packet rather than calling the helper.
+  _test: { _surfaceFrameworkChainHint },
 };

package/lib/core/navigation/projections.cjs

@@ -0,0 +1,201 @@
+'use strict';
+// Phase 125-01 -- pure projection helpers for f-selector-ranker (Plan 05 consumer).
+// All three functions are pure + synchronous; they project roomState into the
+// three signals D4's scoring formula consumes. No I/O. No Brain calls. No db
+// writes. Database READS via existing navigation primitives only -- no direct
+// room-db access.
+//
+// Canon Part 9: SQL remembers and navigates; these helpers are the "navigate"
+// projections over the local mind that the ranker reads BEFORE making its
+// recommendation. Canon Part 7: extension of navigation/, not modification of
+// navigation.cjs's closed surface. Plan 05 may require these directly from
+// projections.cjs OR via navigation.cjs re-export -- Plan 01 ships the
+// projections; navigation.cjs re-export is OPTIONAL (deferred to Plan 05 if
+// preferred to avoid the closed-surface widening discussion).
+//
+// Function signatures (LOCKED in 125-CONTEXT.md "Function signatures (LOCKED)"):
+//   resolveActiveFrameworks(roomState) -> Array<{name, weight, source}>
+//   resolveHopDepth(roomState)         -> {depth: 1|2|3, rationale: string}
+//   computeInvestmentLevel(roomState)  -> {level: number, label: string}
+//
+// roomState shape (extends the chain-recommender.cjs shape per RESEARCH G-03 + G-04):
+//   {
+//     problemType?: 'UDP'|'IDP'|'WDP'|string,
+//     governing_thought?: string,
+//     activeJtbd?: string,
+//     brainAnchors?: string[],
+//     framework_invocations?: number,    // from COUNT(memory_event WHERE event_type='framework_invoked')
+//     feedsIntoEdges?: Edge[],
+//     brainSection?: object,
+//     brainSections?: object,
+//     recentFrameworks?: string[],       // from findRecentChanges memory_event 'framework_invoked'
+//   }
+
+// Common frameworks in the Brain teaching graph -- used as substring hints
+// when extracting from governing_thought free-text. NOT exhaustive (the Brain
+// has 100+ frameworks); just the high-traffic ones for early-room
+// governing_thought parsing. Plan 05 may extend this list or replace with a
+// registry-derived superset; the projection helper is just a substring scan.
+const KNOWN_FRAMEWORK_HINTS = Object.freeze([
+  'Beautiful Question Framework', 'Mullins 7 Domains', 'SWOT', 'Porter Five Forces',
+  'JTBD', 'Jobs to be Done', 'Lean Canvas', 'Business Model Canvas',
+  'Six Thinking Hats', 'Cynefin', 'Root Cause Analysis', 'First Principles',
+  'Wardley Map', 'OKR', 'Scenario Planning', 'Design Thinking',
+]);
+
+function _extractFrameworkFromThought(text) {
+  if (typeof text !== 'string' || text.length === 0) return null;
+  for (const fw of KNOWN_FRAMEWORK_HINTS) {
+    if (text.indexOf(fw) !== -1) return fw;
+  }
+  return null;
+}
+
+// Resolve a JTBD id to a framework name via:
+//   jtbd-taxonomy.json (entry.methodology_hooks[0]) -> command slug
+//   command-registry.json (commands[].command) -> first frameworks[]
+// Synchronous, fs-only read. Returns null on any failure -- never throws.
+// Mirrors lib/brain/chain-recommender.cjs::_jtbdToFramework (same fs pattern,
+// same fail-soft contract). Plan 05 may share the registry via injection if
+// it wants to centralize the cache; Plan 01 just reads.
+function _jtbdToFramework(activeJtbd) {
+  if (typeof activeJtbd !== 'string' || activeJtbd.length === 0) return null;
+  const path = require('node:path');
+  const fs = require('node:fs');
+  const TAXONOMY_PATH = path.join(__dirname, '..', '..', 'hmi', 'jtbd-taxonomy.json');
+  const REGISTRY_PATH = path.join(__dirname, '..', '..', '..', 'data', 'command-registry.json');
+  let tax;
+  let reg;
+  try { tax = JSON.parse(fs.readFileSync(TAXONOMY_PATH, 'utf8')); } catch (_e) { return null; }
+  try { reg = JSON.parse(fs.readFileSync(REGISTRY_PATH, 'utf8')); } catch (_e) { return null; }
+  const entry = (tax.entries || []).find((e) => e && e.id === activeJtbd);
+  if (!entry || !Array.isArray(entry.methodology_hooks) || entry.methodology_hooks.length === 0) return null;
+  const firstHook = entry.methodology_hooks[0]; // e.g. '/mos:beautiful-question' or 'mos:beautiful-question'
+  if (typeof firstHook !== 'string') return null;
+  const parts = firstHook.split(':');
+  if (parts.length < 2) return null;
+  const slug = parts.slice(1).join(':');
+  const cmd = (reg.commands || []).find((c) => c && typeof c.command === 'string' && c.command.split(':').slice(1).join(':') === slug);
+  return (cmd && Array.isArray(cmd.frameworks) && cmd.frameworks.length > 0) ? cmd.frameworks[0] : null;
+}
+
+// D1 -- Active-framework multi-signal projection.
+// Precedence (highest -> lowest weight):
+//   1.00  governing_thought  (CONTEXT signal, Phase 90)
+//   0.75  activeJtbd         (INTENT signal, /mos:jtbd via taxonomy)
+//   0.50  brainAnchors       (MEMORY signal, BRAIN.md anchors per Phase 90)
+//   0.25  recentFrameworks   (TEMPORAL signal, memory_event 'framework_invoked' recency)
+// First-write-wins per framework name (a framework already claimed by a higher
+// signal does NOT also appear at a lower one). Empty array on empty roomState.
+function resolveActiveFrameworks(roomState) {
+  if (!roomState || typeof roomState !== 'object') return [];
+  const out = new Map(); // name -> {name, weight, source}
+
+  // 1. governing_thought (CONTEXT signal, weight 1.0)
+  if (typeof roomState.governing_thought === 'string' && roomState.governing_thought.length > 0) {
+    const fw = _extractFrameworkFromThought(roomState.governing_thought);
+    if (fw) out.set(fw, { name: fw, weight: 1.0, source: 'governing_thought' });
+  }
+
+  // 2. activeJtbd (INTENT signal, weight 0.75)
+  if (typeof roomState.activeJtbd === 'string' && roomState.activeJtbd.length > 0) {
+    const fw = _jtbdToFramework(roomState.activeJtbd);
+    if (fw && !out.has(fw)) {
+      out.set(fw, { name: fw, weight: 0.75, source: 'activeJtbd' });
+    }
+  }
+
+  // 3. BRAIN.md anchors (MEMORY signal, weight 0.5)
+  if (Array.isArray(roomState.brainAnchors)) {
+    for (const a of roomState.brainAnchors) {
+      if (typeof a === 'string' && a.length > 0 && !out.has(a)) {
+        out.set(a, { name: a, weight: 0.5, source: 'brain_md' });
+      }
+    }
+  }
+
+  // 4. memory_event recency (TEMPORAL signal, weight 0.25)
+  if (Array.isArray(roomState.recentFrameworks)) {
+    for (const a of roomState.recentFrameworks) {
+      if (typeof a === 'string' && a.length > 0 && !out.has(a)) {
+        out.set(a, { name: a, weight: 0.25, source: 'memory_event' });
+      }
+    }
+  }
+
+  return Array.from(out.values()).sort((a, b) => b.weight - a.weight);
+}
+
+// D2 -- Variable hop depth, context-driven.
+// Defaults to depth 3 (WIDE) on ambiguity per CONTEXT.md.
+//   depth 1: WDP + strong governing_thought (execution mode)
+//   depth 2: IDP (exploratory mode); or WDP without governing_thought
+//   depth 3: wicked / undefined / no anchor (default WIDE)
+function resolveHopDepth(roomState) {
+  if (!roomState || typeof roomState !== 'object') {
+    return { depth: 3, rationale: 'no roomState provided; defaulting WIDE on ambiguity' };
+  }
+  const problemType = roomState.problemType;
+  const hasGoverningThought =
+    typeof roomState.governing_thought === 'string' && roomState.governing_thought.length > 0;
+  if (problemType === 'WDP' && hasGoverningThought) {
+    return {
+      depth: 1,
+      rationale: 'well-defined state with strong governing_thought; execution mode',
+    };
+  }
+  if (problemType === 'IDP') {
+    return {
+      depth: 2,
+      rationale: 'ill-defined state; evolving governing_thought; exploratory mode',
+    };
+  }
+  if (problemType === 'WDP') {
+    return {
+      depth: 2,
+      rationale: 'well-defined problemType but no governing_thought; moderate slice',
+    };
+  }
+  return {
+    depth: 3,
+    rationale: 'wicked or undefined state; no anchor; defaulting WIDE on ambiguity',
+  };
+}
+
+// D3 -- Continuous investment gradient.
+//   level = min(1.0, max(0.0, framework_invocations / 10))
+//   level === 0       -> "fresh room, ranking with Brain priors"
+//   0 < level < 0.5   -> "warming up: Brain + early local signal"
+//   0.5 <= level < 1  -> "balanced: Brain + memory equal weight"
+//   level === 1.0     -> "full local scoring with Brain confidence"
+// Caps at 1.0 for >= 10 invocations; floors at 0.0 for missing or negative
+// counter. Drives D4's scoring formula:
+//   score = brain_confidence*0.40 + (1-recency_decay)*0.30*investment_level
+//         + problem_type_bind*0.30*investment_level
+//   (normalized to 0..1)
+function computeInvestmentLevel(roomState) {
+  const raw =
+    roomState && typeof roomState === 'object' && typeof roomState.framework_invocations === 'number'
+      ? roomState.framework_invocations
+      : 0;
+  const level = Math.min(1.0, Math.max(0.0, raw / 10));
+  let label;
+  if (level === 0) {
+    label = 'fresh room, ranking with Brain priors';
+  } else if (level < 0.5) {
+    label = 'warming up: Brain + early local signal';
+  } else if (level < 1.0) {
+    label = 'balanced: Brain + memory equal weight';
+  } else {
+    label = 'full local scoring with Brain confidence';
+  }
+  return { level, label };
+}
+
+module.exports = {
+  resolveActiveFrameworks,
+  resolveHopDepth,
+  computeInvestmentLevel,
+  // Test seam (private; used by lib/memory/navigation-projections.test.cjs only).
+  _test: { _extractFrameworkFromThought, _jtbdToFramework, KNOWN_FRAMEWORK_HINTS },
+};

package/lib/core/navigation.cjs

@@ -10,6 +10,16 @@
 // re-exports those plus internal helpers as needed) requires canon amendment.
 // Canon Part 9: navigation IS the local mind; this is the only module callers should
 // require for graph reads, ranking, packet building, and truth-state promotion.
+//
+// Phase 125-00 amendment (Pass 3 GAP-2 resolution): writeEdge added as a thin
+// re-export on the navigation surface. Additive extension per the Phase 110-03
+// logMemoryEvent precedent (and the Phase 124-01 firstCapturedLastTouchedBySection
+// precedent shipped between 110-03 and here). The closed DOCUMENTED 13-function
+// API is unchanged in spirit -- additive re-exports of internal helpers are
+// needed for the Plan 06 selector-decisions surface to write typed cascade edges
+// (DEFERRED / REJECTED per CONTEXT.md D7) without bypassing the chokepoint.
+// Canon Part 4 binding: every choice is graph data; writeEdge is the primitive
+// that lets the F-selector ranker emit those choices as typed edges.
 
 const focus = require('./navigation/focus.cjs');
 const neighborhoodMod = require('./navigation/neighborhood.cjs');
@@ -19,6 +29,7 @@ const insights = require('./navigation/insights.cjs');
 const packet = require('./navigation/packet.cjs');
 const ingestion = require('./navigation/ingestion.cjs');
 const roomHome = require('./navigation/room-home.cjs');
+const edges = require('./navigation/edges.cjs');
 
 function notImplementedYet(name, plan) {
   return function () {
@@ -63,4 +74,18 @@ module.exports = {
   //   reaching into the internal navigation/memory-events.cjs. The closed navigation surface is
   //   the DOCUMENTED 13-function API; the implementation re-exports internal helpers as needed.)
   logMemoryEvent: memoryEvents.logEvent,
+
+  // First-captured / last-touched scalars by section (Phase 124-01 -- a thin re-export so
+  //   lib/core/feynman/timeline-renderer.cjs can compose its D-05 summary line over the
+  //   memory_event log without reaching into the internal navigation/insights.cjs. The closed
+  //   navigation surface is the DOCUMENTED 13-function API; the implementation re-exports
+  //   internal helpers as needed -- same pattern as the Phase 110-03 logMemoryEvent re-export.)
+  firstCapturedLastTouchedBySection: insights.firstCapturedLastTouchedBySection,
+
+  // Edge-write primitive (Phase 125-00 -- Pass 3 GAP-2 resolution; D7 typed cascade edge
+  //   surface for F.1 defer / F.2 reject. Allowlist gated on ALLOWED_EDGE_TYPES Set in
+  //   navigation/edges.cjs. Plan 06 selector-decisions.cjs is the first consumer; Phase
+  //   116/117/118 will extend the allowlist additively for tension / auto-explore /
+  //   MVA edges. Same additive-re-export pattern as logMemoryEvent + firstCapturedLastTouchedBySection.)
+  writeEdge: edges.writeEdge,
 };

package/lib/mcp/larry-server-instructions.md

@@ -1,6 +1,6 @@
 # Larry -- MCP Server Instructions
 
-You are Larry, a thinking partner modeled on Prof. Lawrence Aronhime (30+ years teaching innovation at Johns Hopkins). NOT a textbook, NOT a framework dispenser. If your response looks like a PDF, start over.
+You are Larry, a thinking partner modeled on Prof. Lawrence Aronhime (30+ years teaching innovation). NOT a textbook, NOT a framework dispenser. If your response looks like a PDF, start over.
 
 ## Voice