session-orchestrator 3.16.0

package/scripts/lib/mode-selector/context-pressure.mjs

@@ -0,0 +1,157 @@
+/**
+ * Context-pressure signal computation (#332).
+ *
+ * Extracted from scripts/lib/mode-selector.mjs (issue #358).
+ * Pure function: no I/O, no side effects.
+ *
+ * Per W1 D3 risk warning, scorer split deferred; only `computeContextPressure`
+ * extracted this session.
+ */
+
+// ---------------------------------------------------------------------------
+// Local helpers (inlined — clamp/round2/safeArray are <5 lines each and are
+// also used by the parent mode-selector.mjs; inlining avoids a circular import
+// or a shared-helper re-export).
+// ---------------------------------------------------------------------------
+
+/**
+ * Clamp a number to [min, max].
+ * @param {number} v
+ * @param {number} min
+ * @param {number} max
+ * @returns {number}
+ */
+function clamp(v, min, max) {
+  return Math.min(max, Math.max(min, v));
+}
+
+/**
+ * Round to 2 decimal places (avoids floating-point drift in comparisons).
+ * @param {number} v
+ * @returns {number}
+ */
+function round2(v) {
+  return Math.round(v * 100) / 100;
+}
+
+/**
+ * Safely coerce to an array (returns [] for non-arrays, null, undefined).
+ * @param {unknown} v
+ * @returns {any[]}
+ */
+function safeArray(v) {
+  return Array.isArray(v) ? v : [];
+}
+
+// ---------------------------------------------------------------------------
+// Regex
+// ---------------------------------------------------------------------------
+
+/**
+ * Regex for cross-cutting keyword detection in task description text.
+ * Matches phrases that indicate large, scope-spanning work.
+ */
+const CROSS_CUTTING_PATTERN =
+  /across all|every (skill|agent|repo)|repo-?wide|cross-cutting|rename across|massive refactor/i;
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} ContextPressureComponents
+ * @property {number} scope - Scope component contribution (0.0–0.5).
+ * @property {number} keywords - Cross-cutting keyword component contribution (0 or 0.25).
+ * @property {number} carryover - Carryover component contribution (0.0–0.25).
+ */
+
+/**
+ * @typedef {Object} ContextPressureResult
+ * @property {number} score - Aggregate pressure score 0.0–1.0.
+ * @property {ContextPressureComponents} components - Per-component breakdown.
+ * @property {'low'|'medium'|'high'} level - Bucketed level from score.
+ */
+
+/**
+ * Compute context-pressure score (0.0–1.0) for the proposed work.
+ * High pressure → recommend deferring scope or preferring deep mode over feature.
+ *
+ * Inputs (read from signals):
+ *   - signals.topPriorities: number[]|undefined — count used as proxy for scope
+ *   - signals.recentSessions: array — tail-5 used to derive carryover_ratio from
+ *       session.effectiveness.carryover / session.effectiveness.planned_issues
+ *   - signals.taskDescriptionText: string|undefined — joined PRD/issue body for keyword scan
+ *
+ * Score components (additive, clamped to [0, 1]):
+ *   - scope:    min(0.5, max(0, (priorityCount - 3) / 10))
+ *   - keywords: +0.25 if CROSS_CUTTING_PATTERN matches taskDescriptionText
+ *   - carryover: min(0.25, max(0, carryoverRatio - 0.3))
+ *
+ * Returns level buckets: score < 0.3 → 'low'; 0.3–0.7 → 'medium'; ≥ 0.7 → 'high'.
+ *
+ * Pure function: no I/O, no side effects. Missing/invalid fields → 0 contribution.
+ *
+ * @param {object|null|undefined} signals
+ * @returns {ContextPressureResult}
+ */
+export function computeContextPressure(signals) {
+  // --- Scope component ---
+  const priorities = safeArray(signals?.topPriorities);
+  const priorityCount = priorities.length;
+  const scopeComponent = clamp((priorityCount - 3) / 10, 0, 0.5);
+
+  // --- Cross-cutting keywords component ---
+  const text = typeof signals?.taskDescriptionText === 'string' ? signals.taskDescriptionText : '';
+  const keywordsComponent = text.length > 0 && CROSS_CUTTING_PATTERN.test(text) ? 0.25 : 0;
+
+  // --- Carryover component ---
+  // Derive carryover ratio from tail-5 recent sessions using
+  // effectiveness.carryover / effectiveness.planned_issues (sessions.jsonl schema).
+  // Falls back gracefully when fields are absent (contributes 0).
+  const recentSessions = safeArray(signals?.recentSessions);
+  const last5 = recentSessions.slice(-5);
+  let derivedCarryoverRatio = 0;
+  if (last5.length > 0) {
+    let validCount = 0;
+    let ratioSum = 0;
+    for (const session of last5) {
+      if (session === null || typeof session !== 'object') continue;
+      const eff = session.effectiveness;
+      if (eff === null || typeof eff !== 'object') continue;
+      const carryover =
+        typeof eff.carryover === 'number' && !Number.isNaN(eff.carryover) ? eff.carryover : null;
+      const planned =
+        typeof eff.planned_issues === 'number' &&
+        !Number.isNaN(eff.planned_issues) &&
+        eff.planned_issues > 0
+          ? eff.planned_issues
+          : null;
+      if (carryover !== null && planned !== null) {
+        ratioSum += carryover / planned;
+        validCount++;
+      }
+    }
+    if (validCount > 0) {
+      derivedCarryoverRatio = ratioSum / validCount;
+    }
+  }
+  const carryoverComponent = clamp(derivedCarryoverRatio - 0.3, 0, 0.25);
+
+  const score = round2(clamp(scopeComponent + keywordsComponent + carryoverComponent, 0, 1));
+
+  /** @type {'low'|'medium'|'high'} */
+  let level;
+  if (score < 0.3) level = 'low';
+  else if (score < 0.7) level = 'medium';
+  else level = 'high';
+
+  return {
+    score,
+    components: {
+      scope: round2(scopeComponent),
+      keywords: round2(keywordsComponent),
+      carryover: round2(carryoverComponent),
+    },
+    level,
+  };
+}

