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

package/commands/room.md

@@ -5,6 +5,7 @@ argument-hint: [overview|<section>]
 body_shape_overview: B (Semantic Tree)
 body_shape_section: C (Room Card)
 serves_jtbd: ["audit-room"]
+teaching: "When you need to view or launch the active Data Room, /mos:room opens the room view with its current state. The default entry point for room navigation."
 ui_reference: skills/ui-system/SKILL.md
 allowed-tools:
   - Read

package/commands/rooms.md

@@ -4,6 +4,7 @@ description: List, switch, or archive project rooms
 argument-hint: [list|switch|archive|park]
 body_shape: B (Semantic Tree)
 serves_jtbd: ["audit-room"]
+teaching: "When you have multiple venture rooms and need to switch, list, or archive them, /mos:rooms manages the registry. One person, many ventures."
 ui_reference: skills/ui-system/SKILL.md
 allowed-tools:
   - Read

package/commands/root-cause.md

@@ -2,6 +2,7 @@
 name: root-cause
 description: Trace root cause via 5-Whys, Fishbone, Fault Tree
 serves_jtbd: ["find-problem"]
+teaching: "When the symptom keeps coming back, /mos:root-cause traces it via 5-Whys, Fishbone, and Fault Tree. Treats the cause, not the recurrence."
 # --- Phase 122 workflow-layer frontmatter ---
 kind: methodology
 frameworks: ["Root Cause Analysis"]

package/commands/rs-experts.md

@@ -3,6 +3,7 @@ name: rs-experts
 description: Resolve the expert network for a topic via Aura Cypher MATCH
 body_shape: D (Comparison Matrix)
 serves_jtbd: ["find-bottleneck", "connect-domains"]
+teaching: "When you need to know who in the world is working on a reverse salient you found, /mos:rs-experts resolves the expert network via Brain Cypher MATCH. Routes you to the people who already know."
 # --- Phase 122 workflow-layer frontmatter ---
 kind: methodology
 frameworks: ["Reverse Salient Analysis"]

package/commands/rs-explain.md

@@ -3,6 +3,7 @@ name: rs-explain
 description: Bidirectional NL-Graph entry point. NL question to graph queries to Larry-voiced explanation.
 body_shape: E (Action Report)
 serves_jtbd: ["find-bottleneck"]
+teaching: "When you have a question about a Reverse Salient discovery, /mos:rs-explain takes natural language in and returns a Larry-voiced explanation grounded in the graph. Bidirectional NL to graph and back."
 # --- Phase 122 workflow-layer frontmatter ---
 kind: methodology
 frameworks: ["Reverse Salient Analysis"]

package/commands/rs-fetch.md

@@ -3,6 +3,7 @@ name: rs-fetch
 description: Run the full Reverse Salient discovery pipeline for a topic
 body_shape: E (Action Report)
 serves_jtbd: ["find-bottleneck", "surface-contradiction"]
+teaching: "When you need the full Reverse Salient pipeline run on a topic, /mos:rs-fetch executes the discovery end-to-end: corpus, math, cross-domain match, thesis. The complete sweep, not a sample."
 # --- Phase 122 workflow-layer frontmatter ---
 kind: methodology
 frameworks: ["Reverse Salient Analysis"]

package/commands/rs-thesis.md

@@ -3,6 +3,7 @@ name: rs-thesis
 description: Read the thesis for a prior Reverse Salient discovery
 body_shape: E (Action Report)
 serves_jtbd: ["find-bottleneck"]
+teaching: "When you ran a Reverse Salient discovery earlier and want the thesis read back, /mos:rs-thesis surfaces the analytic conclusion in plain language. Best for revisiting old findings before a meeting."
 # --- Phase 122 workflow-layer frontmatter ---
 kind: methodology
 frameworks: ["Reverse Salient Analysis"]

package/commands/scenario-plan.md

@@ -2,6 +2,7 @@
 name: scenario-plan
 description: Build a 2x2 scenario matrix of plausible futures
 serves_jtbd: ["compare-options", "plan-execution"]
+teaching: "When the future could go two different ways on two key uncertainties, /mos:scenario-plan builds the 2x2 matrix and names each quadrant. Forces you to plan for the world you do not expect."
 # --- Phase 122 workflow-layer frontmatter ---
 kind: methodology
 frameworks: ["Scenario Planning"]

package/commands/scheduled-tasks.md

