@mindrian_os/install 1.13.0-beta.11

package/lib/core/section-8-trace-schema.cjs

@@ -0,0 +1,138 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ * (Business Source License 1.1; SPDX BUSL-1.1; see LICENSE.)
+ *
+ * Phase 94 Plan 05 -- Section-8 trace schema authority.
+ *
+ * The Section-8 decision-trace schema is forward-additive per the
+ * Phase 91 navigation-engine invariant: writers may emit fields not
+ * present in older readers; readers must tolerate unknown fields.
+ * This module is the canonical schema authority that:
+ *
+ *   1. Documents the shape every writer must produce (intent_persona
+ *      block, plus the new web_research_tier field added in Plan 94-05).
+ *   2. Provides a machine-readable constant (SECTION_8_TRACE_SCHEMA)
+ *      for downstream validators and the Plan 94-05 fixture suite
+ *      (lib/memory/mcp-stack-fallback.test.cjs T6).
+ *   3. Stays a tiny re-export shim. The active writer authority is
+ *      lib/core/navigation-engine.cjs (buildIntentPersona at line ~337
+ *      and ~429) plus scripts/rs-discovery-engine.cjs (decision-trace
+ *      writer for the rs-fetch pipeline). This file does NOT hijack
+ *      writer responsibility; it documents the contract those writers
+ *      MUST honor.
+ *
+ * web_research_tier (Plan 94-05 amendment):
+ *   - Type: string enum, one of 'paid' | 'native' | 'cache' | null
+ *   - Where: intent_persona.web_research_tier
+ *   - Producer: rs-fetcher-* envelope tier annotation (Plan 94-05),
+ *     copied into the Section-8 trace by the decision-trace writer
+ *     reading the envelope.tier field.
+ *   - Why: Canon Part 4 (every choice is graph data). Tier transitions
+ *     (paid -> native, native -> cache) become graph data in the
+ *     Section-8 trace, so the navigator can review which research-tier
+ *     produced their evidence.
+ *
+ * Forward-additive contract (Phase 91 invariant): adding new fields
+ * to this schema does NOT break existing readers. Readers MUST treat
+ * the schema as a superset, ignoring fields they don't recognize.
+ *
+ * Pure CJS, zero npm deps, zero filesystem surface.
+ */
+'use strict';
+
+// ---------- Tier vocabulary ----------
+
+// Canonical tier values for web research per Plan 94-05 amendment.
+// 'paid'    : Tavily / Firecrawl / Exa / keyed academic API returned data.
+// 'native'  : Anthropic native WebSearch (free fallback) returned data.
+// 'cache'   : Read most-recent fetched_results.json from <room>/.mindrian/.
+// 'derived' : Post-processor over an upstream fetcher (e.g. experts over
+//             academic.papers). Not a direct network tier.
+const WEB_RESEARCH_TIERS = Object.freeze(['paid', 'native', 'cache', 'derived']);
+
+// Canonical source tags. These mirror the rs-fetcher-* envelope.source
+// field. Any new source must be added here AND in the fetcher's SOURCES
+// frozen array.
+const WEB_RESEARCH_SOURCES = Object.freeze([
+  'tavily', 'firecrawl', 'exa',
+  'websearch', 'cache', 'derived',
+  'openalex', 'arxiv', 'pubmed', 'scopus', 'ieee', 'nature',
+  'google_patents', 'uspto',
+]);
+
+// ---------- SECTION_8_TRACE_SCHEMA ----------
+//
+// JSON-Schema-flavored literal documenting the Section-8 decision-trace
+// shape. Forward-additive: writers may emit additional keys; readers
+// MUST ignore unknown keys.
+//
+// The schema is intentionally narrow: only the intent_persona block is
+// fully documented because that's where Plan 94-05 adds the new
+// web_research_tier field. Other Section-8 trace blocks (decision_log,
+// routing_source, brain_md_tier_mode, etc.) are out of scope for this
+// plan and live in their owning phase's writer authority.
+
+const SECTION_8_TRACE_SCHEMA = Object.freeze({
+  $id: 'mindrian.section-8-trace.v1',
+  type: 'object',
+  description: 'Section-8 decision-trace per Canon Part 4. Forward-additive '
+    + 'per Phase 91 invariant: readers tolerate unknown keys.',
+  properties: {
+    intent_persona: {
+      type: 'object',
+      description: 'Persona + intent classification block. Phase 91 navigation-'
+        + 'engine writer authority (buildIntentPersona). Plan 94-05 adds the '
+        + 'web_research_tier field.',
+      properties: {
+        // ---- Plan 94-05 amendment: new field ----
+        web_research_tier: {
+          type: ['string', 'null'],
+          enum: ['paid', 'native', 'cache', 'derived', null],
+          description: 'Web research tier that produced the evidence backing '
+            + 'this decision. paid = Tavily / Firecrawl / Exa / keyed '
+            + 'academic API; native = Anthropic native WebSearch; cache = '
+            + 'read from fetched_results.json; derived = post-processor '
+            + 'over an upstream fetcher; null = no web research run for '
+            + 'this decision (e.g. methodology-only path). Producer: '
+            + 'rs-fetcher-* envelope.tier annotation, copied by the '
+            + 'decision-trace writer.',
+          added_in_plan: '94-05',
+        },
+        // Other intent_persona fields (not exhaustive; documented elsewhere).
+      },
+      additionalProperties: true,
+    },
+  },
+  additionalProperties: true,
+});
+
+// ---------- Helpers ----------
+
+// Validate a candidate web_research_tier scalar. Returns true on null
+// or one of the canonical tier values.
+function isValidWebResearchTier(value) {
+  if (value === null || value === undefined) return true;
+  if (typeof value !== 'string') return false;
+  return WEB_RESEARCH_TIERS.indexOf(value) >= 0;
+}
+
+// Validate a candidate web research source tag. Returns true on null
+// or one of the canonical source values.
+function isValidWebResearchSource(value) {
+  if (value === null || value === undefined) return true;
+  if (typeof value !== 'string') return false;
+  return WEB_RESEARCH_SOURCES.indexOf(value) >= 0;
+}
+
+// ---------- Exports ----------
+
+module.exports = {
+  SECTION_8_TRACE_SCHEMA: SECTION_8_TRACE_SCHEMA,
+  WEB_RESEARCH_TIERS: WEB_RESEARCH_TIERS,
+  WEB_RESEARCH_SOURCES: WEB_RESEARCH_SOURCES,
+  isValidWebResearchTier: isValidWebResearchTier,
+  isValidWebResearchSource: isValidWebResearchSource,
+  // Convenience field-name constant for downstream writers / readers
+  // that want to refer to the new field without a string literal.
+  WEB_RESEARCH_TIER_FIELD: 'web_research_tier',
+};