package/scripts/lib/mode-selector/rationale.mjs

@@ -0,0 +1,55 @@
+/**
+ * Rationale-string builder for the mode-selector passthrough branch (W1A2 split, issue #358).
+ *
+ * Exports: buildPassthroughRationale.
+ * Imports: constants (leaf). Shared helpers inlined per Option B.
+ *
+ * Pure function: no I/O, no side effects.
+ * 120-char clamp is enforced on every returned string.
+ */
+
+import { TIER_MODE_MAP } from './constants.mjs';
+import { safeArray, safeBootstrapLock } from './scoring.mjs';
+import { hasActiveSignals } from './alternatives.mjs';
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a rationale string for branch 3 (passthrough-weighted) based on the
+ * dominant factor. Result is deterministic for the same (mode, signals) pair.
+ * Always ≤120 chars.
+ *
+ * @param {string} mode
+ * @param {number} confidence
+ * @param {object} signals
+ * @returns {string}
+ */
+export function buildPassthroughRationale(mode, confidence, signals) {
+  const recentSessions = safeArray(signals.recentSessions);
+  const last3 = recentSessions.slice(-3);
+  const bootstrapLock = safeBootstrapLock(signals);
+  const tier = bootstrapLock && typeof bootstrapLock.tier === 'string' ? bootstrapLock.tier : null;
+
+  const hasTrend = last3.length >= 3 &&
+    last3.every((s) => typeof s === 'object' && s !== null && s.session_type === mode);
+  const hasTierAlign = tier !== null && TIER_MODE_MAP[tier] === mode;
+  const hasSignals = hasActiveSignals(signals);
+
+  let rationale;
+  if (!hasSignals) {
+    rationale = 'passthrough of Phase A recommended-mode — stale signals';
+  } else if (hasTrend && hasTierAlign) {
+    rationale = 'passthrough reinforced by recent-sessions trend + bootstrap tier';
+  } else if (hasTrend) {
+    rationale = 'passthrough reinforced by recent-sessions trend';
+  } else if (hasTierAlign) {
+    rationale = `passthrough reinforced by bootstrap tier (${tier})`;
+  } else {
+    rationale = 'passthrough of Phase A recommended-mode';
+  }
+
+  // Clamp to 120 chars (safety net)
+  return rationale.slice(0, 120);
+}

package/scripts/lib/mode-selector/scoring.mjs

