@mindrian_os/install 1.13.0-beta.11

package/lib/hmi/jtbd-state.cjs

@@ -0,0 +1,199 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 100-03 -- per-room JTBD state I/O at
+ * <roomDir>/.mindrian/jtbd-state.json. Atomic tmp+rename (Phase 95
+ * pattern), schema v1, history bounded at 50, 24h staleness on both
+ * auto current and manual overrides. D-06 per-room scope (no global
+ * file). D-12 manual override semantics. Canon Part 3 graceful
+ * fallback (no throws). Canon Part 8 LOCAL-only by construction.
+ * Pure CJS, node built-ins only, zero deps (Phase 87 invariant).
+ *
+ * API: getCurrent / setCurrent / clear / history / isStale.
+ * See .planning/phases/100-jtbd-inference-engine/100-CONTEXT.md and
+ * 100-03-PLAN.md for full contract.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const SCHEMA_VERSION = 1;
+const HISTORY_MAX = 50;
+const DEFAULT_STALENESS_HOURS = 24;
+const MS_PER_HOUR = 60 * 60 * 1000;
+
+function statePath(roomDir) { return path.join(roomDir, '.mindrian', 'jtbd-state.json'); }
+
+function ensureStateDir(roomDir) {
+  const dir = path.join(roomDir, '.mindrian');
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+function readState(roomDir) {
+  const p = statePath(roomDir);
+  if (!fs.existsSync(p)) return null;
+  let raw;
+  try {
+    raw = fs.readFileSync(p, 'utf8');
+  } catch (e) {
+    process.stderr.write('[jtbd-state] read error at ' + p + ': ' + e.message + '\n');
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    process.stderr.write('[jtbd-state] corrupt JSON at ' + p + ': ' + e.message + '\n');
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object') return null;
+  // Tolerate legacy (version: undefined) reads. version === 1 canonical.
+  return parsed;
+}
+
+function writeStateAtomic(roomDir, state) {
+  ensureStateDir(roomDir);
+  const dir = path.join(roomDir, '.mindrian');
+  const finalPath = path.join(dir, 'jtbd-state.json');
+  // Same-dir tmp -> POSIX-atomic rename(2). pid + hrtime nanos = collision-free.
+  const suffix = process.pid.toString(36) + '-' + process.hrtime.bigint().toString(36);
+  const tmpPath = path.join(dir, '.jtbd-state.json.tmp.' + suffix);
+  const ordered = {
+    version: SCHEMA_VERSION,
+    current: state.current === undefined ? null : state.current,
+    history: Array.isArray(state.history) ? state.history : [],
+  };
+  fs.writeFileSync(tmpPath, JSON.stringify(ordered, null, 2), 'utf8');
+  fs.renameSync(tmpPath, finalPath);
+}
+
+function trimHistory(h) {
+  if (!Array.isArray(h)) return [];
+  return h.length <= HISTORY_MAX ? h.slice() : h.slice(h.length - HISTORY_MAX);
+}
+
+function manualOverrideActive(current) {
+  if (!current || typeof current !== 'object' || !current.expires_at) return false;
+  const expiresMs = Date.parse(current.expires_at);
+  return !Number.isNaN(expiresMs) && expiresMs > Date.now();
+}
+
+function getCurrent(roomDir) {
+  const s = readState(roomDir);
+  return s && s.current && typeof s.current === 'object' ? s.current : null;
+}
+
+function setCurrent(roomDir, opts) {
+  if (!opts || typeof opts !== 'object') {
+    process.stderr.write('[jtbd-state] setCurrent: opts is required\n');
+    return;
+  }
+  const jtbd = opts.jtbd;
+  if (typeof jtbd !== 'string' || jtbd.length === 0) {
+    process.stderr.write('[jtbd-state] setCurrent: opts.jtbd must be non-empty string\n');
+    return;
+  }
+  const confidence = typeof opts.confidence === 'number' ? opts.confidence : 0;
+  const evidence = Array.isArray(opts.evidence) ? opts.evidence.slice() : [];
+  const trigger = typeof opts.trigger === 'string' && opts.trigger.length > 0
+    ? opts.trigger : 'unspecified';
+  const manual = opts.manual === true;
+
+  const now = new Date();
+  const nowIso = now.toISOString();
+
+  const prior = readState(roomDir);
+  const priorCurrent = prior && prior.current && typeof prior.current === 'object'
+    ? prior.current : null;
+  const priorHistory = prior && Array.isArray(prior.history) ? prior.history : [];
+  const fromJtbd = priorCurrent && typeof priorCurrent.jtbd === 'string'
+    ? priorCurrent.jtbd : 'explore';
+
+  // Manual block: auto write inside non-expired manual window -> blocked history row,
+  // current untouched. Manual writes always go through.
+  if (!manual && manualOverrideActive(priorCurrent)) {
+    const blockedRow = {
+      from: fromJtbd, to: jtbd, trigger: 'auto_blocked_by_manual',
+      at: nowIso, evidence: evidence,
+    };
+    try {
+      writeStateAtomic(roomDir, {
+        current: priorCurrent,
+        history: trimHistory(priorHistory.concat([blockedRow])),
+      });
+    } catch (e) {
+      process.stderr.write('[jtbd-state] write error (auto_blocked): ' + e.message + '\n');
+    }
+    return;
+  }
+
+  const newCurrent = {
+    jtbd: jtbd, confidence: confidence, entered_at: nowIso,
+    evidence: evidence,
+    expires_at: manual
+      ? new Date(now.getTime() + DEFAULT_STALENESS_HOURS * MS_PER_HOUR).toISOString()
+      : null,
+  };
+  const transitionRow = {
+    from: fromJtbd, to: jtbd, trigger: trigger, at: nowIso, evidence: evidence,
+  };
+  try {
+    writeStateAtomic(roomDir, {
+      current: newCurrent,
+      history: trimHistory(priorHistory.concat([transitionRow])),
+    });
+  } catch (e) {
+    process.stderr.write('[jtbd-state] write error (setCurrent): ' + e.message + '\n');
+  }
+}
+
+function clear(roomDir) {
+  const prior = readState(roomDir);
+  const priorCurrent = prior && prior.current && typeof prior.current === 'object'
+    ? prior.current : null;
+  const priorHistory = prior && Array.isArray(prior.history) ? prior.history : [];
+  const fromJtbd = priorCurrent && typeof priorCurrent.jtbd === 'string'
+    ? priorCurrent.jtbd : 'explore';
+  const nowIso = new Date().toISOString();
+  const clearRow = {
+    from: fromJtbd, to: null, trigger: 'manual_clear', at: nowIso, evidence: [],
+  };
+  try {
+    writeStateAtomic(roomDir, {
+      current: null,
+      history: trimHistory(priorHistory.concat([clearRow])),
+    });
+  } catch (e) {
+    process.stderr.write('[jtbd-state] write error (clear): ' + e.message + '\n');
+  }
+}
+
+function history(roomDir, n) {
+  const limit = typeof n === 'number' && n > 0 ? Math.floor(n) : 20;
+  const s = readState(roomDir);
+  if (!s || !Array.isArray(s.history)) return [];
+  return s.history.length <= limit ? s.history.slice() : s.history.slice(s.history.length - limit);
+}
+
+function isStale(roomDir, maxAgeHours) {
+  const hours = typeof maxAgeHours === 'number' && maxAgeHours > 0
+    ? maxAgeHours : DEFAULT_STALENESS_HOURS;
+  const current = getCurrent(roomDir);
+  if (!current) return true;
+  if (current.expires_at) {
+    const expiresMs = Date.parse(current.expires_at);
+    if (!Number.isNaN(expiresMs) && expiresMs < Date.now()) return true;
+  }
+  if (typeof current.entered_at !== 'string') return true;
+  const enteredMs = Date.parse(current.entered_at);
+  if (Number.isNaN(enteredMs)) return true;
+  return (Date.now() - enteredMs) > hours * MS_PER_HOUR;
+}
+
+module.exports = {
+  getCurrent, setCurrent, clear, history, isStale,
+  SCHEMA_VERSION, HISTORY_MAX, DEFAULT_STALENESS_HOURS,
+  _internal: { statePath, readState, writeStateAtomic, trimHistory, manualOverrideActive },
+};

package/lib/hmi/jtbd-taxonomy.json

@@ -0,0 +1,392 @@
+{
+  "version": 1,
+  "canon_parts": [2, "2a", 3, 7],
+  "entries": [
+    {
+      "id": "decide-pursue",
+      "one_line": "Decide if a venture / opportunity / approach is worth pursuing.",
+      "cues": [
+        "should we pursue",
+        "go / no-go",
+        "is this worth",
+        "kill it or keep it",
+        "pivot",
+        "double down"
+      ],
+      "methodology_hooks": [
+        "/mos:diagnose",
+        "/mos:build-thesis",
+        "/mos:value-proposition",
+        "/mos:lean-canvas"
+      ],
+      "next_move_verbs": [
+        "Run Methodology",
+        "Devil's Advocate",
+        "Scenario Plan",
+        "Synthesize"
+      ],
+      "completion_shape": "APPROVE/REJECT decision edge in graph + Decisions row in STATE.md",
+      "operator_affinity": ["BUILD_ROOM", "METHODOLOGY"],
+      "persona_affinity": ["Founder", "Investor"],
+      "completion_pattern": {
+        "cascade_edge": "decision_edge:APPROVE|decision_edge:REJECT",
+        "state_md_key": "Decisions"
+      }
+    },
+    {
+      "id": "find-problem",
+      "one_line": "Find the problem worth solving (not the symptom, the root).",
+      "cues": [
+        "what's the real problem",
+        "why are users",
+        "wrong problem",
+        "five whys",
+        "root cause",
+        "first principles"
+      ],
+      "methodology_hooks": [
+        "/mos:beautiful-question",
+        "/mos:root-cause",
+        "/mos:user-needs",
+        "/mos:analyze-needs"
+      ],
+      "next_move_verbs": [
+        "Reformulate",
+        "Run Methodology",
+        "Navigate Graph",
+        "Devil's Advocate",
+        "Synthesize"
+      ],
+      "completion_shape": "new artifact at room/problem-definition/ with reformulated problem statement",
+      "operator_affinity": ["EXPLORE_CAPTURE", "BUILD_ROOM"],
+      "persona_affinity": ["Researcher", "Founder"],
+      "completion_pattern": {
+        "artifact_glob": "**/problem-definition/**/*.md",
+        "cascade_edge": "INFORMS"
+      }
+    },
+    {
+      "id": "understand-market",
+      "one_line": "Understand the market for this idea — size, structure, dynamics.",
+      "cues": [
+        "market size",
+        "TAM SAM SOM",
+        "competitors",
+        "industry",
+        "market dynamics",
+        "Porter"
+      ],
+      "methodology_hooks": [
+        "/mos:macro-trends",
+        "/mos:mullins",
+        "/mos:dominant-designs",
+        "/mos:explore-trends"
+      ],
+      "next_move_verbs": [
+        "Run Methodology",
+        "Spawn Sub-Agent",
+        "Navigate Graph",
+        "Synthesize"
+      ],
+      "completion_shape": "populated room/market-analysis/ with mullins or dominant-designs artifact",
+      "operator_affinity": ["METHODOLOGY", "BUILD_ROOM"],
+      "persona_affinity": ["Researcher", "Investor"],
+      "completion_pattern": {
+        "artifact_glob": "**/market-analysis/**/*.md"
+      }
+    },
+    {
+      "id": "find-bottleneck",
+      "one_line": "Find the lagging component (Hughes 1983 reverse salient) blocking progress.",
+      "cues": [
+        "lagging",
+        "stuck",
+        "reverse salient",
+        "blocking",
+        "bottleneck",
+        "what's slow",
+        "what's holding us back"
+      ],
+      "methodology_hooks": [
+        "/mos:rs-fetch",
+        "/mos:find-bottlenecks",
+        "/mos:systems-thinking",
+        "/mos:analyze-systems"
+      ],
+      "next_move_verbs": [
+        "Run Methodology",
+        "Spawn Sub-Agent",
+        "Navigate Graph",
+        "Synthesize"
+      ],
+      "completion_shape": "rs-thesis artifact filed + REVERSE_SALIENT edges in graph",
+      "operator_affinity": ["METHODOLOGY"],
+      "persona_affinity": ["Researcher", "Operator"],
+      "completion_pattern": {
+        "artifact_glob": "**/rs-thesis*.md",
+        "cascade_edge": "REVERSE_SALIENT"
+      }
+    },
+    {
+      "id": "prepare-pitch",
+      "one_line": "Prepare for an investor / partner / customer meeting.",
+      "cues": [
+        "investor",
+        "pitch deck",
+        "demo day",
+        "fundraising",
+        "meeting on Tuesday",
+        "stakeholder review"
+      ],
+      "methodology_hooks": [
+        "/mos:build-thesis",
+        "/mos:present",
+        "/mos:hat-briefing",
+        "/mos:persona"
+      ],
+      "next_move_verbs": [
+        "Run Methodology",
+        "Synthesize",
+        "Spawn Sub-Agent",
+        "Devil's Advocate",
+        "Navigate Graph"
+      ],
+      "completion_shape": "rendered presentation HTML + STATE.md MEETING-PREP entry",
+      "operator_affinity": ["BUILD_ROOM"],
+      "persona_affinity": ["Founder", "Investor"],
+      "completion_pattern": {
+        "artifact_glob": "**/exports/*.html|**/dashboard*.html",
+        "state_md_key": "MEETING-PREP"
+      }
+    },
+    {
+      "id": "validate-idea",
+      "one_line": "Test if an idea / hypothesis / claim holds up under scrutiny.",
+      "cues": [
+        "test if",
+        "validate",
+        "does this hold up",
+        "stress-test",
+        "challenge",
+        "Devil's Advocate",
+        "red team"
+      ],
+      "methodology_hooks": [
+        "/mos:validate",
+        "/mos:challenge-assumptions",
+        "/mos:think-hats",
+        "/mos:map-unknowns"
+      ],
+      "next_move_verbs": [
+        "Devil's Advocate",
+        "Run Methodology",
+        "Spawn Sub-Agent",
+        "Reformulate",
+        "Synthesize"
+      ],
+      "completion_shape": "validation entry in room/assumptions/ with status (validated / invalidated / needs-data)",
+      "operator_affinity": ["METHODOLOGY"],
+      "persona_affinity": ["Researcher", "Investor"],
+      "completion_pattern": {
+        "artifact_glob": "**/assumptions/**/*.md"
+      }
+    },
+    {
+      "id": "compare-options",
+      "one_line": "Compare alternatives across criteria — choose between A/B/C.",
+      "cues": [
+        "compare",
+        "A vs B",
+        "tradeoffs",
+        "options",
+        "alternatives",
+        "scenarios",
+        "decision matrix"
+      ],
+      "methodology_hooks": [
+        "/mos:compare-ventures",
+        "/mos:scenario-plan",
+        "/mos:deep-grade"
+      ],
+      "next_move_verbs": [
+        "Scenario Plan",
+        "Run Methodology",
+        "Spawn Sub-Agent",
+        "Synthesize"
+      ],
+      "completion_shape": "Shape G (Comparison Matrix, ships in Phase 101) artifact + decision edge",
+      "operator_affinity": ["METHODOLOGY", "DECISION_GATE"],
+      "persona_affinity": ["Founder", "Operator"],
+      "completion_pattern": {
+        "artifact_glob": "**/comparison-matrix*.md|**/scenario-plan*.md"
+      }
+    },
+    {
+      "id": "connect-domains",
+      "one_line": "Find cross-domain analogues — what does this look like in another field?",
+      "cues": [
+        "analogous",
+        "similar to",
+        "from another domain",
+        "cross-domain",
+        "biology of",
+        "what's the equivalent in"
+      ],
+      "methodology_hooks": [
+        "/mos:find-analogies",
+        "/mos:find-connections",
+        "/mos:explore-domains"
+      ],
+      "next_move_verbs": [
+        "Run Methodology",
+        "Spawn Sub-Agent",
+        "Navigate Graph",
+        "Synthesize"
+      ],
+      "completion_shape": "ANALOGY edge or CROSS_DOMAIN edge in graph + opportunity bank ADD candidate",
+      "operator_affinity": ["METHODOLOGY"],
+      "persona_affinity": ["Researcher", "Domain Expert"],
+      "completion_pattern": {
+        "cascade_edge": "CROSS_DOMAIN|ANALOGY"
+      }
+    },
+    {
+      "id": "surface-contradiction",
+      "one_line": "Notice and resolve internal contradictions in the room.",
+      "cues": [
+        "contradicts",
+        "doesn't match",
+        "earlier we said",
+        "inconsistent",
+        "this conflicts with",
+        "challenge our own"
+      ],
+      "methodology_hooks": [
+        "/mos:challenge-assumptions",
+        "/mos:persona",
+        "/mos:think-hats"
+      ],
+      "next_move_verbs": [
+        "Devil's Advocate",
+        "Navigate Graph",
+        "Reformulate",
+        "Synthesize"
+      ],
+      "completion_shape": "CONTRADICTS edge resolution (one side INVALIDATED or both PARKED with reason)",
+      "operator_affinity": ["BUILD_ROOM"],
+      "persona_affinity": ["Mentor", "Domain Expert"],
+      "completion_pattern": {
+        "cascade_edge": "CONTRADICTS"
+      }
+    },
+    {
+      "id": "plan-execution",
+      "one_line": "Plan the next 90 days — milestones, owners, dates.",
+      "cues": [
+        "plan",
+        "next 90 days",
+        "milestones",
+        "roadmap",
+        "what's next",
+        "execution plan",
+        "OKRs"
+      ],
+      "methodology_hooks": [
+        "/mos:act",
+        "/mos:pipeline",
+        "/mos:scenario-plan"
+      ],
+      "next_move_verbs": [
+        "Run Methodology",
+        "Spawn Sub-Agent",
+        "Synthesize",
+        "Bank Opportunity",
+        "Defer"
+      ],
+      "completion_shape": "Shape H (Timeline, ships in Phase 101) artifact + STATE.md milestones section",
+      "operator_affinity": ["BUILD_ROOM", "METHODOLOGY"],
+      "persona_affinity": ["Operator", "Founder"],
+      "completion_pattern": {
+        "state_md_key": "Roadmap|Milestones"
+      }
+    },
+    {
+      "id": "file-meeting",
+      "one_line": "Capture and route meeting intelligence into the room.",
+      "cues": [
+        "transcript",
+        "meeting",
+        "Velma",
+        "spoke with",
+        "spoke to",
+        "call yesterday"
+      ],
+      "methodology_hooks": [
+        "/mos:file-meeting",
+        "/mos:speakers",
+        "/mos:reanalyze"
+      ],
+      "next_move_verbs": [
+        "Run Methodology",
+        "Synthesize",
+        "Navigate Graph",
+        "Bank Opportunity"
+      ],
+      "completion_shape": "filed transcript + cascade edges (INFORMS / CONTRADICTS / CONVERGES)",
+      "operator_affinity": ["METHODOLOGY"],
+      "persona_affinity": ["Operator", "Mentor"],
+      "completion_pattern": {
+        "artifact_glob": "**/meetings/**/*.md",
+        "cascade_edge": "INFORMS|CONVERGES"
+      }
+    },
+    {
+      "id": "audit-room",
+      "one_line": "Audit Data Room health — gaps, drift, evidence tier, decision quality.",
+      "cues": [
+        "is the room healthy",
+        "audit",
+        "drift",
+        "what's missing",
+        "gaps",
+        "deep grade"
+      ],
+      "methodology_hooks": [
+        "/mos:grade",
+        "/mos:deep-grade",
+        "/mos:heal",
+        "/mos:doctor",
+        "/mos:diagnostics"
+      ],
+      "next_move_verbs": [
+        "Run Methodology",
+        "Devil's Advocate",
+        "Navigate Graph",
+        "Synthesize",
+        "Defer"
+      ],
+      "completion_shape": "/mos:grade or /mos:deep-grade Shape E report + STATE.md HEALTH section",
+      "operator_affinity": ["METHODOLOGY"],
+      "persona_affinity": ["Mentor", "Operator"],
+      "completion_pattern": {
+        "artifact_glob": "**/health-report*.md|**/grade*.md",
+        "state_md_key": "HEALTH"
+      }
+    },
+    {
+      "id": "explore",
+      "one_line": "No specific job — general thinking, talking, ranging.",
+      "cues": [],
+      "methodology_hooks": [],
+      "next_move_verbs": [
+        "Free-Text",
+        "Run Methodology",
+        "Defer"
+      ],
+      "completion_shape": "none — explore is the steady state until a job crystallizes",
+      "operator_affinity": ["JUST_TALK", "EXPLORE_CAPTURE"],
+      "persona_affinity": [],
+      "completion_pattern": null
+    }
+  ]
+}