session-orchestrator 3.16.0

package/scripts/lib/mode-selector.mjs

@@ -0,0 +1,160 @@
+/**
+ * Phase B-1 Mode-Selector heuristic v1 (issue #291, Epic #271).
+ *
+ * Thin orchestrator — delegates to submodules (W1A2 split, issue #358).
+ * Pure function: same inputs → same outputs, zero side effects, no I/O.
+ *
+ * Public API:
+ *   selectMode(signals) → Recommendation
+ *   computeContextPressure  (re-export from context-pressure.mjs)
+ */
+
+import { isValidMode } from './recommendations-v0.mjs';
+import { DEFAULT_MODE } from './mode-selector/constants.mjs';
+import { computeDelta, round2, isNonExecutionMode } from './mode-selector/scoring.mjs';
+import { buildAlternatives } from './mode-selector/alternatives.mjs';
+import { buildPassthroughRationale } from './mode-selector/rationale.mjs';
+import { computeContextPressure } from './mode-selector/context-pressure.mjs';
+export { computeContextPressure };
+
+// clamp inlined — used only in selectMode; avoids importing scoring helpers
+// for a single expression.
+function clamp(v, min, max) {
+  return Math.min(max, Math.max(min, v));
+}
+
+/**
+ * Deterministic mode selection for session-start.
+ *
+ * Pure function: same inputs → same outputs, zero side effects, no I/O.
+ *
+ * Heuristic v1 (issue #291) — consumes carryoverRatio, completionRate,
+ * recentSessions trend, bootstrapLock tier-alignment, and learnings hints
+ * to compute a confidence-weighted recommendation with alternatives.
+ *
+ * Decision priority:
+ *   1. SPIRAL    — completionRate < 0.5
+ *   2. CARRYOVER — carryoverRatio >= 0.3
+ *   3. PASSTHROUGH-WEIGHTED — valid recommendedMode + signal scoring
+ *   4. DEFAULT   — no valid mode, no spiral/carryover trigger
+ *
+ * @param {import('./mode-selector/constants.mjs').Signals|null|undefined} signals
+ * @returns {import('./mode-selector/constants.mjs').Recommendation}
+ */
+export function selectMode(signals) {
+  // Null-guard: treat null/undefined as empty signals object.
+  if (signals === null || signals === undefined) {
+    return {
+      mode: DEFAULT_MODE,
+      rationale: 'scaffold: null signals → default',
+      confidence: 0.0,
+      alternatives: [],
+      context_pressure: computeContextPressure({}),
+    };
+  }
+
+  // Defensive extraction of numeric signals.
+  const completionRate =
+    typeof signals.completionRate === 'number' && !Number.isNaN(signals.completionRate)
+      ? signals.completionRate
+      : null;
+  const carryoverRatio =
+    typeof signals.carryoverRatio === 'number' && !Number.isNaN(signals.carryoverRatio)
+      ? signals.carryoverRatio
+      : null;
+
+  // Branch 1 — SPIRAL: low completion rate
+  if (completionRate !== null && completionRate < 0.5) {
+    return {
+      mode: 'plan-retro',
+      rationale: 'low completion → retrospective',
+      confidence: 0.8,
+      alternatives: [
+        { mode: 'feature', confidence: 0.3 },
+        { mode: 'discovery', confidence: 0.25 },
+      ],
+      context_pressure: computeContextPressure(signals),
+    };
+  }
+
+  // Branch 2 — CARRYOVER: high carryover ratio
+  if (carryoverRatio !== null && carryoverRatio >= 0.3) {
+    const pct = Math.round(carryoverRatio * 100);
+    return {
+      mode: 'deep',
+      rationale: `carryover ${pct}% — deep clear`,
+      confidence: 0.75,
+      alternatives: [
+        { mode: 'feature', confidence: 0.3 },
+        { mode: 'plan-retro', confidence: 0.2 },
+      ],
+      context_pressure: computeContextPressure(signals),
+    };
+  }
+
+  // Branch 3 — PASSTHROUGH-WEIGHTED: valid recommendedMode from Phase A
+  const m = signals.recommendedMode;
+  if (typeof m === 'string' && isValidMode(m)) {
+    const delta = computeDelta(m, signals);
+    const confidence = round2(clamp(0.5 + delta, 0.0, 0.9));
+    const pressure = computeContextPressure(signals);
+    let rationale = buildPassthroughRationale(m, confidence, signals);
+
+    // Annotate rationale with pressure level when non-trivial (≤120 char limit).
+    if (pressure.level !== 'low') {
+      const pressureAnnotation = `; pressure:${pressure.level}(${pressure.score})`;
+      rationale = (rationale + pressureAnnotation).slice(0, 120);
+    }
+
+    const alternatives = buildAlternatives(m, signals);
+
+    // Global-max swap (#299): the primary recommendation must be the
+    // highest-confidence mode across {primary, ...alternatives}. When an
+    // alternative outranks the passthrough primary (strict greater-than to
+    // preserve passthrough preference on ties), promote it and demote the
+    // original primary into alternatives, re-sort, slice to top-3.
+    //
+    // NON-EXECUTION GUARDRAIL (#678, PRD §2 line 56 / §4 line 244): read-only
+    // precursor modes (discovery / plan-retro) must NEVER be scoring-promoted
+    // into the primary executed `mode`. They stay surfaceable as SUGGESTIONS in
+    // the alternatives[] list, but the swap candidate is the highest-confidence
+    // EXECUTABLE alternative only. This is guard (b): exclude precursors from
+    // the global-max promotion (the alternatives list itself is unchanged).
+    const promotable = alternatives.find((a) => !isNonExecutionMode(a.mode));
+    if (promotable !== undefined && promotable.confidence > confidence) {
+      const promoted = promotable;
+      const demoted = { mode: m, confidence };
+      // Remove the promoted alternative by reference (it may not be at index 0
+      // once precursors are skipped), then fold the demoted primary back in.
+      // Precursor alternatives are retained here so they remain SUGGESTIONS.
+      const reranked = [demoted, ...alternatives.filter((a) => a !== promoted)]
+        .filter((e) => e.confidence >= 0.1)
+        .sort((a, b) => b.confidence - a.confidence)
+        .slice(0, 3);
+      return {
+        mode: promoted.mode,
+        rationale: `global-max swap: ${promoted.mode} (${promoted.confidence}) outranked passthrough ${m} (${confidence})`.slice(0, 120),
+        confidence: promoted.confidence,
+        alternatives: reranked,
+        context_pressure: pressure,
+      };
+    }
+
+    return {
+      mode: m,
+      rationale,
+      confidence,
+      alternatives,
+      context_pressure: pressure,
+    };
+  }
+
+  // Branch 4 — DEFAULT: no valid mode signal and no spiral/carryover trigger
+  return {
+    mode: DEFAULT_MODE,
+    rationale: 'missing/invalid recommendedMode → default',
+    confidence: 0.0,
+    alternatives: [],
+    context_pressure: computeContextPressure(signals),
+  };
+}

