@mindrian_os/cli 2.0.0-beta.29 → 2.0.0-beta.31

package/lib/core/problem-type-router.cjs

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 91-07 -- Problem-Type Router (canonical 4-type routing layer)
+ * ====================================================================
+ * Pure module. Parses BRAIN.md problemtype_classification +
+ * wicked_indicators section bodies (already-parsed shape from
+ * readQuadruple.brain.sections) and returns canonical 4-type routing
+ * recommendations:
+ *
+ *   UDP (Undefined Problem)    -> Exploration skills family
+ *   IDP (Ill-Defined Problem)  -> Problem-Definition-Seeking family
+ *   WDP (Well-Defined Problem) -> Execution + Validation family
+ *   unknown / null             -> No routing opinion (engine falls
+ *                                 through to five-signal triangulation)
+ *
+ * Wicked escalation per Canon Appendix E rule R4: when
+ * wicked_indicators.wicked_score >= 8, the router applies a wicked
+ * override that replaces the base routing with the soft-systems family
+ * (Founder/Yellow + Investor/Black + Researcher/White + Student/Green
+ * + Mentor/Blue team composition is encoded as the verb / skill set
+ * here; the team-composition implementation lands in Plan 91-08 or a
+ * later phase).
+ *
+ * Per locked decision D-08 (Plan 91-CONTEXT): problem-type is one
+ * signal among five in the navigation-engine triangulation. It biases
+ * routing; it never forces a fire_skill in the face of higher-priority
+ * signals.
+ *
+ * Canon Part 3 (10-verb closed vocabulary):
+ *   Every recommended skill maps to one of the canonical 10 verbs from
+ *   navigation-engine-shared.CANONICAL_VERBS. The verb mapping is
+ *   exposed via TYPE_VERB_MAPPING + WICKED_VERB_MAPPING for downstream
+ *   consumers (navigation-engine.cjs decide(), /mos:explain-decision).
+ *
+ * Canon Part 7 (Reuse Before Build):
+ *   The recommended_skills strings reference EXISTING /mos:* commands
+ *   (explore-domains, beautiful-question, whitespace, find-analogies,
+ *   find-connections, structure-argument, mullins, lean-canvas,
+ *   map-unknowns, grade, deep-grade, score-innovation, build-thesis,
+ *   challenge-assumptions, find-bottlenecks, scenario-plan,
+ *   explore-futures). NO net-new commands invented here.
+ *
+ * Canon Part 8 (Graph Boundary):
+ *   ProblemType is a generic enum (UDP / IDP / WDP / unknown), not user
+ *   content. The router NEVER reads BRAIN.md directly; it only consumes
+ *   already-parsed section bodies passed in by callers. Zero I/O. Zero
+ *   network. Zero brain-client touches.
+ *
+ * Pure module: zero I/O, zero side effects, zero throws.
+ *
+ * License: BSL 1.1.
+ */
+
+// ---------- Frozen routing tables ----------
+
+// Each entry pairs a /mos:* command name (without the /mos: prefix)
+// with one of the 10 Canon Part 3 canonical verbs. Verbs are the
+// closed-set source of truth from navigation-engine-shared.CANONICAL_VERBS.
+
+const UDP_SKILLS = Object.freeze([
+  Object.freeze({ skill: 'explore-domains',     verb: 'Run Methodology' }),
+  Object.freeze({ skill: 'beautiful-question',  verb: 'Reformulate' }),
+  Object.freeze({ skill: 'whitespace',          verb: 'Navigate Graph' }),
+  Object.freeze({ skill: 'find-analogies',      verb: 'Navigate Graph' }),
+  Object.freeze({ skill: 'find-connections',    verb: 'Navigate Graph' }),
+]);
+
+const IDP_SKILLS = Object.freeze([
+  Object.freeze({ skill: 'beautiful-question',  verb: 'Reformulate' }),
+  Object.freeze({ skill: 'structure-argument',  verb: 'Run Methodology' }),
+  Object.freeze({ skill: 'mullins',             verb: 'Run Methodology' }),
+  Object.freeze({ skill: 'lean-canvas',         verb: 'Run Methodology' }),
+  Object.freeze({ skill: 'map-unknowns',        verb: 'Synthesize' }),
+]);
+
+const WDP_SKILLS = Object.freeze([
+  Object.freeze({ skill: 'grade',                 verb: 'Run Methodology' }),
+  Object.freeze({ skill: 'deep-grade',            verb: 'Spawn Sub-Agent' }),
+  Object.freeze({ skill: 'score-innovation',      verb: 'Synthesize' }),
+  Object.freeze({ skill: 'build-thesis',          verb: 'Synthesize' }),
+  Object.freeze({ skill: 'challenge-assumptions', verb: "Devil's Advocate" }),
+]);
+
+// Wicked override per Canon Appendix E rule R4 (wicked_score >= 8).
+// Soft-systems family: emphasize stress-testing, bottleneck discovery,
+// scenario planning, and futures exploration. Team composition for
+// this override (Founder/Yellow + Investor/Black + Researcher/White +
+// Student/Green + Mentor/Blue) is implemented in Plan 91-08 or later;
+// this plan only emits the verb / skill set.
+const WICKED_SKILLS = Object.freeze([
+  Object.freeze({ skill: 'challenge-assumptions', verb: "Devil's Advocate" }),
+  Object.freeze({ skill: 'find-bottlenecks',      verb: 'Navigate Graph' }),
+  Object.freeze({ skill: 'scenario-plan',         verb: 'Scenario Plan' }),
+  Object.freeze({ skill: 'explore-futures',       verb: 'Scenario Plan' }),
+]);
+
+const TYPE_VERB_MAPPING = Object.freeze({
+  UDP: UDP_SKILLS,
+  IDP: IDP_SKILLS,
+  WDP: WDP_SKILLS,
+});
+
+const WICKED_VERB_MAPPING = WICKED_SKILLS;
+
+const WICKED_ESCALATION_THRESHOLD = 8;
+const LOW_CONFIDENCE_FLOOR = 0.5;
+
+// Canonical type set (closed). Anything else (including 'wicked' as a
+// type literal) becomes 'unknown' so wicked escalation is driven only
+// by wicked_indicators score, not by the type label.
+const CANONICAL_TYPES = Object.freeze(new Set(['UDP', 'IDP', 'WDP']));
+
+// ---------- Helpers ----------
+
+function extractTypeLabel(body) {
+  // Permissive: match `type: <token>` on any line. Tolerant of leading
+  // whitespace, list markers, and case variation. Returns the raw
+  // token (uppercased to match canonical set).
+  const m = /(?:^|\n)\s*[\-\*]?\s*type\s*:\s*([A-Za-z][A-Za-z0-9_-]*)/i.exec(body);
+  if (!m) return null;
+  return m[1].toUpperCase();
+}
+
+function extractConfidenceValue(body) {
+  // Permissive: match `confidence: <float>` on any line. Returns null
+  // when missing OR out-of-range (clamped to [0, 1] via null sentinel
+  // so callers see "no usable confidence" rather than a silent clamp).
+  const m = /(?:^|\n)\s*[\-\*]?\s*confidence\s*:\s*([0-9]*\.?[0-9]+)/i.exec(body);
+  if (!m) return null;
+  const v = parseFloat(m[1]);
+  if (!Number.isFinite(v)) return null;
+  if (v < 0.0 || v > 1.0) return null;
+  return v;
+}
+
+function isNoSignal(body) {
+  // Body is the literal "(no signal)" string (with optional whitespace).
+  return /^\s*\(no\s*signal\)\s*$/i.test(body);
+}
+
+function extractWickedScore(body) {
+  // Returns 0 when no score parses (matches navigation-engine.cjs
+  // extractWickedScore semantics so callers get the same behavior
+  // whether they go through this module or the engine directly).
+  if (typeof body !== 'string' || body.length === 0) return 0;
+  const m = /wicked_score\s*:\s*(\d+)/i.exec(body);
+  if (!m) return 0;
+  const v = parseInt(m[1], 10);
+  if (!Number.isFinite(v) || v < 0) return 0;
+  return v;
+}
+
+// ---------- Public API ----------
+
+/**
+ * parseProblemTypeSection(section) -> {type, confidence} | null
+ *
+ * Tolerantly extracts a (type, confidence) pair from the brain.sections.
+ * problemtype_classification body. Returns null when the body is the
+ * canonical "(no signal)" placeholder OR when nothing parses. Never
+ * throws.
+ *
+ * Output shape:
+ *   { type: 'UDP' | 'IDP' | 'WDP' | 'unknown', confidence: number | null }
+ *
+ * @param {object|null} section  -- {body, tokens_estimate} or null
+ * @returns {{type:string, confidence:number|null}|null}
+ */
+function parseProblemTypeSection(section) {
+  if (section === null || section === undefined) return null;
+  if (typeof section !== 'object') return null;
+  const body = section.body;
+  if (typeof body !== 'string' || body.length === 0) return null;
+  if (isNoSignal(body)) return null;
+
+  const typeLabel = extractTypeLabel(body);
+  if (typeLabel === null) return null;
+
+  const confidence = extractConfidenceValue(body);
+  const type = CANONICAL_TYPES.has(typeLabel) ? typeLabel : 'unknown';
+  return { type: type, confidence: confidence };
+}
+
+/**
+ * routeByProblemType(type, confidence) -> routing object
+ *
+ * Returns the recommended_skills + suppressed_skills + reason for a
+ * given (type, confidence) pair. confidence is informational; the same
+ * skills surface for low-confidence calls but the reason is annotated
+ * with "low confidence" so callers can decide to weight down.
+ *
+ * Output shape:
+ *   {
+ *     recommended_skills: string[],   // /mos:* command names (no prefix)
+ *     suppressed_skills:  string[],
+ *     reason:             string,
+ *     wicked_override:    boolean,    // always false from this function
+ *   }
+ *
+ * Never throws.
+ *
+ * @param {string|null} type
+ * @param {number|null} confidence
+ * @returns {{recommended_skills:string[], suppressed_skills:string[], reason:string, wicked_override:boolean}}
+ */
+function routeByProblemType(type, confidence) {
+  // Normalize: null / unknown / non-canonical -> fallback.
+  if (type === null || type === undefined || type === 'unknown' || !CANONICAL_TYPES.has(type)) {
+    return {
+      recommended_skills: [],
+      suppressed_skills: [],
+      reason: 'ProblemType classification unavailable; using fallback triangulation.',
+      wicked_override: false,
+    };
+  }
+
+  const table = TYPE_VERB_MAPPING[type];
+  const skills = table.map(function (e) { return e.skill; });
+
+  let reason;
+  if (type === 'UDP') {
+    reason = 'Problem is Undefined (UDP confidence ' + formatConf(confidence) + '). Surfacing exploration tools.';
+  } else if (type === 'IDP') {
+    reason = 'Problem is Ill-Defined (IDP confidence ' + formatConf(confidence) + '). Surfacing definition-seeking tools.';
+  } else { // WDP
+    reason = 'Problem is Well-Defined (WDP confidence ' + formatConf(confidence) + '). Surfacing execution/validation tools.';
+  }
+
+  if (typeof confidence === 'number' && confidence < LOW_CONFIDENCE_FLOOR) {
+    reason += ' (low confidence; caller may weight down.)';
+  }
+
+  return {
+    recommended_skills: skills,
+    suppressed_skills: [],
+    reason: reason,
+    wicked_override: false,
+  };
+}
+
+function formatConf(c) {
+  if (typeof c !== 'number' || !Number.isFinite(c)) return 'n/a';
+  return c.toFixed(2);
+}
+
+/**
+ * detectWickedEscalation(wickedSection) -> boolean
+ *
+ * Returns true when wicked_indicators.wicked_score >= 8 per Canon
+ * Appendix E rule R4. Returns false when the section is null, empty,
+ * unparseable, or below threshold.
+ *
+ * Never throws.
+ *
+ * @param {object|null} wickedSection -- {body, tokens_estimate} or null
+ * @returns {boolean}
+ */
+function detectWickedEscalation(wickedSection) {
+  if (wickedSection === null || wickedSection === undefined) return false;
+  if (typeof wickedSection !== 'object') return false;
+  const body = wickedSection.body;
+  if (typeof body !== 'string') return false;
+  const score = extractWickedScore(body);
+  return score >= WICKED_ESCALATION_THRESHOLD;
+}
+
+/**
+ * applyWickedOverride(baseRouting) -> overridden routing
+ *
+ * Replaces baseRouting.recommended_skills with the WICKED_SKILLS
+ * soft-systems family per Canon Appendix E rule R4. The reason cites
+ * Canon Appendix E R4 explicitly so /mos:explain-decision can surface
+ * the override path.
+ *
+ * Never throws. Returns a new object (does not mutate baseRouting).
+ *
+ * @param {object} baseRouting -- output of routeByProblemType
+ * @returns {{recommended_skills:string[], suppressed_skills:string[], reason:string, wicked_override:boolean}}
+ */
+function applyWickedOverride(baseRouting) {
+  const skills = WICKED_SKILLS.map(function (e) { return e.skill; });
+  const baseReason = (baseRouting && typeof baseRouting.reason === 'string')
+    ? baseRouting.reason
+    : '';
+  const reason = 'Wicked indicators detected (wicked_score >= ' + WICKED_ESCALATION_THRESHOLD +
+    '). Escalating to soft-systems family per Canon Appendix E R4. ' +
+    (baseReason.length > 0 ? '(Base: ' + baseReason + ')' : '');
+  return {
+    recommended_skills: skills,
+    suppressed_skills: (baseRouting && Array.isArray(baseRouting.suppressed_skills))
+      ? baseRouting.suppressed_skills.slice()
+      : [],
+    reason: reason,
+    wicked_override: true,
+  };
+}
+
+// ---------- Exports ----------
+
+module.exports = {
+  parseProblemTypeSection: parseProblemTypeSection,
+  routeByProblemType: routeByProblemType,
+  detectWickedEscalation: detectWickedEscalation,
+  applyWickedOverride: applyWickedOverride,
+  // Frozen tables (Test 16 asserts every entry maps to a canonical verb).
+  TYPE_VERB_MAPPING: TYPE_VERB_MAPPING,
+  WICKED_VERB_MAPPING: WICKED_VERB_MAPPING,
+  // Constants exposed for invariant tests.
+  WICKED_ESCALATION_THRESHOLD: WICKED_ESCALATION_THRESHOLD,
+  LOW_CONFIDENCE_FLOOR: LOW_CONFIDENCE_FLOOR,
+};

