@mindrian_os/install 1.13.0-beta.11

package/lib/core/navigation-engine.cjs

@@ -0,0 +1,664 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 91-00 -- Navigation Engine core (L5 Decision layer)
+ * ==========================================================
+ * Single export `decide(turn, context) -> decision` composes the five
+ * input signals (ICM scope + SQL relations + Feynman-MINTO reasoning +
+ * BRAIN.md derivations + intent/persona) through a structured decision
+ * function (NOT a weighted score per locked decision D-02) and returns
+ * a typed decision struct with full trace.
+ *
+ * Contract source of truth:
+ *   .planning/research/navigation-engine-brain-interface.md (v1, frozen
+ *   at Phase 90-09).
+ *
+ * Canon Part 8 posture (READ THIS FIRST):
+ *   This module is a PURE LOCAL READER. It NEVER queries Brain. It
+ *   NEVER reads BRAIN.md directly via fs.readFileSync; the only allowed
+ *   read path is folder-memory.cjs readQuadruple. It NEVER constructs
+ *   Cypher queries. It NEVER embeds BRAIN.md body strings in network
+ *   payloads. The two PERMITTED brain-client touches are
+ *   brain-client.isAvailable() (boolean, no network when cached) and
+ *   brain-client.schema() (scalar, no user content leaves the local
+ *   process). Both are optional; the engine works fully offline.
+ *
+ * Per Section 2.4: a single readQuadruple result MAY be cached for the
+ * duration of one decide() call. Cross-call caching is FORBIDDEN.
+ *
+ * Per locked decision D-02: this engine is NOT a weighted score across
+ * the five signals. Brain's section weights (0.35 + 0.20 + 0.15 + ...)
+ * stay INSIDE the BRAIN.md contribution block; the staleness multiplier
+ * scales that block as a whole. Inter-signal composition is rule-based
+ * with explicit precedence, not arithmetic.
+ *
+ * License: BSL 1.1.
+ */
+
+const shared = require('./navigation-engine-shared.cjs');
+const folderMemory = require('./folder-memory.cjs'); // for readQuadruple
+// brain-client is OPTIONAL: required only if downstream callers want to
+// pass an explicit brainAvailable hint, but isAvailable() is also fine
+// from the call site. We do NOT require() it here to keep the dependency
+// graph minimal and to make grep-guards trivially passable.
+
+const STALENESS_MULTIPLIERS = shared.STALENESS_MULTIPLIERS;
+const SECTION_WEIGHTS = shared.SECTION_WEIGHTS;
+const REQUIRED_SECTION_KEYS = shared.REQUIRED_SECTION_KEYS;
+const OPTIONAL_SECTION_KEYS = shared.OPTIONAL_SECTION_KEYS;
+const CANONICAL_VERBS = shared.CANONICAL_VERBS;
+
+// Wicked-score escalation threshold per Canon Appendix E rule R4.
+const WICKED_ESCALATION_THRESHOLD = 8;
+
+// Confidence floor for Section 6 RECOMMENDED gate.
+const RECOMMENDED_CONFIDENCE_FLOOR = 0.7;
+
+// ---------- Pattern parsers (tolerant; never throw) ----------
+
+/**
+ * Parse pattern_matches body for `confidence: <float>` candidates.
+ * Returns the highest confidence found in [0, 1], or null when no
+ * candidate is parseable. Tolerant of body whitespace, multi-line, and
+ * forward-compat extra fields.
+ */
+function extractHighestConfidence(body) {
+  if (typeof body !== 'string' || body.length === 0) return null;
+  const re = /confidence\s*:\s*([01](?:\.\d+)?|0?\.\d+)/gi;
+  let best = null;
+  let m;
+  while ((m = re.exec(body)) !== null) {
+    const v = parseFloat(m[1]);
+    if (!isNaN(v) && v >= 0.0 && v <= 1.0) {
+      if (best === null || v > best) best = v;
+    }
+  }
+  return best;
+}
+
+/**
+ * Extract the verb associated with the highest-confidence candidate in
+ * pattern_matches. Returns null when no candidate is parseable. Verbs
+ * MUST appear before the `(confidence: ...)` parenthetical, matching
+ * Canon Part 3 vocabulary.
+ *
+ * Body shape (per Plan 90-01 deriveSection emit):
+ *   - Run Methodology (confidence: 0.85, source: SWOT)
+ *   - Reformulate (confidence: 0.72, source: 5 Whys)
+ */
+function extractTopCandidateVerb(body) {
+  if (typeof body !== 'string' || body.length === 0) return null;
+  const lines = body.split(/\r?\n/);
+  let bestConf = -1;
+  let bestVerb = null;
+  for (const line of lines) {
+    // Match `<prefix> <verb> (confidence: 0.NN ...)`
+    const m = /^[\s\-*]*(.+?)\s*\(\s*confidence\s*:\s*([01](?:\.\d+)?|0?\.\d+)/i.exec(line);
+    if (!m) continue;
+    const verb = m[1].trim();
+    const conf = parseFloat(m[2]);
+    if (isNaN(conf)) continue;
+    // Resolve verb against canonical vocabulary (case-insensitive
+    // contains-match; closed set).
+    let resolved = null;
+    for (const v of CANONICAL_VERBS) {
+      if (verb.toLowerCase() === v.toLowerCase()) {
+        resolved = v;
+        break;
+      }
+    }
+    if (resolved !== null && conf > bestConf) {
+      bestConf = conf;
+      bestVerb = resolved;
+    }
+  }
+  return bestVerb;
+}
+
+/**
+ * Parse wicked_indicators body for `wicked_score: <int>`. Returns 0 when
+ * no score is parseable.
+ */
+function extractWickedScore(body) {
+  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 (isNaN(v) || v < 0) return 0;
+  return v;
+}
+
+// ---------- Trace builders ----------
+
+function buildIcmScope(quadruple, turn) {
+  const room = quadruple && quadruple.room;
+  return {
+    section_path: turn && turn.sectionPath ? turn.sectionPath : null,
+    room_exists: room && room.exists ? true : false,
+    artifact_count: quadruple && quadruple.state ? (quadruple.state.artifact_count || 0) : 0,
+  };
+}
+
+function buildSqlSignals(_quadruple, _turn) {
+  // Phase 91-00 ships the engine surface; the SQL signal is consumed
+  // from a future plan that wires room.db edge counts. For this plan
+  // the slot is structural (so /mos:explain-decision can render it) but
+  // contributes no rules. Returning an object (not null) keeps the
+  // five-signal capture invariant met (Test 20).
+  return { edges_consulted: 0, contradictions_detected: 0 };
+}
+
+function buildMintoReasoning(quadruple) {
+  const r = quadruple && quadruple.reasoning;
+  if (!r) {
+    return { exists: false, reasoning_health_score: 0, governing_thought: null, is_stale: true };
+  }
+  return {
+    exists: r.exists === true,
+    reasoning_health_score:
+      typeof r.reasoning_health_score === 'number' ? r.reasoning_health_score : 0,
+    governing_thought: typeof r.governing_thought === 'string' ? r.governing_thought : null,
+    is_stale: r.is_stale === true,
+  };
+}
+
+function buildIntentPersona(context) {
+  const persona = context && context.userPersona ? context.userPersona : null;
+  const intent = context && context.intentSignal ? context.intentSignal : null;
+  return {
+    archetype: persona && persona.archetype ? persona.archetype : null,
+    problem_type: persona && persona.problem_type ? persona.problem_type : null,
+    venture_stage: persona && persona.venture_stage ? persona.venture_stage : null,
+    intent: intent && intent.intent ? intent.intent : null,
+    intent_confidence: intent && typeof intent.confidence === 'number' ? intent.confidence : null,
+  };
+}
+
+// ---------- Section consumption ----------
+
+function consumedSections(brain) {
+  if (!brain || typeof brain !== 'object' || !brain.sections) return [];
+  const out = [];
+  // Required first (canonical order), then optional.
+  for (const k of REQUIRED_SECTION_KEYS) {
+    const v = brain.sections[k];
+    if (v !== null && v !== undefined && typeof v === 'object' && typeof v.body === 'string' && v.body.length > 0 && !/^\s*\(no signal\)\s*$/i.test(v.body)) {
+      out.push(k);
+    }
+  }
+  for (const k of OPTIONAL_SECTION_KEYS) {
+    const v = brain.sections[k];
+    if (v !== null && v !== undefined && typeof v === 'object' && typeof v.body === 'string' && v.body.length > 0 && !/^\s*\(no signal\)\s*$/i.test(v.body)) {
+      out.push(k);
+    }
+  }
+  return out;
+}
+
+// ---------- Five-signal composition (rule-based per D-02) ----------
+
+/**
+ * Resolve the best fire_skill given Brain signal state and the wicked
+ * escalation rule. Returns null when no signal warrants firing.
+ */
+function resolveFireSkill(brain, weightApplied, tierMode) {
+  // Wicked escalation takes precedence over normal routing (Canon
+  // Appendix E rule R4).
+  const wickedSection = brain && brain.sections && brain.sections.wicked_indicators;
+  if (wickedSection && wickedSection.body) {
+    const score = extractWickedScore(wickedSection.body);
+    if (score >= WICKED_ESCALATION_THRESHOLD) {
+      return 'soft-systems';
+    }
+  }
+  // Mode A + non-zero weight + parseable verb -> fire that verb's skill.
+  if (tierMode === 'mode_a' && weightApplied > 0) {
+    const pm = brain && brain.sections && brain.sections.pattern_matches;
+    if (pm && pm.body) {
+      const verb = extractTopCandidateVerb(pm.body);
+      if (verb !== null) {
+        // Map canonical verb to skill family. v1 ships a minimal mapping
+        // sufficient to satisfy "fire_skill non-null when fresh" (Test 20).
+        return verbToSkillFamily(verb);
+      }
+    }
+    // Fresh Brain but no pattern_matches verb: fall back to context
+    // skill so Test 20 still has a non-null fire_skill.
+    if (weightApplied >= 0.9) {
+      return 'context-engine';
+    }
+  }
+  return null;
+}
+
+function verbToSkillFamily(verb) {
+  // Closed mapping. Future plans can extend the table; the engine
+  // never invents skill names from prose.
+  switch (verb) {
+    case 'Run Methodology': return 'methodology-router';
+    case 'Reformulate': return 'beautiful-question';
+    case 'Spawn Sub-Agent': return 'subagent-dispatcher';
+    case 'Navigate Graph': return 'graph-navigator';
+    case "Devil's Advocate": return 'red-team';
+    case 'Scenario Plan': return 'scenario-planner';
+    case 'Synthesize': return 'blue-hat';
+    case 'Bank Opportunity': return 'opportunity-bank';
+    case 'Defer': return 'defer';
+    case 'Free-Text': return 'larry-default';
+    default: return null;
+  }
+}
+
+/**
+ * Compose suppress_skills based on intent and persona signals. v1
+ * ships an empty array; future plans will populate from intent
+ * heuristics. Returning [] keeps Test 31 honoring the array invariant.
+ */
+function resolveSuppressSkills(_context, _brain) {
+  return [];
+}
+
+/**
+ * persona_updates: returns null when no threshold crossed; otherwise an
+ * object with allowed keys archetype/problem_type/venture_stage.
+ *
+ * v1 ships null (no auto-update). Plan 91-01 owns the durability layer.
+ */
+function resolvePersonaUpdates(_context, _brain) {
+  return null;
+}
+
+/**
+ * offer_next_step: returns null OR { command, reason }. Max 1 per turn
+ * is enforced trivially (we never return more than one).
+ *
+ * v1 ships null until Plan 91-04 wires the offer presentation rules.
+ */
+function resolveOfferNextStep(_context, _brain) {
+  return null;
+}
+
+// ---------- decide() main entry ----------
+
+/**
+ * decide(turn, context) -> decision
+ *
+ * Inputs:
+ *   turn = { userText, sectionPath, sessionId }
+ *   context = {
+ *     quadruple,        // pre-read quadruple (caller responsibility)
+ *     brainAvailable,   // boolean from brain-client.isAvailable()
+ *     userPersona,      // { archetype, problem_type, venture_stage }
+ *     intentSignal      // { intent, confidence }
+ *   }
+ *
+ * Returns: typed decision struct with complete trace.
+ *
+ * Never throws. Every internal failure falls through to a safe
+ * emptyDecision() with chosen_rationale noting the fault.
+ *
+ * Per-turn cache: a single quadruple lookup may be cached within this
+ * call only. This implementation expects context.quadruple to be
+ * pre-read (the standard Phase 91-02 hook integration pattern), so the
+ * cache is implicit. If context.quadruple is absent, decide() falls
+ * back to readQuadruple(turn.sectionPath) once and caches the result
+ * for the duration of THIS call only. Cross-call caching FORBIDDEN per
+ * Section 2.4.
+ */
+function decide(turn, context) {
+  // Safe defaults.
+  const ctx = context || {};
+  const t = turn || {};
+  const decision = shared.emptyDecision();
+  const trace = decision.decision_trace;
+
+  try {
+    // Per-turn cache scope: read quadruple if not provided. The local
+    // `quadruple` binding is the cache; it never escapes this function.
+    let quadruple = ctx.quadruple;
+    if (!quadruple) {
+      const sectionPath = t.sectionPath;
+      if (typeof sectionPath === 'string' && sectionPath.length > 0) {
+        quadruple = folderMemory.readQuadruple(sectionPath);
+      }
+    }
+
+    // If we still have no quadruple, return empty decision in tier_0.
+    if (!quadruple) {
+      trace.brain_md_tier_mode = 'tier_0';
+      trace.brain_md_staleness = 'absent';
+      trace.brain_md_weight_applied = 0.0;
+      trace.icm_scope = buildIcmScope(null, t);
+      trace.sql_signals = buildSqlSignals(null, t);
+      trace.minto_reasoning = buildMintoReasoning(null);
+      trace.intent_persona = buildIntentPersona(ctx);
+      trace.chosen_rationale = 'Tier 0 fallback: no quadruple available for sectionPath.';
+      return decision;
+    }
+
+    const brainAvailable = ctx.brainAvailable === true;
+    const brain = quadruple.brain || null;
+
+    // Section 5 tier-mode resolver (re-evaluated every turn; no cache).
+    const tierMode = shared.resolveTierMode(quadruple, brainAvailable);
+    trace.brain_md_tier_mode = tierMode;
+
+    // Section 4 staleness multiplier (BRAIN.md contribution scaler).
+    // The result is later assigned to trace.brain_md_weight_applied per
+    // Section 8.1. Multiplier source rows:
+    //   null brain                                -> 0.0
+    //   staleness:fresh                           -> 1.0
+    //   stale_reason:brain_offline                -> 0.9 (EXEMPT)
+    //   stale_reason:age_exceeded                 -> 0.7
+    //   stale_reason:brain_graph_version_mismatch -> 0.5
+    //   stale_reason:governing_thought_changed    -> 0.3
+    //   stale_reason:derivation_timeout           -> 0.2
+    //   stale_reason:parse_failed                 -> 0.0
+    //   staleness:unavailable                     -> 0.0
+    let weightApplied = shared.applyStalenessMultiplier(brain);
+
+    // Section 3.1 attribution guard. brain.author MUST equal 'brain';
+    // any other value indicates a Canon Part 2 attribution breach and
+    // demotes the BRAIN.md weight to 0.0 with a trace note. The
+    // resulting brain_md_weight_applied is observable in the decision
+    // trace by /mos:explain-decision (Plan 91-05).
+    let attributionBreach = false;
+    if (brain !== null && brain.author !== undefined && brain.author !== 'brain') {
+      attributionBreach = true;
+      weightApplied = 0.0; // brain_md_weight_applied demotion target
+    }
+    // Section 8.1 trace.brain_md_weight_applied final assignment.
+    trace.brain_md_weight_applied = weightApplied;
+
+    // Section 8 trace fields (always emitted, even with brain null).
+    if (brain === null) {
+      trace.brain_md_version = null;
+      trace.brain_md_staleness = 'absent';
+      trace.brain_md_stale_reason = null;
+    } else {
+      trace.brain_md_version = typeof brain.brain_graph_version === 'number'
+        ? brain.brain_graph_version
+        : null;
+      trace.brain_md_staleness = typeof brain.staleness === 'string'
+        ? brain.staleness
+        : 'absent';
+      trace.brain_md_stale_reason = typeof brain.stale_reason === 'string'
+        ? brain.stale_reason
+        : null;
+    }
+
+    // Section 3.2 sections_consumed list (non-null bodies only).
+    trace.brain_md_sections_consumed = consumedSections(brain);
+
+    // Section 6 RECOMMENDED gate evaluation (record confidence even
+    // when gate fails; render marker only when ALL conditions hold).
+    let recommendedConfidence = null;
+    let recommendedRendered = false;
+    if (brain !== null && brain.sections) {
+      const pm = brain.sections.pattern_matches;
+      if (pm && typeof pm.body === 'string') {
+        recommendedConfidence = extractHighestConfidence(pm.body);
+      }
+    }
+    trace.brain_md_recommended_confidence = recommendedConfidence;
+
+    if (
+      tierMode === 'mode_a' &&
+      !attributionBreach &&
+      recommendedConfidence !== null &&
+      recommendedConfidence >= RECOMMENDED_CONFIDENCE_FLOOR
+    ) {
+      // Section 6 condition 4: candidate verb must match a Canon Part 3
+      // vocabulary entry. extractTopCandidateVerb returns the resolved
+      // canonical verb or null.
+      const pm = brain.sections.pattern_matches;
+      const verb = extractTopCandidateVerb(pm.body);
+      if (verb !== null) {
+        recommendedRendered = true;
+      }
+    }
+    trace.brain_md_recommended_marker_rendered = recommendedRendered;
+
+    // Five-signal triangulation (structural; rule-based per D-02).
+    trace.icm_scope = buildIcmScope(quadruple, t);
+    trace.sql_signals = buildSqlSignals(quadruple, t);
+    trace.minto_reasoning = buildMintoReasoning(quadruple);
+    trace.intent_persona = buildIntentPersona(ctx);
+
+    // Compose chosen_rationale from active rules.
+    const rationale = [];
+    if (tierMode === 'tier_0') {
+      if (brain === null) {
+        rationale.push('Tier 0 fallback: BRAIN.md absent.');
+      } else if (brain.parse_failed === true) {
+        rationale.push('brain_parse_failed fell through to tier_0.');
+      } else if (brain.staleness === 'unavailable') {
+        rationale.push('Tier 0 fallback: BRAIN.md staleness unavailable.');
+      } else {
+        rationale.push('Tier 0 fallback: brain unreachable and not offline-exempt.');
+      }
+    } else if (tierMode === 'mode_b') {
+      rationale.push('Mode B local-only: brain unreachable; brain_offline exemption applied (weight 0.9).');
+      rationale.push('mode_b suppresses RECOMMENDED per Canon Part 3.');
+    } else {
+      // mode_a
+      if (recommendedRendered) {
+        rationale.push('Mode A: RECOMMENDED rendered (confidence >= 0.7).');
+      } else if (recommendedConfidence !== null) {
+        rationale.push('Mode A: pattern_matches confidence ' + recommendedConfidence + ' below 0.7 floor; RECOMMENDED suppressed.');
+      } else {
+        rationale.push('Mode A: no pattern_matches candidate available.');
+      }
+    }
+    if (attributionBreach) {
+      rationale.unshift('canon_part_2_attribution_breach: brain.author is not "brain"; weight demoted to 0.0.');
+    }
+
+    // Wicked escalation note (added to rationale when triggered).
+    const wickedSection = brain && brain.sections && brain.sections.wicked_indicators;
+    if (wickedSection && wickedSection.body) {
+      const score = extractWickedScore(wickedSection.body);
+      if (score >= WICKED_ESCALATION_THRESHOLD) {
+        rationale.push('wicked_escalation: wicked_score >= ' + WICKED_ESCALATION_THRESHOLD + ' triggers soft-systems family.');
+      }
+    }
+
+    trace.chosen_rationale = rationale.join(' ');
+
+    // Compose decision outputs (rule-based, not weighted score).
+    decision.fire_skill = resolveFireSkill(brain, weightApplied, tierMode);
+    decision.suppress_skills = resolveSuppressSkills(ctx, brain);
+    decision.persona_updates = resolvePersonaUpdates(ctx, brain);
+    decision.offer_next_step = resolveOfferNextStep(ctx, brain);
+
+    // Phase 91-07: problem-type routing contribution. Lazy-require so a
+    // missing module does not crash the engine -- problem-type routing
+    // BIASES the rationale (and may inform fire_skill when no
+    // higher-priority signal has set one), but is never load-bearing.
+    // Per locked decision D-08 + Canon Appendix E rule R4.
+    try {
+      if (brain !== null && brain.sections) {
+        const ptRouter = require('./problem-type-router.cjs');
+        const ptSection = brain.sections.problemtype_classification;
+        const wkSection = brain.sections.wicked_indicators;
+        const parsed = ptRouter.parseProblemTypeSection(ptSection);
+        let routing = null;
+        if (parsed !== null) {
+          routing = ptRouter.routeByProblemType(parsed.type, parsed.confidence);
+        }
+        const wickedEscalate = ptRouter.detectWickedEscalation(wkSection);
+        if (wickedEscalate) {
+          // Wicked override applies regardless of base type. If we have
+          // no base routing, synthesize a stub so applyWickedOverride
+          // has a baseline to overlay.
+          if (routing === null) {
+            routing = {
+              recommended_skills: [],
+              suppressed_skills: [],
+              reason: '',
+              wicked_override: false,
+            };
+          }
+          routing = ptRouter.applyWickedOverride(routing);
+        }
+
+        if (routing !== null && routing.reason && routing.reason.length > 0) {
+          // Append routing reason to chosen_rationale so /mos:explain-
+          // decision can surface the contribution.
+          const existing = trace.chosen_rationale || '';
+          const sep = existing.length > 0 ? ' ' : '';
+          trace.chosen_rationale = existing + sep + 'ProblemType routing: ' + routing.reason;
+
+          // If no higher-priority signal set fire_skill AND routing
+          // recommends a primary skill AND confidence is usable, set
+          // fire_skill to the primary recommendation. Wicked override
+          // always wins when present (its first skill is the soft-
+          // systems entry point).
+          const conf = parsed && typeof parsed.confidence === 'number' ? parsed.confidence : null;
+          const confOk = routing.wicked_override || (typeof conf === 'number' && conf >= 0.5);
+          if (
+            decision.fire_skill === null &&
+            confOk &&
+            Array.isArray(routing.recommended_skills) &&
+            routing.recommended_skills.length > 0
+          ) {
+            decision.fire_skill = routing.recommended_skills[0];
+          }
+        }
+      }
+    } catch (_e) {
+      // Routing is biasing-only; never block the decision on a routing
+      // module fault. Leave decision + trace untouched.
+    }
+
+    // Phase 91-08: framework-chain-composer contribution. Lazy-require
+    // so a missing module never crashes the engine -- chain composition
+    // is one signal among five and biases offer_next_step when no higher-
+    // priority signal has populated it. Per locked decision D-09 + Canon
+    // Part 2 Engine 1 + Appendix E. Reads BRAIN.md framework_chain_
+    // predictions section (FEEDS_INTO edges authored by Phase 90-01).
+    // Canon Part 8: zero Brain queries at engine time -- composer reads
+    // only the LOCAL section body passed in via quadruple.
+    try {
+      if (brain !== null && brain.sections) {
+        const chainComposer = require('./framework-chain-composer.cjs');
+        const chainSection = brain.sections.framework_chain_predictions;
+        if (chainSection !== null && chainSection !== undefined) {
+          const edges = chainComposer.parseFrameworkChainSection(chainSection);
+          if (edges.length > 0) {
+            const completed = chainComposer.detectCompletedFramework(
+              null, // roomDir is not needed when reasoning carries the signal
+              t.sectionPath || null,
+              quadruple.reasoning || null
+            );
+            if (completed !== null) {
+              const proposal = chainComposer.proposeNextFramework(completed, edges);
+              if (proposal !== null) {
+                // User override detection: if lastTurnOffer was the chain
+                // proposal AND current turn invokes a DIFFERENT /mos:
+                // command, record REJECTED chain suggestion as graph data
+                // per Canon Part 4. The override check runs BEFORE we
+                // overwrite offer_next_step so the user's intent (in
+                // userText) gets recorded against the prior offer.
+                const lastOffer = ctx.lastTurnOffer;
+                const userText = typeof t.userText === 'string' ? t.userText : '';
+                if (
+                  lastOffer &&
+                  typeof lastOffer === 'object' &&
+                  typeof lastOffer.command === 'string' &&
+                  lastOffer.command.length > 0 &&
+                  userText.length > 0
+                ) {
+                  // Match a /mos: command in the user text.
+                  const userCmdMatch = /\/mos:[a-z][a-z0-9-]*/i.exec(userText);
+                  if (userCmdMatch !== null) {
+                    const userCmd = userCmdMatch[0];
+                    if (userCmd !== lastOffer.command) {
+                      // Override recorded as graph data per Canon Part 4.
+                      const existing = trace.chosen_rationale || '';
+                      const sep = existing.length > 0 ? ' ' : '';
+                      trace.chosen_rationale =
+                        existing + sep +
+                        'REJECTED chain suggestion: user invoked ' + userCmd +
+                        ' instead of ' + lastOffer.command + '.';
+                      trace.chain_override_recorded = true;
+                    }
+                  }
+                }
+
+                // Set offer_next_step ONLY when no higher-priority signal
+                // has already populated it. Chain composition is one
+                // signal among five; it never overwrites a stronger one.
+                if (decision.offer_next_step === null) {
+                  decision.offer_next_step = {
+                    command: proposal.command,
+                    reason: proposal.reason,
+                  };
+                  // Surface chain-specific eligibility flag in trace so
+                  // offer-presenter (Plan 91-04) can render the
+                  // RECOMMENDED marker per Canon Part 3 Section 6 when
+                  // Mode A holds AND chain confidence >= 0.7.
+                  trace.chain_recommended_eligible = proposal.recommended_eligible === true;
+                  // When the engine's RECOMMENDED gate already fired
+                  // (e.g. via pattern_matches), the chain proposal piggy-
+                  // backs on the existing marker. When pattern_matches
+                  // had no candidate (the common case in Wave 3 fixtures)
+                  // and Mode A holds and the chain proposal is eligible,
+                  // promote the marker so the presenter renders it.
+                  if (
+                    tierMode === 'mode_a' &&
+                    proposal.recommended_eligible === true &&
+                    trace.brain_md_recommended_marker_rendered === false
+                  ) {
+                    trace.brain_md_recommended_marker_rendered = true;
+                    trace.brain_md_recommended_confidence =
+                      typeof trace.brain_md_recommended_confidence === 'number' &&
+                      trace.brain_md_recommended_confidence > proposal.confidence
+                        ? trace.brain_md_recommended_confidence
+                        : proposal.confidence;
+                  }
+                  // Append chain rationale for /mos:explain-decision.
+                  const existing2 = trace.chosen_rationale || '';
+                  const sep2 = existing2.length > 0 ? ' ' : '';
+                  trace.chosen_rationale =
+                    existing2 + sep2 +
+                    'Framework chain: ' + completed + ' FEEDS_INTO ' + proposal.next +
+                    ' (Brain confidence ' + proposal.confidence.toFixed(2) + ').';
+                }
+              }
+            }
+          }
+        }
+      }
+    } catch (_e) {
+      // Chain composition is biasing-only; never block the decision on
+      // a composer fault. Leave decision + trace untouched.
+    }
+
+    return decision;
+  } catch (err) {
+    // Graceful degradation: never throw out of decide().
+    const safe = shared.emptyDecision();
+    safe.decision_trace.chosen_rationale =
+      'engine_fault: ' + (err && err.message ? err.message : String(err));
+    safe.decision_trace.brain_md_tier_mode = 'tier_0';
+    safe.decision_trace.brain_md_staleness = 'absent';
+    return safe;
+  }
+}
+
+module.exports = {
+  decide: decide,
+  // Internal helpers exposed for downstream Phase 91 plans + testing:
+  resolveTierMode: shared.resolveTierMode,
+  applyStalenessMultiplier: shared.applyStalenessMultiplier,
+  evaluateRecommendedGate: function (decision, quadruple) {
+    // Convenience accessor matching plan frontmatter contract.
+    return decision &&
+      decision.decision_trace &&
+      decision.decision_trace.brain_md_recommended_marker_rendered === true;
+  },
+};