package/lib/core/section-registry.cjs

@@ -0,0 +1,111 @@
+/**
+ * MindrianOS Plugin — Section Registry
+ * Metadata for DD-aligned sections + dynamic discovery.
+ * Pure Node.js built-ins only.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * 8 DD-aligned core sections with label and De Stijl color.
+ * Sourced from build-graph SECTION_COLORS/SECTION_LABELS.
+ */
+const CORE_SECTIONS = {
+  'problem-definition':    { label: 'PROBLEM DEFINITION',    color: '#A63D2F' },
+  'market-analysis':       { label: 'MARKET ANALYSIS',       color: '#C8A43C' },
+  'solution-design':       { label: 'SOLUTION DESIGN',       color: '#5C5A56' },
+  'business-model':        { label: 'BUSINESS MODEL',        color: '#2D6B4A' },
+  'competitive-analysis':  { label: 'COMPETITIVE ANALYSIS',  color: '#B5602A' },
+  'team-execution':        { label: 'TEAM & EXECUTION',      color: '#1E3A6E' },
+  'legal-ip':              { label: 'LEGAL & IP',            color: '#6B4E8B' },
+  'financial-model':       { label: 'FINANCIAL MODEL',       color: '#2A6B5E' },
+};
+
+/**
+ * Pre-assigned metadata for known extension sections.
+ */
+const EXTENDED_SECTION_META = {
+  'opportunity-bank': { label: 'OPPORTUNITY BANK', color: '#8B6914' },
+  'funding':          { label: 'FUNDING',          color: '#1A5276' },
+  'personas':         { label: 'PERSONAS',         color: '#6C3483' },
+};
+
+/**
+ * Directories that are structural (not sections).
+ */
+const STRUCTURAL_DIRS = ['meetings', 'team'];
+
+/**
+ * Discover sections in a room directory.
+ * A directory qualifies as a section if it contains at least one .md file
+ * or has a STATE.md. Excludes hidden dirs and structural dirs.
+ *
+ * @param {string} roomDir - Absolute or relative path to room directory
+ * @returns {{ core: string[], extended: string[], all: string[], getMeta: function }}
+ */
+function discoverSections(roomDir) {
+  const resolved = path.resolve(roomDir);
+  const core = [];
+  const extended = [];
+
+  let entries;
+  try {
+    entries = fs.readdirSync(resolved, { withFileTypes: true });
+  } catch (e) {
+    return { core, extended, all: [], getMeta: () => null };
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const name = entry.name;
+
+    // Skip hidden directories
+    if (name.startsWith('.')) continue;
+
+    // Skip structural directories
+    if (STRUCTURAL_DIRS.includes(name)) continue;
+
+    const dirPath = path.join(resolved, name);
+
+    // Check if directory qualifies as a section
+    const hasStateMd = fs.existsSync(path.join(dirPath, 'STATE.md'));
+    let hasMdFiles = false;
+    if (!hasStateMd) {
+      try {
+        const files = fs.readdirSync(dirPath);
+        hasMdFiles = files.some(f => f.endsWith('.md'));
+      } catch (e) {
+        // skip unreadable dirs
+        continue;
+      }
+    }
+
+    if (!hasStateMd && !hasMdFiles) continue;
+
+    if (CORE_SECTIONS[name]) {
+      core.push(name);
+    } else {
+      extended.push(name);
+    }
+  }
+
+  const all = [...core, ...extended];
+
+  function getMeta(name) {
+    if (CORE_SECTIONS[name]) return { ...CORE_SECTIONS[name], type: 'core' };
+    if (EXTENDED_SECTION_META[name]) return { ...EXTENDED_SECTION_META[name], type: 'extended' };
+    // Unknown extension — generate label from name
+    return {
+      label: name.replace(/-/g, ' ').toUpperCase(),
+      color: '#555555',
+      type: 'extended',
+    };
+  }
+
+  return { core, extended, all, getMeta };
+}
+
+module.exports = { CORE_SECTIONS, EXTENDED_SECTION_META, STRUCTURAL_DIRS, discoverSections };