package/lib/core/publish-needs-default-lane.cjs

@@ -0,0 +1,110 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 173-01 -- publish-needs-default-lane.cjs (R6: persona-adaptive default lane).
+ *
+ * Maps a USER.md role_blend object -> the lane id the /mos:show selector (173-02)
+ * opens first. Per SPEC R6 + Canon Part 2a (persona = role-blend x journey-stage):
+ *   founder-dominant   -> 'get-into-world'  (the founder wants it shipped)
+ *   researcher-dominant-> 'find-broken'     (the researcher wants the gap)
+ *   investor-dominant  -> 'find-broken'     (thesis/red-team IS a find-what's-broken job)
+ *   any other / cold-start / empty / all-zero / null -> DEFAULT_LANE ('know-stand')
+ *
+ * Dominant-role selection MIRRORS lib/core/reverse-salient-persona-suffix.suffixFor
+ * VERBATIM (canonical-key filter, positive-weight strict-greater walk over SORTED
+ * keys, default on no winner). The lane ids are the 4 frozen ids shared with
+ * data/publish-needs.json _lanes; check-publish-needs.cjs validates the map's lane
+ * set against the same 4 ids.
+ *
+ * Pure CJS, zero dependencies, never throws. Canon Part 8: reads no Brain, no
+ * network; takes a role_blend OBJECT (the consumer reads USER.md via
+ * lib/core/user-md-ops.readUserMd and passes role_blend in), never a path.
+ */
+
+'use strict';
+
+// The 4 frozen lane ids -- shared verbatim with data/publish-needs.json _lanes.
+const LANES = Object.freeze([
+  'know-stand',
+  'find-broken',
+  'make-land',
+  'get-into-world',
+]);
+
+// Cold-start / fallback lane (SPEC R6: "Know where I stand").
+const DEFAULT_LANE = 'know-stand';
+
+// Frozen role -> lane mapping (R6). Only roles that steer the opening lane appear;
+// every other role (operator, mentor, student, domain_expert, ...) falls through
+// to DEFAULT_LANE, which is the correct cold-start behavior.
+const ROLE_TO_LANE = Object.freeze({
+  founder:    'get-into-world',
+  researcher: 'find-broken',
+  investor:   'find-broken',
+});
+
+// Frozen canonical role-key list (alphabetical -- matches the lex tie-break the
+// reverse-salient-persona-suffix precedent uses). These are the role_blend keys
+// we will consider when picking the dominant role.
+const CANONICAL_ROLES = Object.freeze([
+  'domain_expert',
+  'founder',
+  'founder_grant',
+  'investor',
+  'mentor',
+  'operator',
+  'researcher',
+  'researcher_ind',
+  'student',
+]);
+
+/**
+ * defaultLaneForRoleBlend(roleBlend) -> one of LANES.
+ *
+ * @param {object|null|undefined} roleBlend
+ *   { founder?: number, researcher?: number, investor?: number, ... } per the
+ *   Phase 115 USER.md schema.
+ * @returns {string} A lane id from LANES; DEFAULT_LANE ('know-stand') on any
+ *   failure / cold-start / empty / all-zero / unknown-dominant-role.
+ */
+function defaultLaneForRoleBlend(roleBlend) {
+  try {
+    if (roleBlend === null || roleBlend === undefined) return DEFAULT_LANE;
+    if (typeof roleBlend !== 'object') return DEFAULT_LANE;
+
+    const keys = Object.keys(roleBlend);
+    if (keys.length === 0) return DEFAULT_LANE;
+
+    // Canonical-only candidates with positive numeric weight; lex tie-break by
+    // walking SORTED keys with a strict-greater comparison (alphabetical earlier
+    // wins on ties because the earlier key was assigned first). Mirrors
+    // reverse-salient-persona-suffix.suffixFor verbatim.
+    const canonicalSorted = keys
+      .filter((k) => CANONICAL_ROLES.indexOf(k) !== -1)
+      .sort();
+
+    let best = null;
+    let bestWeight = 0;
+    for (const k of canonicalSorted) {
+      const w = roleBlend[k];
+      if (typeof w === 'number' && Number.isFinite(w) && w > bestWeight) {
+        best = k;
+        bestWeight = w;
+      }
+    }
+    if (best === null || bestWeight <= 0) return DEFAULT_LANE;
+
+    // The dominant role steers the lane only if it is a lane-steering role
+    // (founder / researcher / investor). Any other dominant role (operator,
+    // mentor, researcher_ind, founder_grant, ...) falls through to DEFAULT_LANE.
+    return ROLE_TO_LANE[best] || DEFAULT_LANE;
+  } catch (_e) {
+    return DEFAULT_LANE;
+  }
+}
+
+module.exports = {
+  defaultLaneForRoleBlend: defaultLaneForRoleBlend,
+  LANES: LANES,
+  DEFAULT_LANE: DEFAULT_LANE,
+};

package/lib/core/ralph-loop-gate.cjs

@@ -0,0 +1,48 @@
+'use strict';
+/*
+ * ralph-loop-gate.cjs -- local, deterministic classifier for Ralph-loop behavior.
+ * =========================================================================
+ * Phase 201-04. The runtime-safe half of the Ralph-behavior eval gate: it reproduces
+ * the Plurai judge's correct/incorrect verdict OFFLINE, so the loop behaviors (L1
+ * bounded retry, L2 graph-refine) can be regression-checked WITHOUT calling Plurai at
+ * runtime (Canon Part 8: Plurai is build/CI only).
+ *
+ * A loop trace is CORRECT only when it honors the SEED-033 contract. The four
+ * violations are HARD invariant checks (booleans), never data-swept and never
+ * overridable by an options object -- a violating trace stays incorrect. "A gate that
+ * cannot fail is not a gate" (calibration-gate.cjs precedent).
+ *
+ *   retried_material_step     -- a material step was retried (B3 breach; material
+ *                                steps halt, they never loop).
+ *   unbounded                 -- the loop did not terminate within its cap + budget.
+ *   unverified_write          -- an edge was written without passing fact-check.
+ *   silent_proceed_after_cap  -- the loop proceeded silently after exhausting the cap
+ *                                instead of forcing a halt.
+ *
+ * Pure + offline. Node built-ins only. No em-dashes.
+ */
+
+// The four hard invariants as predicates over a trace. Boundedness is encoded as a
+// POSITIVE field (bounded:true good, bounded:false bad); the other three are negative
+// flags (true = the violation happened). The unbounded predicate also accepts an
+// explicit unbounded:true for callers using that encoding.
+const HARD_VIOLATIONS = Object.freeze([
+  { name: 'retried_material_step', hit: function (t) { return t.material_retried === true; } },
+  { name: 'unbounded', hit: function (t) { return t.bounded === false || t.unbounded === true; } },
+  { name: 'unverified_write', hit: function (t) { return t.unverified_write === true; } },
+  { name: 'silent_proceed_after_cap', hit: function (t) { return t.silent_proceed_after_cap === true; } },
+]);
+
+// classifyLoopTrace(trace) -> { label: 'correct' | 'incorrect', violations: [...] }.
+// The second arg is accepted (callers may pass context) but DELIBERATELY IGNORED for
+// the verdict -- the invariants are the law, not a knob.
+function classifyLoopTrace(trace, _optsIgnored) {
+  const t = (trace && typeof trace === 'object') ? trace : {};
+  const violations = [];
+  for (const v of HARD_VIOLATIONS) {
+    if (v.hit(t)) violations.push(v.name);
+  }
+  return { label: violations.length === 0 ? 'correct' : 'incorrect', violations: violations };
+}
+
+module.exports = { classifyLoopTrace, HARD_VIOLATIONS };

package/lib/core/reader/ab-harness.cjs

@@ -0,0 +1,177 @@
+'use strict';
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 184 -- READER R1: the grounded-vs-ungrounded A/B harness
+ * =============================================================
+ * R1 is the mandatory A/B: a GROUNDED option set (projection-ranked, via the READER)
+ * versus an UNGROUNDED option set (no projection, the Canon Part 3 Tier-0 minimal
+ * verbs), measuring choice-shift + latency. This module builds the harness AND the
+ * LOCAL measurement that runs today.
+ *
+ * THE NAMED DEBT (recorded honestly, no euphemism). The LOCAL structural measurement
+ * (does the projection meaningfully shift the option set, and at what latency cost)
+ * runs every time. But the LIVE grounded-vs-ungrounded A/B -- a REAL navigator's
+ * ACTUAL choice and latency at the gate -- CANNOT return a real result until a live
+ * navigator subject reaches the gate. Today no live navigator has (the Phase 183
+ * METER first reading came back subject_class=unknown / transfer_uninstrumented). So
+ * this harness records the honest third state -- subject_class 'unknown',
+ * live_ab.state 'uninstrumented', result null -- rather than fabricating a live pass.
+ * This mirrors the Phase 183 two-gauge transfer_uninstrumented idiom
+ * (lib/core/meter/two-gauge.cjs): a welded instrument that cannot tell "no quality"
+ * from "no instrument" is blindfolded, so the third state is named, not zeroed.
+ *
+ * The harness is STRUCTURED TO RUN the live A/B the instant a subject exists: pass a
+ * navigator subject_class plus a real liveChoice and the result returns 'measured'.
+ * It does NOT manufacture that subject. (Navigator-authority override note: Phase 184
+ * was built into v1.15.0-beta.9 on navigator authority despite METER reading
+ * subject_class=unknown; the CODE ships green, but R1's LIVE reading remains a NAMED
+ * DEBT until a live navigator reaches the gate. See 184-SUMMARY.md.)
+ *
+ * Canon Part 8: LOCAL only. The harness reads the LOCAL projection through the READER
+ * and derives subject_class from a LOCAL env marker only -- never a key, never a user
+ * id, never any network. House rule: hyphens only, no em-dashes. Never throws.
+ */
+
+const reader = require('./decide-projection-reader.cjs');
+
+// subject_class enum, mirroring lib/core/meter/two-gauge.cjs CORRECTION A. Only
+// subject_class==navigator (a live, non-maintainer keyed turn) with a REAL live
+// choice clears the A/B to 'measured'. A maintainer/dogfood reading does NOT clear
+// it (the entry-20-style override guard: a maintainer reading is not the live
+// navigator reading R1 names).
+const SUBJECT_CLASS = Object.freeze({
+  MAINTAINER: 'maintainer',
+  NAVIGATOR: 'navigator',
+  UNKNOWN: 'unknown',
+});
+const SUBJECT_CLASS_VALUES = Object.freeze([
+  SUBJECT_CLASS.MAINTAINER, SUBJECT_CLASS.NAVIGATOR, SUBJECT_CLASS.UNKNOWN,
+]);
+
+// The live-A/B weld state. Mirrors the two-gauge TRANSFER_STATE { measured,
+// uninstrumented } third-state honesty.
+const LIVE_AB_STATE = Object.freeze({ MEASURED: 'measured', UNINSTRUMENTED: 'uninstrumented' });
+
+// The UNGROUNDED arm: the Canon Part 3 Tier-0 hardcoded minimal verb set (Run
+// Methodology / Reformulate / Free-Text), the option set the gate renders with NO
+// projection grounding. Frozen so the A/B baseline is stable. Each is CONTENT only;
+// fires:false (the harness never runs a capability -- READER-04).
+const UNGROUNDED_OPTIONS = Object.freeze([
+  Object.freeze({ label: 'Run Methodology', command: null, reach_id: null, sub_mode: null, framework: null, why: 'tier-0 minimal (ungrounded)', fires: false }),
+  Object.freeze({ label: 'Reformulate', command: null, reach_id: null, sub_mode: null, framework: null, why: 'tier-0 minimal (ungrounded)', fires: false }),
+  Object.freeze({ label: 'Free-Text', command: null, reach_id: null, sub_mode: null, framework: null, why: 'tier-0 minimal (ungrounded)', fires: false }),
+]);
+
+/**
+ * Derive subject_class from a LOCAL env marker only (Part 8). Default 'unknown' --
+ * the honest default when no maintainer/navigator signal is resolvable, never a
+ * fragile guess. A test seam (opts.subjectClass) overrides for harness exercise.
+ */
+function deriveSubjectClass(opts) {
+  const o = opts || {};
+  if (typeof o.subjectClass === 'string' && SUBJECT_CLASS_VALUES.indexOf(o.subjectClass) !== -1) {
+    return o.subjectClass;
+  }
+  if (typeof process.env.MINDRIAN_DOGFOOD_ROOM_DIR === 'string'
+      && process.env.MINDRIAN_DOGFOOD_ROOM_DIR.trim().length > 0) {
+    return SUBJECT_CLASS.MAINTAINER;
+  }
+  return SUBJECT_CLASS.UNKNOWN;
+}
+
+// LOCAL structural choice-shift: the fraction of grounded option labels NOT present
+// in the ungrounded set. 1.0 means the projection grounding wholly reshaped the
+// option set; 0.0 means it changed nothing. A structural measure, not a live choice.
+function _choiceShift(grounded, ungrounded) {
+  const g = Array.isArray(grounded) ? grounded.map(function (o) { return o && o.label; }) : [];
+  const u = new Set((Array.isArray(ungrounded) ? ungrounded : []).map(function (o) { return o && o.label; }));
+  if (g.length === 0) return 0;
+  let diff = 0;
+  for (const l of g) if (!u.has(l)) diff += 1;
+  return diff / g.length;
+}
+
+/**
+ * runGroundedVsUngroundedAB(context, opts) -> frozen {
+ *   local_measurement: {...},   // the structural A/B that runs TODAY
+ *   live_ab: {...},             // the NAMED DEBT: 'measured' only with a live subject
+ * }
+ *
+ * opts (all optional; the test + future-live seams):
+ *   projection / projectionPath  forwarded to the READER (fixture injection)
+ *   subjectClass                 forces the derived subject_class (test seam)
+ *   liveChoice                   a REAL navigator choice { arm, label, latency_ms }
+ *                                supplied when a live subject exists -> clears to
+ *                                'measured'. Absent -> 'uninstrumented' (the debt).
+ * Never throws.
+ */
+function runGroundedVsUngroundedAB(context, opts) {
+  const o = opts || {};
+
+  // GROUNDED arm -- projection-ranked options via the READER.
+  const tG = Date.now();
+  const grounded = reader.offerProjectionCapabilities(context, o);
+  const latG = Date.now() - tG;
+
+  // UNGROUNDED arm -- the Tier-0 minimal set, no projection.
+  const tU = Date.now();
+  const ungroundedOptions = UNGROUNDED_OPTIONS.slice();
+  const latU = Date.now() - tU;
+
+  const groundedOptions = (grounded && grounded.skipped) ? [] : ((grounded && grounded.options) || []);
+  const choice_shift = _choiceShift(groundedOptions, ungroundedOptions);
+
+  const local_measurement = {
+    grounded_option_count: groundedOptions.length,
+    ungrounded_option_count: ungroundedOptions.length,
+    choice_shift: choice_shift,
+    latency_grounded_ms: latG,
+    latency_ungrounded_ms: latU,
+    latency_delta_ms: latG - latU,
+    grounded_skipped: !!(grounded && grounded.skipped),
+    grounded_reason: grounded ? grounded.reason : 'no_result',
+  };
+
+  // LIVE A/B -- the NAMED DEBT. 'measured' only when a live navigator subject exists
+  // AND supplies a real choice. Otherwise the honest 'uninstrumented' third state.
+  const subject_class = deriveSubjectClass(o);
+  const liveChoice = o.liveChoice;
+  const hasLiveSubject = subject_class === SUBJECT_CLASS.NAVIGATOR
+    && liveChoice && typeof liveChoice === 'object';
+
+  let live_ab;
+  if (hasLiveSubject) {
+    live_ab = {
+      subject_class: subject_class,
+      state: LIVE_AB_STATE.MEASURED,
+      result: {
+        chosen_arm: typeof liveChoice.arm === 'string' ? liveChoice.arm : null,
+        chosen_label: typeof liveChoice.label === 'string' ? liveChoice.label : null,
+        latency_ms: typeof liveChoice.latency_ms === 'number' ? liveChoice.latency_ms : null,
+      },
+      named_debt: null,
+    };
+  } else {
+    live_ab = {
+      subject_class: subject_class,
+      state: LIVE_AB_STATE.UNINSTRUMENTED,
+      result: null,
+      named_debt: 'R1 live grounded-vs-ungrounded A/B is UNINSTRUMENTED: no live navigator '
+        + 'has reached the gate (subject_class=' + subject_class + '). The harness CAN run '
+        + 'the live A/B the instant a navigator subject exists; today it records this honest '
+        + 'third state rather than fabricating a live pass. Mirrors Phase 183 METER '
+        + 'transfer_uninstrumented.',
+    };
+  }
+
+  return Object.freeze({ local_measurement: local_measurement, live_ab: live_ab });
+}
+
+module.exports = {
+  runGroundedVsUngroundedAB: runGroundedVsUngroundedAB,
+  deriveSubjectClass: deriveSubjectClass,
+  SUBJECT_CLASS: SUBJECT_CLASS,
+  LIVE_AB_STATE: LIVE_AB_STATE,
+  UNGROUNDED_OPTIONS: UNGROUNDED_OPTIONS,
+};