heyspex 0.1.0

package/vendor/heyspex-mcp/scheduler.mjs

@@ -0,0 +1,813 @@
+/**
+ * Deterministic scheduler — JS port of spex-console/src/lib/scheduler for the
+ * vendor stdio MCP server, which cannot import TypeScript at runtime.
+ *
+ * Mirrors stages 1 / 2 / 3 / 4 / 5 / 6 / 7 / 8 / 9 of
+ * [[HS-EPIC-Y9OJ-deterministic-priority-scheduler]] (stage 9 = the opt-in
+ * hysteresis band, [[HS-TASK-MI65]]) so `heyspex_next_on_deck` can surface an
+ * `explanation` trace alongside the picked spec. Keep behavior byte-equivalent
+ * to the TypeScript module — if you change one, change the other (and the
+ * matching test suite).
+ *
+ * Phase 3 ([[HS-TASK-XA40]]) adds Stage 6 (testing-batch grouping) plus
+ * `applyPin` for the pin-with-fuse override.
+ */
+
+const TIER_RANK = Object.freeze({
+  infra: 0,
+  foundation: 1,
+  feature: 2,
+  polish: 3,
+});
+
+const DEFAULT_TIER = 'feature';
+const DEFAULT_EFFORT = 3;
+
+// Stage 2.7 — blast-radius band ([[encoding-foundational-and-blast-radius-p]]).
+// Discrete breakage-surface severity; lower rank sorts first. Keep byte-equivalent
+// to spex-console/src/lib/scheduler/types.ts (BLAST_RADIUS_RANK / DEFAULT_BLAST_RADIUS).
+const BLAST_RADIUS_RANK = Object.freeze({
+  'vault-wide': 0,
+  'cross-surface': 1,
+  local: 2,
+});
+const DEFAULT_BLAST_RADIUS = 'local';
+
+/** Milliseconds in one day — the quantum the aging guard measures wait-time in. */
+const MS_PER_DAY = 86_400_000;
+
+/**
+ * Stage 4.5 — aging guard threshold ([[HS-TASK-62Y8]] / [[HS-EPIC-RBST]] AC#3).
+ * A spec whose `created` is at least this many days older than the supplied
+ * reference clock is "aged" and promoted ahead of non-aged peers within its
+ * partition — never across a tier/topological boundary. Code constant under
+ * ADR-level change control, NOT a settings knob. Keep in lockstep with
+ * spex-console/src/lib/scheduler/types.ts.
+ */
+const AGING_THRESHOLD_DAYS = 45;
+
+/**
+ * Stage 9 — hysteresis band ([[HS-TASK-MI65]] / [[HS-EPIC-RBST]] AC#4).
+ * A spec keeps its prior slot unless its freshly computed position moved by at
+ * least this many places; sub-threshold jitter is suppressed so a one-field
+ * edit no longer reshuffles the deck. Applied within a topological layer only
+ * (any permutation inside a layer is depends_on-safe). Inert when no priorOrder
+ * is supplied (the default), so a priorless run is byte-identical and stays in
+ * lockstep with console. Code constant under ADR-level change control, NOT a
+ * settings knob. Keep in lockstep with spex-console/src/lib/scheduler/types.ts.
+ */
+const HYSTERESIS_DELTA = 2;
+
+export class CycleError extends Error {
+  constructor(cycle) {
+    super(`Cycle detected in depends_on graph: ${cycle.join(' → ')}`);
+    this.name = 'CycleError';
+    this.cycle = cycle;
+  }
+}
+
+/**
+ * Duplicate spec ids in the scheduler input — mirror of console
+ * toposort.ts:DuplicateIdError. Without the guard in topologicalSort, duplicate
+ * ids collapse the in-degree map and surface as a misleading CycleError; the
+ * guard catches them with a precise message instead. Keep byte-equivalent to
+ * the console class.
+ */
+export class DuplicateIdError extends Error {
+  constructor(ids) {
+    super(`Duplicate spec ids in scheduler input: ${ids.join(', ')}`);
+    this.name = 'DuplicateIdError';
+    this.ids = ids;
+  }
+}
+
+export function normalizeDependsOnId(raw) {
+  if (raw == null) return '';
+  const inner = String(raw).trim().replace(/^\[\[|\]\]$/g, '').trim();
+  const m = inner.match(/^(HS-(?:TASK|EPIC|RES|CAP|REV|IDEA|FLOW)-(?:\d+|[A-Z0-9]+))/);
+  return m ? m[1] : inner;
+}
+
+/**
+ * The unique per-spec node key ([[HS-K5GQ-DIAG]]). Sibling tasks under one epic
+ * legitimately SHARE a family-key `id:`; keying node identity on `nodeKey` (the
+ * basename) keeps `topologicalSort` from throwing DuplicateIdError on them.
+ * Defaults to `id` so a corpus with no shared family keys is byte-identical.
+ * Keep in lockstep with console toposort.ts:nodeKeyOf.
+ */
+export function nodeKeyOf(spec) {
+  return spec?.nodeKey ?? spec?.id;
+}
+
+/**
+ * Resolve a raw `depends_on` value to the UNIQUE node key it targets within
+ * `specs`, or null when it resolves to no node (absent, or a bare family key
+ * shared by 2+ siblings — ambiguous, so it gates nothing). Edges resolve on the
+ * family-key `id:` even though nodes are keyed on nodeKey. Keep in lockstep with
+ * console toposort.ts:buildDepResolver.
+ */
+export function buildDepResolver(specs) {
+  const nodeKeys = new Set();
+  const nodeKeysByFamily = new Map();
+  for (const s of specs) {
+    const key = nodeKeyOf(s);
+    nodeKeys.add(key);
+    const arr = nodeKeysByFamily.get(s.id);
+    if (arr) arr.push(key);
+    else nodeKeysByFamily.set(s.id, [key]);
+  }
+  return (raw) => {
+    const dep = normalizeDependsOnId(raw);
+    if (nodeKeys.has(dep)) return dep;
+    const fam = nodeKeysByFamily.get(dep);
+    return fam && fam.length === 1 ? fam[0] : null;
+  };
+}
+
+export function tierOf(spec) {
+  const k = spec?.kind;
+  if (k === 'infra' || k === 'foundation' || k === 'feature' || k === 'polish') {
+    return k;
+  }
+  return DEFAULT_TIER;
+}
+
+export function tierRankOf(spec) {
+  return TIER_RANK[tierOf(spec)];
+}
+
+/**
+ * Stage 2.7 — blast-radius band ([[encoding-foundational-and-blast-radius-p]]).
+ * Breakage-surface severity; missing/unrecognized → DEFAULT_BLAST_RADIUS
+ * ("local"). Within-tier only, above what_matters. Byte-equivalent to
+ * comparators.ts (blastRadiusOf / blastRadiusRank).
+ */
+export function blastRadiusOf(spec) {
+  const b = spec?.blast_radius;
+  if (b === 'vault-wide' || b === 'cross-surface' || b === 'local') return b;
+  return DEFAULT_BLAST_RADIUS;
+}
+
+export function blastRadiusRank(spec) {
+  return BLAST_RADIUS_RANK[blastRadiusOf(spec)];
+}
+
+/**
+ * Stage 2.5 — what_matters within-tier value band ([[HS-TASK-PQID]],
+ * [[scheduler-and-whats-next-what-matters-column-mechanics]]). User's coarse
+ * value/cost-of-delay signal: heart (2) > star (1) > unflagged (0). Higher band
+ * sorts first (DESC). Within-tier only (the tier comparator returns first for
+ * cross-tier pairs); within a tier it outranks criticality, in-progress bias,
+ * and effort ("heart = schedule ASAP"). Byte-equivalent to comparators.ts.
+ */
+export function whatMattersRank(spec) {
+  return spec?.what_matters === 'heart' ? 2 : spec?.what_matters === 'star' ? 1 : 0;
+}
+
+export function createdAt(spec) {
+  const raw = (spec?.created ?? '9999-12-31').toString();
+  return raw.slice(0, 19);
+}
+
+export function effortOf(spec) {
+  return typeof spec?.effort === 'number' && Number.isFinite(spec.effort)
+    ? spec.effort
+    : DEFAULT_EFFORT;
+}
+
+export function inProgressRank(spec) {
+  return spec?.status === 'in_progress' ? 0 : 1;
+}
+
+/**
+ * Stage 4.5 — aging guard (anti-starvation). Whole days the spec has waited
+ * since `created`, measured against the caller-supplied reference clock
+ * `nowMs`. The wall clock is not read here — `nowMs` is an explicit input,
+ * quantized to whole days. Undefined `nowMs` ⇒ inert (0), so the order stays a
+ * pure function of frontmatter. Missing/unparseable `created` ⇒ 0 (treated as
+ * brand-new, never infinitely aged). Byte-equivalent to comparators.ts.
+ */
+export function agingDays(spec, nowMs) {
+  if (typeof nowMs !== 'number' || !Number.isFinite(nowMs)) return 0;
+  const createdMs = Date.parse(createdAt(spec));
+  if (Number.isNaN(createdMs)) return 0;
+  const days = Math.floor((nowMs - createdMs) / MS_PER_DAY);
+  return days > 0 ? days : 0;
+}
+
+export function isAged(spec, nowMs) {
+  return agingDays(spec, nowMs) >= AGING_THRESHOLD_DAYS;
+}
+
+/** 0 = aged (promoted), 1 = not aged. Inert (always 1) when nowMs is undefined. */
+export function agingRank(spec, nowMs) {
+  return isAged(spec, nowMs) ? 0 : 1;
+}
+
+export function stableHash(id) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < id.length; i++) {
+    h ^= id.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return (h >>> 0).toString(16).padStart(8, '0');
+}
+
+export function topologicalSort(specs) {
+  // Duplicate node keys collapse the in-degree map below and would otherwise
+  // surface as a misleading CycleError — catch them here with a precise message.
+  // Keyed on `nodeKey` (not the shared family-key `id:`) so legit sibling tasks
+  // no longer false-trip it ([[HS-K5GQ-DIAG]]). Byte-equivalent to console
+  // toposort.ts.
+  const seenIds = new Set();
+  const dupIds = new Set();
+  for (const s of specs) {
+    const key = nodeKeyOf(s);
+    if (seenIds.has(key)) dupIds.add(key);
+    seenIds.add(key);
+  }
+  if (dupIds.size > 0) throw new DuplicateIdError([...dupIds].sort());
+
+  const idSet = seenIds;
+  const resolveDep = buildDepResolver(specs);
+  const inDegree = new Map();
+  const adj = new Map();
+  for (const s of specs) {
+    const key = nodeKeyOf(s);
+    inDegree.set(key, 0);
+    adj.set(key, []);
+  }
+  for (const s of specs) {
+    const sKey = nodeKeyOf(s);
+    for (const raw of s.depends_on ?? []) {
+      const dep = resolveDep(raw);
+      if (dep === null || dep === sKey) continue;
+      adj.get(dep).push(sKey);
+      inDegree.set(sKey, (inDegree.get(sKey) ?? 0) + 1);
+    }
+  }
+
+  const inputIndex = new Map(specs.map((s, i) => [nodeKeyOf(s), i]));
+  const layer = new Map();
+  let queue = [];
+  for (const [id, d] of inDegree) {
+    if (d === 0) {
+      queue.push(id);
+      layer.set(id, 0);
+    }
+  }
+  queue.sort((a, b) => inputIndex.get(a) - inputIndex.get(b));
+
+  const ordered = [];
+  let processed = 0;
+  while (queue.length) {
+    const next = [];
+    for (const id of queue) {
+      ordered.push({ id, layer: layer.get(id) });
+      processed++;
+      for (const successor of adj.get(id) ?? []) {
+        const remaining = (inDegree.get(successor) ?? 0) - 1;
+        inDegree.set(successor, remaining);
+        if (remaining === 0) {
+          next.push(successor);
+          layer.set(successor, layer.get(id) + 1);
+        }
+      }
+    }
+    next.sort((a, b) => inputIndex.get(a) - inputIndex.get(b));
+    queue = next;
+  }
+
+  if (processed < specs.length) {
+    throw new CycleError(findCycle(specs, idSet));
+  }
+  return ordered;
+}
+
+function findCycle(specs, idSet) {
+  const resolveDep = buildDepResolver(specs);
+  const out = new Map();
+  for (const s of specs) {
+    const sKey = nodeKeyOf(s);
+    out.set(
+      sKey,
+      (s.depends_on ?? [])
+        .map(resolveDep)
+        .filter((d) => d !== null && d !== sKey && idSet.has(d)),
+    );
+  }
+  const color = new Map();
+  const parent = new Map();
+  function dfs(start) {
+    const stack = [{ id: start, depIndex: 0 }];
+    color.set(start, 1);
+    while (stack.length) {
+      const frame = stack[stack.length - 1];
+      const deps = out.get(frame.id) ?? [];
+      if (frame.depIndex >= deps.length) {
+        color.set(frame.id, 2);
+        stack.pop();
+        continue;
+      }
+      const dep = deps[frame.depIndex++];
+      const c = color.get(dep) ?? 0;
+      if (c === 1) {
+        const cycle = [dep];
+        let cur = frame.id;
+        while (cur !== dep) {
+          cycle.push(cur);
+          cur = parent.get(cur);
+        }
+        cycle.push(dep);
+        return cycle.reverse();
+      }
+      if (c === 0) {
+        color.set(dep, 1);
+        parent.set(dep, frame.id);
+        stack.push({ id: dep, depIndex: 0 });
+      }
+    }
+    return null;
+  }
+  for (const s of specs) {
+    const sKey = nodeKeyOf(s);
+    if ((color.get(sKey) ?? 0) === 0) {
+      const found = dfs(sKey);
+      if (found) return found;
+    }
+  }
+  return ['<cycle detected but path not recoverable>'];
+}
+
+/**
+ * Detect `depends_on` edges that point at a spec absent from the whole vault
+ * ([[HS-TASK-Y4EY]] / [[HS-EPIC-RBST]] AC#5). Mirror of console
+ * toposort.ts:detectDanglingEdges — keep byte-equivalent.
+ *
+ * `topologicalSort` tolerates such edges (it skips them so the order still
+ * computes), so a deleted/mistyped target is silently ordered around. This
+ * surfaces them as a list. Classification is against `knownVaultIds` — the
+ * FULL vault id set, not the scheduler input set — so a legitimate
+ * cross-cohort dependency (present in the vault, absent from this input) is
+ * NOT flagged; only a target absent from the entire vault is. Self-edges are
+ * skipped. Returns `[{ specId, target }]`. Pure, deterministic.
+ */
+export function detectDanglingEdges(specs, knownVaultIds) {
+  const dangling = [];
+  for (const s of specs) {
+    for (const raw of s.depends_on ?? []) {
+      const dep = normalizeDependsOnId(raw);
+      if (dep === s.id) continue;
+      if (knownVaultIds.has(dep)) continue;
+      dangling.push({ specId: s.id, target: dep });
+    }
+  }
+  return dangling;
+}
+
+/**
+ * Stage 3 — critical-path length per spec (longest downstream chain). See
+ * spex-console/src/lib/scheduler/criticality.ts for the matching TypeScript version;
+ * this is byte-equivalent. Path length, not descendant count, so width-only
+ * fan-out can't inflate rank (HS-EPIC-RBST AC#2; for a pure chain the two
+ * measures coincide).
+ */
+export function computeCriticality(specs) {
+  // Keyed on the unique `nodeKey` (not the shared family-key `id:`) so sibling
+  // tasks each get their own critical-path length ([[HS-K5GQ-DIAG]]).
+  const resolveDep = buildDepResolver(specs);
+  const directDependents = new Map();
+  for (const s of specs) directDependents.set(nodeKeyOf(s), []);
+  for (const s of specs) {
+    const sKey = nodeKeyOf(s);
+    for (const raw of s.depends_on ?? []) {
+      const dep = resolveDep(raw);
+      if (dep === null || dep === sKey) continue;
+      directDependents.get(dep).push(sKey);
+    }
+  }
+  const layered = topologicalSort(specs);
+  // Reverse topo order so each dependent's value is computed before we max over it.
+  const out = new Map();
+  for (let i = layered.length - 1; i >= 0; i--) {
+    const y = layered[i].id;
+    let longest = 0;
+    for (const x of directDependents.get(y) ?? []) {
+      const through = 1 + (out.get(x) ?? 0);
+      if (through > longest) longest = through;
+    }
+    out.set(y, longest);
+  }
+  return out;
+}
+
+export function buildExplanation(
+  spec,
+  layer,
+  criticality = 0,
+  wasClusteredByTesting = false,
+  agedDays = 0,
+) {
+  const tier = tierOf(spec);
+  const rank = tierRankOf(spec);
+  const blast = blastRadiusOf(spec);
+  const created = createdAt(spec);
+  const hash = stableHash(spec.id);
+  const status = spec?.status ?? 'open';
+  const effort = effortOf(spec);
+  // Stage 6.7 — declared parent-order ([[HS-67F4-DIAG]]). `undefined` unless the
+  // cohort boundary stamped a parent-declared position, so `JSON.stringify`
+  // omits both fields and unstamped traces stay byte-identical (console parity).
+  const declaredOrderIndex =
+    typeof spec?.declaredOrderIndex === 'number' ? spec.declaredOrderIndex : undefined;
+  const parentKey = spec?.parent ?? spec?.milestone ?? undefined;
+
+  const reasons = [];
+  if (status === 'in_progress') reasons.push('in_progress');
+  reasons.push(`${tier} tier`);
+  reasons.push(`topological layer ${layer}`);
+  // Stage 2.7 — blast-radius band ([[encoding-foundational-and-blast-radius-p]]).
+  // Cited after tier and before what_matters; omitted for the `local` default.
+  // Mirror explanation.ts.
+  if (blast !== 'local') {
+    reasons.push(`${blast} blast radius`);
+  }
+  // Stage 2.5 — what_matters within-tier value band ([[HS-TASK-PQID]]). Cited
+  // after tier and before criticality; omitted when unset. Mirror explanation.ts.
+  if (spec?.what_matters === 'heart') {
+    reasons.push('user marked very important (heart)');
+  } else if (spec?.what_matters === 'star') {
+    reasons.push('user marked priority (star)');
+  }
+  if (criticality > 0) {
+    reasons.push(`longest downstream chain: ${criticality}`);
+  }
+  // Stage 4.5 — aging guard cite (precedes effort; an aged spec leads non-aged
+  // peers in its bucket regardless of effort).
+  if (agedDays >= AGING_THRESHOLD_DAYS) {
+    reasons.push(`promoted by aging guard (waited ${agedDays}d)`);
+  }
+  reasons.push(`${effort}-pt effort`);
+  if (wasClusteredByTesting) {
+    reasons.push('grouped with adjacent testing-flagged specs');
+  }
+  // Stage 6.7 — declared parent-order cite ([[HS-67F4-DIAG]]). Precedes created
+  // because the owner's authored sequence outranks incidental creation time;
+  // omitted when the spec has no parent-declared position. Mirror explanation.ts.
+  if (declaredOrderIndex !== undefined) {
+    reasons.push(`declared parent-order #${declaredOrderIndex + 1}`);
+  }
+  reasons.push(`created ${created.slice(0, 10)}`);
+  reasons.push(`id-hash=${hash}`);
+
+  return {
+    topologicalLayer: layer,
+    tier,
+    tierRank: rank,
+    blastRadius: blast,
+    criticality,
+    status,
+    agedDays,
+    effort,
+    createdAt: created,
+    idHash: hash,
+    declaredOrderIndex,
+    parentKey,
+    reasons,
+  };
+}
+
+/**
+ * Stage 6 bucket key — composite of every higher-stage signal (the stage-2.5
+ * what_matters band and the aging guard included). Two specs with the same key
+ * are swappable without violating stages 1–5; including what_matters keeps the
+ * cluster pass from reordering a heart spec past an unflagged peer.
+ */
+function stage6BucketKey(spec, layer, criticality, nowMs) {
+  return [
+    layer,
+    tierRankOf(spec),
+    blastRadiusRank(spec),
+    whatMattersRank(spec),
+    criticality,
+    inProgressRank(spec),
+    agingRank(spec, nowMs),
+    effortOf(spec),
+  ].join('|');
+}
+
+function applyTestingBatch(ordered, byId, criticality, nowMs) {
+  const out = [...ordered];
+  const movedTestingSpecs = new Set();
+  // Snapshot original indexes so the partition can cite which flagged specs
+  // actually moved (HS-TASK-Q4EZ — `reasons[]` must reflect the stage 6 swap).
+  const originalIndex = new Map();
+  for (let k = 0; k < ordered.length; k++) originalIndex.set(ordered[k].id, k);
+
+  let i = 0;
+  while (i < out.length) {
+    const seed = byId.get(out[i].id);
+    const key = stage6BucketKey(
+      seed,
+      out[i].layer,
+      criticality.get(out[i].id) ?? 0,
+      nowMs,
+    );
+    let j = i + 1;
+    while (j < out.length) {
+      const next = byId.get(out[j].id);
+      const nextKey = stage6BucketKey(
+        next,
+        out[j].layer,
+        criticality.get(out[j].id) ?? 0,
+        nowMs,
+      );
+      if (nextKey !== key) break;
+      j++;
+    }
+    if (j - i > 1) {
+      const testing = [];
+      const other = [];
+      for (let k = i; k < j; k++) {
+        if (byId.get(out[k].id)?.requires_user_testing === true) {
+          testing.push(out[k]);
+        } else {
+          other.push(out[k]);
+        }
+      }
+      if (testing.length > 0 && other.length > 0) {
+        const merged = [...testing, ...other];
+        for (let k = 0; k < merged.length; k++) {
+          out[i + k] = merged[k];
+          const id = merged[k].id;
+          if (
+            byId.get(id)?.requires_user_testing === true &&
+            originalIndex.get(id) !== i + k
+          ) {
+            movedTestingSpecs.add(id);
+          }
+        }
+      }
+    }
+    i = j;
+  }
+  return { ordered: out, movedTestingSpecs };
+}
+
+/**
+ * Stage 9 — hysteresis band. Mirror of console pipeline.ts:applyHysteresis.
+ * Reorders within topological layers only (layer boundaries are hard, so
+ * nothing crosses a layer), keying each spec by (effectivePos, freshIndex, id).
+ * effectivePos sticks to the prior index when the move is sub-threshold,
+ * otherwise adopts the fresh index. Inert when priorOrder is empty/undefined.
+ */
+function applyHysteresis(ordered, priorOrder) {
+  if (!priorOrder || priorOrder.length === 0) return ordered;
+
+  const priorIndex = new Map();
+  priorOrder.forEach((id, i) => {
+    if (!priorIndex.has(id)) priorIndex.set(id, i);
+  });
+  const freshIndex = new Map();
+  ordered.forEach((o, i) => freshIndex.set(o.id, i));
+
+  const effectivePosOf = (id) => {
+    const fi = freshIndex.get(id);
+    const pi = priorIndex.get(id);
+    if (pi === undefined) return fi;
+    return Math.abs(fi - pi) < HYSTERESIS_DELTA ? pi : fi;
+  };
+
+  const out = [...ordered];
+  let i = 0;
+  while (i < out.length) {
+    let j = i + 1;
+    while (j < out.length && out[j].layer === out[i].layer) j++;
+    if (j - i > 1) {
+      const run = out.slice(i, j);
+      run.sort((a, b) => {
+        const ea = effectivePosOf(a.id);
+        const eb = effectivePosOf(b.id);
+        if (ea !== eb) return ea - eb;
+        const fa = freshIndex.get(a.id);
+        const fb = freshIndex.get(b.id);
+        if (fa !== fb) return fa - fb;
+        return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+      });
+      for (let k = 0; k < run.length; k++) out[i + k] = run[k];
+    }
+    i = j;
+  }
+  return out;
+}
+
+export function computeOrder(specs, opts = {}) {
+  const { nowMs, priorOrder } = opts;
+  // Layered output + `byId` key on the unique `nodeKey` (not the shared
+  // family-key `id:`) so sibling tasks are distinct nodes ([[HS-K5GQ-DIAG]]).
+  const layered = topologicalSort(specs);
+  const byId = new Map(specs.map((s) => [nodeKeyOf(s), s]));
+  const criticality = computeCriticality(specs);
+
+  const sorted = [...layered].sort((a, b) => {
+    if (a.layer !== b.layer) return a.layer - b.layer;
+    const sa = byId.get(a.id);
+    const sb = byId.get(b.id);
+
+    const tr = tierRankOf(sa) - tierRankOf(sb);
+    if (tr !== 0) return tr;
+
+    // Stage 2.7 — blast-radius band ASC (vault-wide < cross-surface < local)
+    // ([[encoding-foundational-and-blast-radius-p]]). Within-tier only; above
+    // what_matters. Inert when every spec is `local`. Mirror pipeline.ts.
+    const br = blastRadiusRank(sa) - blastRadiusRank(sb);
+    if (br !== 0) return br;
+
+    // Stage 2.5 — what_matters within-tier value band: heart > star > unflagged
+    // (DESC). Within-tier only; outranks criticality, in-progress bias, effort.
+    const wm = whatMattersRank(sb) - whatMattersRank(sa);
+    if (wm !== 0) return wm;
+
+    const ca3 = criticality.get(a.id) ?? 0;
+    const cb3 = criticality.get(b.id) ?? 0;
+    if (ca3 !== cb3) return cb3 - ca3;
+
+    const ip = inProgressRank(sa) - inProgressRank(sb);
+    if (ip !== 0) return ip;
+
+    // Stage 4.5 — aging guard (anti-starvation): aged specs lead non-aged peers
+    // within their (layer × tier × criticality × in_progress) partition.
+    const ag = agingRank(sa, nowMs) - agingRank(sb, nowMs);
+    if (ag !== 0) return ag;
+
+    const eff = effortOf(sa) - effortOf(sb);
+    if (eff !== 0) return eff;
+
+    // Stage 6.7 — declared parent-order ([[HS-67F4-DIAG]]): among siblings that
+    // are otherwise tied on every real signal, honor the owner's authored
+    // sequence (milestone `epics:` / epic `children:` position) BEFORE falling
+    // to created/hash. Guarded to siblings sharing a parent (`parent ?? milestone`)
+    // because the comparator ranks the whole cohort at once — comparing declared
+    // indices across different parents is meaningless. Inert (falls through) when
+    // either spec lacks a stamped index, so a cohort built without the stamp
+    // orders byte-identically. Mirror pipeline.ts.
+    const pa = sa.parent ?? sa.milestone;
+    const pb = sb.parent ?? sb.milestone;
+    if (
+      pa != null &&
+      pa === pb &&
+      sa.declaredOrderIndex != null &&
+      sb.declaredOrderIndex != null &&
+      sa.declaredOrderIndex !== sb.declaredOrderIndex
+    ) {
+      return sa.declaredOrderIndex - sb.declaredOrderIndex;
+    }
+
+    const ca = createdAt(sa);
+    const cb = createdAt(sb);
+    if (ca !== cb) return ca < cb ? -1 : 1;
+
+    // Stage 8 — stable hash final tiebreaker on the family-key `id:`
+    // (byte-identical to the pre-nodeKey mirror for every non-sibling pair).
+    const ha = stableHash(sa.id);
+    const hb = stableHash(sb.id);
+    if (ha !== hb) return ha < hb ? -1 : 1;
+    // Same family key (legit sibling tasks, [[HS-K5GQ-DIAG]]) → disambiguate on
+    // the unique node key; distinct hash-collision pairs keep prior behavior.
+    if (sa.id === sb.id) return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+    return 0;
+  });
+
+  const { ordered: clustered, movedTestingSpecs } = applyTestingBatch(
+    sorted,
+    byId,
+    criticality,
+    nowMs,
+  );
+
+  // Stage 9 — hysteresis band (anti-churn), inert without priorOrder.
+  const stabilized = applyHysteresis(clustered, priorOrder);
+
+  // `id` here is the unique node key. Emit the family-key `id:` for display /
+  // pin / claim back-compat AND the unique `nodeKey` for callers that must
+  // disambiguate sibling tasks ([[HS-K5GQ-DIAG]]).
+  return stabilized.map(({ id, layer }, position) => ({
+    id: byId.get(id).id,
+    nodeKey: id,
+    position,
+    explanation: buildExplanation(
+      byId.get(id),
+      layer,
+      criticality.get(id) ?? 0,
+      movedTestingSpecs.has(id),
+      agingDays(byId.get(id), nowMs),
+    ),
+  }));
+}
+
+/**
+ * Pin override ([[HS-TASK-XA40]] / [[HS-TASK-PINQ]]). Re-orders the
+ * `SchedulerOrder` so the pinned spec sits as close to position 0 as its
+ * **open prerequisites allow** — the PM-pushback contract from [[HS-EPIC-CNVG]].
+ *
+ *   1. With `specs` omitted (legacy XA40 contract), move the pin to position 0
+ *      unconditionally. Kept for back-compat with callers that don't yet wire
+ *      prereqs in.
+ *   2. With `specs` provided, walk the pin's transitive `depends_on` closure
+ *      and seat every prereq that is present in the order ahead of the pin in
+ *      its existing relative order. The pin lands immediately after the last
+ *      unmet prereq.
+ *
+ * Keep in lockstep with spex-console/src/lib/scheduler/pipeline.ts:applyPin.
+ */
+export function applyPin(order, pinnedSpecId, specs) {
+  if (!pinnedSpecId) return order;
+  const idx = order.findIndex((o) => o.id === pinnedSpecId);
+  if (idx === -1) return order;
+
+  const unmetPrereqs =
+    specs && specs.length > 0
+      ? computeOpenPrereqClosure(pinnedSpecId, specs, order)
+      : new Set();
+
+  if (unmetPrereqs.size === 0) {
+    if (idx === 0) return order;
+    const pinned = order[idx];
+    const rest = [...order.slice(0, idx), ...order.slice(idx + 1)];
+    return [pinned, ...rest].map((o, position) => ({ ...o, position }));
+  }
+
+  const prereqEntries = [];
+  const otherEntries = [];
+  const pinned = order[idx];
+  for (let i = 0; i < order.length; i++) {
+    if (i === idx) continue;
+    const entry = order[i];
+    if (unmetPrereqs.has(entry.id)) prereqEntries.push(entry);
+    else otherEntries.push(entry);
+  }
+  const reordered = [...prereqEntries, pinned, ...otherEntries];
+  return reordered.map((o, position) => ({ ...o, position }));
+}
+
+function computeOpenPrereqClosure(pinId, specs, order) {
+  const orderIds = new Set(order.map((o) => o.id));
+  const byId = new Map(specs.map((s) => [s.id, s]));
+  const unmet = new Set();
+  const visited = new Set([pinId]);
+  const queue = [pinId];
+  while (queue.length > 0) {
+    const cur = queue.shift();
+    const spec = byId.get(cur);
+    if (!spec || !spec.depends_on) continue;
+    for (const depRaw of spec.depends_on) {
+      const dep = normalizeDependsOnId(depRaw);
+      if (!dep || dep === cur || dep === pinId) continue;
+      if (visited.has(dep)) continue;
+      visited.add(dep);
+      if (orderIds.has(dep)) unmet.add(dep);
+      queue.push(dep);
+    }
+  }
+  return unmet;
+}
+
+/**
+ * Convert a vault spec's frontmatter (raw, as loaded by parseFrontmatter)
+ * into the minimal scheduler input. Tolerates `depends_on` as wikilink array
+ * or scalar; missing/legacy `kind` defaults to feature.
+ */
+export function frontmatterToSchedulerSpec(specId, frontmatter = {}) {
+  const dependsRaw = frontmatter.depends_on;
+  const depends = Array.isArray(dependsRaw)
+    ? dependsRaw
+    : dependsRaw == null
+      ? []
+      : [dependsRaw];
+  return {
+    id: specId,
+    kind: typeof frontmatter.kind === 'string' ? frontmatter.kind : undefined,
+    effort: typeof frontmatter.effort === 'number' ? frontmatter.effort : undefined,
+    requires_user_testing:
+      typeof frontmatter.requires_user_testing === 'boolean'
+        ? frontmatter.requires_user_testing
+        : undefined,
+    depends_on: depends,
+    created:
+      typeof frontmatter.created === 'string'
+        ? frontmatter.created
+        : frontmatter.created instanceof Date
+          ? frontmatter.created.toISOString()
+          : undefined,
+    status: typeof frontmatter.status === 'string' ? frontmatter.status : undefined,
+    canonical:
+      typeof frontmatter.canonical === 'boolean' ? frontmatter.canonical : undefined,
+    // Stage 2.5 input — what_matters value band ([[HS-TASK-PQID]]). Guarded to
+    // the two recognized levels; any other value (or absent) → undefined, so the
+    // band is inert. Mirrors console toSchedulerSpec (focus-explanations.ts).
+    what_matters:
+      frontmatter.what_matters === 'star' || frontmatter.what_matters === 'heart'
+        ? frontmatter.what_matters
+        : undefined,
+  };
+}