package/scripts/lib/multi-provider-build/providers.mjs

@@ -0,0 +1,64 @@
+/**
+ * scripts/lib/multi-provider-build/providers.mjs
+ *
+ * Provider configuration for the single-source → many-provider build PoC.
+ *
+ * Scope: the THREE harnesses session-orchestrator actually targets
+ * (Claude Code primary, Codex CLI, Cursor IDE). Inspired by pbakaus/impeccable's
+ * 12-provider build (Apache-2.0) — we deliberately keep the templating mechanic
+ * and drop the 12-provider breadth (maintenance ≫ value for providers with ~0
+ * users; see the linked backlog issue's overengineering verdict).
+ *
+ * Each provider entry:
+ *   {
+ *     key,            // canonical id used in build output paths
+ *     tags,           // <tag> block markers this provider keeps (rest are stripped)
+ *     configDir,      // on-disk harness dir
+ *     placeholders: { model, configFile, commandPrefix, askInstruction }
+ *   }
+ */
+
+/** @typedef {{key:string, tags:string[], configDir:string, placeholders:{model:string, configFile:string, commandPrefix:string, askInstruction:string}}} ProviderConfig */
+
+/** @type {Record<string, ProviderConfig>} */
+export const PROVIDERS = {
+  'claude-code': {
+    key: 'claude-code',
+    tags: ['claude-code', 'claude'],
+    configDir: '.claude',
+    placeholders: {
+      model: 'Claude',
+      configFile: 'CLAUDE.md',
+      commandPrefix: '/',
+      askInstruction: 'STOP and call the AskUserQuestion tool to clarify.',
+    },
+  },
+  codex: {
+    key: 'codex',
+    tags: ['codex'],
+    configDir: '.codex',
+    placeholders: {
+      model: 'GPT',
+      configFile: 'AGENTS.md',
+      commandPrefix: '$',
+      askInstruction: "STOP and use Codex's structured user-input tool to clarify.",
+    },
+  },
+  cursor: {
+    key: 'cursor',
+    tags: ['cursor'],
+    configDir: '.cursor',
+    placeholders: {
+      model: 'the model',
+      configFile: '.cursorrules',
+      commandPrefix: '/',
+      askInstruction: 'ask the user directly to clarify before proceeding.',
+    },
+  },
+};
+
+/** The full set of recognized provider block tags across ALL providers. */
+export const ALL_BLOCK_TAGS = new Set(Object.values(PROVIDERS).flatMap((p) => p.tags));
+
+/** Provider keys in a stable order. */
+export const PROVIDER_KEYS = Object.keys(PROVIDERS);