@@ -3,6 +3,7 @@ name: scheduled-tasks
 description: Define Cowork scheduled tasks for the room
 body_shape: E (Action Report)
 serves_jtbd: ["plan-execution"]
+teaching: "When you want Cowork to run something on a schedule against this room, /mos:scheduled-tasks defines the recurring job. Best for nightly grant sweeps or weekly meeting digests."
 ui_reference: skills/ui-system/SKILL.md
 surface: cowork
 allowed-tools:

package/commands/score-innovation.md

@@ -2,6 +2,7 @@
 name: score-innovation
 description: Score cross-domain innovation via HSI
 serves_jtbd: ["compare-options", "validate-idea"]
+teaching: "When you are choosing between cross-domain innovation candidates, /mos:score-innovation runs HSI scoring to rank them by semantic surprise. The math reveals which idea is actually novel."
 # --- Phase 122 workflow-layer frontmatter ---
 kind: methodology
 frameworks: ["HSI Semantic Surprise Analysis Assistant"]

package/commands/scout.md

@@ -3,6 +3,7 @@ name: scout
 description: Run sentinel scans across the room
 body_shape: E (Action Report)
 serves_jtbd: ["explore", "understand-market"]
+teaching: "When you want background scans running across the room without driving them yourself, /mos:scout fires the sentinel checks. The proactive layer, not the reactive one."
 ui_reference: skills/ui-system/SKILL.md
 allowed-tools:
   - Read

package/commands/setup.md

@@ -3,6 +3,7 @@ name: setup
 description: Configure optional integrations (Brain, Velma)
 argument-hint: [brain|velma|graph]
 serves_jtbd: ["explore"]
+teaching: "When you want to wire optional integrations like Brain or Velma, /mos:setup walks you through configuration. MindrianOS works without them; they make it work harder."
 allowed-tools:
   - Read
   - Write
@@ -142,7 +143,7 @@ Remove `neo4j-brain` and `pinecone-brain` from `.mcp.json` if present.
 
 Ask the user:
 
-> "Do you have a Brain API key? If not, request one at mindrianos-jsagirs-projects.vercel.app/brain-access -- you'll get it within 24 hours."
+> "Do you have a Brain API key? If not, request one at mindrianos.vercel.app/brain-access -- you'll get it within 24 hours."
 
 If the user provides a key:
 
@@ -163,9 +164,13 @@ if [ -f ~/.mindrian.env ] && grep -q "MINDRIAN_BRAIN_KEY" ~/.mindrian.env; then
 else
   echo "MINDRIAN_BRAIN_KEY=<their-key>" >> ~/.mindrian.env
 fi