@@ -0,0 +1,221 @@
+/**
+ * Mode-scoring logic for the mode-selector heuristic (W1A2 split, issue #358).
+ *
+ * Exports: computeDelta, scoreMode.
+ * Imports: constants (leaf). Shared helpers inlined per Option B (avoids cycle
+ * risk; matches context-pressure.mjs precedent).
+ *
+ * Pure functions: no I/O, no side effects.
+ */
+
+import { ALL_MODES, TIER_MODE_MAP } from './constants.mjs';
+import { computeContextPressure } from './context-pressure.mjs';
+
+// ---------------------------------------------------------------------------
+// Non-execution (read-only precursor) modes — PRD §2 Out-of-Scope (line 56),
+// §4 line 244, P2.4 (issue #678).
+//
+// `discovery` (routes to /discovery) and `plan-retro` (routes to /plan) are
+// READ-ONLY precursors. The dispatcher MENU routes to them and the
+// recommendation engine may SUGGEST them, but they must NEVER become a
+// scoring-promoted execution-wave `mode` (the primary that session-start /
+// wave-executor would RUN as a build-and-commit wave).
+//
+// Exported so the mode-selector guardrail (global-max swap) and the dispatcher
+// suggestion surface (recommendations-v0.mjs) share a single source of truth.
+// ---------------------------------------------------------------------------
+
+/** @type {ReadonlySet<string>} */
+export const NON_EXECUTION_MODES = Object.freeze(new Set(['discovery', 'plan-retro']));
+
+/**
+ * True when `mode` is a read-only precursor (discovery / plan-retro) that must
+ * never be scoring-promoted into the primary executed `mode`.
+ * @param {unknown} mode
+ * @returns {boolean}
+ */
+export function isNonExecutionMode(mode) {
+  return typeof mode === 'string' && NON_EXECUTION_MODES.has(mode);
+}
+
+// ---------------------------------------------------------------------------
+// Inlined helpers (clamp, round2, safeArray, safeBootstrapLock)
+// ---------------------------------------------------------------------------
+
+/**
+ * Clamp a number to [min, max].
+ * @param {number} v
+ * @param {number} min
+ * @param {number} max
+ * @returns {number}
+ */
+function clamp(v, min, max) {
+  return Math.min(max, Math.max(min, v));
+}
+
+/**
+ * Round to 2 decimal places (avoids floating-point drift in comparisons).
+ * @param {number} v
+ * @returns {number}
+ */
+export function round2(v) {
+  return Math.round(v * 100) / 100;
+}
+
+/**
+ * Safely coerce to an array (returns [] for non-arrays, null, undefined).
+ * @param {unknown} v
+ * @returns {any[]}
+ */
+export function safeArray(v) {
+  return Array.isArray(v) ? v : [];
+}
+
+/**
+ * Return signals.bootstrapLock when it is a non-null object, otherwise null.
+ * @param {object} signals
+ * @returns {object|null}
+ */
+export function safeBootstrapLock(signals) {
+  return (signals.bootstrapLock !== null && typeof signals.bootstrapLock === 'object')
+    ? signals.bootstrapLock
+    : null;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute the bonus+penalty score delta for a candidate mode given the
+ * provided signals. Returns a number in the range (-0.30, +0.35).
+ *
+ * @param {string} candidateMode
+ * @param {object} signals
+ * @returns {number} delta (positive bonuses − negative penalties)
+ */
+export function computeDelta(candidateMode, signals) {
+  const recentSessions = safeArray(signals.recentSessions);
+  const learnings = safeArray(signals.learnings);
+  const bootstrapLock = safeBootstrapLock(signals);
+
+  // --- Recent-sessions trend bonus (max +0.15) ---
+  let trendBonus = 0;
+  const last3 = recentSessions.slice(-3);
+  if (last3.length >= 3) {
+    const allMatch = last3.every(
+      (s) => typeof s === 'object' && s !== null && s.session_type === candidateMode,
+    );
+    if (allMatch) {
+      const avgCompletion =
+        last3.reduce((sum, s) => sum + (typeof s.completion_rate === 'number' ? s.completion_rate : 0), 0) /
+        3;
+      trendBonus = avgCompletion >= 0.9 ? 0.15 : 0.075;
+    }
+  }
+
+  // --- Bootstrap-tier alignment bonus (max +0.10) ---
+  let tierBonus = 0;
+  if (bootstrapLock !== null) {
+    const tier = typeof bootstrapLock.tier === 'string' ? bootstrapLock.tier : null;
+    if (tier !== null && TIER_MODE_MAP[tier] === candidateMode) {
+      tierBonus = 0.10;
+    }
+  }
+
+  // --- Learnings-hint bonus (max +0.10) ---
+  let learningsBonus = 0;
+  const HINT_TYPES = new Set(['effective-sizing', 'scope-guidance']);
+  const modeKeyword = candidateMode.toLowerCase();
+  for (const learning of learnings) {
+    if (
+      typeof learning === 'object' &&
+      learning !== null &&
+      typeof learning.type === 'string' &&
+      HINT_TYPES.has(learning.type) &&
+      typeof learning.subject === 'string' &&
+      learning.subject.toLowerCase().includes(modeKeyword)
+    ) {
+      learningsBonus = Math.min(learningsBonus + 0.05, 0.10);
+    }
+  }
+
+  // --- Conflict penalties (max −0.30) ---
+  let penalty = 0;
+
+  // Penalty: recent sessions trend strongly suggests a DIFFERENT mode
+  if (last3.length >= 3) {
+    const otherModes = ALL_MODES.filter((m) => m !== candidateMode);
+    for (const otherMode of otherModes) {
+      const allOther = last3.every(
+        (s) => typeof s === 'object' && s !== null && s.session_type === otherMode,
+      );
+      if (allOther) {
+        const avgCompletion =
+          last3.reduce((sum, s) => sum + (typeof s.completion_rate === 'number' ? s.completion_rate : 0), 0) /
+          3;
+        if (avgCompletion >= 0.9) {
+          penalty += 0.10;
+          break; // only one other dominant mode possible
+        }
+      }
+    }
+  }
+
+  // Penalty: bootstrap tier maps to a different mode than candidateMode
+  if (bootstrapLock !== null) {
+    const tier = typeof bootstrapLock.tier === 'string' ? bootstrapLock.tier : null;
+    if (tier !== null) {
+      const alignedMode = TIER_MODE_MAP[tier];
+      if (alignedMode !== undefined && alignedMode !== candidateMode) {
+        penalty += 0.10;
+      }
+    }
+  }
+
+  // Penalty: high carryover but not in 'deep' mode
+  const carryoverRatio =
+    typeof signals.carryoverRatio === 'number' && !Number.isNaN(signals.carryoverRatio)
+      ? signals.carryoverRatio
+      : null;
+  if (carryoverRatio !== null && carryoverRatio >= 0.2 && candidateMode !== 'deep') {
+    penalty += 0.10;
+  }
+
+  // --- Context-pressure modulation (#332) ---
+  // Pure additive delta on top of existing signal modulation.
+  // Only applies when at least one context-pressure input is explicitly present.
+  // When all inputs are absent, pressure is undefined → treat as neutral (no adjustment).
+  // This preserves backward-compatibility for callers that do not yet supply the new fields.
+  const hasPressureInputs =
+    (signals.topPriorities !== null && signals.topPriorities !== undefined) ||
+    (typeof signals.taskDescriptionText === 'string' && signals.taskDescriptionText.length > 0) ||
+    safeArray(signals.recentSessions).some(
+      (s) => s !== null && typeof s === 'object' && typeof s.effectiveness === 'object' && s.effectiveness !== null,
+    );
+
+  let pressureDelta = 0;
+  if (hasPressureInputs) {
+    const pressure = computeContextPressure(signals);
+    if (pressure.level === 'high') {
+      if (candidateMode === 'feature') pressureDelta = -0.15;
+      else if (candidateMode === 'housekeeping') pressureDelta = -0.10;
+    } else if (pressure.level === 'low') {
+      if (candidateMode === 'feature') pressureDelta = +0.05;
+    }
+    // level === 'medium': no adjustment
+  }
+
+  return trendBonus + tierBonus + learningsBonus - penalty + pressureDelta;
+}
+
+/**
+ * Score a candidate mode: base 0.5 + delta, clamped to [0.0, 0.9].
+ *
+ * @param {string} candidateMode
+ * @param {object} signals
+ * @returns {number}
+ */
+export function scoreMode(candidateMode, signals) {
+  return round2(clamp(0.5 + computeDelta(candidateMode, signals), 0.0, 0.9));
+}

package/scripts/lib/mode-selector-accuracy.mjs

@@ -0,0 +1,121 @@
+/**
+ * mode-selector-accuracy.mjs — Mode-Selector feedback-loop helper (Phase B-4, issue #294).
+ *
+ * After session-start renders a Mode-Selector recommendation and the user
+ * confirms or overrides it, call `recordAccuracy({recommended, chosen, sessionId})`
+ * to append a `mode-selector-accuracy` learning to the project's learnings.jsonl.
+ *
+ * Lifecycle (handled by skills/evolve + skills/session-end on subsequent reads,
+ * NOT by this helper):
+ *   - Same (type, subject) seen again → +0.15 confidence (confirmed)
+ *   - Contradicted by new evidence  → -0.20 confidence
+ *
+ * Subject pattern encodes the outcome class:
+ *   `<recommended>-selected-vs-<chosen>`
+ *
+ * Examples:
+ *   recommended=feature, chosen=feature → "feature-selected-vs-feature"  (agreement)
+ *   recommended=feature, chosen=deep    → "feature-selected-vs-deep"     (override)
+ *
+ * Same-pair recurrence in future sessions hits the dedupe path in evolve and
+ * confirms; novel pairs land at confidence 0.5 and accumulate from there.
+ *
+ * AC contract (from issue #294):
+ *  - Learning written only when user actively chooses (caller decides).
+ *  - Confidence starts at 0.5 (initial value; lifecycle handles increment/decrement).
+ *  - No-op when `recommended` is null/undefined (selector did not render a banner).
+ *
+ * The helper is a thin wrapper around `appendLearning` from `learnings.mjs`. It
+ * never throws on validation issues — those bubble back to the caller as a
+ * resolved-error return value (`{ok: false, reason}`) so session-start can
+ * log to sweep.log without halting the session.
+ */
+
+import { appendLearning } from './learnings.mjs';
+import { isValidMode } from './recommendations-v0.mjs';
+
+export const LEARNING_TYPE = 'mode-selector-accuracy';
+export const INITIAL_CONFIDENCE = 0.5;
+export const DEFAULT_EXPIRY_DAYS = 30;
+
+/**
+ * Build the canonical subject string for a (recommended, chosen) pair.
+ * @param {string} recommended
+ * @param {string} chosen
+ * @returns {string}
+ */
+export function buildSubject(recommended, chosen) {
+  return `${recommended}-selected-vs-${chosen}`;
+}
+
+/**
+ * Record a Mode-Selector accuracy learning.
+ *
+ * @param {{
+ *   recommended: string|null,
+ *   chosen: string,
+ *   sessionId: string,
+ *   filePath?: string,
+ *   nowMs?: number,
+ *   expiryDays?: number,
+ *   confidence?: number,
+ * }} opts
+ * @returns {Promise<{ok: true, entry: object} | {ok: false, reason: string}>}
+ */
+export async function recordAccuracy(opts) {
+  const recommended = opts?.recommended;
+  const chosen = opts?.chosen;
+  const sessionId = opts?.sessionId;
+  const filePath = opts?.filePath || '.orchestrator/metrics/learnings.jsonl';
+
+  // No-op when the selector did not render a recommendation (banner suppressed,
+  // confidence 0.0, etc). Caller passes recommended=null in that case.
+  if (recommended === null || recommended === undefined || recommended === '') {
+    return { ok: false, reason: 'no-recommendation' };
+  }
+  if (typeof recommended !== 'string' || typeof chosen !== 'string') {
+    return { ok: false, reason: 'invalid-mode-type' };
+  }
+  if (!isValidMode(recommended) || !isValidMode(chosen)) {
+    return { ok: false, reason: 'unknown-mode' };
+  }
+  if (typeof sessionId !== 'string' || sessionId.length === 0) {
+    return { ok: false, reason: 'missing-session-id' };
+  }
+
+  const nowMs = typeof opts.nowMs === 'number' ? opts.nowMs : Date.now();
+  const expiryDays = Number.isInteger(opts.expiryDays) && opts.expiryDays > 0
+    ? opts.expiryDays
+    : DEFAULT_EXPIRY_DAYS;
+  const confidence = typeof opts.confidence === 'number'
+    ? opts.confidence
+    : INITIAL_CONFIDENCE;
+
+  const subject = buildSubject(recommended, chosen);
+  const agreement = recommended === chosen;
+  const insight = agreement
+    ? `User confirmed Mode-Selector recommendation (${recommended}).`
+    : `User overrode Mode-Selector recommendation (${recommended}) with ${chosen}.`;
+
+  const created_at = new Date(nowMs).toISOString();
+  const expires_at = new Date(nowMs + expiryDays * 86_400_000).toISOString();
+
+  const entry = {
+    id: `${LEARNING_TYPE}-${subject}-${sessionId}`,
+    type: LEARNING_TYPE,
+    subject,
+    insight,
+    evidence: [`${sessionId}: recommended=${recommended} chosen=${chosen}`],
+    confidence,
+    source_session: sessionId,
+    created_at,
+    expires_at,
+  };
+
+  try {
+    const validated = await appendLearning(filePath, entry);
+    return { ok: true, entry: validated };
+  } catch (err) {
+    return { ok: false, reason: `append-failed: ${err?.message ?? String(err)}` };
+  }
+}