package/scripts/lib/multi-provider-build/templating.mjs

@@ -0,0 +1,130 @@
+/**
+ * scripts/lib/multi-provider-build/templating.mjs
+ *
+ * Single-source → many-provider templating (PoC). One source document with
+ * provider-conditional blocks + placeholders renders to a provider-specific
+ * artifact. This replaces the "maintain N near-identical copies by hand" model
+ * our codex-install.mjs / cursor-install.mjs currently imply.
+ *
+ * Two primitives (clean-room reimplementation of impeccable's mechanic):
+ *   1. compileProviderBlocks(content, activeTags)
+ *        <codex> … </codex> blocks: keep body iff the tag is active, else drop.
+ *        Unknown tags are left untouched (so real HTML/JSX isn't mangled).
+ *   2. replacePlaceholders(content, providerKey, opts)
+ *        {{model}} {{config_file}} {{command_prefix}} {{ask_instruction}}
+ *        {{available_commands}} substitution + optional /cmd → $cmd rewrite.
+ *
+ * renderForProvider() composes both in the correct order (blocks first, then
+ * placeholders — matching impeccable's pipeline).
+ */
+
+import { PROVIDERS, ALL_BLOCK_TAGS } from './providers.mjs';
+
+/**
+ * Keep `<tag>…</tag>` blocks whose tag is in `activeTags`; strip the rest.
+ * Only tags in `knownTags` are treated as conditional blocks — any other
+ * `<foo>…</foo>` (e.g. real markup) is left exactly as-is.
+ *
+ * Tags must sit on their own line, e.g.:
+ *   <codex>
+ *   Codex-only text.
+ *   </codex>
+ *
+ * @param {string} content
+ * @param {Iterable<string>} activeTags
+ * @param {Iterable<string>} [knownTags] — defaults to ALL_BLOCK_TAGS
+ * @returns {string}
+ */
+export function compileProviderBlocks(content, activeTags, knownTags = ALL_BLOCK_TAGS) {
+  const active = new Set(activeTags);
+  const known = new Set(knownTags);
+  let compiledAny = false;
+
+  // Match a block: leading newline (or start), <tag> on its own line, body,
+  // </tag> on its own line. Non-greedy body; the backreference enforces matching.
+  const blockRe = /(^|\r?\n)[ \t]*<([a-z][a-z0-9-]*)>[ \t]*\r?\n([\s\S]*?)\r?\n[ \t]*<\/\2>[ \t]*(?=\r?\n|$)/g;
+
+  const out = content.replace(blockRe, (match, prefix, tag, body) => {
+    if (!known.has(tag)) return match; // not a provider block — leave untouched
+    compiledAny = true;
+    return active.has(tag) ? `${prefix}${body}` : prefix;
+  });
+
+  // Collapse the 3+ blank-line runs that stripping can leave behind.
+  return compiledAny ? out.replace(/(\r?\n){3,}/g, '\n\n') : out;
+}
+
+/**
+ * Substitute {{placeholders}} for a provider and (optionally) rewrite command
+ * invocations from `/name` to the provider's prefix.
+ *
+ * @param {string} content
+ * @param {string} providerKey
+ * @param {{ commandNames?: string[] }} [opts]
+ * @returns {string}
+ */
+export function replacePlaceholders(content, providerKey, opts = {}) {
+  const provider = PROVIDERS[providerKey];
+  if (!provider) throw new Error(`Unknown provider: ${providerKey}`);
+  const { model, configFile, commandPrefix, askInstruction } = provider.placeholders;
+  const commandNames = opts.commandNames ?? [];
+
+  const availableCommands = commandNames.map((n) => `${commandPrefix}${n}`).join(', ');
+
+  let result = content
+    .replace(/\{\{model\}\}/g, model)
+    .replace(/\{\{config_file\}\}/g, configFile)
+    .replace(/\{\{ask_instruction\}\}/g, askInstruction)
+    .replace(/\{\{available_commands\}\}/g, availableCommands)
+    .replace(/\{\{command_prefix\}\}/g, commandPrefix);
+
+  // Rewrite `/cmd` invocations to the provider prefix (e.g. Codex uses `$`).
+  // Longest names first so `/session-end` is rewritten before `/session`.
+  if (commandPrefix !== '/' && commandNames.length > 0) {
+    const sorted = [...commandNames].sort((a, b) => b.length - a.length);
+    for (const name of sorted) {
+      // `/name` where name is followed by a non-identifier char or end.
+      const re = new RegExp(`\\/(${escapeRegex(name)})(?=[^a-zA-Z0-9_-]|$)`, 'g');
+      // Use a replacement FUNCTION, not a string — a `$` commandPrefix would
+      // otherwise collide with String.replace's `$$`/`$1` escape syntax.
+      result = result.replace(re, (_match, g1) => `${commandPrefix}${g1}`);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Render a source document for a single provider: compile blocks, then
+ * substitute placeholders.
+ *
+ * @param {string} source
+ * @param {string} providerKey
+ * @param {{ commandNames?: string[] }} [opts]
+ * @returns {string}
+ */
+export function renderForProvider(source, providerKey, opts = {}) {
+  const provider = PROVIDERS[providerKey];
+  if (!provider) throw new Error(`Unknown provider: ${providerKey}`);
+  const compiled = compileProviderBlocks(source, provider.tags);
+  return replacePlaceholders(compiled, providerKey, opts);
+}
+
+/**
+ * Render a source for every configured provider.
+ * @param {string} source
+ * @param {{ commandNames?: string[] }} [opts]
+ * @returns {Record<string,string>} keyed by provider key
+ */
+export function renderAll(source, opts = {}) {
+  const out = {};
+  for (const key of Object.keys(PROVIDERS)) {
+    out[key] = renderForProvider(source, key, opts);
+  }
+  return out;
+}
+
+/** @param {string} s */
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/scripts/lib/named-baseline-resolver.mjs

@@ -0,0 +1,233 @@
+/**
+ * named-baseline-resolver.mjs — Per-context plan-baseline resolution (Issue #819).
+ *
+ * Cousin of `named-vault-resolver.mjs`. Where the vault resolver matches a repo
+ * to a named vault by its git-remote org/repo slug, this resolver matches the
+ * current working directory to a named baseline by a local FILESYSTEM directory
+ * prefix. Each named baseline is declared in the host-local `owner.yaml` under an
+ * optional `baselines:` list. When `baselines:` is absent, every export degrades
+ * gracefully to a null-fallback — absent-tolerant, never throws.
+ *
+ * ── Deliberate divergences from named-vault-resolver ─────────────────────────
+ *
+ *   - Match key is `path-prefix` (a local directory tree like `~/Projects/private-world`),
+ *     NOT `org-prefix` (which matches git-remote slugs). Baseline selection is by
+ *     directory tree, so no git calls are needed — this module is pure/synchronous.
+ *   - Entry field is `path` (a single directory), replacing vaults' `root` + `suffix`.
+ *   - `match` is REQUIRED: a baseline with no `path-prefix` can never be selected, so
+ *     it is dropped-and-WARNed rather than kept (vaults keep entries without a match).
+ *
+ * ── Precedence (implemented by resolveNamedBaseline) ─────────────────────────
+ *
+ *   The caller (scripts/lib/config.mjs) owns the full plan-baseline-path chain:
+ *     1. SO_BASELINE_PATH env  (highest)
+ *     2. baselines: match      (this module → {source:'match'})
+ *     3. owner.yaml paths.baseline-path (legacy)
+ *     4. committed Session Config value
+ *
+ *   This module implements tier 2 only. As a self-contained, testable contract it
+ *   also YIELDS to tier 1: when SO_BASELINE_PATH is set (non-blank), resolveNamedBaseline
+ *   returns the null-fallback ({source:null}) so the caller's env tier wins.
+ *
+ * ── Exports ──────────────────────────────────────────────────────────────────
+ *
+ *   parseBaselines(ownerConfig)
+ *   matchBaselineForPath(absPath, baselines)
+ *   resolveNamedBaseline({ cwd, ownerConfig, env })
+ */
+
+import { normalize, sep } from 'node:path';
+import { expandTilde } from './common.mjs';
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/** @param {unknown} v */
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+/**
+ * Tilde-expand + normalize a filesystem path, stripping any trailing separator
+ * (but preserving the filesystem root). Used to canonicalise BOTH the target
+ * path and each configured prefix before a directory-prefix comparison.
+ *
+ * @param {unknown} p
+ * @returns {string}
+ */
+function _normalizePath(p) {
+  const expanded = expandTilde(String(p ?? ''));
+  const normalized = normalize(expanded);
+  if (normalized.length > 1 && normalized.endsWith(sep)) {
+    return normalized.slice(0, -1);
+  }
+  return normalized;
+}
+
+// ---------------------------------------------------------------------------
+// parseBaselines — PURE
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract and validate the `baselines:` list from a raw ownerConfig object.
+ *
+ * Drop-and-WARN on malformed entries; never throw. Returns [] when the section
+ * is absent, null, or empty — the backward-compat no-op path.
+ *
+ * Each valid entry: { name: string, path: string, match: { 'path-prefix': string } }
+ *
+ * @param {object|undefined} ownerConfig — raw parsed owner.yaml (NOT merged with defaults)
+ * @returns {Array<{name:string, path:string, match:{'path-prefix':string}}>}
+ */
+export function parseBaselines(ownerConfig) {
+  const raw = ownerConfig?.baselines;
+
+  // Absent or explicit null/empty → no-op
+  if (raw === undefined || raw === null) return [];
+  if (Array.isArray(raw) && raw.length === 0) return [];
+
+  if (!Array.isArray(raw)) {
+    process.stderr.write(
+      'WARN named-baseline-resolver: owner.yaml baselines: must be an array; ignoring\n',
+    );
+    return [];
+  }
+
+  const result = [];
+  for (let i = 0; i < raw.length; i++) {
+    const entry = raw[i];
+    if (!isPlainObject(entry)) {
+      process.stderr.write(
+        `WARN named-baseline-resolver: owner.yaml baselines[${i}] is not an object; dropping\n`,
+      );
+      continue;
+    }
+
+    const { name, path: entryPath, match } = entry;
+
+    if (typeof name !== 'string' || name.trim() === '') {
+      process.stderr.write(
+        `WARN named-baseline-resolver: owner.yaml baselines[${i}].name must be a non-empty string; dropping entry\n`,
+      );
+      continue;
+    }
+    if (typeof entryPath !== 'string' || entryPath.trim() === '') {
+      process.stderr.write(
+        `WARN named-baseline-resolver: owner.yaml baselines[${i}].path must be a non-empty string; dropping entry\n`,
+      );
+      continue;
+    }
+
+    // match is REQUIRED (unlike vaults) — a baseline with no path-prefix can
+    // never be selected, so it is dropped rather than kept.
+    if (!isPlainObject(match)) {
+      process.stderr.write(
+        `WARN named-baseline-resolver: owner.yaml baselines[${i}].match must be an object; dropping entry\n`,
+      );
+      continue;
+    }
+    const pathPrefix = match['path-prefix'];
+    if (typeof pathPrefix !== 'string' || pathPrefix.trim() === '') {
+      process.stderr.write(
+        `WARN named-baseline-resolver: owner.yaml baselines[${i}].match.path-prefix must be a non-empty string; dropping entry\n`,
+      );
+      continue;
+    }
+
+    result.push({
+      name: name.trim(),
+      path: entryPath.trim(),
+      match: { 'path-prefix': pathPrefix.trim() },
+    });
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// matchBaselineForPath — PURE
+// ---------------------------------------------------------------------------
+
+/**
+ * Find the first named baseline whose `match.path-prefix` is a directory-prefix
+ * of the given absolute path. Both the path and each prefix are tilde-expanded
+ * and path-normalized before comparison.
+ *
+ * A prefix matches when the target path IS the prefix, or starts with
+ * `prefix + path.sep` (so `/a/b` matches `/a/b` and `/a/b/c`, but NOT `/a/bc`).
+ *
+ * First-match-wins. On an ambiguous multi-match, emits a WARN (never throws) and
+ * returns the first match.
+ *
+ * @param {string} absPath — the working directory to classify
+ * @param {Array<{name:string, path:string, match:{'path-prefix':string}}>} baselines
+ * @returns {{name:string, path:string, match:{'path-prefix':string}}|null}
+ */
+export function matchBaselineForPath(absPath, baselines) {
+  if (!absPath || !Array.isArray(baselines) || baselines.length === 0) return null;
+
+  const target = _normalizePath(absPath);
+  const matched = [];
+
+  for (const b of baselines) {
+    const prefixRaw = b?.match?.['path-prefix'];
+    if (typeof prefixRaw !== 'string' || prefixRaw.trim() === '') continue;
+    const prefix = _normalizePath(prefixRaw);
+    if (target === prefix || target.startsWith(`${prefix}${sep}`)) {
+      matched.push(b);
+    }
+  }
+
+  if (matched.length > 1) {
+    process.stderr.write(
+      `WARN named-baseline-resolver: multiple baselines match path "${absPath}": ${matched
+        .map((b) => b.name)
+        .join(', ')}; using first match "${matched[0].name}"\n`,
+    );
+  }
+
+  return matched.length > 0 ? matched[0] : null;
+}
+
+// ---------------------------------------------------------------------------
+// resolveNamedBaseline — main resolution entry point (tier 2)
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the `baselines:` match tier for a given cwd.
+ *
+ * Returns:
+ *   { path, name, source:'match' } when a baseline directory-prefix matches cwd.
+ *   { path:null, name:null, source:null } (the null-fallback) otherwise — including
+ *   when SO_BASELINE_PATH env is set (this tier yields to the higher env tier the
+ *   caller owns), when no `baselines:` are configured, or when nothing matches.
+ *
+ * Pure + synchronous — no git calls, no disk reads. Never throws.
+ *
+ * @param {{
+ *   cwd?: string,
+ *   ownerConfig?: object,
+ *   env?: Record<string, string|undefined>,
+ * }} [opts]
+ * @returns {{ path: string|null, name: string|null, source: 'match'|null }}
+ */
+export function resolveNamedBaseline({
+  cwd = process.cwd(),
+  ownerConfig,
+  env = process.env,
+} = {}) {
+  // Yield to the higher-precedence env tier the caller owns (SO_BASELINE_PATH).
+  const envVal = env?.SO_BASELINE_PATH;
+  if (typeof envVal === 'string' && envVal.trim() !== '') {
+    return { path: null, name: null, source: null };
+  }
+
+  const baselines = parseBaselines(ownerConfig);
+  const matched = baselines.length > 0 ? matchBaselineForPath(cwd, baselines) : null;
+  if (matched !== null) {
+    return { path: matched.path, name: matched.name, source: 'match' };
+  }
+
+  return { path: null, name: null, source: null };
+}