+# SEC-02 (Phase 123 Plan-07): lock down permissions on POSIX (no-op on Windows).
+# Without this, lib/core/resolve-brain-key.cjs refuses to load the key from a
+# group/world-readable file and session-start shows "Brain: NOT loaded".
+chmod 600 "$HOME/.mindrian.env" 2>/dev/null || true
 ```
 
-Tell the user: "Key saved to both your project `.env` and `~/.mindrian.env` (global backup). Brain will connect from any directory now."
+Tell the user: "Key saved to both your project `.env` and `~/.mindrian.env` (global backup, chmod 600). Brain will connect from any directory now."
 
 ### 4. Test Connection
 
@@ -206,7 +211,7 @@ curl -s -w "\n%{http_code}" --max-time 15 \
 > "Brain connected and verified. Larry just got smarter. Your existing commands now have graph intelligence behind them. Try `/mos:suggest-next`."
 
 **On health OK but key auth failure (401):**
-> "Brain server is up, but your key was rejected. Double-check the key you received, or request a new one at mindrianos-jsagirs-projects.vercel.app/brain-access"
+> "Brain server is up, but your key was rejected. Double-check the key you received, or request a new one at mindrianos.vercel.app/brain-access"
 
 **On health OK but key verification timeout:**
 > "Brain server is up and your key is saved. Verification timed out but that is normal on first connect. Try `/mos:suggest-next` to confirm it works."

package/commands/snapshot.md

@@ -3,6 +3,7 @@ name: snapshot
 description: Package a Data Room snapshot for sharing
 argument-hint: '[<room-path>] [--open]'
 serves_jtbd: ["prepare-pitch", "audit-room"]
+teaching: "When you need a frozen Data Room artifact to share with someone outside the team, /mos:snapshot packages everything into a portable bundle. Read-only by design."
 disable-model-invocation: true
 usage: /mos:snapshot [ROOM_PATH] [--output PATH] [--open]
 category: export

package/commands/speakers.md

@@ -4,6 +4,7 @@ description: Show who spoke in your meetings and their roles
 body_shape: C (Room Card)
 body_shape_detail: Each speaker as a card with role, expertise, meeting count
 serves_jtbd: ["file-meeting"]
+teaching: "When you have a meeting filed and want to know who said what, /mos:speakers shows the participants with their roles, attendance, and contribution patterns. The people layer of meeting intelligence."
 ui_reference: skills/ui-system/SKILL.md
 allowed-tools:
   - Read

package/commands/splash.md

@@ -3,6 +3,7 @@ name: splash
 description: Display the MindrianOS Mondrian banner
 body_shape: raw
 serves_jtbd: ["explore"]
+teaching: "When you want the MindrianOS Mondrian banner, /mos:splash displays it. Mostly decorative; useful for screenshots and demo openings."
 allowed-tools:
   - Bash
 ---

package/commands/status.md

@@ -4,6 +4,7 @@ description: Show governing thought per section + health glyphs
 argument-hint: "[section] [--stale-only]"
 body_shape: E (Action Report)
 serves_jtbd: ["audit-room", "explore"]
+teaching: "When you need a fast read on the room's current state, /mos:status shows the governing thought per section plus health glyphs. The 10-second status check."
 ui_reference: skills/ui-system/SKILL.md
 allowed-tools:
   - Bash(node scripts/mos-status.cjs:*)

package/commands/structure-argument.md

@@ -2,6 +2,7 @@
 name: structure-argument
 description: Structure an argument with Minto + SCQA + MECE
 serves_jtbd: ["validate-idea", "explore"]
+teaching: "When an argument is muddled and you cannot say why, /mos:structure-argument restructures it with Minto pyramid, SCQA, and MECE. The right structure usually surfaces the missing premise."
 # --- Phase 122 workflow-layer frontmatter ---
 kind: methodology
 frameworks: ["The Pyramid Principle", "MECE (Mutually Exclusive, Collectively Exhaustive)"]

package/commands/suggest-next.md

@@ -2,6 +2,7 @@
 name: suggest-next
 description: Suggest the next move using the room graph
 serves_jtbd: ["plan-execution", "explore"]
+teaching: "When you finish a step and want Larry to recommend the next move, /mos:suggest-next reads the room graph and proposes 3-5 options with reasons. The Navigation Engine made visible."
 # --- Phase 122 workflow-layer frontmatter ---
 kind: meta
 frameworks: []

package/commands/systems-thinking.md

@@ -2,6 +2,7 @@
 name: systems-thinking
 description: Map feedback loops, stocks, and flows
 serves_jtbd: ["find-bottleneck"]
+teaching: "When the dynamics matter more than the parts, /mos:systems-thinking maps feedback loops, stocks, and flows. Surfaces where the leverage actually lives in the system."
 # --- Phase 122 workflow-layer frontmatter ---
 kind: methodology
 frameworks: ["Systems Thinking"]

package/commands/think-hats.md

@@ -2,6 +2,7 @@
 name: think-hats
 description: Rotate through De Bono's Six Thinking Hats
 serves_jtbd: ["explore", "compare-options"]
+teaching: "When the team keeps wearing the same hat and missing perspectives, /mos:think-hats rotates them through de Bono's six. The discomfort is the point; that is where the new thought lives."
 # --- Phase 122 workflow-layer frontmatter ---
 kind: methodology
 frameworks: ["Six Thinking Hats"]

package/commands/update.md

@@ -3,6 +3,7 @@ name: update
 description: Check for MindrianOS updates and install via Claude Code's native plugin loader
 argument-hint: [check|reapply|force]
 serves_jtbd: ["audit-room"]
+teaching: "When you suspect MindrianOS has a newer version waiting, /mos:update checks and installs via Claude Code's native plugin loader. Stale plugins quietly diverge from the docs."
 allowed-tools:
   - Bash
   - Read

package/commands/user-needs.md

@@ -2,6 +2,7 @@
 name: user-needs
 description: Map user needs with importance vs satisfaction
 serves_jtbd: ["find-problem"]
+teaching: "When you need to map what users actually want versus what they say they want, /mos:user-needs plots importance against satisfaction. The gap is where the opportunity lives."
 # --- Phase 122 workflow-layer frontmatter ---
 kind: methodology
 frameworks: ["Jobs to Be Done (JTBD)"]

package/commands/validate.md

@@ -2,6 +2,7 @@
 name: validate
 description: Validate ideas via importance-satisfaction scoring
 serves_jtbd: ["validate-idea"]
+teaching: "When an idea needs a real test before more investment, /mos:validate runs importance-satisfaction scoring against the customer segment. Validation is a measurement, not a feeling."
 # --- Phase 122 workflow-layer frontmatter ---
 kind: methodology
 frameworks: ["Jobs to Be Done (JTBD)"]

package/commands/value-proposition.md

@@ -2,6 +2,7 @@
 name: validate-proposition
 description: Score your value proposition against 3 VP gates
 serves_jtbd: ["validate-idea", "prepare-pitch"]
+teaching: "When you have a value proposition but no proof it holds, /mos:validate-proposition scores it against the three PWS VP gates with sequential math. A clean gate failure beats a vague pass."
 # --- Phase 122 workflow-layer frontmatter ---
 kind: methodology
 frameworks: ["PWS Value Proposition"]

package/commands/vault.md

@@ -5,6 +5,7 @@ argument-hint: '[<room-name>] [--path <dir>]'
 disable-model-invocation: true
 body_shape_overview: E (Mini Report)
 serves_jtbd: ["prepare-pitch"]
+teaching: "When you want the Data Room available in Obsidian for offline reading, /mos:vault exports it as a nested vault with wikilinks intact. Graph view comes free."
 ui_reference: skills/ui-system/SKILL.md
 allowed-tools:
   - Read

package/commands/visualize.md

@@ -4,6 +4,7 @@ description: Open room diagrams in the browser
 argument-hint: [structure|graph|chart]
 body_shape: D (Document View)
 serves_jtbd: ["audit-room", "prepare-pitch"]
+teaching: "When you want to see the room as diagrams in a browser, /mos:visualize opens the visual layer. Best when a stakeholder needs the picture, not the prose."
 ui_reference: skills/ui-system/SKILL.md
 allowed-tools:
   - Bash

package/commands/whitespace.md

@@ -3,6 +3,7 @@ name: whitespace
 description: Detect whitespace gaps in the room's coverage
 body_shape: varies
 serves_jtbd: ["connect-domains", "find-problem"]
+teaching: "When you suspect a gap exists in the room's coverage of a domain, /mos:whitespace runs HSI scoring across the artifact corpus to find under-explored zones. Best after the room has 20+ entries."
 # --- Phase 122 workflow-layer frontmatter ---
 kind: methodology
 frameworks: ["HSI Semantic Surprise Analysis Assistant"]

package/commands/wiki.md

@@ -3,6 +3,7 @@ name: wiki
 description: Open the Data Room wiki of room sections
 body_shape: D (Document View)
 serves_jtbd: ["audit-room", "prepare-pitch"]
+teaching: "When you want to read the Data Room as linked wiki pages, /mos:wiki opens the wiki view. Section by section, with cross-references rendered as hyperlinks."
 ui_reference: skills/ui-system/SKILL.md
 allowed-tools:
   - Bash

package/lib/brain/framework-chain-slice.cjs

@@ -0,0 +1,193 @@
+'use strict';
+// Phase 125-02 -- Brain Cypher slice query (parameterized 1-3 hop FEEDS_INTO; LIMIT 50).
+// CONTEXT.md Scope IN section B item 4 -- the LOCKED Cypher. Async wrapper over
+// brain-client.query that produces the framework_chain_hint shape Plan 03 stitches
+// into the packet's local_graph_summary.
+//
+// Canon Part 8: only $active_frameworks (array of generic framework name strings,
+// each passed through sanitizeCypherInput) + $max_hops (1|2|3 int) cross the wire.
+// No user content. No artifact text. No room identifiers in the query.
+//
+// Graceful degradation: any failure path (Brain unreachable, query throws, invalid
+// max_hops, empty active_frameworks, all-rejected-by-sanitizer, non-array result)
+// returns a degraded result envelope rather than throwing. Tier 0 stays functional.
+
+const crypto = require('node:crypto');
+const defaultBrainClient = require('../core/brain-client.cjs');
+
+// LOCKED Cypher template per CONTEXT.md Scope IN section B item 4.
+// READ-ONLY (MATCH/RETURN/LIMIT only -- no MERGE/CREATE/DELETE). The two $-bound
+// params ($active_frameworks, $max_hops) are the ONLY values that cross the wire;
+// every framework name in $active_frameworks is sanitized via the brain-client
+// sanitizeCypherInput whitelist before binding (Canon Part 8 invariant).
+const FRAMEWORK_CHAIN_SLICE_CYPHER =
+  'MATCH (f:Framework)-[r:FEEDS_INTO*1..$max_hops]->(g:Framework) ' +
+  'WHERE f.name IN $active_frameworks ' +
+  'RETURN f.name AS from, g.name AS to, ' +
+  '       r.confidence AS confidence, ' +
+  '       r.transform_description AS transform_description, ' +
+  '       length(r) AS hop_distance ' +
+  'LIMIT 50';
+
+function _nowIso() {
+  return new Date().toISOString();
+}
+
+function _sha256Hex(s) {
+  return crypto.createHash('sha256').update(String(s), 'utf8').digest('hex');
+}
+
+function _degraded(opts) {
+  const max_hops = (opts && (opts.max_hops === 1 || opts.max_hops === 2 || opts.max_hops === 3))
+    ? opts.max_hops
+    : 3;
+  return {
+    edges: [],
+    slice_scope: max_hops,
+    slice_rationale: (opts && opts.rationale) ? String(opts.rationale) : 'degraded',
+    brain_snapshot_id: null,
+    fetched_at: _nowIso(),
+  };
+}
+
+// Normalize result rows from brain-client.query. The shipped brain-client.query
+// returns { records: Array<row> } for the brain_query path; tests + the
+// CONTEXT.md spec describe the inner array of rows. Accept BOTH shapes so we
+// stay compatible whether the caller stubs query() with an Array directly OR
+// the live brain-client wraps in { records }. Any other shape degrades cleanly.
+function _unwrapRows(result) {
+  if (Array.isArray(result)) return result;
+  if (result && Array.isArray(result.records)) return result.records;
+  return null;
+}
+
+/**
+ * Fetch a parameterized 1-3 hop FEEDS_INTO slice from the live Brain.
+ *
+ * @param {object} opts
+ * @param {string[]} opts.active_frameworks - Array of framework name strings.
+ *   Empty array short-circuits to a degraded envelope.
+ * @param {1|2|3} opts.max_hops - Hop depth (must be exactly 1, 2, or 3).
+ *   Any other value short-circuits to a degraded envelope.
+ * @param {object} [opts.brainClient] - Test seam; defaults to live brain-client.
+ * @returns {Promise<{
+ *   edges: Array<{from:string|null, to:string|null, confidence:number|null,
+ *                 transform_description:string|null, hop_distance:number|null}>,
+ *   slice_scope: 1|2|3,
+ *   slice_rationale: string,
+ *   brain_snapshot_id: string|null,
+ *   fetched_at: string
+ * }>}
+ */
+async function fetchFrameworkChainSlice(opts) {
+  const o = opts || {};
+  const active_frameworks = Array.isArray(o.active_frameworks) ? o.active_frameworks : [];
+  const max_hops = (o.max_hops === 1 || o.max_hops === 2 || o.max_hops === 3) ? o.max_hops : null;
+  const brainClient = o.brainClient || defaultBrainClient;
+
+  // Gate 1: max_hops must be 1, 2, or 3. Anything else (0, 4, undefined,
+  // string, null) returns a degraded envelope with slice_scope defaulted to 3.
+  if (max_hops === null) {
+    return _degraded({ max_hops: 3, rationale: 'invalid_max_hops; expected 1|2|3' });
+  }
+
+  // Gate 2: empty active_frameworks short-circuits before any Brain contact.
+  // The Cypher would match nothing anyway; the degraded envelope is honest.
+  if (active_frameworks.length === 0) {
+    return _degraded({ max_hops: max_hops, rationale: 'empty active_frameworks; no slice fetched' });
+  }
+
+  // Gate 3: Brain reachability check before issuing the Cypher query. The
+  // live brain-client.isAvailable() is sync + cheap (an API-key resolve).
+  if (typeof brainClient.isAvailable === 'function' && !brainClient.isAvailable()) {
+    return _degraded({ max_hops: max_hops, rationale: 'brain_unreachable' });
+  }
+
+  // Canon Part 8 sanitization. brain-client._test.sanitizeCypherInput is the
+  // shipped whitelist (Phase 110-05 D-04 invariant). Each framework name is
+  // sanitized BEFORE binding; values that scrub down to empty are dropped.
+  // Fallback no-op only when the seam is genuinely absent (the live
+  // brain-client always exposes it; tests may stub a minimal client).
+  const sanitizer = (brainClient._test && typeof brainClient._test.sanitizeCypherInput === 'function')
+    ? brainClient._test.sanitizeCypherInput
+    : function (s) { return s; };
+  const sanitized = active_frameworks
+    .filter(function (n) { return typeof n === 'string' && n.length > 0; })
+    .map(function (n) { return sanitizer(n); })
+    .filter(function (n) { return typeof n === 'string' && n.length > 0; });
+
+  if (sanitized.length === 0) {
+    return _degraded({
+      max_hops: max_hops,
+      rationale: 'all_active_frameworks_rejected_by_sanitizer',
+    });
+  }
+
+  // Issue the parameterized Cypher. The ONLY $-bound values are the sanitized
+  // framework name array + the max_hops integer. The Cypher string itself is
+  // a frozen constant -- no template interpolation, no string concatenation
+  // with caller-derived data (Canon Part 8 enforced by inspection).
+  let result;
+  try {
+    result = await brainClient.query(FRAMEWORK_CHAIN_SLICE_CYPHER, {
+      active_frameworks: sanitized,
+      max_hops: max_hops,
+    });
+  } catch (e) {
+    const msg = (e && e.message) ? String(e.message) : 'unknown';
+    return _degraded({
+      max_hops: max_hops,
+      rationale: 'brain_query_failed: ' + msg.slice(0, 60),
+    });
+  }
+
+  const rows = _unwrapRows(result);
+  if (rows === null) {
+    return _degraded({ max_hops: max_hops, rationale: 'brain_returned_non_array' });
+  }
+
+  // Map raw rows to the framework_chain_hint edge shape. Null-tolerant per
+  // G-05: confidence and transform_description may be null on the live graph
+  // and we preserve null explicitly (no defaults). hop_distance comes from
+  // length(r) which is always a number when the row exists.
+  // Defensive: hard-cap at 50 even though the Cypher already enforces LIMIT 50.
+  const edges = rows.slice(0, 50).map(function (r) {
+    return {
+      from: (r && typeof r.from === 'string') ? r.from : null,
+      to: (r && typeof r.to === 'string') ? r.to : null,
+      confidence: (r && typeof r.confidence === 'number') ? r.confidence : null,
+      transform_description: (r && typeof r.transform_description === 'string')
+        ? r.transform_description
+        : null,
+      hop_distance: (r && typeof r.hop_distance === 'number') ? r.hop_distance : null,
+    };
+  });
+
+  // brain_snapshot_id: per CONTEXT.md Open Question #4, "Brain commit_id if
+  // exposed, else SHA of Cypher result." The shipped brain_query does NOT
+  // expose a commit_id; we derive a deterministic content hash of the raw
+  // rows so callers can detect slice changes without holding the rows
+  // themselves (Plan 03 + downstream packet validator never sees them).
+  const snapshotId = _sha256Hex(JSON.stringify(rows));
+
+  return {
+    edges: edges,
+    slice_scope: max_hops,
+    slice_rationale: 'brain_reachable; ' + edges.length + ' edges fetched; '
+      + sanitized.length + ' active_frameworks; max_hops=' + max_hops,
+    brain_snapshot_id: snapshotId,
+    fetched_at: _nowIso(),
+  };
+}
+
+module.exports = {
+  fetchFrameworkChainSlice: fetchFrameworkChainSlice,
+  FRAMEWORK_CHAIN_SLICE_CYPHER: FRAMEWORK_CHAIN_SLICE_CYPHER,
+  // Test seam -- helpers exposed for invariant tests; not part of the
+  // public API. Plan 03 (packet builder) consumes only the two above.
+  _test: {
+    _degraded: _degraded,
+    _sha256Hex: _sha256Hex,
+    _unwrapRows: _unwrapRows,
+  },
+};

package/lib/core/active-plugin-root.cjs

@@ -116,19 +116,84 @@ function fromLegacyClone(home) {
   return isPluginDir(legacy) ? legacy : null;
 }
 
+// Phase 123 Plan-02 (HARNESS-123-05): classify the resolved plugin root into one
+// of the 4 known topologies. RESEARCH Pitfall 4: a legacy-clone dir can carry an
+// unrelated origin remote (the dogfood box's ~/.claude/plugins/mindrian-os/ has
+// its origin pointed at mindrian-agno-backend.git) so a naive "has origin ->
+// dev-clone" heuristic mis-classifies it. The order below is precedence-locked:
+// env override and explicit legacy path win before the structural git probe.
+//
+// Returns one of: 'marketplace-cache' | 'dev-clone' | 'legacy' | 'not-found'.
+function classifyTopology(root, source) {
+  if (!root) return 'not-found';
+  // env override -> always treated as a dev clone (tests, dev boxes, hand clones).
+  if (source === 'MINDRIAN_OS_ROOT') return 'dev-clone';
+
+  const home = os.homedir();
+  // Explicit legacy path wins before the structural check -- some legacy clones
+  // carry an unrelated origin remote (Pitfall 4).
+  try {
+    if (path.resolve(root) === path.resolve(home, '.claude', 'plugins', 'mindrian-os')) {
+      return 'legacy';
+    }
+  } catch { /* ignore */ }
+
+  // Marketplace cache: under ~/.claude/plugins/cache/<mp>/{mos|mindrian-os}/<version>/.
+  try {
+    const cacheBase = path.resolve(home, '.claude', 'plugins', 'cache');
+    const resolved = path.resolve(root);
+    if (resolved.startsWith(cacheBase + path.sep)) {
+      return 'marketplace-cache';
+    }
+  } catch { /* ignore */ }
+
+  // Dev clone structural probe: a .git + install.sh + an origin remote URL that
+  // mentions the plugin repo name. execSync is wrapped in try/catch so a missing
+  // git binary or a non-git dir falls through cleanly.
+  try {
+    if (fs.existsSync(path.join(root, '.git')) && fs.existsSync(path.join(root, 'install.sh'))) {
+      const cp = require('node:child_process');
+      let originUrl = '';
+      try {
+        originUrl = cp.execSync('git -C ' + JSON.stringify(root) + ' remote get-url origin', {
+          stdio: ['ignore', 'pipe', 'ignore'],
+          encoding: 'utf8',
+          timeout: 1500,
+        }).trim();
+      } catch { /* no origin remote, swallow */ }
+      if (/mindrian-os-plugin/i.test(originUrl)) return 'dev-clone';
+    }
+  } catch { /* ignore */ }
+
+  // Defensive defaults: respect the resolver's source classification.
+  if (source === 'legacy-clone') return 'legacy';
+  // A resolved plugin dir that is not under a recognized cache path and not the
+  // legacy fixed path and does not pass the dev-clone probe -- treat as
+  // marketplace-cache (the bin/cli.js + installed_plugins.json path).
+  return 'marketplace-cache';
+}
+
 function resolveActivePluginRoot() {
   const envRoot = process.env.MINDRIAN_OS_ROOT;
-  if (envRoot) return { root: envRoot, source: 'MINDRIAN_OS_ROOT' };
+  if (envRoot) {
+    return { root: envRoot, source: 'MINDRIAN_OS_ROOT', topology: classifyTopology(envRoot, 'MINDRIAN_OS_ROOT') };
+  }
 
   const home = os.homedir();
   let r;
-  if ((r = fromInstalledPlugins(home))) return { root: r, source: 'installed_plugins.json' };
-  if ((r = fromMarketplaceCache(home))) return { root: r, source: 'marketplace-cache' };
-  if ((r = fromLegacyClone(home))) return { root: r, source: 'legacy-clone' };
-  return { root: null, source: 'not-found' };
+  if ((r = fromInstalledPlugins(home))) {
+    return { root: r, source: 'installed_plugins.json', topology: classifyTopology(r, 'installed_plugins.json') };
+  }
+  if ((r = fromMarketplaceCache(home))) {
+    return { root: r, source: 'marketplace-cache', topology: classifyTopology(r, 'marketplace-cache') };
+  }
+  if ((r = fromLegacyClone(home))) {
+    return { root: r, source: 'legacy-clone', topology: classifyTopology(r, 'legacy-clone') };
+  }
+  return { root: null, source: 'not-found', topology: 'not-found' };
 }
 
-module.exports = { resolveActivePluginRoot };
+module.exports = { resolveActivePluginRoot, classifyTopology };
 
 // CLI entry point.
 if (require.main === module) {