package/lib/core/session-state.cjs

@@ -0,0 +1,144 @@
+'use strict';
+
+/**
+ * session-state.cjs -- Structured last-session.md writer
+ *
+ * Writes a structured last-session.md to room/.mindrian/ with fields
+ * consumable by future KAIROS daily logs. Called from on-stop hook.
+ *
+ * Requirement: READY-01
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Write structured session state to last-session.md
+ *
+ * @param {string} roomPath - Absolute path to room/ directory
+ * @param {object} state - Session state fields
+ * @param {string} [state.active_methodology] - Currently active methodology (e.g., "bono-six-hats", "minto-pyramid")
+ * @param {string[]} [state.open_questions] - Unresolved questions from this session
+ * @param {string} [state.next_suggested_action] - What Larry recommends doing next
+ * @param {number} [state.confidence_level] - 0-100 confidence in current room completeness
+ * @param {string[]} [state.artifacts_created] - List of artifacts filed this session
+ * @param {number} [state.session_duration] - Session duration in seconds
+ */
+function writeSessionState(roomPath, state = {}) {
+  if (!roomPath || !fs.existsSync(roomPath)) {
+    return { success: false, error: 'Room path does not exist' };
+  }
+
+  const mindrianDir = path.join(roomPath, '.mindrian');
+  if (!fs.existsSync(mindrianDir)) {
+    fs.mkdirSync(mindrianDir, { recursive: true });
+  }
+
+  const now = new Date().toISOString();
+  const {
+    active_methodology = 'none',
+    open_questions = [],
+    next_suggested_action = 'Review room state and continue where you left off',
+    confidence_level = 50,
+    artifacts_created = [],
+    session_duration = 0,
+  } = state;
+
+  // Format duration as human-readable
+  const mins = Math.floor(session_duration / 60);
+  const secs = session_duration % 60;
+  const durationStr = mins > 0 ? `${mins}m ${secs}s` : `${secs}s`;
+
+  const content = `---
+last_updated: "${now}"
+active_methodology: "${active_methodology}"
+confidence_level: ${confidence_level}
+session_duration_seconds: ${session_duration}
+artifacts_count: ${artifacts_created.length}
+---
+
+# Last Session State
+
+**Ended:** ${now}
+**Duration:** ${durationStr}
+**Active Methodology:** ${active_methodology}
+**Confidence Level:** ${confidence_level}/100
+
+## Open Questions
+
+${open_questions.length > 0
+    ? open_questions.map(q => `- ${q}`).join('\n')
+    : '- No open questions from this session'}
+
+## Next Suggested Action
+
+${next_suggested_action}
+
+## Artifacts Created
+
+${artifacts_created.length > 0
+    ? artifacts_created.map(a => `- ${a}`).join('\n')
+    : '- No artifacts created this session'}
+`;
+
+  const filePath = path.join(mindrianDir, 'last-session.md');
+  fs.writeFileSync(filePath, content, 'utf8');
+
+  return { success: true, path: filePath, timestamp: now };
+}
+
+/**
+ * Read last session state from last-session.md
+ *
+ * @param {string} roomPath - Absolute path to room/ directory
+ * @returns {object|null} Parsed session state or null if not found
+ */
+function readSessionState(roomPath) {
+  if (!roomPath) return null;
+
+  const filePath = path.join(roomPath, '.mindrian', 'last-session.md');
+  if (!fs.existsSync(filePath)) return null;
+
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const frontmatterMatch = raw.match(/^---\n([\s\S]*?)\n---/);
+    if (!frontmatterMatch) return null;
+
+    const fm = frontmatterMatch[1];
+    const state = {};
+
+    const extract = (key) => {
+      const m = fm.match(new RegExp(`${key}:\\s*"?([^"\\n]*)"?`));
+      return m ? m[1].trim() : null;
+    };
+
+    state.last_updated = extract('last_updated');
+    state.active_methodology = extract('active_methodology');
+    state.confidence_level = parseInt(extract('confidence_level') || '50', 10);
+    state.session_duration_seconds = parseInt(extract('session_duration_seconds') || '0', 10);
+    state.artifacts_count = parseInt(extract('artifacts_count') || '0', 10);
+
+    // Extract open questions from body
+    const questionsMatch = raw.match(/## Open Questions\n\n([\s\S]*?)(?=\n## )/);
+    if (questionsMatch) {
+      state.open_questions = questionsMatch[1]
+        .split('\n')
+        .filter(l => l.startsWith('- ') && !l.includes('No open questions'))
+        .map(l => l.replace(/^- /, ''));
+    } else {
+      state.open_questions = [];
+    }
+
+    // Extract next suggested action
+    const actionMatch = raw.match(/## Next Suggested Action\n\n([\s\S]*?)(?=\n## )/);
+    if (actionMatch) {
+      state.next_suggested_action = actionMatch[1].trim();
+    }
+
+    return state;
+  } catch (e) {
+    return null;
+  }
+}
+
+module.exports = { writeSessionState, readSessionState };

package/lib/core/shallow-doc-parser.cjs

@@ -0,0 +1,174 @@
+'use strict';
+
+/*
+ * Phase 115-02 -- shallow-doc-parser (DISCRETION-01 strategy b)
+ *
+ * Extracts 1 user + 1 venture + 1-3 claim nodes from CV / memo / pitch paste.
+ * Routes ALL graph writes through lib/core/navigation.cjs (Phase 109 chokepoint).
+ * Graceful degradation: returns { user: null, venture: null, claims: [] } on
+ * parse failure; NEVER throws.
+ *
+ * Canon Part 7 (reuse before build): consumes the existing Phase 109 navigation
+ * surface. setFocus + recordMemoryEvent. No direct require of room-db.cjs.
+ *
+ * Canon Part 8 (graph boundary): no Brain queries, no user-content egress.
+ * The function operates entirely on the input string and writes only to
+ * LOCAL room.db via navigation.cjs.
+ *
+ * Pitfall 7 alignment: parseRoleHints maps to the 7-key role_blend axes
+ * (Founder / Researcher / Investor / Operator). Researcher.IND and
+ * Founder.grant are NOT inferable from a CV paste alone today; they alias
+ * to default until a future phase extends role_blend.
+ *
+ * Cold-start contract: shallow file is best-effort. If the document does
+ * not contain detectable role / venture / claims, the parser returns the
+ * empty result and emits zero memory events. This is the explicit
+ * graceful-degradation path (DISCRETION-01 strategy (b) "falls back to
+ * 0 nodes on failure").
+ */
+
+const navigation = require('./navigation.cjs');
+const crypto = require('node:crypto');
+
+// ----- Role detection (7-key role_blend space, Pitfall 7) -----
+
+const ROLE_PATTERNS = [
+  { canonical: 'Founder', regex: /\b(founder|co-?founder|ceo|cto)\b/i },
+  { canonical: 'Investor', regex: /\b(gp|lp|managing director|managing partner|venture partner|principal at)\b/i },
+  { canonical: 'Researcher', regex: /\b(phd|researcher|professor|scientist|investigator|principal investigator|\bpi\b)\b/i },
+  { canonical: 'Operator', regex: /\b(coo|head of operations|director of operations|vp operations|chief operating)\b/i },
+];
+
+function parseRoleHints(text) {
+  if (!text || typeof text !== 'string') return null;
+  for (const { canonical, regex } of ROLE_PATTERNS) {
+    if (regex.test(text)) {
+      return { canonical_role: canonical, confidence: 0.85 };
+    }
+  }
+  return null;
+}
+
+// ----- Venture detection -----
+
+function parseVentureHint(text) {
+  if (!text || typeof text !== 'string') return { name: null, stage: 'unknown' };
+
+  // Clinical trial NCT ID anywhere in the text -> dedicated stage
+  const nct = text.match(/\b(NCT\d{8})\b/);
+  if (nct) {
+    return { name: nct[1], stage: 'clinical-trial' };
+  }
+
+  // "Founder of X", "CEO of X", "founded X", "PI on X"
+  // Capture 1-3 capitalized words as a name. Use [ \t]+ for separators
+  // so the match does NOT span across newlines (which can pull in the next
+  // CV section like "Founder of Acme Robotics\nPhD" -> "Acme Robotics PhD").
+  const namePattern = /(?:founder of|co-?founder of|ceo of|cto of|founded|pi on|principal investigator on)[ \t]+([A-Z][\w-]*(?:[ \t]+[A-Z][\w-]*){0,2})/i;
+  const m = text.match(namePattern);
+  if (m && m[1]) {
+    return { name: m[1].trim(), stage: 'unknown' };
+  }
+  return { name: null, stage: 'unknown' };
+}
+
+// ----- Claim detection (top-level bullet statements) -----
+
+function parseClaims(text, max) {
+  const limit = Number.isInteger(max) && max > 0 ? max : 3;
+  if (!text || typeof text !== 'string') return [];
+  const lines = text.split(/\r?\n/);
+  const claims = [];
+  for (const line of lines) {
+    // Match leading bullet markers (-, *, bullet char, or "1.", "2.", etc.) followed by 10-200 chars
+    const m = line.match(/^[\s]*(?:[-*•]|\d+\.)\s+(.{10,200}?)\s*$/);
+    if (m && m[1]) {
+      claims.push({ text: m[1].trim() });
+      if (claims.length >= limit) break;
+    }
+  }
+  return claims;
+}
+
+// ----- Node ID helper (deterministic) -----
+
+function nodeIdFor(prefix, content) {
+  const hash = crypto.createHash('sha256').update(String(content)).digest('hex').slice(0, 8);
+  return prefix + '-' + hash;
+}
+
+// ----- Internal: safe call to navigation.recordMemoryEvent if present -----
+// The Phase 109 public surface today exposes setFocus + 12 other functions.
+// recordMemoryEvent is the proposed 14th re-export (per RESEARCH cross-phase
+// wiring). When absent at runtime, we no-op the memory_event call so the
+// shallow-file flow still completes (graceful degradation per DISCRETION-01).
+
+function safeRecord(sessionId, eventType, payload) {
+  if (typeof navigation.recordMemoryEvent === 'function') {
+    try {
+      navigation.recordMemoryEvent(sessionId, eventType, payload);
+    } catch (_) {
+      // graceful degradation
+    }
+  }
+}
+
+// ----- extractShallow (DISCRETION-01 strategy (b) entry point) -----
+
+function extractShallow(text, sessionId) {
+  const result = { user: null, venture: null, claims: [] };
+  if (!text || typeof text !== 'string') return result;
+  if (!sessionId || typeof sessionId !== 'string') return result;
+
+  try {
+    const role = parseRoleHints(text);
+    const venture = parseVentureHint(text);
+    const claims = parseClaims(text);
+
+    // 1 user node (if a role inferred)
+    if (role) {
+      const userNodeId = nodeIdFor('user', role.canonical_role + ':' + sessionId);
+      result.user = {
+        node_id: userNodeId,
+        canonical_role: role.canonical_role,
+        confidence: role.confidence,
+      };
+      safeRecord(sessionId, 'node_created', { node_id: userNodeId, kind: 'user', canonical_role: role.canonical_role });
+    }
+
+    // 1 venture node (if named entity found) -- also sets focus
+    if (venture && venture.name) {
+      const ventureNodeId = nodeIdFor('venture', venture.name);
+      result.venture = {
+        node_id: ventureNodeId,
+        name: venture.name,
+        stage: venture.stage,
+      };
+      // setFocus signature aligned with Phase 109 closed surface (sessionId, nodeId, setBy)
+      try {
+        navigation.setFocus(sessionId, ventureNodeId, 'auto-from-upload');
+      } catch (_) {
+        // graceful degradation; focus is best-effort
+      }
+      safeRecord(sessionId, 'node_created', { node_id: ventureNodeId, kind: 'venture', name: venture.name });
+    }
+
+    // 1-3 claim nodes
+    for (const c of claims) {
+      const claimNodeId = nodeIdFor('claim', c.text);
+      result.claims.push({ node_id: claimNodeId, text: c.text });
+      safeRecord(sessionId, 'node_created', { node_id: claimNodeId, kind: 'claim' });
+    }
+  } catch (_) {
+    // Catch-all graceful degradation: never throw upstream.
+  }
+
+  return result;
+}
+
+module.exports = {
+  extractShallow,
+  parseRoleHints,
+  parseVentureHint,
+  parseClaims,
+};