heyspex 0.2.6 → 0.2.7

package/vendor/heyspex-mcp/on-deck-scheduler.mjs

@@ -1,1708 +1,1708 @@
-// Which spec is on deck: vault/scheduler loaders, milestone scoping, the frozen
-// scheduler order, focus overrides, and resolveNextOnDeck itself. The brief
-// renderer (on-deck-brief.mjs) sits on top of this. Extracted from cli.mjs under
-// [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]] (no behavior change).
-//
-// ─────────────────────────────────────────────────────────────────────────────
-// Scheduler cohort + pin resolution ([[HS-TASK-CLIM]])
-//
-// Mirrors console's `/api/scheduler/inspect` + `/api/roadmap/[id]` cohort
-// assembly so vendor `resolveNextOnDeck` picks position-0 from the same global
-// order computeOrderCached exposes to the console surfaces. The parity contract
-// is: same vault, same focus pin → same #1 spec_id. Console's
-// `partitionForScheduler` / active-milestone scope are caller-side concerns
-// (the vendor parity test explicitly excludes them from byte-equivalence,
-// [[HS-TASK-ZJLX]]), so the filters live here rather than in scheduler.mjs.
-// ─────────────────────────────────────────────────────────────────────────────
-//
-// Reorder a list of `{ id, status, ... }` candidate epics by running
-// computeOrder LOCALLY over them, mirroring console's `pickMilestoneOnDeck`
-// descent pattern. Epics whose status is non-actionable (closed / in_review /
-// hibernated) are excluded from the local cohort but kept in the output at the
-// tail in their original relative order so the surface caller still sees them.
-// Cycles / cohort load failures degrade to the input order.
-// [[HS-EPIC-FRZE]] file-fallback removed (2026-06-10). The milestone snapshot is
-// Neon-only; the console never writes `.heyspex/milestone-snapshots/*.json`, so the
-// former `readMilestoneSnapshotFile` / `applyFrozenEpicOrder` / `isMilestoneSnapshotEnabled`
-// helpers always no-opped. /hs-next returns live scheduler order until a real
-// Neon-backed snapshot read lands (deferred follow-up).
-
-import { findSpecFile, loadRoadmap, loadSpec, loadTask, loadTaskViaGraph, parseFrontmatter, wikilinkTarget } from './vault-io.mjs';
-import { CycleError as SchedulerCycleError, applyPin as schedulerApplyPin, buildExplanation as schedulerBuildExplanation, computeOrder as schedulerComputeOrder, frontmatterToSchedulerSpec, normalizeDependsOnId } from './scheduler.mjs';
-import { buildBlockerBanner, buildEpicBoundaryPromptMarkdown, computeUnmetBlockers as computeUnmetBlockersImpl, mapStateToHint, resolveEpicChildTask as resolveEpicChildTaskImpl, resolveMilestoneState as resolveMilestoneStateImpl } from './blocker-resolver.mjs';
-import { readMvpModeState } from './mvp-mode.mjs';
-import { consoleReadErrorFrom, readViaSelector } from './read-path.mjs';
-import { consoleFetch } from './console-transport.mjs';
-import { join } from 'node:path';
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { detectUITags, loadDesignMemories } from './memory-tools.mjs';
-import { assessBriefReadiness, buildClarificationPrompt, buildExecutionBrief, classifyBriefTier, extractDecompositionContext, readReadinessFloorSettings } from './alignment-gate.mjs';
-import { formatBriefTierLog, recordBriefTier } from './brief-observability.mjs';
-import { buildWhyNow as schedulerBuildWhyNow } from './why-now.mjs';
-import { toCanonicalFamilyFirstId } from './spec-id-lib.mjs';
-
-export function loadFocusOverride(vaultRoot, options = {}) {
-  // Neon layer-1 pin (precedence #1) wins when present. It is the console-set
-  // fuse pin, which on a Neon-up machine is DORMANT in the file (vault.ts writes
-  // it to Neon `focus_pin`, not focus.yaml — [[heyspex-is-saas-cloud-primary-both-tiers]]).
-  // The caller fetches it at the async boundary (`injectNeonFocusPin`) and threads
-  // the spec_id in here so this sync resolver can honor it. We resolve it to a
-  // focus object that supersedes the file's layer-2 `spec_path` entirely, so a
-  // stale dormant-file pin is never resurrected. FCPN follow-on (the documented
-  // paid-tier soak gap). Falls through to the file when the id doesn't resolve.
-  const neonPinSpecId = options.neonPinSpecId;
-  if (typeof neonPinSpecId === 'string' && neonPinSpecId) {
-    const resolved = findSpecFile(vaultRoot, neonPinSpecId);
-    if (resolved) {
-      return { spec_path: resolved, pin: { spec_id: neonPinSpecId } };
-    }
-    // id doesn't resolve to a vault file → don't steer nowhere; use the file.
-  }
-
-  // Precedence #2: the Neon `focus_selection` layer-2 spec_path ([[HS-TASK-FSEL]]).
-  // On a Neon-up machine the console writes layer-2 here, not the (dormant) file —
-  // so reading it keeps vendor /hs-next in agreement with the console On-Deck.
-  // The stored value is already a repo-relative `specs/…md` path.
-  const neonSelectionSpecPath = options.neonSelectionSpecPath;
-  if (typeof neonSelectionSpecPath === 'string' && neonSelectionSpecPath) {
-    return { spec_path: neonSelectionSpecPath };
-  }
-
-  // No `.heyspex/focus.yaml` fallback ([[no-fallbacks-by-default]]; the
-  // focus.yaml-fallback incident). Focus lives only in Neon, fetched at the
-  // async boundary (`injectNeonFocusPin`) and threaded in via the options
-  // above. When neither a Neon pin nor selection is present (console
-  // unreachable, or simply no focus set), there is no override — /hs-next
-  // resolves the scheduler default off the local vault. Focus steering is a
-  // nicety, not a correctness gate, so an absent console degrades to "no
-  // steer", never to a stale file read.
-  return null;
-}
-
-export function extractNextStepBlock(body) {
-  // Look for a "NEXT STEP" or "## NEXT STEP" section
-  const patterns = [
-    /```[^\n]*NEXT STEP[^\n]*\n([\s\S]*?)```/i,
-    /## NEXT STEP[:\s]*Ready-to-paste prompt\s*\n\s*```[^\n]*\n([\s\S]*?)```/i,
-    /NEXT STEP[:\s]*\n\s*```[^\n]*\n([\s\S]*?)```/i,
-  ];
-
-  for (const pattern of patterns) {
-    const match = body.match(pattern);
-    if (match) return match[1].trim();
-  }
-
-  return null;
-}
-
-/**
- * Build the "Design System Requirements" section for UI epics.
- * @param {Array} decisions - Design decisions to include
- * @param {string[]} triggerTags - Tags that triggered this
- * @returns {string} - Markdown section
- */
-export function buildDesignContextSection(decisions, triggerTags) {
-  if (decisions.length === 0) return '';
-
-  const lines = [
-    '## Design System Requirements',
-    '',
-    `> **Triggered by tags:** ${triggerTags.join(', ')}`,
-    '>',
-    '> Apply these design decisions before implementation. Violations will be caught by pre-commit hooks.',
-    '',
-  ];
-
-  for (const decision of decisions) {
-    lines.push(`### ${decision.id}`);
-    lines.push('');
-    lines.push(decision.summary);
-    lines.push('');
-
-    if (decision.checklist && decision.checklist.length > 0) {
-      lines.push('**Checklist:**');
-      for (const item of decision.checklist) {
-        lines.push(`- [ ] ${item}`);
-      }
-      lines.push('');
-    }
-  }
-
-  lines.push('---');
-  lines.push('');
-
-  return lines.join('\n');
-}
-
-export function isInitiative(taskId) {
-  return taskId.includes('ROADMAP') || taskId.startsWith('HS-ROADMAP-');
-}
-
-// Status filter mirror of `spex-console/src/lib/db/repositories/helpers.ts:SCHEDULER_EXCLUDED_STATUSES`.
-// [[HS-EPIC-FRZE]] — synced to console's full 6-status set (added cancelled /
-// superseded / duplicate). Previously the cli excluded only 3, so `/hs-next`
-// and the console could disagree on the active set for a terminal-but-not-shipped
-// spec (CNVG-AC1 divergence). These are terminal: the work was intentionally
-// dropped, so it must never earn an on-deck position on either surface.
-export const SCHEDULER_EXCLUDED_STATUSES = new Set([
-  'closed',
-  'hibernated',
-  'in_review',
-  'cancelled',
-  'superseded',
-  'duplicate',
-  // [[HS-DIAG-YMN3]]: `parked` = indefinite park; scheduler-invisible. Mirrors
-  // console's `SCHEDULER_EXCLUDED_STATUSES` (helpers.ts) so `/hs-next` never
-  // ranks a parked spec into the active cohort the way the console no longer does.
-  'parked',
-]);
-
-export function isSchedulerExcluded(status, canonical) {
-  if (SCHEDULER_EXCLUDED_STATUSES.has(status)) return true;
-  return canonical === false;
-}
-
-// Mirror of `spex-console/src/lib/scheduler/toposort.ts:isCanonicalSpecId`.
-export function isCanonicalSpecId(id) {
-  // Family-keyed kinds (TASK/EPIC/MIL/RES/CAP/REV/…): accept EITHER ordering by
-  // recomposing via parseSpecId ([[HS-EPIC-DLE3]]). Non-family-keyed labels
-  // (ROADMAP/IDEA/FLOW) are not reordered, so keep the type-first bare check.
-  if (toCanonicalFamilyFirstId(id)) return true;
-  return /^HS-(?:ROADMAP|IDEA|FLOW)-[A-Z0-9]+$/.test(id);
-}
-
-// Mirror of `spex-console/src/lib/vault-shared.ts:canonicalizeSpecRef` — strips
-// wikilink wrappers + slug tails, returning the bare canonical id.
-export function canonicalizeSpecRef(value) {
-  if (value == null) return null;
-  const inner = wikilinkTarget(String(value));
-  if (!inner) return null;
-  const m = inner.match(
-    /^(HS-(?:TASK|EPIC|MIL|ROADMAP|RES|CAP|REV|IDEA|FLOW)-(?:\d+|[A-Z0-9]+))/,
-  );
-  return m ? m[1] : inner;
-}
-
-// Walk specs/{tasks,epics,milestones} and return one entry per .md file.
-// Result entries are `{ id, frontmatter, relPath }`. Used to seed the scheduler
-// cohort below — we keep the full milestone set so `getActiveMilestones` can
-// run, and partition them out before computeOrder.
-export function loadVaultSpecsForScheduler(vaultRoot) {
-  const out = [];
-  // Diagnoses ([[HS-MIL-BFIX]]) join the scheduler pool so an open bug fix
-  // competes for on-deck by `severity:` (channel B). It is the SINGLE ranker
-  // that decides order; the Resolution surface only advises via severity.
-  // Disk-only readdir — misses Neon-only (cloud-filed) diagnoses; see [[HS-7UJZ-O86I-DIAG]].
-  for (const dir of ['specs/tasks', 'specs/epics', 'specs/milestones', 'specs/diagnoses']) {
-    const full = join(vaultRoot, dir);
-    if (!existsSync(full)) continue;
-    let files;
-    try {
-      files = readdirSync(full, { withFileTypes: true });
-    } catch {
-      continue;
-    }
-    for (const entry of files) {
-      if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
-      const relPath = `${dir}/${entry.name}`;
-      try {
-        const content = readFileSync(join(vaultRoot, relPath), 'utf-8');
-        const { frontmatter } = parseFrontmatter(content);
-        const fallback = entry.name.replace(/\.md$/i, '');
-        const id = typeof frontmatter.id === 'string' && frontmatter.id ? frontmatter.id : fallback;
-        out.push({ id, frontmatter, relPath });
-      } catch {
-        // ignore unreadable / malformed files
-      }
-    }
-  }
-  return out;
-}
-
-// Map a diagnose's `severity:` onto the scheduler's existing `kind` tier
-// ([[HS-MIL-BFIX]] channel B — "map severity to existing signals"). The tier is
-// the first within-layer ranking key in computeOrder. Moderate mapping (owner
-// decision 2026-06-16): an error-severity bug competes at FOUNDATION (just below
-// core infra), a warning at feature, an info at polish — so a build-breaking bug
-// surfaces high WITHOUT outranking genuine infra. Absent/invalid severity →
-// 'feature' (matches detect-bugs.ts's `warning` default). MUST stay byte-identical
-// to the console copy in `spex-console/src/lib/vault.ts` (`DIAGNOSE_SEVERITY_TIER`)
-// so vendor↔console on-deck order is parity-identical.
-export const DIAGNOSE_SEVERITY_TIER = { error: 'foundation', warning: 'feature', info: 'polish' };
-
-// The four scheduler tiers a pillar's `library_tier:` may name. Mirrors
-// console `TIER_ORDER` (spex-console/src/lib/scheduler/types.ts).
-export const PILLAR_TIER_VALUES = new Set(['infra', 'foundation', 'feature', 'polish']);
-
-// Build a `pillar id → scheduler tier` map by reading `specs/pillars/*.md`.
-// Mirrors console `buildPillarTierMap` (spex-console/src/lib/db/repositories/
-// helpers.ts): an evergreen pillar with `library_tier: foundation` lets epics
-// under it inherit the foundation tier when they set no explicit `kind:`.
-// Pillars whose `library_tier` is not a tier (e.g. `meta`) or is unset
-// contribute no entry. Read from disk separately because the scheduler row
-// loader (`loadVaultSpecsForScheduler`) deliberately omits the pillars dir.
-export function loadPillarTierMap(vaultRoot) {
-  const out = new Map();
-  const full = join(vaultRoot, 'specs/pillars');
-  if (!existsSync(full)) return out;
-  let files;
-  try {
-    files = readdirSync(full, { withFileTypes: true });
-  } catch {
-    return out;
-  }
-  for (const entry of files) {
-    if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
-    try {
-      const content = readFileSync(join(full, entry.name), 'utf-8');
-      const { frontmatter: fm } = parseFrontmatter(content);
-      if (fm.type !== 'pillar') continue;
-      const lt = typeof fm.library_tier === 'string' ? fm.library_tier : null;
-      if (lt && PILLAR_TIER_VALUES.has(lt)) {
-        const fallback = entry.name.replace(/\.md$/i, '');
-        const id = typeof fm.id === 'string' && fm.id ? fm.id : fallback;
-        out.set(canonicalizeSpecRef(id) || id, lt);
-      }
-    } catch {
-      // ignore unreadable / malformed files
-    }
-  }
-  return out;
-}
-
-/**
- * A console `GET /api/specs` row (`SpecSummary`) already flattens every
- * scheduler-relevant frontmatter field to the top level (id, type, status,
- * tags, effort, requires_user_testing, depends_on, canonical, created, kind,
- * library_tier, blast_radius, epics, children, milestone, parent, pillar) —
- * see `spex-console/src/lib/vault-shared.ts`. `vaultRowToSchedulerSpec` /
- * `frontmatterToSchedulerSpec` read the row as if it WERE frontmatter, so this
- * just renames the one field that doesn't share its frontmatter name.
- *
- * Known gap (no console fields= extension exists to close it without editing
- * spex-console, forbidden by this task): `SpecSummary` does not carry
- * `severity`, so a diagnose's severity-derived tier
- * (`vaultRowToSchedulerSpec`'s `DIAGNOSE_SEVERITY_TIER` lookup) always falls
- * back to `'feature'` in cloud reliance instead of reflecting the real
- * severity — documented here rather than silently accepted.
- */
-export function summaryRowToFrontmatterLike(row) {
-  return { ...row, what_matters: row.whatMatters ?? row.what_matters };
-}
-
-/**
- * Cloud-reliant sibling of `loadVaultSpecsForScheduler` ([[HS-DJWP-MCPC-TASK]]
- * "Scheduler cohort" family). `loadVaultSpecsForScheduler` stays untouched
- * (the `diskRead` branch); in `neon` tier this asks `GET /api/specs` once
- * (no `type=` — the four wanted types are filtered client-side, mirroring
- * the four directories the disk loader walks) instead of `readdirSync`ing
- * `specs/{tasks,epics,milestones,diagnoses}`.
- */
-export async function loadVaultSpecsForSchedulerViaTier(vaultRoot, { tier, consoleUrl }) {
-  return readViaSelector({
-    tier,
-    diskRead: () => loadVaultSpecsForScheduler(vaultRoot),
-    neonRead: async () => {
-      const res = await consoleFetch('/api/specs');
-      if (!res.ok) {
-        throw consoleReadErrorFrom(res, `GET /api/specs returned ${res.status}: ${res.error || JSON.stringify(res.body ?? {})}`, null);
-      }
-      const rows = Array.isArray(res.body?.specs) ? res.body.specs : [];
-      const wanted = new Set(['task', 'epic', 'milestone', 'diagnose']);
-      return rows
-        .filter((r) => wanted.has(r.type))
-        .map((r) => ({ id: r.id, frontmatter: summaryRowToFrontmatterLike(r), relPath: r.relPath }));
-    },
-    routeLabel: 'GET /api/specs',
-    consoleUrl,
-  });
-}
-
-/**
- * Cloud-reliant sibling of `loadPillarTierMap` ([[HS-DJWP-MCPC-TASK]] "Pillar
- * tier map" family). `loadPillarTierMap` stays untouched (the `diskRead`
- * branch); in `neon` tier this asks `GET /api/specs?type=pillar` instead of
- * `readdirSync`ing `specs/pillars`.
- */
-export async function loadPillarTierMapViaTier(vaultRoot, { tier, consoleUrl }) {
-  return readViaSelector({
-    tier,
-    diskRead: () => loadPillarTierMap(vaultRoot),
-    neonRead: async () => {
-      const res = await consoleFetch('/api/specs?type=pillar');
-      if (!res.ok) {
-        throw consoleReadErrorFrom(res, `GET /api/specs?type=pillar returned ${res.status}: ${res.error || JSON.stringify(res.body ?? {})}`, null);
-      }
-      const rows = Array.isArray(res.body?.specs) ? res.body.specs : [];
-      const out = new Map();
-      for (const r of rows) {
-        const lt = typeof r.library_tier === 'string' ? r.library_tier : null;
-        if (lt && PILLAR_TIER_VALUES.has(lt)) {
-          out.set(canonicalizeSpecRef(r.id) || r.id, lt);
-        }
-      }
-      return out;
-    },
-    routeLabel: 'GET /api/specs?type=pillar',
-    consoleUrl,
-  });
-}
-
-// Promote a loaded vault row into the SchedulerSpec shape. Mirrors console
-// `summaryToSchedulerSpec` — same fields, derived from raw frontmatter.
-// The unique scheduler node key for a spec row/task ([[HS-K5GQ-DIAG]]): its
-// basename, derived from `relPath` (scheduler rows) or `specPath` (loadTask).
-// Sibling tasks under one epic share a family-key `id:`; the basename is what
-// disambiguates them so `computeOrder` doesn't throw DuplicateIdError. Falls
-// back to `id` when no path is on hand (keeps nodeKey === id, byte-identical).
-export function specBasename(rowOrTask) {
-  const p = rowOrTask?.relPath || rowOrTask?.specPath;
-  if (typeof p === 'string' && p) {
-    return p.replace(/^.*[/\\]/, '').replace(/\.md$/i, '');
-  }
-  return rowOrTask?.id;
-}
-
-// [[HS-67F4-DIAG]] — build a child-id → declared-order-index map from every
-// milestone's `epics:` array and every epic's `children:` array, so the global
-// cohort can stamp each spec's position in its parent's authored sequence
-// (Stage 6.7 tiebreak). Keyed on the canonical child id; first occurrence wins.
-export function buildDeclaredOrderByChild(rows) {
-  const byChild = new Map();
-  for (const row of rows) {
-    const fm = row.frontmatter || {};
-    const refs = fm.type === 'milestone' ? fm.epics : fm.type === 'epic' ? fm.children : null;
-    if (!Array.isArray(refs)) continue;
-    refs.forEach((ref, i) => {
-      const key = canonicalizeSpecRef(ref);
-      if (key && !byChild.has(key)) byChild.set(key, i);
-    });
-  }
-  return byChild;
-}
-
-export function vaultRowToSchedulerSpec(row, pillarTierById, declaredOrderByChild) {
-  const spec = frontmatterToSchedulerSpec(row.id, row.frontmatter || {});
-  // Unique node key so sibling tasks in the global cohort don't collide.
-  spec.nodeKey = specBasename(row);
-  const fm = row.frontmatter || {};
-  spec.type = typeof fm.type === 'string' ? fm.type : undefined;
-  if (spec.type === 'milestone') {
-    const epics = Array.isArray(fm.epics) ? fm.epics : [];
-    spec.epicsCount = epics.length;
-  }
-  // Diagnoses carry `severity:`, not the `kind:` tier vocab — derive the tier so
-  // computeOrder ranks them by severity instead of sorting them last (no kind).
-  if (spec.type === 'diagnose' && !spec.kind) {
-    const sev = typeof fm.severity === 'string' ? fm.severity.trim().toLowerCase() : '';
-    spec.kind = DIAGNOSE_SEVERITY_TIER[sev] || 'feature';
-  }
-  spec.milestone = canonicalizeSpecRef(fm.milestone) || undefined;
-  spec.parent = canonicalizeSpecRef(fm.parent) || undefined;
-  // [[HS-67F4-DIAG]] Stage 6.7 — position in the parent's declared child array.
-  if (declaredOrderByChild) {
-    const idx = declaredOrderByChild.get(canonicalizeSpecRef(row.id) || row.id);
-    if (idx != null) spec.declaredOrderIndex = idx;
-  }
-  // Stage 2.7 blast-radius band ([[encoding-foundational-and-blast-radius-p]]).
-  spec.blast_radius = typeof fm.blast_radius === 'string' ? fm.blast_radius : undefined;
-  // Pillar-tier inheritance ([[encoding-foundational-and-blast-radius-p]]): an
-  // epic with no explicit `kind:` inherits its pillar's `library_tier` tier, so
-  // foundation-pillar work (e.g. HS-PILR-architecture) auto-sorts foundation.
-  // Explicit `kind:` always wins; inert when no map is supplied.
-  if (!spec.kind && pillarTierById) {
-    const pillar = canonicalizeSpecRef(fm.pillar);
-    const inherited = pillar ? pillarTierById.get(pillar) : undefined;
-    if (inherited) spec.kind = inherited;
-  }
-  return spec;
-}
-
-// Mirror of `spex-console/src/lib/scheduler/pipeline.ts:partitionForScheduler`.
-// Drops epicless milestones + non-canonical-id duplicates. Pure — same input,
-// same output, same byte-equivalence with console.
-export function partitionSchedulerInput(specs) {
-  const afterMilestones = [];
-  for (const spec of specs) {
-    if (spec.type === 'milestone' && (spec.epicsCount ?? 0) === 0) continue;
-    afterMilestones.push(spec);
-  }
-  const kept = [];
-  const seen = new Set();
-  for (const spec of afterMilestones) {
-    // Dedup on the unique nodeKey (not the shared family-key `id:`) so legit
-    // sibling tasks both survive ([[HS-K5GQ-DIAG]]); byte-identical when unset.
-    const key = spec.nodeKey ?? spec.id;
-    if (!seen.has(key)) {
-      seen.add(key);
-      kept.push(spec);
-      continue;
-    }
-    if (isCanonicalSpecId(spec.id)) kept.push(spec);
-    // Non-canonical dup → drop (parity with console; vendor doesn't surface
-    // SkippedDuplicate to the agent, only the picked head).
-  }
-  return kept;
-}
-
-// Mirror of `spex-console/src/lib/scheduler/active-milestone.ts:getActiveMilestones`.
-export function getActiveMilestoneIds(specs, manifestOrder) {
-  const milestones = specs.filter((s) => s.type === 'milestone');
-  if (milestones.length === 0) return [];
-  const inProgressEpicMilestones = new Set();
-  for (const s of specs) {
-    if (s.type !== 'epic' || s.status !== 'in_progress' || !s.milestone) continue;
-    inProgressEpicMilestones.add(s.milestone);
-  }
-  const active = new Set();
-  for (const m of milestones) {
-    if (m.status === 'in_progress') active.add(m.id);
-    else if (m.status === 'open' && inProgressEpicMilestones.has(m.id)) active.add(m.id);
-  }
-  if (active.size === 0) return [];
-  if (manifestOrder && manifestOrder.length > 0) {
-    const normalized = manifestOrder.map((id) => normalizeDependsOnId(id));
-    const out = [];
-    const seen = new Set();
-    for (const id of normalized) {
-      if (active.has(id) && !seen.has(id)) {
-        out.push(id);
-        seen.add(id);
-      }
-    }
-    const leftover = [...active].filter((id) => !seen.has(id)).sort();
-    return [...out, ...leftover];
-  }
-  return [...active].sort();
-}
-
-// Mirror of `spex-console/src/lib/scheduler/active-milestone.ts:scopeToActiveMilestones`.
-// Drops epics whose milestone is not active (unless pinned), and tasks whose
-// epic-parent was dropped (unless pinned). Inert when no active milestone exists.
-export function scopeToActiveMilestones(specs, opts = {}) {
-  const activeMs = opts.activeMilestones ?? new Set();
-  const pinned = opts.pinnedIds ?? new Set();
-  if (activeMs.size === 0) return [...specs];
-  const keptEpicIds = new Set();
-  for (const s of specs) {
-    if (s.type !== 'epic') continue;
-    if (pinned.has(s.id)) {
-      keptEpicIds.add(s.id);
-      continue;
-    }
-    if (s.milestone && activeMs.has(s.milestone)) keptEpicIds.add(s.id);
-  }
-  const out = [];
-  for (const s of specs) {
-    if (s.type === 'epic') {
-      if (keptEpicIds.has(s.id)) out.push(s);
-      continue;
-    }
-    if (s.type === 'task') {
-      if (pinned.has(s.id)) { out.push(s); continue; }
-      if (s.milestone && activeMs.has(s.milestone)) { out.push(s); continue; }
-      if (s.parent && keptEpicIds.has(s.parent)) out.push(s);
-      continue;
-    }
-    out.push(s);
-  }
-  return out;
-}
-
-// Mirror of `spex-console/src/lib/vault.ts:getPinnedSpecIdForScheduler`. The pin
-// id is the input to `applyPin` so vendor and console float the same head.
-export function getPinnedSpecIdFromFocus(focus) {
-  if (!focus) return null;
-  if (focus.pin && typeof focus.pin.spec_id === 'string' && focus.pin.spec_id) {
-    return focus.pin.spec_id;
-  }
-  if (typeof focus.spec_path === 'string' && focus.spec_path) {
-    const base = focus.spec_path.replace(/^.*[/\\]/, '').replace(/\.md$/i, '');
-    const m = base.match(
-      /^(HS-(?:TASK|EPIC|MIL|ROADMAP|RES|CAP|REV|IDEA|FLOW|PROTO)-(?:\d+|[A-Z0-9]+))/,
-    );
-    if (m) return m[1];
-  }
-  return null;
-}
-
-// Pick the first scheduler-ordered id that belongs to `candidateIds`. Returns
-// null when none match. The candidates may include refs (basenames /
-// wikilinks); they are canonicalized before lookup so a milestone's `epics:`
-// entry written as `[[HS-EPIC-CNVG-…]]` resolves against the canonical id the
-// scheduler emits.
-export function pickFromSchedulerOrder(scheduler, candidateRefs) {
-  if (!scheduler?.order?.length) return null;
-  const set = new Set();
-  for (const ref of candidateRefs ?? []) {
-    const id = canonicalizeSpecRef(ref);
-    if (id) set.add(id);
-  }
-  if (set.size === 0) return null;
-  for (const entry of scheduler.order) {
-    if (set.has(entry.id)) return entry.id;
-  }
-  return null;
-}
-
-export function sortCandidateEpicsBySchedulerOrder(candidates, vaultRoot) {
-  if (!Array.isArray(candidates) || candidates.length === 0) return candidates;
-  const cohort = [];
-  const skipped = [];
-  for (const c of candidates) {
-    if (isSchedulerExcluded(c.status, c.canonical)) {
-      skipped.push(c);
-      continue;
-    }
-    const id = canonicalizeSpecRef(c.id) || c.id;
-    const epic = loadTask(vaultRoot, id);
-    if (!epic) {
-      skipped.push(c);
-      continue;
-    }
-    const spec = frontmatterToSchedulerSpec(epic.id, epic.frontmatter || {});
-    // [[HS-67F4-DIAG]] — stamp the epic's position in the milestone's declared
-    // `epics:` order (candidates arrive in that order) + the shared milestone
-    // parent, so the Stage 6.7 tiebreak keeps the seed pick in the owner's
-    // authored sequence when the epics are otherwise tied on every real signal.
-    spec.milestone = canonicalizeSpecRef(epic.frontmatter?.milestone) || '__milestone_epics__';
-    spec.declaredOrderIndex = cohort.length;
-    cohort.push({ candidate: c, spec });
-  }
-  if (cohort.length === 0) return candidates;
-  let order;
-  try {
-    order = schedulerComputeOrder(cohort.map((e) => e.spec));
-  } catch {
-    return candidates;
-  }
-  const byId = new Map(cohort.map((e) => [e.spec.id, e.candidate]));
-  const sorted = [];
-  for (const entry of order) {
-    const c = byId.get(entry.id);
-    if (c) sorted.push(c);
-  }
-  return [...sorted, ...skipped];
-}
-
-// [[HS-TASK-JHIA]] — reorder candidate epics by the FROZEN milestone snapshot
-// order (Neon-sourced via `GET /api/scheduler/milestone-snapshot/:id`), restoring
-// the freeze parity `/hs-next` lost when the file-read seam was removed
-// (2026-06-10). Epics present in the frozen order render in that order; epics
-// absent from it (filed after the snapshot was written, or an empty snapshot)
-// keep their incoming relative order at the tail so new work appends and never
-// reshuffles the frozen rows. Both sides are canonicalized to bare ids so a
-// frozen bare id matches a full-slug candidate ([[scheduler-cache-id-form-parity]]).
-export function applyFrozenEpicOrder(candidates, frozenEpicOrderIds) {
-  if (!Array.isArray(candidates) || candidates.length === 0) return candidates;
-  if (!Array.isArray(frozenEpicOrderIds) || frozenEpicOrderIds.length === 0) return candidates;
-  const pos = new Map();
-  frozenEpicOrderIds.forEach((id, idx) => {
-    const key = canonicalizeSpecRef(id) || id;
-    if (key && !pos.has(key)) pos.set(key, idx);
-  });
-  const known = [];
-  const unknown = [];
-  for (const c of candidates) {
-    const key = canonicalizeSpecRef(c.id) || c.id;
-    if (pos.has(key)) known.push(c);
-    else unknown.push(c);
-  }
-  known.sort((a, b) => {
-    const ka = canonicalizeSpecRef(a.id) || a.id;
-    const kb = canonicalizeSpecRef(b.id) || b.id;
-    return pos.get(ka) - pos.get(kb);
-  });
-  return [...known, ...unknown];
-}
-
-// Build the global scheduler cohort + order for `/hs-next`. Mirrors the path
-// `/api/roadmap/[id]` walks: status filter → active-milestone scope → partition
-// → computeOrder → applyPin. Returns { order, byId, pinnedSpecId, error? }.
-// Errors (cycle, duplicate id) degrade gracefully — caller can fall back to
-// the legacy manifest traversal so a single bad-frontmatter day doesn't break
-// /hs-next.
-// `precomputed.schedulerRows` / `precomputed.pillarTierById` ([[HS-DJWP-MCPC-TASK]]):
-// when supplied, used INSTEAD of the disk loaders below — `handleNextOnDeck`
-// pre-fetches both over HTTP in cloud reliance and threads them in via
-// `resolveNextOnDeck`'s options, so this function never calls
-// `loadVaultSpecsForScheduler`/`loadPillarTierMap` in that tier. Omitted (the
-// default on every OTHER call site) preserves today's disk-only behavior
-// byte-for-byte.
-export function computeGlobalSchedulerOrder(vaultRoot, focus, precomputed = {}) {
-  try {
-    const rows = precomputed.schedulerRows ?? loadVaultSpecsForScheduler(vaultRoot);
-    const pillarTierById = precomputed.pillarTierById ?? loadPillarTierMap(vaultRoot);
-    const declaredOrderByChild = buildDeclaredOrderByChild(rows);
-    const allSchedulerSpecs = rows.map((r) =>
-      vaultRowToSchedulerSpec(r, pillarTierById, declaredOrderByChild),
-    );
-    const activeMilestones = new Set(getActiveMilestoneIds(allSchedulerSpecs));
-    // Tasks + epics + diagnoses with a scheduler-relevant status feed computeOrder
-    // (mirrors the `active` filter in console's roadmap + inspect routes).
-    // Diagnoses ([[HS-MIL-BFIX]]) are milestone-less leaves; `scopeToActiveMilestones`
-    // passes non-epic/task types through its catch-all, so a standalone bug bypasses
-    // milestone scoping and competes in the global on-deck queue by `severity:`.
-    const active = allSchedulerSpecs.filter(
-      (s) => (s.type === 'task' || s.type === 'epic' || s.type === 'diagnose')
-        && !isSchedulerExcluded(s.status, s.canonical),
-    );
-    const pinnedSpecId = getPinnedSpecIdFromFocus(focus);
-    const pinnedIds = new Set();
-    if (pinnedSpecId) pinnedIds.add(pinnedSpecId);
-    const scoped = scopeToActiveMilestones(active, { activeMilestones, pinnedIds });
-    const partitioned = partitionSchedulerInput(scoped);
-    const base = schedulerComputeOrder(partitioned);
-    const order = pinnedSpecId
-      ? schedulerApplyPin(base, pinnedSpecId, partitioned)
-      : base;
-    // Dual-keyed ([[HS-K5GQ-DIAG]]): every row is reachable by its family-key
-    // `id:` (back-compat for family-grain consumers) AND by its unique basename
-    // (`order[].nodeKey`), so a sibling-task head resolves to the RIGHT row via
-    // `byId.get(entry.nodeKey)` instead of an ambiguous family-key lookup.
-    const byId = new Map();
-    for (const r of rows) {
-      byId.set(r.id, r);
-      byId.set(specBasename(r), r);
-    }
-    return { order, byId, pinnedSpecId };
-  } catch (err) {
-    return { error: err, order: [], byId: new Map(), pinnedSpecId: null };
-  }
-}
-
-// Bind the pure resolver helpers to this server's vault-aware `loadTask`.
-// The resolver lives in `./blocker-resolver.mjs` — it's unit-testable with a
-// synthetic loader and surfaces a discriminated state per
-// [[depends-on-canonical-blocker-field]] for the focus-override caller below.
-// `mvp_mode.review_backlog_never_blocks` — opt-OUT only, and the default holds
-// with MVP mode OFF too: `in_review` / `review_pending` mean build-complete at
-// every grain, so a review backlog never gates the next claim (owner ruling
-// 2026-08-14; mirrors the console's `PREREQ_SATISFIED_STATUSES`).
-export function blockerOpts(vaultRoot) {
-  const mvp = vaultRoot ? readMvpModeState(vaultRoot) : null;
-  return { reviewBacklogNeverBlocks: mvp?.review_backlog_never_blocks !== false };
-}
-
-export function computeUnmetBlockers(vaultRoot, task) {
-  return computeUnmetBlockersImpl((id) => loadTask(vaultRoot, id), task, blockerOpts(vaultRoot));
-}
-
-export function resolveEpicChildTask(vaultRoot, epicFrontmatter) {
-  return resolveEpicChildTaskImpl(
-    (id) => loadTask(vaultRoot, id),
-    epicFrontmatter,
-    blockerOpts(vaultRoot),
-  );
-}
-
-// [[HS-TASK-CLIM]] — scheduler-order epic-drill. Picks the seed child by
-// running computeOrder LOCALLY over the epic's actionable children, mirroring
-// console's `pickMilestoneOnDeck` descent pattern. Falls back to the legacy
-// manifest-order resolveEpicChildTask when no children resolve, when no child
-// is actionable (boundary states epic_implementation_complete / epic_done /
-// epic_empty still go through the legacy resolver), or when the local
-// computeOrder throws on a cycle. This deliberately supersedes the
-// manifest-order rule from
-// [[HS-DEC-epic-drill-resolver-manifest-order-and-blocker-filter]] — the
-// "blocker filter" half of that decision still holds (blockers surfaced in
-// the banner via computeUnmetBlockers), but the ordering authority moves to
-// the scheduler so vendor and console cannot disagree on the seed.
-export function resolveEpicChildTaskViaScheduler(vaultRoot, epicFrontmatter) {
-  const legacy = () => resolveEpicChildTask(vaultRoot, epicFrontmatter);
-  const children = epicFrontmatter?.children;
-  if (!Array.isArray(children) || children.length === 0) return { state: 'epic_empty' };
-
-  const actionable = [];
-  for (const raw of children) {
-    const target = wikilinkTarget(raw);
-    if (!target) continue;
-    const task = loadTask(vaultRoot, target);
-    if (!task) continue;
-    const status = task.status || task.frontmatter?.status;
-    if (status === 'open' || status === 'in_progress') {
-      actionable.push(task);
-    }
-  }
-  if (actionable.length === 0) return legacy(); // boundary states stay with legacy
-
-  // Key the LOCAL cohort on each child's unique basename ([[HS-K5GQ-DIAG]]).
-  // Sibling tasks under one epic legitimately share a family-key `id:` (e.g. all
-  // `id: HS-W6AD-TASK`); without a unique nodeKey `schedulerComputeOrder` throws
-  // DuplicateIdError, which — rethrown below — blanked What's Next
-  // (SUBPROCESS_EMPTY). The pick is resolved back by that same basename.
-  let pickedNodeKey;
-  try {
-    // [[HS-67F4-DIAG]] — stamp each child's position in the epic's declared
-    // `children:` order (`actionable` preserves it) + the shared epic parent, so
-    // the Stage 6.7 tiebreak keeps the seed task in the owner's authored sequence
-    // when the children are otherwise tied on every real signal.
-    const childParentKey =
-      canonicalizeSpecRef(epicFrontmatter?.id) || epicFrontmatter?.id || '__epic_children__';
-    const cohort = actionable.map((t, i) => ({
-      ...frontmatterToSchedulerSpec(t.id, t.frontmatter || {}),
-      nodeKey: specBasename(t),
-      parent: childParentKey,
-      declaredOrderIndex: i,
-    }));
-    const order = schedulerComputeOrder(cohort);
-    pickedNodeKey = order[0]?.nodeKey;
-  } catch (err) {
-    if (err instanceof SchedulerCycleError) return legacy();
-    throw err;
-  }
-  if (!pickedNodeKey) return legacy();
-  const picked = actionable.find((t) => specBasename(t) === pickedNodeKey);
-  if (!picked) return legacy();
-
-  const { blockers, severity } = computeUnmetBlockers(vaultRoot, picked);
-  const status = picked.status || picked.frontmatter?.status;
-  let state;
-  if (status === 'in_progress') state = 'resume';
-  else if (severity === 'none') state = 'ready';
-  else if (severity === 'soft_review') state = 'soft_review';
-  else state = 'hard_blocked';
-  return { state, task: picked, blockers, severity };
-}
-
-export function resolveMilestoneState(vaultRoot, milestoneFrontmatter) {
-  return resolveMilestoneStateImpl(
-    (id) => loadTask(vaultRoot, id),
-    milestoneFrontmatter,
-  );
-}
-
-/**
- * Build the structured `/hs-next` response when focus pins a milestone whose
- * `epics:` array is empty (or all entries fail to resolve). Shape matches
- * [[HS-TASK-SKEM-scheduler-skip-epicless-milestones]] §"Structured /hs-next
- * response": `status: "needs_breakdown"`, `suggested_actions[]`, and
- * `next_eligible_spec: null`. The console UI consumer is
- * [[HS-EPIC-MNBD-milestone-needs-breakdown-awareness]].
- */
-export function buildMilestoneNeedsBreakdownResponse({
-  milestoneId,
-  milestoneName,
-  focusSpecPath,
-  roadmapId,
-  reason,
-}) {
-  const suggestedActions = [
-    {
-      action: 'file_epic',
-      cli: `hs epic new --milestone ${milestoneId}`,
-      mcp_tool: 'heyspex_file_epic',
-    },
-    { action: 'unpin', cli: 'hs focus clear' },
-  ];
-
-  const promptLines = [
-    `## needs_breakdown — ${milestoneId}`,
-    '',
-    `**Milestone:** ${milestoneName}`,
-    `**Roadmap:** ${roadmapId}`,
-    '',
-    `${reason}`,
-    '',
-    '### Suggested next moves',
-    '',
-    `1. **File a child epic** to break this milestone down: \`${suggestedActions[0].cli}\` (MCP: \`${suggestedActions[0].mcp_tool}\`).`,
-    `2. **Unpin** if this milestone was pinned by mistake: \`${suggestedActions[1].cli}\`.`,
-    '',
-    `_Pinned via \`.heyspex/focus.yaml\` (\`${focusSpecPath}\`). Milestone has no schedulable work yet — surfacing breakdown choices instead of a body excerpt._`,
-  ];
-
-  return {
-    status: 'needs_breakdown',
-    kind: 'milestone',
-    spec_id: milestoneId,
-    spec_title: milestoneName,
-    reason,
-    suggested_actions: suggestedActions,
-    next_eligible_spec: null,
-    source_kind: 'milestone_needs_breakdown',
-    roadmap_id: roadmapId,
-    spec_path: focusSpecPath,
-    prompt_markdown: promptLines.join('\n'),
-    next_action_hint: 'file_epic',
-  };
-}
-
-/**
- * Build the `/hs-next` response when focus pins a milestone with a populated
- * `epics:` array ([[HS-TASK-K7L9]] of [[HS-EPIC-M2J3]] §5). The milestone is
- * the *scope* of focus; the deferral picks the next actionable child epic
- * (in_progress first, else first non-closed, else first listed) so the agent
- * has a concrete claim target. Multiple equally-actionable epics surface in
- * `candidate_epics` so the agent can ask the human which to start.
- *
- * Mirrors `buildMilestoneNeedsBreakdownResponse` shape: the surface
- * structurally distinguishes "pick a child to start" (this) from "file a child
- * to start" (needs_breakdown) so the console can render either intent without
- * grain-aware fork code.
- */
-export function buildMilestoneDeferToSeedEpicResponse({
-  milestoneId,
-  milestoneName,
-  milestoneBody,
-  focusSpecPath,
-  roadmapId,
-  candidateEpics,
-}) {
-  // Pick the scheduler's position-0 over the actionable subset. `candidateEpics`
-  // has already been sorted by `sortCandidateEpicsBySchedulerOrder`, which
-  // appends SCHEDULER_EXCLUDED_STATUSES items to the tail; falling through to
-  // the first non-terminal preserves the scheduler's pick when the head is
-  // actionable, and only reaches the tail if every actionable epic was skipped
-  // during cohort load. This is the parity contract with console's On Deck —
-  // do NOT re-apply a manifest-style "first in_progress" filter here ([[HS-TASK-CLIM]]).
-  const SEED_TERMINAL = new Set(['closed', 'shipped', 'archived', 'hibernated', 'in_review']);
-  const seed =
-    candidateEpics.find((e) => !SEED_TERMINAL.has(e.status)) || candidateEpics[0];
-  const multiple = candidateEpics.length > 1;
-  const promptLines = [
-    `## focus_override_milestone_drill — ${milestoneId}`,
-    '',
-    `**Milestone:** ${milestoneName}`,
-    `**Roadmap:** ${roadmapId}`,
-    '',
-    `_Pinned via \`.heyspex/focus.yaml\`. Strategic focus is at the milestone grain — pick a child epic to start work below._`,
-    '',
-    '### Defer to seed epic',
-    '',
-    multiple
-      ? `**Seed epic candidates** (${candidateEpics.length}):`
-      : `**Seed epic:** \`${seed.id}\` (\`status: ${seed.status}\`).`,
-    '',
-    ...candidateEpics.map(
-      (e) =>
-        `- \`${e.id}\` · status: \`${e.status}\`${e.id === seed.id ? ' ← suggested next' : ''}`,
-    ),
-    '',
-    multiple
-      ? `Ask the human which to claim, or default to \`${seed.id}\` (first by scheduler order).`
-      : `Run \`/hs-next ${seed.id}\` to drill into the seed epic and claim its next task.`,
-    '',
-    '---',
-    '',
-    '### Milestone body excerpt',
-    '',
-    milestoneBody.length > 2000
-      ? `${milestoneBody.slice(0, 2000)}\n\n[... truncated ...]`
-      : milestoneBody,
-    '',
-    '---',
-    '',
-    `_Spec path: \`${focusSpecPath}\`_`,
-  ];
-
-  return {
-    spec_id: milestoneId,
-    title: milestoneName,
-    status: 'in_progress',
-    source_kind: 'focus_override_milestone_drill',
-    kind: 'milestone',
-    roadmap_id: roadmapId,
-    spec_path: focusSpecPath,
-    prompt_markdown: promptLines.join('\n'),
-    pinned_milestone: { id: milestoneId, name: milestoneName, spec_path: focusSpecPath },
-    candidate_epics: candidateEpics,
-    seed_epic: seed,
-    next_action_hint: multiple ? 'pick_epic' : 'drill_epic',
-  };
-}
-
-export const STALE_FOCUS_STATUSES = new Set(['in_review', 'closed', 'hibernated']);
-
-/**
- * Compute the scheduler explanation trace for `spec` relative to `cohort`
- * — i.e. the same set the spec was picked from. For epic-drill that's the
- * epic's children; for manifest paths that's the phase's open tasks; for
- * direct lookup the cohort is just the spec itself (layer 0, no tiebreaker
- * pressure). Returns `null` if computeOrder fails (cycle) — the caller still
- * surfaces the spec; explanation absence is non-fatal so /hs-next doesn't
- * regress on a bad-frontmatter day.
- *
- * `cohortSpecs` items must be `{ id, frontmatter }` shaped (raw vault loads).
- * The function looks up `pickedSpecId` after computing order and returns the
- * full ExplanationTrace, which always cites tier (stage 2), topological
- * layer (stage 1), and at least one tiebreaker (stage 7 or 8) per AC #1 of
- * [[HS-TASK-C2ZQ]].
- */
-/**
- * Load an epic's child tasks into the `{ id, frontmatter }` shape
- * `buildOnDeckExplanation` expects. Skips children that don't resolve to a
- * vault file — same tolerance as `resolveEpicChildTask`.
- */
-export function loadEpicChildrenCohort(vaultRoot, epicFrontmatter) {
-  const children = epicFrontmatter?.children;
-  if (!Array.isArray(children)) return [];
-  const out = [];
-  for (const raw of children) {
-    const target = wikilinkTarget(raw);
-    if (!target) continue;
-    const task = loadTask(vaultRoot, target);
-    if (!task) continue;
-    out.push({ id: task.id, frontmatter: task.frontmatter || {} });
-  }
-  return out;
-}
-
-/**
- * Load all open tasks declared in a roadmap phase's `tasks:` list into the
- * `{ id, frontmatter }` shape `buildOnDeckExplanation` expects. Initiative
- * refs (nested roadmaps) are not flattened — they're rare in scheduled
- * phases and the picked spec would always be the first open of its phase.
- */
-export function loadPhaseOpenCohort(vaultRoot, phase) {
-  const tasks = phase?.tasks;
-  if (!Array.isArray(tasks)) return [];
-  const out = [];
-  for (const raw of tasks) {
-    if (isInitiative(raw)) continue;
-    const task = loadTask(vaultRoot, raw);
-    if (!task) continue;
-    if (task.status !== 'open') continue;
-    out.push({ id: task.id, frontmatter: task.frontmatter || {} });
-  }
-  return out;
-}
-
-/**
- * Hysteresis anchor for the stateless MCP ([[HS-TASK-MI65]]). Reads the
- * cohort's prior relative order out of the console-written scheduler cache
- * (`<vaultRoot>/.heyspex/scheduler-cache.json`) so `/hs-next` stabilizes the
- * same way the console Scheduler surface does. Best-effort: any missing file,
- * parse error, or schema mismatch returns undefined → hysteresis inert, order
- * byte-identical to a priorless run. Returns cohort ids in cached order.
- */
-export function readSchedulerCachePriorOrder(vaultRoot, cohortIds) {
-  if (!vaultRoot) return undefined;
-  try {
-    const cachePath = join(vaultRoot, '.heyspex', 'scheduler-cache.json');
-    if (!existsSync(cachePath)) return undefined;
-    const parsed = JSON.parse(readFileSync(cachePath, 'utf-8'));
-    const order = Array.isArray(parsed?.order) ? parsed.order : null;
-    if (!order || order.length === 0) return undefined;
-    const inCohort = new Set(cohortIds);
-    const priorOrder = order
-      .map((o) => o?.id)
-      .filter((id) => typeof id === 'string' && inCohort.has(id));
-    return priorOrder.length > 0 ? priorOrder : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-/**
- * Full global scheduler order (bare ids, global rank) from the console-written
- * cache. Used to converge the claim target onto scheduler output so /hs-next's
- * `claim_target` agrees with its own `seed_epic` and the console On Deck
- * ([[HS-EPIC-CNVG]]). Best-effort: any miss returns `[]` →
- * `computeClaimTarget` falls back to declared (`epics:`/`children:`) order.
- */
-export function readSchedulerCacheOrderIds(vaultRoot) {
-  if (!vaultRoot) return [];
-  try {
-    const cachePath = join(vaultRoot, '.heyspex', 'scheduler-cache.json');
-    if (!existsSync(cachePath)) return [];
-    const parsed = JSON.parse(readFileSync(cachePath, 'utf-8'));
-    const order = Array.isArray(parsed?.order) ? parsed.order : null;
-    if (!order) return [];
-    return order.map((o) => o?.id).filter((id) => typeof id === 'string');
-  } catch {
-    return [];
-  }
-}
-
-export function buildOnDeckExplanation(pickedSpecId, cohortSpecs, vaultRoot) {
-  if (!pickedSpecId) return null;
-  const cohort = Array.isArray(cohortSpecs) && cohortSpecs.length > 0
-    ? cohortSpecs
-    : [{ id: pickedSpecId, frontmatter: {} }];
-  const hasPicked = cohort.some((c) => c.id === pickedSpecId);
-  const effective = hasPicked
-    ? cohort
-    : [...cohort, { id: pickedSpecId, frontmatter: {} }];
-  const schedulerSpecs = effective.map((c) =>
-    frontmatterToSchedulerSpec(c.id, c.frontmatter || {}),
-  );
-  const priorOrder = readSchedulerCachePriorOrder(
-    vaultRoot,
-    schedulerSpecs.map((s) => s.id),
-  );
-  try {
-    const order = schedulerComputeOrder(schedulerSpecs, { priorOrder });
-    const hit = order.find((o) => o.id === pickedSpecId);
-    return hit?.explanation ?? null;
-  } catch (err) {
-    // Degenerate fallback so a cycle in unrelated cohort entries doesn't
-    // erase the picked spec's row-level signal.
-    if (err instanceof SchedulerCycleError) {
-      const picked = schedulerSpecs.find((s) => s.id === pickedSpecId);
-      if (picked) return schedulerBuildExplanation(picked, 0);
-    }
-    return null;
-  }
-}
-
-/** Attach the one-line why-now legibility field alongside the raw explanation trace. */
-export function attachWhyNowFields(response, explanation, pinnedSpecId) {
-  if (!response || !explanation) return;
-  response.explanation = explanation;
-  const pinned =
-    typeof pinnedSpecId === 'string' &&
-    typeof response.spec_id === 'string' &&
-    response.spec_id === pinnedSpecId;
-  response.why_now = schedulerBuildWhyNow(explanation, { pinned });
-}
-
-export function resolveNextOnDeck(vaultRoot, roadmapId, options = {}) {
-  const {
-    ignoreFocus = false,
-    includeHorizon = false,
-    neonPinSpecId,
-    neonSelectionSpecPath,
-    frozenEpicOrder,
-    // [[HS-DJWP-MCPC-TASK]]: pre-fetched over HTTP by `handleNextOnDeck` when
-    // cloud-reliant; undefined on every other (disk-reliant) call site, which
-    // falls through to computeGlobalSchedulerOrder's own disk loaders.
-    schedulerRows,
-    pillarTierById,
-  } = options;
-
-  // [[HS-TASK-CLIM]] — global scheduler order, computed once per call. The pin
-  // (Neon `focus_pin` precedence #1 via `neonPinSpecId`, else the file's layer-2
-  // `spec_path`) is fed into applyPin so vendor /hs-next and the console surfaces
-  // (`/api/scheduler/inspect`, `/api/roadmap/[id]`, `/api/focus`) agree on
-  // position-0. Loaded here even when `ignoreFocus: true` is set so the no-pin
-  // path can still consult the scheduler for the head pick.
-  const focus = !ignoreFocus
-    ? loadFocusOverride(vaultRoot, { neonPinSpecId, neonSelectionSpecPath })
-    : null;
-  const scheduler = computeGlobalSchedulerOrder(vaultRoot, focus, { schedulerRows, pillarTierById });
-
-  let staleFocusPin = null;
-
-  const decorate = (response) => {
-    if (!staleFocusPin || !response) return response;
-    response.stale_focus_pin = staleFocusPin;
-    const banner = `> ⚠️ **Stale focus pin ignored:** \`${staleFocusPin.spec_id}\` is \`status: ${staleFocusPin.status}\` (non-actionable). Clear or repoint \`.heyspex/focus.yaml\` — falling through to manifest traversal.\n\n`;
-    if (typeof response.prompt_markdown === 'string') {
-      response.prompt_markdown = banner + response.prompt_markdown;
-    } else if (typeof response.message === 'string') {
-      response.message = `${response.message}. Also: stale focus pin ${staleFocusPin.spec_id} (${staleFocusPin.status}) was ignored — clear or repoint .heyspex/focus.yaml.`;
-    }
-    return response;
-  };
-
-  // Check focus override first. The focus.yaml pin is the canonical
-  // "on deck" signal — it must always win when present (matches the console
-  // On Deck surface). If the focus spec has a NEXT STEP block we use it
-  // verbatim (source_kind: self_perpetuating); otherwise we return a body
-  // excerpt so /hs-next still surfaces the pinned spec instead of drifting
-  // back to manifest order.
-  //
-  // Exception: if the pinned spec's status is non-actionable
-  // (in_review / closed / hibernated), the pin is stale — capture a warning
-  // and fall through to manifest traversal so /hs-next never returns a spec
-  // the agent cannot work on.
-  if (!ignoreFocus) {
-    if (focus && focus.spec_path) {
-      const focusSpec = loadSpec(vaultRoot, focus.spec_path);
-      if (focusSpec && STALE_FOCUS_STATUSES.has(focusSpec.frontmatter.status)) {
-        staleFocusPin = {
-          spec_id: focusSpec.frontmatter.id || focus.spec_path,
-          spec_path: focus.spec_path,
-          status: focusSpec.frontmatter.status,
-          reason: focus.reason || null,
-        };
-      } else if (focusSpec) {
-        // If the pin is a milestone (kind: milestone or type: milestone), the
-        // milestone is the *scope* of focus — the actual work is a child
-        // epic, which itself walks to a child task. Today this resolver only
-        // handles the `needs_breakdown` case (empty/unresolved epics: array);
-        // drilling into a populated milestone is out of scope for SKEM and
-        // falls through to the body-excerpt branch. See
-        // [[HS-TASK-SKEM-scheduler-skip-epicless-milestones]].
-        const isMilestonePin =
-          focus.kind === 'milestone' ||
-          focusSpec.frontmatter.type === 'milestone';
-        if (isMilestonePin) {
-          const milestoneId = focusSpec.frontmatter.id || focus.spec_path;
-          const milestoneName = focusSpec.frontmatter.name || 'Pinned milestone';
-          const milestoneResult = resolveMilestoneState(
-            vaultRoot,
-            focusSpec.frontmatter,
-          );
-          if (milestoneResult.state === 'milestone_needs_breakdown') {
-            return buildMilestoneNeedsBreakdownResponse({
-              milestoneId,
-              milestoneName,
-              focusSpecPath: focus.spec_path,
-              roadmapId,
-              reason: 'Milestone has no child epics yet.',
-            });
-          }
-          if (milestoneResult.state === 'milestone_empty_after_filter') {
-            return buildMilestoneNeedsBreakdownResponse({
-              milestoneId,
-              milestoneName,
-              focusSpecPath: focus.spec_path,
-              roadmapId,
-              reason:
-                'Milestone declares child epics, but none of them resolve to a spec in the vault — breakdown still pending.',
-            });
-          }
-          if (milestoneResult.state === 'milestone_has_epics') {
-            // [[HS-TASK-K7L9]] of [[HS-EPIC-M2J3]] §5 — milestone is the
-            // *scope* of focus; surface the milestone body and defer the
-            // claim path to the seed epic. [[HS-TASK-CLIM]] resorts the
-            // candidate epics by scheduler position so the seed pick agrees
-            // with console's What's Next column. Scheduler errors / cohort
-            // misses degrade gracefully: epics absent from the order keep
-            // their manifest position (sorted after scheduler-ranked ones).
-            // [[HS-EPIC-FRZE]] / [[HS-TASK-JHIA]]: the frozen milestone snapshot
-            // lives in Neon and this cli has no Neon client, so the frozen epic
-            // order is fetched over HTTP at the async handler boundary
-            // (`injectFrozenMilestoneOrder` → `frozenEpicOrder`). When present we
-            // honor the freeze — the seed epic agrees with the console What's Next
-            // / On Deck surfaces. When absent (flag off, no snapshot, or console
-            // unreachable) we degrade to LIVE scheduler order, exactly as before.
-            const candidateEpics =
-              Array.isArray(frozenEpicOrder) && frozenEpicOrder.length > 0
-                ? applyFrozenEpicOrder(milestoneResult.epics, frozenEpicOrder)
-                : sortCandidateEpicsBySchedulerOrder(milestoneResult.epics, vaultRoot);
-            return buildMilestoneDeferToSeedEpicResponse({
-              milestoneId,
-              milestoneName,
-              milestoneBody: focusSpec.body || '',
-              focusSpecPath: focus.spec_path,
-              roadmapId,
-              candidateEpics,
-            });
-          }
-        }
-
-        // If the pin is an epic (kind: epic or type: epic), the epic is the
-        // *scope* of focus — the actual work is a child task. Drill to the
-        // next actionable child (in_progress first, else first open by
-        // priority) and return that task. Falls through to body-excerpt
-        // behavior only if the epic has no actionable child.
-        const isEpicPin =
-          focus.kind === 'epic' || focusSpec.frontmatter.type === 'epic';
-        if (isEpicPin) {
-          // [[HS-TASK-CLIM]] — drill into children in scheduler position order
-          // (local computeOrder over epic.children, mirroring console's
-          // milestone-descent pattern) so the seed task agrees with console's
-          // On Deck pick. Boundary states (epic_implementation_complete /
-          // epic_done / epic_empty) and scheduler errors fall back to the
-          // legacy manifest-order resolver.
-          const childResult = resolveEpicChildTaskViaScheduler(
-            vaultRoot,
-            focusSpec.frontmatter,
-          );
-          const epicId = focusSpec.frontmatter.id || focus.spec_path;
-          const epicName = focusSpec.frontmatter.name || 'Pinned epic';
-
-          if (childResult && childResult.task) {
-            // resume / ready / soft_review / hard_blocked — picked an actionable
-            // child. Build the standard task response, then decorate with the
-            // state-specific banner + machine-readable hint per
-            // [[depends-on-canonical-blocker-field]].
-            const { task: childTask, blockers = [], severity = 'none', state } = childResult;
-            const phase = { id: epicId, name: `Pinned epic — ${epicName}` };
-            const cohort = loadEpicChildrenCohort(vaultRoot, focusSpec.frontmatter);
-            const response = buildTaskResponse(
-              vaultRoot,
-              childTask,
-              phase,
-              roadmapId,
-              'focus_override_epic_drill',
-              cohort,
-            );
-            response.pinned_epic = { id: epicId, name: epicName, spec_path: focus.spec_path };
-            response.child_state = state;
-            response.next_action_hint = mapStateToHint(state);
-            response.blocker_severity = severity;
-            if (blockers.length > 0) {
-              response.unmet_blockers = blockers;
-              const banner = buildBlockerBanner(state, blockers);
-              if (banner) {
-                response.prompt_markdown = response.prompt_markdown.replace(
-                  '\n\n---\n\n',
-                  `${banner}\n\n---\n\n`,
-                );
-              }
-            }
-            return response;
-          }
-
-          if (
-            childResult &&
-            (childResult.state === 'epic_implementation_complete' ||
-              childResult.state === 'epic_done')
-          ) {
-            // Epic boundary — no actionable child. Surface a real prompt with
-            // the three next-move choices (advance focus, /hs-review, ship)
-            // instead of falling through to a confusing body excerpt.
-            const reviewCandidates = childResult.review_candidates || [];
-            const milestoneNextEpics = childResult.milestone_next_epics || [];
-            const promptMarkdown = buildEpicBoundaryPromptMarkdown({
-              state: childResult.state,
-              epicId,
-              epicName,
-              reviewCandidates,
-              milestoneNextEpics,
-              roadmapId,
-              focusSpecPath: focus.spec_path,
-            });
-            return {
-              spec_id: epicId,
-              title: epicName,
-              status: focusSpec.frontmatter.status,
-              source_kind: childResult.state,
-              roadmap_id: roadmapId,
-              prompt_markdown: promptMarkdown,
-              spec_path: focus.spec_path,
-              focus_reason: focus.reason,
-              pinned_epic: { id: epicId, name: epicName, spec_path: focus.spec_path },
-              child_state: childResult.state,
-              next_action_hint: mapStateToHint(childResult.state),
-              review_candidates: reviewCandidates,
-              milestone_next_epics: milestoneNextEpics,
-            };
-          }
-          // epic_empty (or null from legacy code path) — fall through to
-          // body-excerpt behavior below so the agent at least sees the epic
-          // body and can decide what to do.
-        }
-
-        // [[HS-TASK-CLIM]] — task-grain pin parity. When the focused TASK has
-        // unmet open prerequisites, the global scheduler seats those prereqs
-        // ahead of the pin (applyPin is prereq-aware per [[HS-TASK-PINQ]]). The
-        // CLI's #1 must equal computeOrderCached's position-0 — i.e. the
-        // prereq, not the pin — so we re-route to the prereq with a banner.
-        // Epic-empty / milestone fall-throughs and self_perpetuating NEXT STEP
-        // blocks bypass this so a structured pin display isn't replaced with
-        // an unexpected sibling task.
-        const focusType = focus.kind || focusSpec.frontmatter.type;
-        const pinnedId = focusSpec.frontmatter.id
-          || (focus.spec_path
-            ? focus.spec_path.replace(/^.*[/\\]/, '').replace(/\.md$/i, '')
-            : null);
-        if (
-          focusType === 'task'
-          && scheduler
-          && !scheduler.error
-          && scheduler.order?.length
-          && scheduler.order[0].id !== pinnedId
-        ) {
-          const prereqEntry = scheduler.order[0];
-          const prereqId = prereqEntry.id;
-          // Load by the unique nodeKey (basename) so a sibling-task prereq
-          // resolves to the right file, not an ambiguous family-key match
-          // ([[HS-K5GQ-DIAG]]); the banner still shows the family-key id.
-          const prereqTask = loadTask(vaultRoot, prereqEntry.nodeKey ?? prereqId);
-          if (prereqTask) {
-            const phase = {
-              id: pinnedId || 'focus_pin',
-              name: `Pinned task — ${focusSpec.frontmatter.name || pinnedId}`,
-            };
-            const cohort = scheduler.order
-              .slice(0, 25)
-              .map((o) => scheduler.byId.get(o.nodeKey ?? o.id))
-              .filter(Boolean)
-              .map((row) => ({ id: row.id, frontmatter: row.frontmatter }));
-            const response = buildTaskResponse(
-              vaultRoot,
-              prereqTask,
-              phase,
-              roadmapId,
-              'focus_override_prereq',
-              cohort,
-            );
-            const banner =
-              `\n\n> ⚠️ **Pinned \`${pinnedId}\` has unmet prerequisites.** ` +
-              `Scheduler seated \`${prereqId}\` ahead so the pin can land. ` +
-              `Clear this prereq first, or pin a different spec.`;
-            response.prompt_markdown = response.prompt_markdown.replace(
-              '\n\n---\n\n',
-              `${banner}\n\n---\n\n`,
-            );
-            response.pinned_task = {
-              id: pinnedId,
-              name: focusSpec.frontmatter.name || pinnedId,
-              spec_path: focus.spec_path,
-            };
-            response.next_action_hint = 'clear_prereq';
-            return response;
-          }
-        }
-
-        const uiTags = detectUITags(focusSpec.frontmatter);
-        let designContext = null;
-        let designSection = '';
-        if (uiTags.length > 0) {
-          const designDecisions = loadDesignMemories(vaultRoot, uiTags);
-          if (designDecisions.length > 0) {
-            designContext = {
-              triggered_by_tags: uiTags,
-              decisions: designDecisions,
-            };
-            designSection = buildDesignContextSection(designDecisions, uiTags);
-          }
-        }
-
-        const specId = focusSpec.frontmatter.id || focus.spec_path;
-        const title = focusSpec.frontmatter.name || 'Focus Override';
-        const status = focusSpec.frontmatter.status || 'in_progress';
-
-        // [[HS-TASK-G0HF]] the pinned spec always gets a derived execution brief
-        // (the `## NEXT STEP` block, if any, rides in as the Tier-0 override).
-        // The old "no NEXT STEP → body excerpt" disclaimer path is retired.
-        const hasOverride = !!extractNextStepBlock(focusSpec.body);
-        const promptMarkdown = designSection + deriveTaskBrief(vaultRoot, {
-          id: specId,
-          name: title,
-          status,
-          roadmapId,
-          frontmatter: focusSpec.frontmatter,
-          body: focusSpec.body,
-          specPath: focus.spec_path,
-        });
-        const sourceKind = hasOverride ? 'self_perpetuating' : 'focus_override';
-
-        const response = {
-          spec_id: specId,
-          title,
-          status,
-          source_kind: sourceKind,
-          roadmap_id: roadmapId,
-          prompt_markdown: promptMarkdown,
-          spec_path: focus.spec_path,
-          focus_reason: focus.reason,
-        };
-
-        if (designContext) {
-          response.design_context = designContext;
-        }
-
-        const focusExplanation = buildOnDeckExplanation(specId, [
-          { id: specId, frontmatter: focusSpec.frontmatter || {} },
-        ], vaultRoot);
-        attachWhyNowFields(response, focusExplanation, specId);
-
-        return response;
-      }
-    }
-  }
-
-  // Load roadmap
-  const roadmap = loadRoadmap(vaultRoot, roadmapId);
-  if (!roadmap) {
-    return { error: 'ROADMAP_NOT_FOUND', message: `Roadmap ${roadmapId} not found` };
-  }
-
-  const manifest = roadmap.frontmatter.roadmap_manifest;
-  if (!manifest || (!manifest.milestones && !manifest.phases)) {
-    return { error: 'NO_MANIFEST', message: `Roadmap ${roadmapId} has no manifest` };
-  }
-
-  // [[HS-TASK-CLIM]] — when no focus pin steered the resolver and the global
-  // scheduler returned a non-empty order, the head pick comes straight from
-  // position-0 (source_kind: `scheduler_default`). This is the no-pin parity
-  // contract — console's `/api/focus` and `/api/roadmap/[id]` use the same
-  // computeOrderCached call, so the agent and the surfaces stay in sync. The
-  // v3 manifest traversal below is kept as a graceful fallback for scheduler
-  // errors (cycle, duplicate id) and for cohort emptiness (every spec is
-  // closed / in_review / hibernated).
-  if (scheduler && !scheduler.error && scheduler.order?.length > 0) {
-    const head = scheduler.order[0];
-    // Resolve the head by its unique nodeKey (basename) so a sibling-task head
-    // loads the right file, not an ambiguous family-key match ([[HS-K5GQ-DIAG]]).
-    const headKey = head.nodeKey ?? head.id;
-    const row = scheduler.byId.get(headKey);
-    if (row) {
-      const task = loadTask(vaultRoot, headKey);
-      if (task) {
-        const phase = {
-          id: roadmapId,
-          name: `Scheduler default — ${roadmapId}`,
-        };
-        const cohort = scheduler.order
-          .slice(0, 25)
-          .map((o) => scheduler.byId.get(o.nodeKey ?? o.id))
-          .filter(Boolean)
-          .map((r) => ({ id: r.id, frontmatter: r.frontmatter }));
-        return decorate(
-          buildTaskResponse(vaultRoot, task, phase, roadmapId, 'scheduler_default', cohort),
-        );
-      }
-    }
-  }
-
-  // Manifest v3 ([[HS-TASK-JN9H]]): top-level `milestones:` is the
-  // authoritative priority order. Active-milestone scoping ([[HS-TASK-YDUH]])
-  // skips milestones whose status is not in_progress (and that have no
-  // in_progress child epic). Pinned-focus override already happened above —
-  // this branch is only reached when no focus.yaml drill applied and the
-  // scheduler-default pick above could not produce a head (cycle, empty cohort,
-  // or row not loadable).
-  if (Array.isArray(manifest.milestones)) {
-    const picked = pickFromV3Milestones(vaultRoot, manifest.milestones, roadmapId);
-    if (picked && !picked.error) return decorate(picked);
-  } else if (Array.isArray(manifest.phases)) {
-    // v2 backcompat — kept for one release window per [[HS-TASK-JN9H]] §2.
-    for (const phase of manifest.phases) {
-      for (const taskId of phase.tasks || []) {
-        if (isInitiative(taskId)) {
-          const nested = resolveNextOnDeckOpen(vaultRoot, taskId);
-          if (nested && !nested.error) {
-            return decorate({ ...nested, phase_id: phase.id, phase_name: phase.name });
-          }
-        } else {
-          const task = loadTask(vaultRoot, taskId);
-          if (task && task.status === 'open') {
-            const cohort = loadPhaseOpenCohort(vaultRoot, phase);
-            return decorate(buildTaskResponse(vaultRoot, task, phase, roadmapId, 'on_deck', cohort));
-          }
-        }
-      }
-    }
-  }
-
-  // Horizon (if enabled and no scheduled open tasks). Retired in v3 per
-  // [[HS-TASK-JN9H]] §1; kept here only as a v2 backcompat fall-through.
-  if (includeHorizon && manifest.horizon) {
-    const horizonPhase = { id: 'horizon', name: 'Horizon Backlog', tasks: manifest.horizon };
-    const horizonCohort = loadPhaseOpenCohort(vaultRoot, horizonPhase);
-    for (const taskId of manifest.horizon) {
-      const task = loadTask(vaultRoot, taskId);
-      if (task && task.status === 'open') {
-        return decorate(buildTaskResponse(vaultRoot, task, horizonPhase, roadmapId, 'horizon', horizonCohort));
-      }
-    }
-  }
-
-  return decorate({ error: 'NO_ACTIONABLE_TASK', message: 'All tasks closed or in progress — no open tasks on deck' });
-}
-
-/**
- * v3 manifest traversal with active-milestone scoping ([[HS-TASK-YDUH]]).
- *
- * Walks `manifest.milestones` in priority order, skips milestones that are
- * not active (status !== in_progress AND no in_progress epic child), and
- * drills into the first active milestone with an actionable child task.
- *
- * Returns the standard task-response payload (with `phase_id` set to the
- * milestone id so existing callers' shape stays intact) or null when no
- * active milestone has an open child.
- */
-export function pickFromV3Milestones(vaultRoot, milestoneRefs, roadmapId) {
-  for (const ref of milestoneRefs) {
-    const milestoneSpec = loadRoadmap(vaultRoot, ref);
-    if (!milestoneSpec) continue;
-    const fm = milestoneSpec.frontmatter || {};
-    if (fm.type !== 'milestone') continue;
-    const status = fm.status;
-    const milestoneState = resolveMilestoneState(vaultRoot, fm);
-    if (milestoneState.state !== 'milestone_has_epics') continue;
-    const epics = milestoneState.epics;
-    const isActive =
-      status === 'in_progress' ||
-      (status === 'open' && epics.some((e) => e.status === 'in_progress'));
-    if (!isActive) continue;
-
-    // Active milestone — drill into its epics looking for an actionable child.
-    // Prefer in_progress epics first (continue the WIP), then open epics.
-    const sortedEpics = [
-      ...epics.filter((e) => e.status === 'in_progress'),
-      ...epics.filter((e) => e.status === 'open'),
-    ];
-    for (const epicSummary of sortedEpics) {
-      const epic = loadTask(vaultRoot, epicSummary.id);
-      if (!epic) continue;
-      const childResult = resolveEpicChildTask(vaultRoot, epic.frontmatter);
-      if (!childResult || !childResult.task) continue;
-      const { task: childTask, blockers = [], severity = 'none', state } = childResult;
-      const phase = { id: epic.id, name: `Active milestone — ${fm.name || ref}` };
-      const cohort = loadEpicChildrenCohort(vaultRoot, epic.frontmatter);
-      const response = buildTaskResponse(
-        vaultRoot,
-        childTask,
-        phase,
-        roadmapId,
-        'manifest_active_milestone_drill',
-        cohort,
-      );
-      response.active_milestone = {
-        id: fm.id || ref,
-        name: fm.name || ref,
-        spec_path: milestoneSpec.specPath,
-      };
-      response.pinned_epic = {
-        id: epic.id,
-        name: epic.frontmatter?.name || epic.id,
-        spec_path: epic.specPath,
-      };
-      response.child_state = state;
-      response.next_action_hint = mapStateToHint(state);
-      response.blocker_severity = severity;
-      if (blockers.length > 0) {
-        response.unmet_blockers = blockers;
-        const banner = buildBlockerBanner(state, blockers);
-        if (banner) {
-          response.prompt_markdown = response.prompt_markdown.replace(
-            '\n\n---\n\n',
-            `${banner}\n\n---\n\n`,
-          );
-        }
-      }
-      return response;
-    }
-  }
-  return null;
-}
-
-export function resolveNextOnDeckOpen(vaultRoot, roadmapId) {
-  const roadmap = loadRoadmap(vaultRoot, roadmapId);
-  if (!roadmap) return null;
-
-  const manifest = roadmap.frontmatter.roadmap_manifest;
-  if (!manifest || !manifest.phases) return null;
-
-  for (const phase of manifest.phases) {
-    for (const taskId of phase.tasks || []) {
-      if (isInitiative(taskId)) {
-        const nested = resolveNextOnDeckOpen(vaultRoot, taskId);
-        if (nested) return nested;
-      } else {
-        const task = loadTask(vaultRoot, taskId);
-        if (task && task.status === 'open') {
-          const cohort = loadPhaseOpenCohort(vaultRoot, phase);
-          return buildTaskResponse(vaultRoot, task, phase, roadmapId, 'manifest_open', cohort);
-        }
-      }
-    }
-  }
-
-  return null;
-}
-
-/**
- * Build the derived execution brief for a task-shaped spec node (the Tier 0–2
- * composer lives in alignment-gate.mjs). The NEXT STEP block, if present, is the
- * Tier-0 override (prepended). Pure aside from the injected vault loader.
- */
-export function deriveTaskBrief(vaultRoot, { id, name, status, roadmapId, frontmatter, body, specPath, cloudTaskGraph }) {
-  // [[HS-H227-MCPC-TASK]]: `cloudTaskGraph`, when supplied by the direct
-  // spec_id branch of `resolveNextOnDeckPayload` (cloud tier only), routes
-  // this decomposition-context walk through the HTTP pre-fetch instead of
-  // disk. Every other caller (buildTaskResponse's disk-only scheduler path)
-  // passes nothing here and keeps the original `loadTask` behavior.
-  const loadRef = (ref) => loadTaskViaGraph(vaultRoot, ref, cloudTaskGraph);
-  const node = { id, name, frontmatter: frontmatter || {}, body: body || '' };
-  const context = extractDecompositionContext(node, loadRef, 'epic');
-  const override = extractNextStepBlock(body || '');
-  const hasOverride = typeof override === 'string' && override.trim().length > 0;
-
-  // Tier-3 readiness floor ([[HS-TASK-RW3B]]) — runs BEFORE synthesis. A spec
-  // below the minimum-viable-input threshold routes to a recoverable
-  // clarification surface naming the missing fields instead of a thin brief.
-  // An authored `## NEXT STEP` override is itself sufficient input (a human
-  // pinned the prompt), so it bypasses the floor.
-  let ready = true;
-  let markdown;
-  if (hasOverride) {
-    markdown = buildExecutionBrief({ id, name, status, roadmapId, context, override });
-  } else {
-    const floor = readReadinessFloorSettings(vaultRoot);
-    const readiness = assessBriefReadiness({ name, context, floor });
-    ready = readiness.ready;
-    markdown = ready
-      ? buildExecutionBrief({ id, name, status, roadmapId, context, override })
-      : buildClarificationPrompt({
-          id,
-          name,
-          status,
-          roadmapId,
-          missing: readiness.missing,
-          focusSpecPath: specPath,
-        });
-  }
-
-  // Observability ([[HS-TASK-68NO]]) — record the served tier + emit the running
-  // degraded-mode rate so a degrading system is visible, never silent.
-  const tier = classifyBriefTier({ override, context, ready });
-  const stats = recordBriefTier(tier);
-  // One-shot CLI paths (`hs next`, `hs mcp call`, unit tests) set
-  // HEYSPEX_DISABLE_STDIO_BOOTSTRAP — skip stderr tier logs there. PowerShell
-  // paints stderr red and shows NativeCommandError even on success; humans
-  // running `--json` only want stdout JSON ([[HS-TASK-ISK7]]).
-  if (process.env.HEYSPEX_DISABLE_STDIO_BOOTSTRAP !== '1') {
-    process.stderr.write(`${formatBriefTierLog({ tier, id, stats })}\n`);
-  }
-
-  return markdown;
-}
-
-export function buildTaskResponse(vaultRoot, task, phase, roadmapId, sourceKind, cohortSpecs = null) {
-  // Detect UI tags and load design context if applicable
-  const uiTags = detectUITags(task.frontmatter);
-  let designContext = null;
-  let designSection = '';
-
-  if (uiTags.length > 0) {
-    const designDecisions = loadDesignMemories(vaultRoot, uiTags);
-    if (designDecisions.length > 0) {
-      designContext = {
-        triggered_by_tags: uiTags,
-        decisions: designDecisions,
-      };
-      designSection = buildDesignContextSection(designDecisions, uiTags);
-    }
-  }
-
-  // [[HS-TASK-G0HF]] derived execution brief — the only path. An acceptance-
-  // criteria contract composed deterministically; the `## NEXT STEP` block, if
-  // present, rides in as the Tier-0 override (no raw body-excerpt fallback).
-  const brief = deriveTaskBrief(vaultRoot, {
-    id: task.id,
-    name: task.name,
-    status: task.status,
-    roadmapId,
-    frontmatter: task.frontmatter,
-    body: task.body,
-    specPath: task.specPath,
-  });
-  const promptMarkdown = `${designSection}${brief}\n\n---\n\n_Spec path: \`${task.specPath}\`_`;
-
-  const response = {
-    spec_id: task.id,
-    title: task.name,
-    status: task.status,
-    source_kind: sourceKind,
-    phase_id: phase.id,
-    phase_name: phase.name,
-    roadmap_id: roadmapId,
-    prompt_markdown: promptMarkdown,
-    spec_path: task.specPath,
-  };
-
-  // Include design_context if UI tags detected
-  if (designContext) {
-    response.design_context = designContext;
-  }
-
-  // Scheduler explanation trace ([[HS-TASK-C2ZQ]] AC #1). Cohort defaults to
-  // the picked spec when callers don't pass a richer set — better to emit a
-  // single-spec trace than to drop the field entirely.
-  const cohort = Array.isArray(cohortSpecs) && cohortSpecs.length > 0
-    ? cohortSpecs
-    : [{ id: task.id, frontmatter: task.frontmatter || {} }];
-  const explanation = buildOnDeckExplanation(task.id, cohort, vaultRoot);
-  attachWhyNowFields(response, explanation, null);
-
-  return response;
-}
+// Which spec is on deck: vault/scheduler loaders, milestone scoping, the frozen
+// scheduler order, focus overrides, and resolveNextOnDeck itself. The brief
+// renderer (on-deck-brief.mjs) sits on top of this. Extracted from cli.mjs under
+// [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]] (no behavior change).
+//
+// ─────────────────────────────────────────────────────────────────────────────
+// Scheduler cohort + pin resolution ([[HS-TASK-CLIM]])
+//
+// Mirrors console's `/api/scheduler/inspect` + `/api/roadmap/[id]` cohort
+// assembly so vendor `resolveNextOnDeck` picks position-0 from the same global
+// order computeOrderCached exposes to the console surfaces. The parity contract
+// is: same vault, same focus pin → same #1 spec_id. Console's
+// `partitionForScheduler` / active-milestone scope are caller-side concerns
+// (the vendor parity test explicitly excludes them from byte-equivalence,
+// [[HS-TASK-ZJLX]]), so the filters live here rather than in scheduler.mjs.
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// Reorder a list of `{ id, status, ... }` candidate epics by running
+// computeOrder LOCALLY over them, mirroring console's `pickMilestoneOnDeck`
+// descent pattern. Epics whose status is non-actionable (closed / in_review /
+// hibernated) are excluded from the local cohort but kept in the output at the
+// tail in their original relative order so the surface caller still sees them.
+// Cycles / cohort load failures degrade to the input order.
+// [[HS-EPIC-FRZE]] file-fallback removed (2026-06-10). The milestone snapshot is
+// Neon-only; the console never writes `.heyspex/milestone-snapshots/*.json`, so the
+// former `readMilestoneSnapshotFile` / `applyFrozenEpicOrder` / `isMilestoneSnapshotEnabled`
+// helpers always no-opped. /hs-next returns live scheduler order until a real
+// Neon-backed snapshot read lands (deferred follow-up).
+
+import { findSpecFile, loadRoadmap, loadSpec, loadTask, loadTaskViaGraph, parseFrontmatter, wikilinkTarget } from './vault-io.mjs';
+import { CycleError as SchedulerCycleError, applyPin as schedulerApplyPin, buildExplanation as schedulerBuildExplanation, computeOrder as schedulerComputeOrder, frontmatterToSchedulerSpec, normalizeDependsOnId } from './scheduler.mjs';
+import { buildBlockerBanner, buildEpicBoundaryPromptMarkdown, computeUnmetBlockers as computeUnmetBlockersImpl, mapStateToHint, resolveEpicChildTask as resolveEpicChildTaskImpl, resolveMilestoneState as resolveMilestoneStateImpl } from './blocker-resolver.mjs';
+import { readMvpModeState } from './mvp-mode.mjs';
+import { consoleReadErrorFrom, readViaSelector } from './read-path.mjs';
+import { consoleFetch } from './console-transport.mjs';
+import { join } from 'node:path';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { detectUITags, loadDesignMemories } from './memory-tools.mjs';
+import { assessBriefReadiness, buildClarificationPrompt, buildExecutionBrief, classifyBriefTier, extractDecompositionContext, readReadinessFloorSettings } from './alignment-gate.mjs';
+import { formatBriefTierLog, recordBriefTier } from './brief-observability.mjs';
+import { buildWhyNow as schedulerBuildWhyNow } from './why-now.mjs';
+import { toCanonicalFamilyFirstId } from './spec-id-lib.mjs';
+
+export function loadFocusOverride(vaultRoot, options = {}) {
+  // Neon layer-1 pin (precedence #1) wins when present. It is the console-set
+  // fuse pin, which on a Neon-up machine is DORMANT in the file (vault.ts writes
+  // it to Neon `focus_pin`, not focus.yaml — [[heyspex-is-saas-cloud-primary-both-tiers]]).
+  // The caller fetches it at the async boundary (`injectNeonFocusPin`) and threads
+  // the spec_id in here so this sync resolver can honor it. We resolve it to a
+  // focus object that supersedes the file's layer-2 `spec_path` entirely, so a
+  // stale dormant-file pin is never resurrected. FCPN follow-on (the documented
+  // paid-tier soak gap). Falls through to the file when the id doesn't resolve.
+  const neonPinSpecId = options.neonPinSpecId;
+  if (typeof neonPinSpecId === 'string' && neonPinSpecId) {
+    const resolved = findSpecFile(vaultRoot, neonPinSpecId);
+    if (resolved) {
+      return { spec_path: resolved, pin: { spec_id: neonPinSpecId } };
+    }
+    // id doesn't resolve to a vault file → don't steer nowhere; use the file.
+  }
+
+  // Precedence #2: the Neon `focus_selection` layer-2 spec_path ([[HS-TASK-FSEL]]).
+  // On a Neon-up machine the console writes layer-2 here, not the (dormant) file —
+  // so reading it keeps vendor /hs-next in agreement with the console On-Deck.
+  // The stored value is already a repo-relative `specs/…md` path.
+  const neonSelectionSpecPath = options.neonSelectionSpecPath;
+  if (typeof neonSelectionSpecPath === 'string' && neonSelectionSpecPath) {
+    return { spec_path: neonSelectionSpecPath };
+  }
+
+  // No `.heyspex/focus.yaml` fallback ([[no-fallbacks-by-default]]; the
+  // focus.yaml-fallback incident). Focus lives only in Neon, fetched at the
+  // async boundary (`injectNeonFocusPin`) and threaded in via the options
+  // above. When neither a Neon pin nor selection is present (console
+  // unreachable, or simply no focus set), there is no override — /hs-next
+  // resolves the scheduler default off the local vault. Focus steering is a
+  // nicety, not a correctness gate, so an absent console degrades to "no
+  // steer", never to a stale file read.
+  return null;
+}
+
+export function extractNextStepBlock(body) {
+  // Look for a "NEXT STEP" or "## NEXT STEP" section
+  const patterns = [
+    /```[^\n]*NEXT STEP[^\n]*\n([\s\S]*?)```/i,
+    /## NEXT STEP[:\s]*Ready-to-paste prompt\s*\n\s*```[^\n]*\n([\s\S]*?)```/i,
+    /NEXT STEP[:\s]*\n\s*```[^\n]*\n([\s\S]*?)```/i,
+  ];
+
+  for (const pattern of patterns) {
+    const match = body.match(pattern);
+    if (match) return match[1].trim();
+  }
+
+  return null;
+}
+
+/**
+ * Build the "Design System Requirements" section for UI epics.
+ * @param {Array} decisions - Design decisions to include
+ * @param {string[]} triggerTags - Tags that triggered this
+ * @returns {string} - Markdown section
+ */
+export function buildDesignContextSection(decisions, triggerTags) {
+  if (decisions.length === 0) return '';
+
+  const lines = [
+    '## Design System Requirements',
+    '',
+    `> **Triggered by tags:** ${triggerTags.join(', ')}`,
+    '>',
+    '> Apply these design decisions before implementation. Violations will be caught by pre-commit hooks.',
+    '',
+  ];
+
+  for (const decision of decisions) {
+    lines.push(`### ${decision.id}`);
+    lines.push('');
+    lines.push(decision.summary);
+    lines.push('');
+
+    if (decision.checklist && decision.checklist.length > 0) {
+      lines.push('**Checklist:**');
+      for (const item of decision.checklist) {
+        lines.push(`- [ ] ${item}`);
+      }
+      lines.push('');
+    }
+  }
+
+  lines.push('---');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+export function isInitiative(taskId) {
+  return taskId.includes('ROADMAP') || taskId.startsWith('HS-ROADMAP-');
+}
+
+// Status filter mirror of `spex-console/src/lib/db/repositories/helpers.ts:SCHEDULER_EXCLUDED_STATUSES`.
+// [[HS-EPIC-FRZE]] — synced to console's full 6-status set (added cancelled /
+// superseded / duplicate). Previously the cli excluded only 3, so `/hs-next`
+// and the console could disagree on the active set for a terminal-but-not-shipped
+// spec (CNVG-AC1 divergence). These are terminal: the work was intentionally
+// dropped, so it must never earn an on-deck position on either surface.
+export const SCHEDULER_EXCLUDED_STATUSES = new Set([
+  'closed',
+  'hibernated',
+  'in_review',
+  'cancelled',
+  'superseded',
+  'duplicate',
+  // [[HS-DIAG-YMN3]]: `parked` = indefinite park; scheduler-invisible. Mirrors
+  // console's `SCHEDULER_EXCLUDED_STATUSES` (helpers.ts) so `/hs-next` never
+  // ranks a parked spec into the active cohort the way the console no longer does.
+  'parked',
+]);
+
+export function isSchedulerExcluded(status, canonical) {
+  if (SCHEDULER_EXCLUDED_STATUSES.has(status)) return true;
+  return canonical === false;
+}
+
+// Mirror of `spex-console/src/lib/scheduler/toposort.ts:isCanonicalSpecId`.
+export function isCanonicalSpecId(id) {
+  // Family-keyed kinds (TASK/EPIC/MIL/RES/CAP/REV/…): accept EITHER ordering by
+  // recomposing via parseSpecId ([[HS-EPIC-DLE3]]). Non-family-keyed labels
+  // (ROADMAP/IDEA/FLOW) are not reordered, so keep the type-first bare check.
+  if (toCanonicalFamilyFirstId(id)) return true;
+  return /^HS-(?:ROADMAP|IDEA|FLOW)-[A-Z0-9]+$/.test(id);
+}
+
+// Mirror of `spex-console/src/lib/vault-shared.ts:canonicalizeSpecRef` — strips
+// wikilink wrappers + slug tails, returning the bare canonical id.
+export function canonicalizeSpecRef(value) {
+  if (value == null) return null;
+  const inner = wikilinkTarget(String(value));
+  if (!inner) return null;
+  const m = inner.match(
+    /^(HS-(?:TASK|EPIC|MIL|ROADMAP|RES|CAP|REV|IDEA|FLOW)-(?:\d+|[A-Z0-9]+))/,
+  );
+  return m ? m[1] : inner;
+}
+
+// Walk specs/{tasks,epics,milestones} and return one entry per .md file.
+// Result entries are `{ id, frontmatter, relPath }`. Used to seed the scheduler
+// cohort below — we keep the full milestone set so `getActiveMilestones` can
+// run, and partition them out before computeOrder.
+export function loadVaultSpecsForScheduler(vaultRoot) {
+  const out = [];
+  // Diagnoses ([[HS-MIL-BFIX]]) join the scheduler pool so an open bug fix
+  // competes for on-deck by `severity:` (channel B). It is the SINGLE ranker
+  // that decides order; the Resolution surface only advises via severity.
+  // Disk-only readdir — misses Neon-only (cloud-filed) diagnoses; see [[HS-7UJZ-O86I-DIAG]].
+  for (const dir of ['specs/tasks', 'specs/epics', 'specs/milestones', 'specs/diagnoses']) {
+    const full = join(vaultRoot, dir);
+    if (!existsSync(full)) continue;
+    let files;
+    try {
+      files = readdirSync(full, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of files) {
+      if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+      const relPath = `${dir}/${entry.name}`;
+      try {
+        const content = readFileSync(join(vaultRoot, relPath), 'utf-8');
+        const { frontmatter } = parseFrontmatter(content);
+        const fallback = entry.name.replace(/\.md$/i, '');
+        const id = typeof frontmatter.id === 'string' && frontmatter.id ? frontmatter.id : fallback;
+        out.push({ id, frontmatter, relPath });
+      } catch {
+        // ignore unreadable / malformed files
+      }
+    }
+  }
+  return out;
+}
+
+// Map a diagnose's `severity:` onto the scheduler's existing `kind` tier
+// ([[HS-MIL-BFIX]] channel B — "map severity to existing signals"). The tier is
+// the first within-layer ranking key in computeOrder. Moderate mapping (owner
+// decision 2026-06-16): an error-severity bug competes at FOUNDATION (just below
+// core infra), a warning at feature, an info at polish — so a build-breaking bug
+// surfaces high WITHOUT outranking genuine infra. Absent/invalid severity →
+// 'feature' (matches detect-bugs.ts's `warning` default). MUST stay byte-identical
+// to the console copy in `spex-console/src/lib/vault.ts` (`DIAGNOSE_SEVERITY_TIER`)
+// so vendor↔console on-deck order is parity-identical.
+export const DIAGNOSE_SEVERITY_TIER = { error: 'foundation', warning: 'feature', info: 'polish' };
+
+// The four scheduler tiers a pillar's `library_tier:` may name. Mirrors
+// console `TIER_ORDER` (spex-console/src/lib/scheduler/types.ts).
+export const PILLAR_TIER_VALUES = new Set(['infra', 'foundation', 'feature', 'polish']);
+
+// Build a `pillar id → scheduler tier` map by reading `specs/pillars/*.md`.
+// Mirrors console `buildPillarTierMap` (spex-console/src/lib/db/repositories/
+// helpers.ts): an evergreen pillar with `library_tier: foundation` lets epics
+// under it inherit the foundation tier when they set no explicit `kind:`.
+// Pillars whose `library_tier` is not a tier (e.g. `meta`) or is unset
+// contribute no entry. Read from disk separately because the scheduler row
+// loader (`loadVaultSpecsForScheduler`) deliberately omits the pillars dir.
+export function loadPillarTierMap(vaultRoot) {
+  const out = new Map();
+  const full = join(vaultRoot, 'specs/pillars');
+  if (!existsSync(full)) return out;
+  let files;
+  try {
+    files = readdirSync(full, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of files) {
+    if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+    try {
+      const content = readFileSync(join(full, entry.name), 'utf-8');
+      const { frontmatter: fm } = parseFrontmatter(content);
+      if (fm.type !== 'pillar') continue;
+      const lt = typeof fm.library_tier === 'string' ? fm.library_tier : null;
+      if (lt && PILLAR_TIER_VALUES.has(lt)) {
+        const fallback = entry.name.replace(/\.md$/i, '');
+        const id = typeof fm.id === 'string' && fm.id ? fm.id : fallback;
+        out.set(canonicalizeSpecRef(id) || id, lt);
+      }
+    } catch {
+      // ignore unreadable / malformed files
+    }
+  }
+  return out;
+}
+
+/**
+ * A console `GET /api/specs` row (`SpecSummary`) already flattens every
+ * scheduler-relevant frontmatter field to the top level (id, type, status,
+ * tags, effort, requires_user_testing, depends_on, canonical, created, kind,
+ * library_tier, blast_radius, epics, children, milestone, parent, pillar) —
+ * see `spex-console/src/lib/vault-shared.ts`. `vaultRowToSchedulerSpec` /
+ * `frontmatterToSchedulerSpec` read the row as if it WERE frontmatter, so this
+ * just renames the one field that doesn't share its frontmatter name.
+ *
+ * Known gap (no console fields= extension exists to close it without editing
+ * spex-console, forbidden by this task): `SpecSummary` does not carry
+ * `severity`, so a diagnose's severity-derived tier
+ * (`vaultRowToSchedulerSpec`'s `DIAGNOSE_SEVERITY_TIER` lookup) always falls
+ * back to `'feature'` in cloud reliance instead of reflecting the real
+ * severity — documented here rather than silently accepted.
+ */
+export function summaryRowToFrontmatterLike(row) {
+  return { ...row, what_matters: row.whatMatters ?? row.what_matters };
+}
+
+/**
+ * Cloud-reliant sibling of `loadVaultSpecsForScheduler` ([[HS-DJWP-MCPC-TASK]]
+ * "Scheduler cohort" family). `loadVaultSpecsForScheduler` stays untouched
+ * (the `diskRead` branch); in `neon` tier this asks `GET /api/specs` once
+ * (no `type=` — the four wanted types are filtered client-side, mirroring
+ * the four directories the disk loader walks) instead of `readdirSync`ing
+ * `specs/{tasks,epics,milestones,diagnoses}`.
+ */
+export async function loadVaultSpecsForSchedulerViaTier(vaultRoot, { tier, consoleUrl }) {
+  return readViaSelector({
+    tier,
+    diskRead: () => loadVaultSpecsForScheduler(vaultRoot),
+    neonRead: async () => {
+      const res = await consoleFetch('/api/specs');
+      if (!res.ok) {
+        throw consoleReadErrorFrom(res, `GET /api/specs returned ${res.status}: ${res.error || JSON.stringify(res.body ?? {})}`, null);
+      }
+      const rows = Array.isArray(res.body?.specs) ? res.body.specs : [];
+      const wanted = new Set(['task', 'epic', 'milestone', 'diagnose']);
+      return rows
+        .filter((r) => wanted.has(r.type))
+        .map((r) => ({ id: r.id, frontmatter: summaryRowToFrontmatterLike(r), relPath: r.relPath }));
+    },
+    routeLabel: 'GET /api/specs',
+    consoleUrl,
+  });
+}
+
+/**
+ * Cloud-reliant sibling of `loadPillarTierMap` ([[HS-DJWP-MCPC-TASK]] "Pillar
+ * tier map" family). `loadPillarTierMap` stays untouched (the `diskRead`
+ * branch); in `neon` tier this asks `GET /api/specs?type=pillar` instead of
+ * `readdirSync`ing `specs/pillars`.
+ */
+export async function loadPillarTierMapViaTier(vaultRoot, { tier, consoleUrl }) {
+  return readViaSelector({
+    tier,
+    diskRead: () => loadPillarTierMap(vaultRoot),
+    neonRead: async () => {
+      const res = await consoleFetch('/api/specs?type=pillar');
+      if (!res.ok) {
+        throw consoleReadErrorFrom(res, `GET /api/specs?type=pillar returned ${res.status}: ${res.error || JSON.stringify(res.body ?? {})}`, null);
+      }
+      const rows = Array.isArray(res.body?.specs) ? res.body.specs : [];
+      const out = new Map();
+      for (const r of rows) {
+        const lt = typeof r.library_tier === 'string' ? r.library_tier : null;
+        if (lt && PILLAR_TIER_VALUES.has(lt)) {
+          out.set(canonicalizeSpecRef(r.id) || r.id, lt);
+        }
+      }
+      return out;
+    },
+    routeLabel: 'GET /api/specs?type=pillar',
+    consoleUrl,
+  });
+}
+
+// Promote a loaded vault row into the SchedulerSpec shape. Mirrors console
+// `summaryToSchedulerSpec` — same fields, derived from raw frontmatter.
+// The unique scheduler node key for a spec row/task ([[HS-K5GQ-DIAG]]): its
+// basename, derived from `relPath` (scheduler rows) or `specPath` (loadTask).
+// Sibling tasks under one epic share a family-key `id:`; the basename is what
+// disambiguates them so `computeOrder` doesn't throw DuplicateIdError. Falls
+// back to `id` when no path is on hand (keeps nodeKey === id, byte-identical).
+export function specBasename(rowOrTask) {
+  const p = rowOrTask?.relPath || rowOrTask?.specPath;
+  if (typeof p === 'string' && p) {
+    return p.replace(/^.*[/\\]/, '').replace(/\.md$/i, '');
+  }
+  return rowOrTask?.id;
+}
+
+// [[HS-67F4-DIAG]] — build a child-id → declared-order-index map from every
+// milestone's `epics:` array and every epic's `children:` array, so the global
+// cohort can stamp each spec's position in its parent's authored sequence
+// (Stage 6.7 tiebreak). Keyed on the canonical child id; first occurrence wins.
+export function buildDeclaredOrderByChild(rows) {
+  const byChild = new Map();
+  for (const row of rows) {
+    const fm = row.frontmatter || {};
+    const refs = fm.type === 'milestone' ? fm.epics : fm.type === 'epic' ? fm.children : null;
+    if (!Array.isArray(refs)) continue;
+    refs.forEach((ref, i) => {
+      const key = canonicalizeSpecRef(ref);
+      if (key && !byChild.has(key)) byChild.set(key, i);
+    });
+  }
+  return byChild;
+}
+
+export function vaultRowToSchedulerSpec(row, pillarTierById, declaredOrderByChild) {
+  const spec = frontmatterToSchedulerSpec(row.id, row.frontmatter || {});
+  // Unique node key so sibling tasks in the global cohort don't collide.
+  spec.nodeKey = specBasename(row);
+  const fm = row.frontmatter || {};
+  spec.type = typeof fm.type === 'string' ? fm.type : undefined;
+  if (spec.type === 'milestone') {
+    const epics = Array.isArray(fm.epics) ? fm.epics : [];
+    spec.epicsCount = epics.length;
+  }
+  // Diagnoses carry `severity:`, not the `kind:` tier vocab — derive the tier so
+  // computeOrder ranks them by severity instead of sorting them last (no kind).
+  if (spec.type === 'diagnose' && !spec.kind) {
+    const sev = typeof fm.severity === 'string' ? fm.severity.trim().toLowerCase() : '';
+    spec.kind = DIAGNOSE_SEVERITY_TIER[sev] || 'feature';
+  }
+  spec.milestone = canonicalizeSpecRef(fm.milestone) || undefined;
+  spec.parent = canonicalizeSpecRef(fm.parent) || undefined;
+  // [[HS-67F4-DIAG]] Stage 6.7 — position in the parent's declared child array.
+  if (declaredOrderByChild) {
+    const idx = declaredOrderByChild.get(canonicalizeSpecRef(row.id) || row.id);
+    if (idx != null) spec.declaredOrderIndex = idx;
+  }
+  // Stage 2.7 blast-radius band ([[encoding-foundational-and-blast-radius-p]]).
+  spec.blast_radius = typeof fm.blast_radius === 'string' ? fm.blast_radius : undefined;
+  // Pillar-tier inheritance ([[encoding-foundational-and-blast-radius-p]]): an
+  // epic with no explicit `kind:` inherits its pillar's `library_tier` tier, so
+  // foundation-pillar work (e.g. HS-PILR-architecture) auto-sorts foundation.
+  // Explicit `kind:` always wins; inert when no map is supplied.
+  if (!spec.kind && pillarTierById) {
+    const pillar = canonicalizeSpecRef(fm.pillar);
+    const inherited = pillar ? pillarTierById.get(pillar) : undefined;
+    if (inherited) spec.kind = inherited;
+  }
+  return spec;
+}
+
+// Mirror of `spex-console/src/lib/scheduler/pipeline.ts:partitionForScheduler`.
+// Drops epicless milestones + non-canonical-id duplicates. Pure — same input,
+// same output, same byte-equivalence with console.
+export function partitionSchedulerInput(specs) {
+  const afterMilestones = [];
+  for (const spec of specs) {
+    if (spec.type === 'milestone' && (spec.epicsCount ?? 0) === 0) continue;
+    afterMilestones.push(spec);
+  }
+  const kept = [];
+  const seen = new Set();
+  for (const spec of afterMilestones) {
+    // Dedup on the unique nodeKey (not the shared family-key `id:`) so legit
+    // sibling tasks both survive ([[HS-K5GQ-DIAG]]); byte-identical when unset.
+    const key = spec.nodeKey ?? spec.id;
+    if (!seen.has(key)) {
+      seen.add(key);
+      kept.push(spec);
+      continue;
+    }
+    if (isCanonicalSpecId(spec.id)) kept.push(spec);
+    // Non-canonical dup → drop (parity with console; vendor doesn't surface
+    // SkippedDuplicate to the agent, only the picked head).
+  }
+  return kept;
+}
+
+// Mirror of `spex-console/src/lib/scheduler/active-milestone.ts:getActiveMilestones`.
+export function getActiveMilestoneIds(specs, manifestOrder) {
+  const milestones = specs.filter((s) => s.type === 'milestone');
+  if (milestones.length === 0) return [];
+  const inProgressEpicMilestones = new Set();
+  for (const s of specs) {
+    if (s.type !== 'epic' || s.status !== 'in_progress' || !s.milestone) continue;
+    inProgressEpicMilestones.add(s.milestone);
+  }
+  const active = new Set();
+  for (const m of milestones) {
+    if (m.status === 'in_progress') active.add(m.id);
+    else if (m.status === 'open' && inProgressEpicMilestones.has(m.id)) active.add(m.id);
+  }
+  if (active.size === 0) return [];
+  if (manifestOrder && manifestOrder.length > 0) {
+    const normalized = manifestOrder.map((id) => normalizeDependsOnId(id));
+    const out = [];
+    const seen = new Set();
+    for (const id of normalized) {
+      if (active.has(id) && !seen.has(id)) {
+        out.push(id);
+        seen.add(id);
+      }
+    }
+    const leftover = [...active].filter((id) => !seen.has(id)).sort();
+    return [...out, ...leftover];
+  }
+  return [...active].sort();
+}
+
+// Mirror of `spex-console/src/lib/scheduler/active-milestone.ts:scopeToActiveMilestones`.
+// Drops epics whose milestone is not active (unless pinned), and tasks whose
+// epic-parent was dropped (unless pinned). Inert when no active milestone exists.
+export function scopeToActiveMilestones(specs, opts = {}) {
+  const activeMs = opts.activeMilestones ?? new Set();
+  const pinned = opts.pinnedIds ?? new Set();
+  if (activeMs.size === 0) return [...specs];
+  const keptEpicIds = new Set();
+  for (const s of specs) {
+    if (s.type !== 'epic') continue;
+    if (pinned.has(s.id)) {
+      keptEpicIds.add(s.id);
+      continue;
+    }
+    if (s.milestone && activeMs.has(s.milestone)) keptEpicIds.add(s.id);
+  }
+  const out = [];
+  for (const s of specs) {
+    if (s.type === 'epic') {
+      if (keptEpicIds.has(s.id)) out.push(s);
+      continue;
+    }
+    if (s.type === 'task') {
+      if (pinned.has(s.id)) { out.push(s); continue; }
+      if (s.milestone && activeMs.has(s.milestone)) { out.push(s); continue; }
+      if (s.parent && keptEpicIds.has(s.parent)) out.push(s);
+      continue;
+    }
+    out.push(s);
+  }
+  return out;
+}
+
+// Mirror of `spex-console/src/lib/vault.ts:getPinnedSpecIdForScheduler`. The pin
+// id is the input to `applyPin` so vendor and console float the same head.
+export function getPinnedSpecIdFromFocus(focus) {
+  if (!focus) return null;
+  if (focus.pin && typeof focus.pin.spec_id === 'string' && focus.pin.spec_id) {
+    return focus.pin.spec_id;
+  }
+  if (typeof focus.spec_path === 'string' && focus.spec_path) {
+    const base = focus.spec_path.replace(/^.*[/\\]/, '').replace(/\.md$/i, '');
+    const m = base.match(
+      /^(HS-(?:TASK|EPIC|MIL|ROADMAP|RES|CAP|REV|IDEA|FLOW|PROTO)-(?:\d+|[A-Z0-9]+))/,
+    );
+    if (m) return m[1];
+  }
+  return null;
+}
+
+// Pick the first scheduler-ordered id that belongs to `candidateIds`. Returns
+// null when none match. The candidates may include refs (basenames /
+// wikilinks); they are canonicalized before lookup so a milestone's `epics:`
+// entry written as `[[HS-EPIC-CNVG-…]]` resolves against the canonical id the
+// scheduler emits.
+export function pickFromSchedulerOrder(scheduler, candidateRefs) {
+  if (!scheduler?.order?.length) return null;
+  const set = new Set();
+  for (const ref of candidateRefs ?? []) {
+    const id = canonicalizeSpecRef(ref);
+    if (id) set.add(id);
+  }
+  if (set.size === 0) return null;
+  for (const entry of scheduler.order) {
+    if (set.has(entry.id)) return entry.id;
+  }
+  return null;
+}
+
+export function sortCandidateEpicsBySchedulerOrder(candidates, vaultRoot) {
+  if (!Array.isArray(candidates) || candidates.length === 0) return candidates;
+  const cohort = [];
+  const skipped = [];
+  for (const c of candidates) {
+    if (isSchedulerExcluded(c.status, c.canonical)) {
+      skipped.push(c);
+      continue;
+    }
+    const id = canonicalizeSpecRef(c.id) || c.id;
+    const epic = loadTask(vaultRoot, id);
+    if (!epic) {
+      skipped.push(c);
+      continue;
+    }
+    const spec = frontmatterToSchedulerSpec(epic.id, epic.frontmatter || {});
+    // [[HS-67F4-DIAG]] — stamp the epic's position in the milestone's declared
+    // `epics:` order (candidates arrive in that order) + the shared milestone
+    // parent, so the Stage 6.7 tiebreak keeps the seed pick in the owner's
+    // authored sequence when the epics are otherwise tied on every real signal.
+    spec.milestone = canonicalizeSpecRef(epic.frontmatter?.milestone) || '__milestone_epics__';
+    spec.declaredOrderIndex = cohort.length;
+    cohort.push({ candidate: c, spec });
+  }
+  if (cohort.length === 0) return candidates;
+  let order;
+  try {
+    order = schedulerComputeOrder(cohort.map((e) => e.spec));
+  } catch {
+    return candidates;
+  }
+  const byId = new Map(cohort.map((e) => [e.spec.id, e.candidate]));
+  const sorted = [];
+  for (const entry of order) {
+    const c = byId.get(entry.id);
+    if (c) sorted.push(c);
+  }
+  return [...sorted, ...skipped];
+}
+
+// [[HS-TASK-JHIA]] — reorder candidate epics by the FROZEN milestone snapshot
+// order (Neon-sourced via `GET /api/scheduler/milestone-snapshot/:id`), restoring
+// the freeze parity `/hs-next` lost when the file-read seam was removed
+// (2026-06-10). Epics present in the frozen order render in that order; epics
+// absent from it (filed after the snapshot was written, or an empty snapshot)
+// keep their incoming relative order at the tail so new work appends and never
+// reshuffles the frozen rows. Both sides are canonicalized to bare ids so a
+// frozen bare id matches a full-slug candidate ([[scheduler-cache-id-form-parity]]).
+export function applyFrozenEpicOrder(candidates, frozenEpicOrderIds) {
+  if (!Array.isArray(candidates) || candidates.length === 0) return candidates;
+  if (!Array.isArray(frozenEpicOrderIds) || frozenEpicOrderIds.length === 0) return candidates;
+  const pos = new Map();
+  frozenEpicOrderIds.forEach((id, idx) => {
+    const key = canonicalizeSpecRef(id) || id;
+    if (key && !pos.has(key)) pos.set(key, idx);
+  });
+  const known = [];
+  const unknown = [];
+  for (const c of candidates) {
+    const key = canonicalizeSpecRef(c.id) || c.id;
+    if (pos.has(key)) known.push(c);
+    else unknown.push(c);
+  }
+  known.sort((a, b) => {
+    const ka = canonicalizeSpecRef(a.id) || a.id;
+    const kb = canonicalizeSpecRef(b.id) || b.id;
+    return pos.get(ka) - pos.get(kb);
+  });
+  return [...known, ...unknown];
+}
+
+// Build the global scheduler cohort + order for `/hs-next`. Mirrors the path
+// `/api/roadmap/[id]` walks: status filter → active-milestone scope → partition
+// → computeOrder → applyPin. Returns { order, byId, pinnedSpecId, error? }.
+// Errors (cycle, duplicate id) degrade gracefully — caller can fall back to
+// the legacy manifest traversal so a single bad-frontmatter day doesn't break
+// /hs-next.
+// `precomputed.schedulerRows` / `precomputed.pillarTierById` ([[HS-DJWP-MCPC-TASK]]):
+// when supplied, used INSTEAD of the disk loaders below — `handleNextOnDeck`
+// pre-fetches both over HTTP in cloud reliance and threads them in via
+// `resolveNextOnDeck`'s options, so this function never calls
+// `loadVaultSpecsForScheduler`/`loadPillarTierMap` in that tier. Omitted (the
+// default on every OTHER call site) preserves today's disk-only behavior
+// byte-for-byte.
+export function computeGlobalSchedulerOrder(vaultRoot, focus, precomputed = {}) {
+  try {
+    const rows = precomputed.schedulerRows ?? loadVaultSpecsForScheduler(vaultRoot);
+    const pillarTierById = precomputed.pillarTierById ?? loadPillarTierMap(vaultRoot);
+    const declaredOrderByChild = buildDeclaredOrderByChild(rows);
+    const allSchedulerSpecs = rows.map((r) =>
+      vaultRowToSchedulerSpec(r, pillarTierById, declaredOrderByChild),
+    );
+    const activeMilestones = new Set(getActiveMilestoneIds(allSchedulerSpecs));
+    // Tasks + epics + diagnoses with a scheduler-relevant status feed computeOrder
+    // (mirrors the `active` filter in console's roadmap + inspect routes).
+    // Diagnoses ([[HS-MIL-BFIX]]) are milestone-less leaves; `scopeToActiveMilestones`
+    // passes non-epic/task types through its catch-all, so a standalone bug bypasses
+    // milestone scoping and competes in the global on-deck queue by `severity:`.
+    const active = allSchedulerSpecs.filter(
+      (s) => (s.type === 'task' || s.type === 'epic' || s.type === 'diagnose')
+        && !isSchedulerExcluded(s.status, s.canonical),
+    );
+    const pinnedSpecId = getPinnedSpecIdFromFocus(focus);
+    const pinnedIds = new Set();
+    if (pinnedSpecId) pinnedIds.add(pinnedSpecId);
+    const scoped = scopeToActiveMilestones(active, { activeMilestones, pinnedIds });
+    const partitioned = partitionSchedulerInput(scoped);
+    const base = schedulerComputeOrder(partitioned);
+    const order = pinnedSpecId
+      ? schedulerApplyPin(base, pinnedSpecId, partitioned)
+      : base;
+    // Dual-keyed ([[HS-K5GQ-DIAG]]): every row is reachable by its family-key
+    // `id:` (back-compat for family-grain consumers) AND by its unique basename
+    // (`order[].nodeKey`), so a sibling-task head resolves to the RIGHT row via
+    // `byId.get(entry.nodeKey)` instead of an ambiguous family-key lookup.
+    const byId = new Map();
+    for (const r of rows) {
+      byId.set(r.id, r);
+      byId.set(specBasename(r), r);
+    }
+    return { order, byId, pinnedSpecId };
+  } catch (err) {
+    return { error: err, order: [], byId: new Map(), pinnedSpecId: null };
+  }
+}
+
+// Bind the pure resolver helpers to this server's vault-aware `loadTask`.
+// The resolver lives in `./blocker-resolver.mjs` — it's unit-testable with a
+// synthetic loader and surfaces a discriminated state per
+// [[depends-on-canonical-blocker-field]] for the focus-override caller below.
+// `mvp_mode.review_backlog_never_blocks` — opt-OUT only, and the default holds
+// with MVP mode OFF too: `in_review` / `review_pending` mean build-complete at
+// every grain, so a review backlog never gates the next claim (owner ruling
+// 2026-08-14; mirrors the console's `PREREQ_SATISFIED_STATUSES`).
+export function blockerOpts(vaultRoot) {
+  const mvp = vaultRoot ? readMvpModeState(vaultRoot) : null;
+  return { reviewBacklogNeverBlocks: mvp?.review_backlog_never_blocks !== false };
+}
+
+export function computeUnmetBlockers(vaultRoot, task) {
+  return computeUnmetBlockersImpl((id) => loadTask(vaultRoot, id), task, blockerOpts(vaultRoot));
+}
+
+export function resolveEpicChildTask(vaultRoot, epicFrontmatter) {
+  return resolveEpicChildTaskImpl(
+    (id) => loadTask(vaultRoot, id),
+    epicFrontmatter,
+    blockerOpts(vaultRoot),
+  );
+}
+
+// [[HS-TASK-CLIM]] — scheduler-order epic-drill. Picks the seed child by
+// running computeOrder LOCALLY over the epic's actionable children, mirroring
+// console's `pickMilestoneOnDeck` descent pattern. Falls back to the legacy
+// manifest-order resolveEpicChildTask when no children resolve, when no child
+// is actionable (boundary states epic_implementation_complete / epic_done /
+// epic_empty still go through the legacy resolver), or when the local
+// computeOrder throws on a cycle. This deliberately supersedes the
+// manifest-order rule from
+// [[HS-DEC-epic-drill-resolver-manifest-order-and-blocker-filter]] — the
+// "blocker filter" half of that decision still holds (blockers surfaced in
+// the banner via computeUnmetBlockers), but the ordering authority moves to
+// the scheduler so vendor and console cannot disagree on the seed.
+export function resolveEpicChildTaskViaScheduler(vaultRoot, epicFrontmatter) {
+  const legacy = () => resolveEpicChildTask(vaultRoot, epicFrontmatter);
+  const children = epicFrontmatter?.children;
+  if (!Array.isArray(children) || children.length === 0) return { state: 'epic_empty' };
+
+  const actionable = [];
+  for (const raw of children) {
+    const target = wikilinkTarget(raw);
+    if (!target) continue;
+    const task = loadTask(vaultRoot, target);
+    if (!task) continue;
+    const status = task.status || task.frontmatter?.status;
+    if (status === 'open' || status === 'in_progress') {
+      actionable.push(task);
+    }
+  }
+  if (actionable.length === 0) return legacy(); // boundary states stay with legacy
+
+  // Key the LOCAL cohort on each child's unique basename ([[HS-K5GQ-DIAG]]).
+  // Sibling tasks under one epic legitimately share a family-key `id:` (e.g. all
+  // `id: HS-W6AD-TASK`); without a unique nodeKey `schedulerComputeOrder` throws
+  // DuplicateIdError, which — rethrown below — blanked What's Next
+  // (SUBPROCESS_EMPTY). The pick is resolved back by that same basename.
+  let pickedNodeKey;
+  try {
+    // [[HS-67F4-DIAG]] — stamp each child's position in the epic's declared
+    // `children:` order (`actionable` preserves it) + the shared epic parent, so
+    // the Stage 6.7 tiebreak keeps the seed task in the owner's authored sequence
+    // when the children are otherwise tied on every real signal.
+    const childParentKey =
+      canonicalizeSpecRef(epicFrontmatter?.id) || epicFrontmatter?.id || '__epic_children__';
+    const cohort = actionable.map((t, i) => ({
+      ...frontmatterToSchedulerSpec(t.id, t.frontmatter || {}),
+      nodeKey: specBasename(t),
+      parent: childParentKey,
+      declaredOrderIndex: i,
+    }));
+    const order = schedulerComputeOrder(cohort);
+    pickedNodeKey = order[0]?.nodeKey;
+  } catch (err) {
+    if (err instanceof SchedulerCycleError) return legacy();
+    throw err;
+  }
+  if (!pickedNodeKey) return legacy();
+  const picked = actionable.find((t) => specBasename(t) === pickedNodeKey);
+  if (!picked) return legacy();
+
+  const { blockers, severity } = computeUnmetBlockers(vaultRoot, picked);
+  const status = picked.status || picked.frontmatter?.status;
+  let state;
+  if (status === 'in_progress') state = 'resume';
+  else if (severity === 'none') state = 'ready';
+  else if (severity === 'soft_review') state = 'soft_review';
+  else state = 'hard_blocked';
+  return { state, task: picked, blockers, severity };
+}
+
+export function resolveMilestoneState(vaultRoot, milestoneFrontmatter) {
+  return resolveMilestoneStateImpl(
+    (id) => loadTask(vaultRoot, id),
+    milestoneFrontmatter,
+  );
+}
+
+/**
+ * Build the structured `/hs-next` response when focus pins a milestone whose
+ * `epics:` array is empty (or all entries fail to resolve). Shape matches
+ * [[HS-TASK-SKEM-scheduler-skip-epicless-milestones]] §"Structured /hs-next
+ * response": `status: "needs_breakdown"`, `suggested_actions[]`, and
+ * `next_eligible_spec: null`. The console UI consumer is
+ * [[HS-EPIC-MNBD-milestone-needs-breakdown-awareness]].
+ */
+export function buildMilestoneNeedsBreakdownResponse({
+  milestoneId,
+  milestoneName,
+  focusSpecPath,
+  roadmapId,
+  reason,
+}) {
+  const suggestedActions = [
+    {
+      action: 'file_epic',
+      cli: `hs epic new --milestone ${milestoneId}`,
+      mcp_tool: 'heyspex_file_epic',
+    },
+    { action: 'unpin', cli: 'hs focus clear' },
+  ];
+
+  const promptLines = [
+    `## needs_breakdown — ${milestoneId}`,
+    '',
+    `**Milestone:** ${milestoneName}`,
+    `**Roadmap:** ${roadmapId}`,
+    '',
+    `${reason}`,
+    '',
+    '### Suggested next moves',
+    '',
+    `1. **File a child epic** to break this milestone down: \`${suggestedActions[0].cli}\` (MCP: \`${suggestedActions[0].mcp_tool}\`).`,
+    `2. **Unpin** if this milestone was pinned by mistake: \`${suggestedActions[1].cli}\`.`,
+    '',
+    `_Pinned via \`.heyspex/focus.yaml\` (\`${focusSpecPath}\`). Milestone has no schedulable work yet — surfacing breakdown choices instead of a body excerpt._`,
+  ];
+
+  return {
+    status: 'needs_breakdown',
+    kind: 'milestone',
+    spec_id: milestoneId,
+    spec_title: milestoneName,
+    reason,
+    suggested_actions: suggestedActions,
+    next_eligible_spec: null,
+    source_kind: 'milestone_needs_breakdown',
+    roadmap_id: roadmapId,
+    spec_path: focusSpecPath,
+    prompt_markdown: promptLines.join('\n'),
+    next_action_hint: 'file_epic',
+  };
+}
+
+/**
+ * Build the `/hs-next` response when focus pins a milestone with a populated
+ * `epics:` array ([[HS-TASK-K7L9]] of [[HS-EPIC-M2J3]] §5). The milestone is
+ * the *scope* of focus; the deferral picks the next actionable child epic
+ * (in_progress first, else first non-closed, else first listed) so the agent
+ * has a concrete claim target. Multiple equally-actionable epics surface in
+ * `candidate_epics` so the agent can ask the human which to start.
+ *
+ * Mirrors `buildMilestoneNeedsBreakdownResponse` shape: the surface
+ * structurally distinguishes "pick a child to start" (this) from "file a child
+ * to start" (needs_breakdown) so the console can render either intent without
+ * grain-aware fork code.
+ */
+export function buildMilestoneDeferToSeedEpicResponse({
+  milestoneId,
+  milestoneName,
+  milestoneBody,
+  focusSpecPath,
+  roadmapId,
+  candidateEpics,
+}) {
+  // Pick the scheduler's position-0 over the actionable subset. `candidateEpics`
+  // has already been sorted by `sortCandidateEpicsBySchedulerOrder`, which
+  // appends SCHEDULER_EXCLUDED_STATUSES items to the tail; falling through to
+  // the first non-terminal preserves the scheduler's pick when the head is
+  // actionable, and only reaches the tail if every actionable epic was skipped
+  // during cohort load. This is the parity contract with console's On Deck —
+  // do NOT re-apply a manifest-style "first in_progress" filter here ([[HS-TASK-CLIM]]).
+  const SEED_TERMINAL = new Set(['closed', 'shipped', 'archived', 'hibernated', 'in_review']);
+  const seed =
+    candidateEpics.find((e) => !SEED_TERMINAL.has(e.status)) || candidateEpics[0];
+  const multiple = candidateEpics.length > 1;
+  const promptLines = [
+    `## focus_override_milestone_drill — ${milestoneId}`,
+    '',
+    `**Milestone:** ${milestoneName}`,
+    `**Roadmap:** ${roadmapId}`,
+    '',
+    `_Pinned via \`.heyspex/focus.yaml\`. Strategic focus is at the milestone grain — pick a child epic to start work below._`,
+    '',
+    '### Defer to seed epic',
+    '',
+    multiple
+      ? `**Seed epic candidates** (${candidateEpics.length}):`
+      : `**Seed epic:** \`${seed.id}\` (\`status: ${seed.status}\`).`,
+    '',
+    ...candidateEpics.map(
+      (e) =>
+        `- \`${e.id}\` · status: \`${e.status}\`${e.id === seed.id ? ' ← suggested next' : ''}`,
+    ),
+    '',
+    multiple
+      ? `Ask the human which to claim, or default to \`${seed.id}\` (first by scheduler order).`
+      : `Run \`/hs-next ${seed.id}\` to drill into the seed epic and claim its next task.`,
+    '',
+    '---',
+    '',
+    '### Milestone body excerpt',
+    '',
+    milestoneBody.length > 2000
+      ? `${milestoneBody.slice(0, 2000)}\n\n[... truncated ...]`
+      : milestoneBody,
+    '',
+    '---',
+    '',
+    `_Spec path: \`${focusSpecPath}\`_`,
+  ];
+
+  return {
+    spec_id: milestoneId,
+    title: milestoneName,
+    status: 'in_progress',
+    source_kind: 'focus_override_milestone_drill',
+    kind: 'milestone',
+    roadmap_id: roadmapId,
+    spec_path: focusSpecPath,
+    prompt_markdown: promptLines.join('\n'),
+    pinned_milestone: { id: milestoneId, name: milestoneName, spec_path: focusSpecPath },
+    candidate_epics: candidateEpics,
+    seed_epic: seed,
+    next_action_hint: multiple ? 'pick_epic' : 'drill_epic',
+  };
+}
+
+export const STALE_FOCUS_STATUSES = new Set(['in_review', 'closed', 'hibernated']);
+
+/**
+ * Compute the scheduler explanation trace for `spec` relative to `cohort`
+ * — i.e. the same set the spec was picked from. For epic-drill that's the
+ * epic's children; for manifest paths that's the phase's open tasks; for
+ * direct lookup the cohort is just the spec itself (layer 0, no tiebreaker
+ * pressure). Returns `null` if computeOrder fails (cycle) — the caller still
+ * surfaces the spec; explanation absence is non-fatal so /hs-next doesn't
+ * regress on a bad-frontmatter day.
+ *
+ * `cohortSpecs` items must be `{ id, frontmatter }` shaped (raw vault loads).
+ * The function looks up `pickedSpecId` after computing order and returns the
+ * full ExplanationTrace, which always cites tier (stage 2), topological
+ * layer (stage 1), and at least one tiebreaker (stage 7 or 8) per AC #1 of
+ * [[HS-TASK-C2ZQ]].
+ */
+/**
+ * Load an epic's child tasks into the `{ id, frontmatter }` shape
+ * `buildOnDeckExplanation` expects. Skips children that don't resolve to a
+ * vault file — same tolerance as `resolveEpicChildTask`.
+ */
+export function loadEpicChildrenCohort(vaultRoot, epicFrontmatter) {
+  const children = epicFrontmatter?.children;
+  if (!Array.isArray(children)) return [];
+  const out = [];
+  for (const raw of children) {
+    const target = wikilinkTarget(raw);
+    if (!target) continue;
+    const task = loadTask(vaultRoot, target);
+    if (!task) continue;
+    out.push({ id: task.id, frontmatter: task.frontmatter || {} });
+  }
+  return out;
+}
+
+/**
+ * Load all open tasks declared in a roadmap phase's `tasks:` list into the
+ * `{ id, frontmatter }` shape `buildOnDeckExplanation` expects. Initiative
+ * refs (nested roadmaps) are not flattened — they're rare in scheduled
+ * phases and the picked spec would always be the first open of its phase.
+ */
+export function loadPhaseOpenCohort(vaultRoot, phase) {
+  const tasks = phase?.tasks;
+  if (!Array.isArray(tasks)) return [];
+  const out = [];
+  for (const raw of tasks) {
+    if (isInitiative(raw)) continue;
+    const task = loadTask(vaultRoot, raw);
+    if (!task) continue;
+    if (task.status !== 'open') continue;
+    out.push({ id: task.id, frontmatter: task.frontmatter || {} });
+  }
+  return out;
+}
+
+/**
+ * Hysteresis anchor for the stateless MCP ([[HS-TASK-MI65]]). Reads the
+ * cohort's prior relative order out of the console-written scheduler cache
+ * (`<vaultRoot>/.heyspex/scheduler-cache.json`) so `/hs-next` stabilizes the
+ * same way the console Scheduler surface does. Best-effort: any missing file,
+ * parse error, or schema mismatch returns undefined → hysteresis inert, order
+ * byte-identical to a priorless run. Returns cohort ids in cached order.
+ */
+export function readSchedulerCachePriorOrder(vaultRoot, cohortIds) {
+  if (!vaultRoot) return undefined;
+  try {
+    const cachePath = join(vaultRoot, '.heyspex', 'scheduler-cache.json');
+    if (!existsSync(cachePath)) return undefined;
+    const parsed = JSON.parse(readFileSync(cachePath, 'utf-8'));
+    const order = Array.isArray(parsed?.order) ? parsed.order : null;
+    if (!order || order.length === 0) return undefined;
+    const inCohort = new Set(cohortIds);
+    const priorOrder = order
+      .map((o) => o?.id)
+      .filter((id) => typeof id === 'string' && inCohort.has(id));
+    return priorOrder.length > 0 ? priorOrder : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Full global scheduler order (bare ids, global rank) from the console-written
+ * cache. Used to converge the claim target onto scheduler output so /hs-next's
+ * `claim_target` agrees with its own `seed_epic` and the console On Deck
+ * ([[HS-EPIC-CNVG]]). Best-effort: any miss returns `[]` →
+ * `computeClaimTarget` falls back to declared (`epics:`/`children:`) order.
+ */
+export function readSchedulerCacheOrderIds(vaultRoot) {
+  if (!vaultRoot) return [];
+  try {
+    const cachePath = join(vaultRoot, '.heyspex', 'scheduler-cache.json');
+    if (!existsSync(cachePath)) return [];
+    const parsed = JSON.parse(readFileSync(cachePath, 'utf-8'));
+    const order = Array.isArray(parsed?.order) ? parsed.order : null;
+    if (!order) return [];
+    return order.map((o) => o?.id).filter((id) => typeof id === 'string');
+  } catch {
+    return [];
+  }
+}
+
+export function buildOnDeckExplanation(pickedSpecId, cohortSpecs, vaultRoot) {
+  if (!pickedSpecId) return null;
+  const cohort = Array.isArray(cohortSpecs) && cohortSpecs.length > 0
+    ? cohortSpecs
+    : [{ id: pickedSpecId, frontmatter: {} }];
+  const hasPicked = cohort.some((c) => c.id === pickedSpecId);
+  const effective = hasPicked
+    ? cohort
+    : [...cohort, { id: pickedSpecId, frontmatter: {} }];
+  const schedulerSpecs = effective.map((c) =>
+    frontmatterToSchedulerSpec(c.id, c.frontmatter || {}),
+  );
+  const priorOrder = readSchedulerCachePriorOrder(
+    vaultRoot,
+    schedulerSpecs.map((s) => s.id),
+  );
+  try {
+    const order = schedulerComputeOrder(schedulerSpecs, { priorOrder });
+    const hit = order.find((o) => o.id === pickedSpecId);
+    return hit?.explanation ?? null;
+  } catch (err) {
+    // Degenerate fallback so a cycle in unrelated cohort entries doesn't
+    // erase the picked spec's row-level signal.
+    if (err instanceof SchedulerCycleError) {
+      const picked = schedulerSpecs.find((s) => s.id === pickedSpecId);
+      if (picked) return schedulerBuildExplanation(picked, 0);
+    }
+    return null;
+  }
+}
+
+/** Attach the one-line why-now legibility field alongside the raw explanation trace. */
+export function attachWhyNowFields(response, explanation, pinnedSpecId) {
+  if (!response || !explanation) return;
+  response.explanation = explanation;
+  const pinned =
+    typeof pinnedSpecId === 'string' &&
+    typeof response.spec_id === 'string' &&
+    response.spec_id === pinnedSpecId;
+  response.why_now = schedulerBuildWhyNow(explanation, { pinned });
+}
+
+export function resolveNextOnDeck(vaultRoot, roadmapId, options = {}) {
+  const {
+    ignoreFocus = false,
+    includeHorizon = false,
+    neonPinSpecId,
+    neonSelectionSpecPath,
+    frozenEpicOrder,
+    // [[HS-DJWP-MCPC-TASK]]: pre-fetched over HTTP by `handleNextOnDeck` when
+    // cloud-reliant; undefined on every other (disk-reliant) call site, which
+    // falls through to computeGlobalSchedulerOrder's own disk loaders.
+    schedulerRows,
+    pillarTierById,
+  } = options;
+
+  // [[HS-TASK-CLIM]] — global scheduler order, computed once per call. The pin
+  // (Neon `focus_pin` precedence #1 via `neonPinSpecId`, else the file's layer-2
+  // `spec_path`) is fed into applyPin so vendor /hs-next and the console surfaces
+  // (`/api/scheduler/inspect`, `/api/roadmap/[id]`, `/api/focus`) agree on
+  // position-0. Loaded here even when `ignoreFocus: true` is set so the no-pin
+  // path can still consult the scheduler for the head pick.
+  const focus = !ignoreFocus
+    ? loadFocusOverride(vaultRoot, { neonPinSpecId, neonSelectionSpecPath })
+    : null;
+  const scheduler = computeGlobalSchedulerOrder(vaultRoot, focus, { schedulerRows, pillarTierById });
+
+  let staleFocusPin = null;
+
+  const decorate = (response) => {
+    if (!staleFocusPin || !response) return response;
+    response.stale_focus_pin = staleFocusPin;
+    const banner = `> ⚠️ **Stale focus pin ignored:** \`${staleFocusPin.spec_id}\` is \`status: ${staleFocusPin.status}\` (non-actionable). Clear or repoint \`.heyspex/focus.yaml\` — falling through to manifest traversal.\n\n`;
+    if (typeof response.prompt_markdown === 'string') {
+      response.prompt_markdown = banner + response.prompt_markdown;
+    } else if (typeof response.message === 'string') {
+      response.message = `${response.message}. Also: stale focus pin ${staleFocusPin.spec_id} (${staleFocusPin.status}) was ignored — clear or repoint .heyspex/focus.yaml.`;
+    }
+    return response;
+  };
+
+  // Check focus override first. The focus.yaml pin is the canonical
+  // "on deck" signal — it must always win when present (matches the console
+  // On Deck surface). If the focus spec has a NEXT STEP block we use it
+  // verbatim (source_kind: self_perpetuating); otherwise we return a body
+  // excerpt so /hs-next still surfaces the pinned spec instead of drifting
+  // back to manifest order.
+  //
+  // Exception: if the pinned spec's status is non-actionable
+  // (in_review / closed / hibernated), the pin is stale — capture a warning
+  // and fall through to manifest traversal so /hs-next never returns a spec
+  // the agent cannot work on.
+  if (!ignoreFocus) {
+    if (focus && focus.spec_path) {
+      const focusSpec = loadSpec(vaultRoot, focus.spec_path);
+      if (focusSpec && STALE_FOCUS_STATUSES.has(focusSpec.frontmatter.status)) {
+        staleFocusPin = {
+          spec_id: focusSpec.frontmatter.id || focus.spec_path,
+          spec_path: focus.spec_path,
+          status: focusSpec.frontmatter.status,
+          reason: focus.reason || null,
+        };
+      } else if (focusSpec) {
+        // If the pin is a milestone (kind: milestone or type: milestone), the
+        // milestone is the *scope* of focus — the actual work is a child
+        // epic, which itself walks to a child task. Today this resolver only
+        // handles the `needs_breakdown` case (empty/unresolved epics: array);
+        // drilling into a populated milestone is out of scope for SKEM and
+        // falls through to the body-excerpt branch. See
+        // [[HS-TASK-SKEM-scheduler-skip-epicless-milestones]].
+        const isMilestonePin =
+          focus.kind === 'milestone' ||
+          focusSpec.frontmatter.type === 'milestone';
+        if (isMilestonePin) {
+          const milestoneId = focusSpec.frontmatter.id || focus.spec_path;
+          const milestoneName = focusSpec.frontmatter.name || 'Pinned milestone';
+          const milestoneResult = resolveMilestoneState(
+            vaultRoot,
+            focusSpec.frontmatter,
+          );
+          if (milestoneResult.state === 'milestone_needs_breakdown') {
+            return buildMilestoneNeedsBreakdownResponse({
+              milestoneId,
+              milestoneName,
+              focusSpecPath: focus.spec_path,
+              roadmapId,
+              reason: 'Milestone has no child epics yet.',
+            });
+          }
+          if (milestoneResult.state === 'milestone_empty_after_filter') {
+            return buildMilestoneNeedsBreakdownResponse({
+              milestoneId,
+              milestoneName,
+              focusSpecPath: focus.spec_path,
+              roadmapId,
+              reason:
+                'Milestone declares child epics, but none of them resolve to a spec in the vault — breakdown still pending.',
+            });
+          }
+          if (milestoneResult.state === 'milestone_has_epics') {
+            // [[HS-TASK-K7L9]] of [[HS-EPIC-M2J3]] §5 — milestone is the
+            // *scope* of focus; surface the milestone body and defer the
+            // claim path to the seed epic. [[HS-TASK-CLIM]] resorts the
+            // candidate epics by scheduler position so the seed pick agrees
+            // with console's What's Next column. Scheduler errors / cohort
+            // misses degrade gracefully: epics absent from the order keep
+            // their manifest position (sorted after scheduler-ranked ones).
+            // [[HS-EPIC-FRZE]] / [[HS-TASK-JHIA]]: the frozen milestone snapshot
+            // lives in Neon and this cli has no Neon client, so the frozen epic
+            // order is fetched over HTTP at the async handler boundary
+            // (`injectFrozenMilestoneOrder` → `frozenEpicOrder`). When present we
+            // honor the freeze — the seed epic agrees with the console What's Next
+            // / On Deck surfaces. When absent (flag off, no snapshot, or console
+            // unreachable) we degrade to LIVE scheduler order, exactly as before.
+            const candidateEpics =
+              Array.isArray(frozenEpicOrder) && frozenEpicOrder.length > 0
+                ? applyFrozenEpicOrder(milestoneResult.epics, frozenEpicOrder)
+                : sortCandidateEpicsBySchedulerOrder(milestoneResult.epics, vaultRoot);
+            return buildMilestoneDeferToSeedEpicResponse({
+              milestoneId,
+              milestoneName,
+              milestoneBody: focusSpec.body || '',
+              focusSpecPath: focus.spec_path,
+              roadmapId,
+              candidateEpics,
+            });
+          }
+        }
+
+        // If the pin is an epic (kind: epic or type: epic), the epic is the
+        // *scope* of focus — the actual work is a child task. Drill to the
+        // next actionable child (in_progress first, else first open by
+        // priority) and return that task. Falls through to body-excerpt
+        // behavior only if the epic has no actionable child.
+        const isEpicPin =
+          focus.kind === 'epic' || focusSpec.frontmatter.type === 'epic';
+        if (isEpicPin) {
+          // [[HS-TASK-CLIM]] — drill into children in scheduler position order
+          // (local computeOrder over epic.children, mirroring console's
+          // milestone-descent pattern) so the seed task agrees with console's
+          // On Deck pick. Boundary states (epic_implementation_complete /
+          // epic_done / epic_empty) and scheduler errors fall back to the
+          // legacy manifest-order resolver.
+          const childResult = resolveEpicChildTaskViaScheduler(
+            vaultRoot,
+            focusSpec.frontmatter,
+          );
+          const epicId = focusSpec.frontmatter.id || focus.spec_path;
+          const epicName = focusSpec.frontmatter.name || 'Pinned epic';
+
+          if (childResult && childResult.task) {
+            // resume / ready / soft_review / hard_blocked — picked an actionable
+            // child. Build the standard task response, then decorate with the
+            // state-specific banner + machine-readable hint per
+            // [[depends-on-canonical-blocker-field]].
+            const { task: childTask, blockers = [], severity = 'none', state } = childResult;
+            const phase = { id: epicId, name: `Pinned epic — ${epicName}` };
+            const cohort = loadEpicChildrenCohort(vaultRoot, focusSpec.frontmatter);
+            const response = buildTaskResponse(
+              vaultRoot,
+              childTask,
+              phase,
+              roadmapId,
+              'focus_override_epic_drill',
+              cohort,
+            );
+            response.pinned_epic = { id: epicId, name: epicName, spec_path: focus.spec_path };
+            response.child_state = state;
+            response.next_action_hint = mapStateToHint(state);
+            response.blocker_severity = severity;
+            if (blockers.length > 0) {
+              response.unmet_blockers = blockers;
+              const banner = buildBlockerBanner(state, blockers);
+              if (banner) {
+                response.prompt_markdown = response.prompt_markdown.replace(
+                  '\n\n---\n\n',
+                  `${banner}\n\n---\n\n`,
+                );
+              }
+            }
+            return response;
+          }
+
+          if (
+            childResult &&
+            (childResult.state === 'epic_implementation_complete' ||
+              childResult.state === 'epic_done')
+          ) {
+            // Epic boundary — no actionable child. Surface a real prompt with
+            // the three next-move choices (advance focus, /hs-review, ship)
+            // instead of falling through to a confusing body excerpt.
+            const reviewCandidates = childResult.review_candidates || [];
+            const milestoneNextEpics = childResult.milestone_next_epics || [];
+            const promptMarkdown = buildEpicBoundaryPromptMarkdown({
+              state: childResult.state,
+              epicId,
+              epicName,
+              reviewCandidates,
+              milestoneNextEpics,
+              roadmapId,
+              focusSpecPath: focus.spec_path,
+            });
+            return {
+              spec_id: epicId,
+              title: epicName,
+              status: focusSpec.frontmatter.status,
+              source_kind: childResult.state,
+              roadmap_id: roadmapId,
+              prompt_markdown: promptMarkdown,
+              spec_path: focus.spec_path,
+              focus_reason: focus.reason,
+              pinned_epic: { id: epicId, name: epicName, spec_path: focus.spec_path },
+              child_state: childResult.state,
+              next_action_hint: mapStateToHint(childResult.state),
+              review_candidates: reviewCandidates,
+              milestone_next_epics: milestoneNextEpics,
+            };
+          }
+          // epic_empty (or null from legacy code path) — fall through to
+          // body-excerpt behavior below so the agent at least sees the epic
+          // body and can decide what to do.
+        }
+
+        // [[HS-TASK-CLIM]] — task-grain pin parity. When the focused TASK has
+        // unmet open prerequisites, the global scheduler seats those prereqs
+        // ahead of the pin (applyPin is prereq-aware per [[HS-TASK-PINQ]]). The
+        // CLI's #1 must equal computeOrderCached's position-0 — i.e. the
+        // prereq, not the pin — so we re-route to the prereq with a banner.
+        // Epic-empty / milestone fall-throughs and self_perpetuating NEXT STEP
+        // blocks bypass this so a structured pin display isn't replaced with
+        // an unexpected sibling task.
+        const focusType = focus.kind || focusSpec.frontmatter.type;
+        const pinnedId = focusSpec.frontmatter.id
+          || (focus.spec_path
+            ? focus.spec_path.replace(/^.*[/\\]/, '').replace(/\.md$/i, '')
+            : null);
+        if (
+          focusType === 'task'
+          && scheduler
+          && !scheduler.error
+          && scheduler.order?.length
+          && scheduler.order[0].id !== pinnedId
+        ) {
+          const prereqEntry = scheduler.order[0];
+          const prereqId = prereqEntry.id;
+          // Load by the unique nodeKey (basename) so a sibling-task prereq
+          // resolves to the right file, not an ambiguous family-key match
+          // ([[HS-K5GQ-DIAG]]); the banner still shows the family-key id.
+          const prereqTask = loadTask(vaultRoot, prereqEntry.nodeKey ?? prereqId);
+          if (prereqTask) {
+            const phase = {
+              id: pinnedId || 'focus_pin',
+              name: `Pinned task — ${focusSpec.frontmatter.name || pinnedId}`,
+            };
+            const cohort = scheduler.order
+              .slice(0, 25)
+              .map((o) => scheduler.byId.get(o.nodeKey ?? o.id))
+              .filter(Boolean)
+              .map((row) => ({ id: row.id, frontmatter: row.frontmatter }));
+            const response = buildTaskResponse(
+              vaultRoot,
+              prereqTask,
+              phase,
+              roadmapId,
+              'focus_override_prereq',
+              cohort,
+            );
+            const banner =
+              `\n\n> ⚠️ **Pinned \`${pinnedId}\` has unmet prerequisites.** ` +
+              `Scheduler seated \`${prereqId}\` ahead so the pin can land. ` +
+              `Clear this prereq first, or pin a different spec.`;
+            response.prompt_markdown = response.prompt_markdown.replace(
+              '\n\n---\n\n',
+              `${banner}\n\n---\n\n`,
+            );
+            response.pinned_task = {
+              id: pinnedId,
+              name: focusSpec.frontmatter.name || pinnedId,
+              spec_path: focus.spec_path,
+            };
+            response.next_action_hint = 'clear_prereq';
+            return response;
+          }
+        }
+
+        const uiTags = detectUITags(focusSpec.frontmatter);
+        let designContext = null;
+        let designSection = '';
+        if (uiTags.length > 0) {
+          const designDecisions = loadDesignMemories(vaultRoot, uiTags);
+          if (designDecisions.length > 0) {
+            designContext = {
+              triggered_by_tags: uiTags,
+              decisions: designDecisions,
+            };
+            designSection = buildDesignContextSection(designDecisions, uiTags);
+          }
+        }
+
+        const specId = focusSpec.frontmatter.id || focus.spec_path;
+        const title = focusSpec.frontmatter.name || 'Focus Override';
+        const status = focusSpec.frontmatter.status || 'in_progress';
+
+        // [[HS-TASK-G0HF]] the pinned spec always gets a derived execution brief
+        // (the `## NEXT STEP` block, if any, rides in as the Tier-0 override).
+        // The old "no NEXT STEP → body excerpt" disclaimer path is retired.
+        const hasOverride = !!extractNextStepBlock(focusSpec.body);
+        const promptMarkdown = designSection + deriveTaskBrief(vaultRoot, {
+          id: specId,
+          name: title,
+          status,
+          roadmapId,
+          frontmatter: focusSpec.frontmatter,
+          body: focusSpec.body,
+          specPath: focus.spec_path,
+        });
+        const sourceKind = hasOverride ? 'self_perpetuating' : 'focus_override';
+
+        const response = {
+          spec_id: specId,
+          title,
+          status,
+          source_kind: sourceKind,
+          roadmap_id: roadmapId,
+          prompt_markdown: promptMarkdown,
+          spec_path: focus.spec_path,
+          focus_reason: focus.reason,
+        };
+
+        if (designContext) {
+          response.design_context = designContext;
+        }
+
+        const focusExplanation = buildOnDeckExplanation(specId, [
+          { id: specId, frontmatter: focusSpec.frontmatter || {} },
+        ], vaultRoot);
+        attachWhyNowFields(response, focusExplanation, specId);
+
+        return response;
+      }
+    }
+  }
+
+  // Load roadmap
+  const roadmap = loadRoadmap(vaultRoot, roadmapId);
+  if (!roadmap) {
+    return { error: 'ROADMAP_NOT_FOUND', message: `Roadmap ${roadmapId} not found` };
+  }
+
+  const manifest = roadmap.frontmatter.roadmap_manifest;
+  if (!manifest || (!manifest.milestones && !manifest.phases)) {
+    return { error: 'NO_MANIFEST', message: `Roadmap ${roadmapId} has no manifest` };
+  }
+
+  // [[HS-TASK-CLIM]] — when no focus pin steered the resolver and the global
+  // scheduler returned a non-empty order, the head pick comes straight from
+  // position-0 (source_kind: `scheduler_default`). This is the no-pin parity
+  // contract — console's `/api/focus` and `/api/roadmap/[id]` use the same
+  // computeOrderCached call, so the agent and the surfaces stay in sync. The
+  // v3 manifest traversal below is kept as a graceful fallback for scheduler
+  // errors (cycle, duplicate id) and for cohort emptiness (every spec is
+  // closed / in_review / hibernated).
+  if (scheduler && !scheduler.error && scheduler.order?.length > 0) {
+    const head = scheduler.order[0];
+    // Resolve the head by its unique nodeKey (basename) so a sibling-task head
+    // loads the right file, not an ambiguous family-key match ([[HS-K5GQ-DIAG]]).
+    const headKey = head.nodeKey ?? head.id;
+    const row = scheduler.byId.get(headKey);
+    if (row) {
+      const task = loadTask(vaultRoot, headKey);
+      if (task) {
+        const phase = {
+          id: roadmapId,
+          name: `Scheduler default — ${roadmapId}`,
+        };
+        const cohort = scheduler.order
+          .slice(0, 25)
+          .map((o) => scheduler.byId.get(o.nodeKey ?? o.id))
+          .filter(Boolean)
+          .map((r) => ({ id: r.id, frontmatter: r.frontmatter }));
+        return decorate(
+          buildTaskResponse(vaultRoot, task, phase, roadmapId, 'scheduler_default', cohort),
+        );
+      }
+    }
+  }
+
+  // Manifest v3 ([[HS-TASK-JN9H]]): top-level `milestones:` is the
+  // authoritative priority order. Active-milestone scoping ([[HS-TASK-YDUH]])
+  // skips milestones whose status is not in_progress (and that have no
+  // in_progress child epic). Pinned-focus override already happened above —
+  // this branch is only reached when no focus.yaml drill applied and the
+  // scheduler-default pick above could not produce a head (cycle, empty cohort,
+  // or row not loadable).
+  if (Array.isArray(manifest.milestones)) {
+    const picked = pickFromV3Milestones(vaultRoot, manifest.milestones, roadmapId);
+    if (picked && !picked.error) return decorate(picked);
+  } else if (Array.isArray(manifest.phases)) {
+    // v2 backcompat — kept for one release window per [[HS-TASK-JN9H]] §2.
+    for (const phase of manifest.phases) {
+      for (const taskId of phase.tasks || []) {
+        if (isInitiative(taskId)) {
+          const nested = resolveNextOnDeckOpen(vaultRoot, taskId);
+          if (nested && !nested.error) {
+            return decorate({ ...nested, phase_id: phase.id, phase_name: phase.name });
+          }
+        } else {
+          const task = loadTask(vaultRoot, taskId);
+          if (task && task.status === 'open') {
+            const cohort = loadPhaseOpenCohort(vaultRoot, phase);
+            return decorate(buildTaskResponse(vaultRoot, task, phase, roadmapId, 'on_deck', cohort));
+          }
+        }
+      }
+    }
+  }
+
+  // Horizon (if enabled and no scheduled open tasks). Retired in v3 per
+  // [[HS-TASK-JN9H]] §1; kept here only as a v2 backcompat fall-through.
+  if (includeHorizon && manifest.horizon) {
+    const horizonPhase = { id: 'horizon', name: 'Horizon Backlog', tasks: manifest.horizon };
+    const horizonCohort = loadPhaseOpenCohort(vaultRoot, horizonPhase);
+    for (const taskId of manifest.horizon) {
+      const task = loadTask(vaultRoot, taskId);
+      if (task && task.status === 'open') {
+        return decorate(buildTaskResponse(vaultRoot, task, horizonPhase, roadmapId, 'horizon', horizonCohort));
+      }
+    }
+  }
+
+  return decorate({ error: 'NO_ACTIONABLE_TASK', message: 'All tasks closed or in progress — no open tasks on deck' });
+}
+
+/**
+ * v3 manifest traversal with active-milestone scoping ([[HS-TASK-YDUH]]).
+ *
+ * Walks `manifest.milestones` in priority order, skips milestones that are
+ * not active (status !== in_progress AND no in_progress epic child), and
+ * drills into the first active milestone with an actionable child task.
+ *
+ * Returns the standard task-response payload (with `phase_id` set to the
+ * milestone id so existing callers' shape stays intact) or null when no
+ * active milestone has an open child.
+ */
+export function pickFromV3Milestones(vaultRoot, milestoneRefs, roadmapId) {
+  for (const ref of milestoneRefs) {
+    const milestoneSpec = loadRoadmap(vaultRoot, ref);
+    if (!milestoneSpec) continue;
+    const fm = milestoneSpec.frontmatter || {};
+    if (fm.type !== 'milestone') continue;
+    const status = fm.status;
+    const milestoneState = resolveMilestoneState(vaultRoot, fm);
+    if (milestoneState.state !== 'milestone_has_epics') continue;
+    const epics = milestoneState.epics;
+    const isActive =
+      status === 'in_progress' ||
+      (status === 'open' && epics.some((e) => e.status === 'in_progress'));
+    if (!isActive) continue;
+
+    // Active milestone — drill into its epics looking for an actionable child.
+    // Prefer in_progress epics first (continue the WIP), then open epics.
+    const sortedEpics = [
+      ...epics.filter((e) => e.status === 'in_progress'),
+      ...epics.filter((e) => e.status === 'open'),
+    ];
+    for (const epicSummary of sortedEpics) {
+      const epic = loadTask(vaultRoot, epicSummary.id);
+      if (!epic) continue;
+      const childResult = resolveEpicChildTask(vaultRoot, epic.frontmatter);
+      if (!childResult || !childResult.task) continue;
+      const { task: childTask, blockers = [], severity = 'none', state } = childResult;
+      const phase = { id: epic.id, name: `Active milestone — ${fm.name || ref}` };
+      const cohort = loadEpicChildrenCohort(vaultRoot, epic.frontmatter);
+      const response = buildTaskResponse(
+        vaultRoot,
+        childTask,
+        phase,
+        roadmapId,
+        'manifest_active_milestone_drill',
+        cohort,
+      );
+      response.active_milestone = {
+        id: fm.id || ref,
+        name: fm.name || ref,
+        spec_path: milestoneSpec.specPath,
+      };
+      response.pinned_epic = {
+        id: epic.id,
+        name: epic.frontmatter?.name || epic.id,
+        spec_path: epic.specPath,
+      };
+      response.child_state = state;
+      response.next_action_hint = mapStateToHint(state);
+      response.blocker_severity = severity;
+      if (blockers.length > 0) {
+        response.unmet_blockers = blockers;
+        const banner = buildBlockerBanner(state, blockers);
+        if (banner) {
+          response.prompt_markdown = response.prompt_markdown.replace(
+            '\n\n---\n\n',
+            `${banner}\n\n---\n\n`,
+          );
+        }
+      }
+      return response;
+    }
+  }
+  return null;
+}
+
+export function resolveNextOnDeckOpen(vaultRoot, roadmapId) {
+  const roadmap = loadRoadmap(vaultRoot, roadmapId);
+  if (!roadmap) return null;
+
+  const manifest = roadmap.frontmatter.roadmap_manifest;
+  if (!manifest || !manifest.phases) return null;
+
+  for (const phase of manifest.phases) {
+    for (const taskId of phase.tasks || []) {
+      if (isInitiative(taskId)) {
+        const nested = resolveNextOnDeckOpen(vaultRoot, taskId);
+        if (nested) return nested;
+      } else {
+        const task = loadTask(vaultRoot, taskId);
+        if (task && task.status === 'open') {
+          const cohort = loadPhaseOpenCohort(vaultRoot, phase);
+          return buildTaskResponse(vaultRoot, task, phase, roadmapId, 'manifest_open', cohort);
+        }
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Build the derived execution brief for a task-shaped spec node (the Tier 0–2
+ * composer lives in alignment-gate.mjs). The NEXT STEP block, if present, is the
+ * Tier-0 override (prepended). Pure aside from the injected vault loader.
+ */
+export function deriveTaskBrief(vaultRoot, { id, name, status, roadmapId, frontmatter, body, specPath, cloudTaskGraph }) {
+  // [[HS-H227-MCPC-TASK]]: `cloudTaskGraph`, when supplied by the direct
+  // spec_id branch of `resolveNextOnDeckPayload` (cloud tier only), routes
+  // this decomposition-context walk through the HTTP pre-fetch instead of
+  // disk. Every other caller (buildTaskResponse's disk-only scheduler path)
+  // passes nothing here and keeps the original `loadTask` behavior.
+  const loadRef = (ref) => loadTaskViaGraph(vaultRoot, ref, cloudTaskGraph);
+  const node = { id, name, frontmatter: frontmatter || {}, body: body || '' };
+  const context = extractDecompositionContext(node, loadRef, 'epic');
+  const override = extractNextStepBlock(body || '');
+  const hasOverride = typeof override === 'string' && override.trim().length > 0;
+
+  // Tier-3 readiness floor ([[HS-TASK-RW3B]]) — runs BEFORE synthesis. A spec
+  // below the minimum-viable-input threshold routes to a recoverable
+  // clarification surface naming the missing fields instead of a thin brief.
+  // An authored `## NEXT STEP` override is itself sufficient input (a human
+  // pinned the prompt), so it bypasses the floor.
+  let ready = true;
+  let markdown;
+  if (hasOverride) {
+    markdown = buildExecutionBrief({ id, name, status, roadmapId, context, override });
+  } else {
+    const floor = readReadinessFloorSettings(vaultRoot);
+    const readiness = assessBriefReadiness({ name, context, floor });
+    ready = readiness.ready;
+    markdown = ready
+      ? buildExecutionBrief({ id, name, status, roadmapId, context, override })
+      : buildClarificationPrompt({
+          id,
+          name,
+          status,
+          roadmapId,
+          missing: readiness.missing,
+          focusSpecPath: specPath,
+        });
+  }
+
+  // Observability ([[HS-TASK-68NO]]) — record the served tier + emit the running
+  // degraded-mode rate so a degrading system is visible, never silent.
+  const tier = classifyBriefTier({ override, context, ready });
+  const stats = recordBriefTier(tier);
+  // One-shot CLI paths (`hs next`, `hs mcp call`, unit tests) set
+  // HEYSPEX_DISABLE_STDIO_BOOTSTRAP — skip stderr tier logs there. PowerShell
+  // paints stderr red and shows NativeCommandError even on success; humans
+  // running `--json` only want stdout JSON ([[HS-TASK-ISK7]]).
+  if (process.env.HEYSPEX_DISABLE_STDIO_BOOTSTRAP !== '1') {
+    process.stderr.write(`${formatBriefTierLog({ tier, id, stats })}\n`);
+  }
+
+  return markdown;
+}
+
+export function buildTaskResponse(vaultRoot, task, phase, roadmapId, sourceKind, cohortSpecs = null) {
+  // Detect UI tags and load design context if applicable
+  const uiTags = detectUITags(task.frontmatter);
+  let designContext = null;
+  let designSection = '';
+
+  if (uiTags.length > 0) {
+    const designDecisions = loadDesignMemories(vaultRoot, uiTags);
+    if (designDecisions.length > 0) {
+      designContext = {
+        triggered_by_tags: uiTags,
+        decisions: designDecisions,
+      };
+      designSection = buildDesignContextSection(designDecisions, uiTags);
+    }
+  }
+
+  // [[HS-TASK-G0HF]] derived execution brief — the only path. An acceptance-
+  // criteria contract composed deterministically; the `## NEXT STEP` block, if
+  // present, rides in as the Tier-0 override (no raw body-excerpt fallback).
+  const brief = deriveTaskBrief(vaultRoot, {
+    id: task.id,
+    name: task.name,
+    status: task.status,
+    roadmapId,
+    frontmatter: task.frontmatter,
+    body: task.body,
+    specPath: task.specPath,
+  });
+  const promptMarkdown = `${designSection}${brief}\n\n---\n\n_Spec path: \`${task.specPath}\`_`;
+
+  const response = {
+    spec_id: task.id,
+    title: task.name,
+    status: task.status,
+    source_kind: sourceKind,
+    phase_id: phase.id,
+    phase_name: phase.name,
+    roadmap_id: roadmapId,
+    prompt_markdown: promptMarkdown,
+    spec_path: task.specPath,
+  };
+
+  // Include design_context if UI tags detected
+  if (designContext) {
+    response.design_context = designContext;
+  }
+
+  // Scheduler explanation trace ([[HS-TASK-C2ZQ]] AC #1). Cohort defaults to
+  // the picked spec when callers don't pass a richer set — better to emit a
+  // single-spec trace than to drop the field entirely.
+  const cohort = Array.isArray(cohortSpecs) && cohortSpecs.length > 0
+    ? cohortSpecs
+    : [{ id: task.id, frontmatter: task.frontmatter || {} }];
+  const explanation = buildOnDeckExplanation(task.id, cohort, vaultRoot);
+  attachWhyNowFields(response, explanation, null);
+
+  return response;
+}