heyspex 0.1.0

package/vendor/heyspex-mcp/blocker-resolver.mjs

@@ -0,0 +1,891 @@
+/**
+ * Blocker resolver — pure logic backing heyspex_next_on_deck epic-drill.
+ *
+ * Reads `depends_on` (canonical) and `blocked_by` (back-compat) from spec
+ * frontmatter, classifies blocker severity by target status, and returns a
+ * discriminated state for the resolver caller in cli.mjs.
+ *
+ * Pure-ish: every IO is injected via `loadTask(idOrBasename) => task|null`,
+ * so this module is hermetic against the vault and unit-testable with a
+ * synthetic loader.
+ *
+ * Spec: see `C:\Users\pwher\.claude\plans\mighty-baking-biscuit.md`.
+ * Workflow context: the user implements an entire epic (sometimes an entire
+ * milestone) before reviewing — so sibling `in_review` / `review_pending`
+ * predecessors are EXPECTED intra-epic state, not a stop-and-review signal
+ * (and never a reason to ask the owner for permission). Intra-epic
+ * blockers surface as `soft_review` with a brief "proceed" note; only at the
+ * epic boundary (no `open` children left) does the resolver surface review
+ * candidates and next-epic options.
+ */
+
+import { readMvpModeState } from './mvp-mode.mjs';
+import { classifyParentRollup, rollupOptsFromMvpState } from './review-rollup.mjs';
+import { toCanonicalFamilyFirstId } from './spec-id-lib.mjs';
+
+/**
+ * Statuses at which a dependency is fully MET — dropped from the blocker list
+ * entirely. Mirror of `PREREQ_SATISFIED_STATUSES`
+ * (`spex-console/src/lib/scheduler/blocker-category.ts`) **minus** the two
+ * review states, which stay listed so the agent still SEES the batched-review
+ * context in the banner (they are advisory, never gating — see below).
+ */
+const PREREQ_MET_STATUSES = new Set(['closed', 'approved', 'shipped']);
+
+/**
+ * Review backlog is NEVER a blocker. `in_review` and `review_pending` both mean
+ * "build-complete, awaiting review at an ancestor grain" — the dependent code is
+ * already in the tree, so they classify as `soft_review` (proceed, with a note),
+ * never `hard`. `review_pending` grouping with `in_review` is the canonical rule
+ * ([[review-pending-must-group-with-in-review]]); omitting it here let a
+ * build-complete dependency fall through the `|| 'hard'` default and hard-block
+ * its dependent — the MCP-side instance of the same trap the console fixed in
+ * `PREREQ_SATISFIED_STATUSES` (2026-06-22).
+ */
+const STATUS_SEVERITY = {
+  closed: 'none',
+  approved: 'none',
+  shipped: 'none',
+  in_review: 'soft_review',
+  review_pending: 'soft_review',
+  hibernated: 'hard',
+  in_progress: 'hard',
+  open: 'hard',
+  draft: 'hard',
+  missing: 'integrity',
+  unknown: 'integrity',
+};
+
+const SEVERITY_RANK = { none: 0, soft_review: 1, hard: 2, integrity: 3 };
+
+function combineSeverity(a, b) {
+  return SEVERITY_RANK[a] >= SEVERITY_RANK[b] ? a : b;
+}
+
+function wikilinkTarget(raw) {
+  if (typeof raw !== 'string') return null;
+  const m = raw.match(/\[\[([^\]]+)\]\]/);
+  return m ? m[1].trim() : raw.trim();
+}
+
+// Strip wikilink wrapper + slug tail → bare canonical id. Mirror of
+// `cli.mjs:canonicalizeSpecRef` / `vault-shared.ts:canonicalizeSpecRef`.
+// Needed so scheduler-cache ids (bare, e.g. `HS-EPIC-PLRV`) compare equal to
+// the full-slug refs carried in `epics:` / `children:` frontmatter
+// ([[scheduler-cache-id-form-parity]]).
+function canonicalizeRef(value) {
+  if (value == null) return null;
+  const inner = wikilinkTarget(String(value));
+  if (!inner) return null;
+  // Family-keyed kinds: normalize EITHER ordering (type-first HS-EPIC-PLRV or
+  // family-first HS-PLRV-EPIC) to the canonical family-first bare id so the two
+  // orderings compare equal ([[HS-EPIC-DLE3]]).
+  const canonical = toCanonicalFamilyFirstId(inner);
+  if (canonical) return canonical;
+  // Non-family-keyed kinds (ROADMAP/IDEA/FLOW) are not reordered — just strip any
+  // slug tail to the bare id.
+  const m = inner.match(/^(HS-(?:ROADMAP|IDEA|FLOW)-(?:\d+|[A-Z0-9]+))/);
+  return m ? m[1] : inner;
+}
+
+/**
+ * Stable-sort child refs by their position in the deterministic scheduler
+ * order (`schedulerOrderIds`, bare ids in global rank). Refs absent from the
+ * order keep their declared array position at the tail. With no order supplied
+ * this is the identity — preserving the prior declared-order behavior + tests.
+ * This is what converges the claim target onto scheduler output so it agrees
+ * with every display surface ([[HS-EPIC-CNVG]]); without it the milestone /
+ * epic walk picks the first *written* child, not the first *scheduled* one.
+ */
+function rankRefsBySchedulerOrder(refs, schedulerOrderIds) {
+  if (!Array.isArray(schedulerOrderIds) || schedulerOrderIds.length === 0) return refs;
+  const rank = new Map();
+  schedulerOrderIds.forEach((id, i) => {
+    const c = canonicalizeRef(id);
+    if (c && !rank.has(c)) rank.set(c, i);
+  });
+  return refs
+    .map((ref, i) => ({
+      ref,
+      i,
+      r: rank.get(canonicalizeRef(ref)) ?? Number.MAX_SAFE_INTEGER,
+    }))
+    .sort((a, b) => (a.r !== b.r ? a.r - b.r : a.i - b.i))
+    .map((x) => x.ref);
+}
+
+/**
+ * Inspect `task.frontmatter.depends_on` + `task.frontmatter.blocked_by`,
+ * resolve each wikilink via `loadTask`, classify by status, and return:
+ *   { blockers: [{ id, status, source }], severity }
+ * - `depends_on` is the canonical field; `blocked_by` is unioned for back-compat.
+ * - Targets whose status is in `PREREQ_MET_STATUSES` are omitted (blocker met).
+ * - Final `severity` is the worst (max-rank) across all unmet blockers.
+ * - `'none'` means the task is unblocked.
+ */
+function computeUnmetBlockers(loadTask, task, opts = {}) {
+  // `mvp_mode.review_backlog_never_blocks` — opt-OUT only, so anything but an
+  // explicit `false` keeps review states advisory.
+  const reviewBacklogNeverBlocks = opts.reviewBacklogNeverBlocks !== false;
+  const fm = task?.frontmatter || {};
+  const dependsOn = Array.isArray(fm.depends_on) ? fm.depends_on : [];
+  const blockedBy = Array.isArray(fm.blocked_by) ? fm.blocked_by : [];
+
+  const seen = new Set();
+  const targets = [];
+  for (const raw of dependsOn) {
+    const t = wikilinkTarget(raw);
+    if (!t || seen.has(t)) continue;
+    seen.add(t);
+    targets.push({ target: t, source: 'depends_on' });
+  }
+  for (const raw of blockedBy) {
+    const t = wikilinkTarget(raw);
+    if (!t || seen.has(t)) continue;
+    seen.add(t);
+    targets.push({ target: t, source: 'blocked_by' });
+  }
+
+  const blockers = [];
+  let severity = 'none';
+  for (const { target, source } of targets) {
+    const blocker = loadTask(target);
+    if (!blocker) {
+      blockers.push({ id: target, status: 'missing', source });
+      severity = combineSeverity(severity, 'integrity');
+      continue;
+    }
+    const status = blocker.status || blocker.frontmatter?.status || 'unknown';
+    if (PREREQ_MET_STATUSES.has(status)) continue;
+    blockers.push({ id: blocker.id || target, status, source });
+    let classified = STATUS_SEVERITY[status] || 'hard';
+    if (classified === 'soft_review' && !reviewBacklogNeverBlocks) classified = 'hard';
+    severity = combineSeverity(severity, classified);
+  }
+  return { blockers, severity };
+}
+
+/**
+ * When focus.yaml pins an epic, classify the next move by walking the epic's
+ * declared `children:` in manifest order. Returns a discriminated state:
+ *
+ *   { state: 'resume',                       task, blockers, severity }
+ *   { state: 'ready',                        task, blockers: [], severity: 'none' }
+ *   { state: 'soft_review',                  task, blockers, severity: 'soft_review' }
+ *   { state: 'hard_blocked',                 task, blockers, severity }
+ *   { state: 'epic_implementation_complete', review_candidates, milestone_next_epics }
+ *   { state: 'epic_done',                    review_candidates: [], milestone_next_epics }
+ *   { state: 'epic_empty' }
+ *
+ * Selection order:
+ *   1) Resume the first `in_progress` child (blockers shown but don't gate).
+ *   2) Walk `open` children in manifest order and bucket by severity:
+ *      'none' wins; else 'soft_review'; else 'hard'/'integrity'.
+ *   3) If no `open` children remain, summarize the epic boundary state from
+ *      the children's statuses + parent-milestone next-epic lookup.
+ */
+function resolveEpicChildTask(loadTask, epicFrontmatter, opts = {}) {
+  const children = epicFrontmatter?.children;
+  if (!Array.isArray(children) || children.length === 0) {
+    return { state: 'epic_empty' };
+  }
+
+  const loaded = [];
+  for (const raw of children) {
+    const target = wikilinkTarget(raw);
+    if (!target) continue;
+    const task = loadTask(target);
+    if (!task) continue;
+    loaded.push(task);
+  }
+
+  if (loaded.length === 0) {
+    return { state: 'epic_empty' };
+  }
+
+  const resume = loaded.find((t) => (t.status || t.frontmatter?.status) === 'in_progress');
+  if (resume) {
+    const { blockers, severity } = computeUnmetBlockers(loadTask, resume, opts);
+    return { state: 'resume', task: resume, blockers, severity };
+  }
+
+  let firstReady = null;
+  let firstSoft = null;
+  let firstHard = null;
+  for (const task of loaded) {
+    const status = task.status || task.frontmatter?.status;
+    if (status !== 'open') continue;
+    const { blockers, severity } = computeUnmetBlockers(loadTask, task, opts);
+    if (severity === 'none' && firstReady === null) {
+      firstReady = { task, blockers, severity };
+    } else if (severity === 'soft_review' && firstSoft === null) {
+      firstSoft = { task, blockers, severity };
+    } else if ((severity === 'hard' || severity === 'integrity') && firstHard === null) {
+      firstHard = { task, blockers, severity };
+    }
+  }
+  if (firstReady) return { state: 'ready', ...firstReady };
+  if (firstSoft) return { state: 'soft_review', ...firstSoft };
+  if (firstHard) return { state: 'hard_blocked', ...firstHard };
+
+  // No open children — classify epic boundary. `review_pending` groups with
+  // `in_review` here too: below the active review grain a build-complete child
+  // carries `review_pending`, and it is just as much a review candidate
+  // ([[review-pending-must-group-with-in-review]]).
+  const reviewCandidates = loaded
+    .filter((t) => {
+      const s = t.status || t.frontmatter?.status;
+      return s === 'in_review' || s === 'review_pending';
+    })
+    .map((t) => t.id || t.frontmatter?.id)
+    .filter(Boolean);
+  const closedCount = loaded.filter(
+    (t) => (t.status || t.frontmatter?.status) === 'closed',
+  ).length;
+  const milestoneNext = resolveMilestoneNextEpics(loadTask, epicFrontmatter);
+
+  if (reviewCandidates.length > 0) {
+    return {
+      state: 'epic_implementation_complete',
+      review_candidates: reviewCandidates,
+      milestone_next_epics: milestoneNext,
+    };
+  }
+  if (closedCount === loaded.length) {
+    return {
+      state: 'epic_done',
+      review_candidates: [],
+      milestone_next_epics: milestoneNext,
+    };
+  }
+
+  // Mixed weird state — no open, no in_review, not all closed (drafts /
+  // hibernated only?). Treat as empty so the caller falls through to the
+  // existing body-excerpt behavior rather than fabricating a misleading hint.
+  return { state: 'epic_empty' };
+}
+
+/**
+ * Walk the parent milestone's `children:` list and return up to 3 next-epic
+ * ids whose status is `open` or `in_progress` after the current epic.
+ * Returns [] when no parent milestone is set, can't be loaded, has no
+ * children, or has no actionable successors.
+ */
+function resolveMilestoneNextEpics(loadTask, epicFrontmatter) {
+  const milestoneRaw = epicFrontmatter?.milestone;
+  if (!milestoneRaw) return [];
+  const milestoneTarget = wikilinkTarget(milestoneRaw);
+  if (!milestoneTarget) return [];
+  const milestone = loadTask(milestoneTarget);
+  if (!milestone) return [];
+
+  const mfm = milestone.frontmatter || {};
+  if (!Array.isArray(mfm.children)) return [];
+
+  const currentId = epicFrontmatter.id || '';
+  const childIds = mfm.children.map(wikilinkTarget).filter(Boolean);
+  const currentIdx = childIds.findIndex(
+    (id) => id === currentId || id.startsWith(currentId + '-') || id.startsWith(currentId),
+  );
+  const after = currentIdx >= 0 ? childIds.slice(currentIdx + 1) : childIds;
+
+  const next = [];
+  for (const id of after) {
+    const child = loadTask(id);
+    if (!child) continue;
+    const ctype = child.type || child.frontmatter?.type;
+    if (ctype && ctype !== 'epic') continue;
+    const cstatus = child.status || child.frontmatter?.status;
+    if (cstatus === 'open' || cstatus === 'in_progress') {
+      next.push(child.id || child.frontmatter?.id || id);
+      if (next.length >= 3) break;
+    }
+  }
+  return next;
+}
+
+/**
+ * Map a child-state to the short `next_action_hint` exposed on the response
+ * payload. Hint is the machine-readable shape; the human-facing markdown
+ * comes from `buildBlockerBanner` / `buildEpicBoundaryPromptMarkdown`.
+ */
+function mapStateToHint(state) {
+  switch (state) {
+    case 'resume': return 'resume';
+    case 'ready': return 'start';
+    case 'soft_review': return 'start_batched';
+    case 'hard_blocked': return 'hard_blocked';
+    case 'epic_implementation_complete': return 'advance_or_review';
+    case 'epic_done': return 'ship_epic';
+    case 'epic_empty': return 'inspect_epic';
+    case 'milestone_needs_breakdown': return 'file_epic';
+    case 'milestone_empty_after_filter': return 'file_epic';
+    case 'milestone_has_epics': return 'drill_milestone';
+    default: return 'start';
+  }
+}
+
+/**
+ * Milestone-pin analogue of `resolveEpicChildTask`. Inspects a milestone's
+ * declared `epics:` field (canonical per [[HS-PROTO-spec-hierarchy]] —
+ * milestones use `epics:`, never `children:`) and returns a discriminated
+ * state. See [[HS-TASK-SKEM-scheduler-skip-epicless-milestones]] for the
+ * `/hs-next` `needs_breakdown` consumer.
+ *
+ *   { state: 'milestone_needs_breakdown' }
+ *     → `epics:` is missing or empty. No actionable work below this pin.
+ *   { state: 'milestone_empty_after_filter', unresolved }
+ *     → `epics:` listed entries but none resolved via `loadTask`. Treated the
+ *       same as needs_breakdown at the cli layer — still no actionable epic.
+ *   { state: 'milestone_has_epics', epics: [{ id, status }] }
+ *     → at least one entry resolved. Out-of-band for this resolver; the
+ *       caller decides whether to drill (out of scope for SKEM).
+ */
+function resolveMilestoneState(loadTask, milestoneFrontmatter) {
+  const raw = milestoneFrontmatter?.epics;
+  const entries = Array.isArray(raw) ? raw : [];
+  if (entries.length === 0) {
+    return { state: 'milestone_needs_breakdown' };
+  }
+
+  const resolved = [];
+  const unresolved = [];
+  const seen = new Set();
+  for (const ref of entries) {
+    const target = wikilinkTarget(ref);
+    if (!target || seen.has(target)) continue;
+    seen.add(target);
+    const epic = loadTask(target);
+    if (!epic) {
+      unresolved.push(target);
+      continue;
+    }
+    resolved.push({
+      id: epic.id || target,
+      status: epic.status || epic.frontmatter?.status || 'unknown',
+    });
+  }
+
+  if (resolved.length === 0) {
+    return { state: 'milestone_empty_after_filter', unresolved };
+  }
+  return { state: 'milestone_has_epics', epics: resolved };
+}
+
+/**
+ * Banner inserted into prompt_markdown when blockers are present. Tone
+ * differs by state: `soft_review` reassures the agent to proceed (epic-batch
+ * is the intended workflow); `hard_blocked` warns and names the predecessor;
+ * `integrity` flags a schema error.
+ */
+function buildBlockerBanner(state, blockers) {
+  if (!Array.isArray(blockers) || blockers.length === 0) return '';
+  const list = blockers
+    .map(
+      (b) =>
+        `\`${b.id}\` (${b.status}${b.source === 'blocked_by' ? ', via blocked_by' : ''})`,
+    )
+    .join(', ');
+  if (state === 'soft_review') {
+    return (
+      `\n\n> **Sibling awaiting review (batched, expected):** ${list}. ` +
+      `Proceed — this is the intended workflow when implementing a whole epic before reviewing. ` +
+      `A review backlog is never a blocker and needs no owner permission to work past: ` +
+      `do NOT offer to pause, redirect the claim, or ask the owner to review/commit first. ` +
+      `If review later rejects a sibling and forces redesign, revisit this task then.`
+    );
+  }
+  if (state === 'hard_blocked') {
+    return (
+      `\n\n> ⚠️ **Hard blockers:** ${list}. ` +
+      `The predecessor(s) above must reach \`in_progress\` or \`closed\` before this task can land cleanly. ` +
+      `Claim a blocker first, or re-pin focus to a different epic.`
+    );
+  }
+  // resume or integrity fall-through
+  const integrity = blockers.find((b) => b.status === 'missing');
+  if (integrity) {
+    return (
+      `\n\n> ⚠️ **Integrity error:** blocker \`${integrity.id}\` does not resolve to any spec in the vault. ` +
+      `Fix the wikilink in this task's \`depends_on\` / \`blocked_by\` frontmatter.`
+    );
+  }
+  return `\n\n> Blockers: ${list}.`;
+}
+
+/**
+ * Build prompt_markdown for the epic-boundary states (no actionable child).
+ * Surfaces three options: re-pin focus to next epic in milestone, run
+ * `/hs-review` on the queue, or `ship_epic`. The order matches the user's
+ * stated preference for epic-batch workflow — advance-then-review-then-ship.
+ */
+function buildEpicBoundaryPromptMarkdown({
+  state,
+  epicId,
+  epicName,
+  reviewCandidates = [],
+  milestoneNextEpics = [],
+  roadmapId,
+  focusSpecPath,
+}) {
+  const lines = [];
+  const heading =
+    state === 'epic_implementation_complete'
+      ? 'epic_implementation_complete'
+      : state === 'epic_done'
+        ? 'epic_done'
+        : state;
+  lines.push(`## ${heading} — ${epicId}`);
+  lines.push('');
+  lines.push(`**Epic:** ${epicName}`);
+  lines.push(`**Roadmap:** ${roadmapId}`);
+  lines.push('');
+  if (state === 'epic_implementation_complete') {
+    lines.push(
+      `All ${reviewCandidates.length} child task${reviewCandidates.length === 1 ? '' : 's'} of this epic are build-complete ` +
+        `(\`in_review\` / \`review_pending\`). The epic's implementation work is done; no actionable child remains. ` +
+        `The pending reviews do **not** gate anything below — advancing is always available without owner permission. ` +
+        `What to do next:`,
+    );
+  } else if (state === 'epic_done') {
+    lines.push(`All children of this epic are \`closed\`. The epic itself can be shipped.`);
+  }
+  lines.push('');
+  lines.push('### Suggested next moves');
+  lines.push('');
+
+  let stepNum = 1;
+  if (milestoneNextEpics.length > 0) {
+    lines.push(
+      `${stepNum}. **Advance focus to the next epic in this milestone** ` +
+        `(preferred if you're batching review for milestone close-out). Re-pin \`.heyspex/focus.yaml\`:`,
+    );
+    for (const eid of milestoneNextEpics) {
+      lines.push(`   - \`${eid}\``);
+    }
+    stepNum += 1;
+  } else {
+    lines.push(
+      `${stepNum}. **Re-pin \`.heyspex/focus.yaml\`** to the next epic you want to implement ` +
+        `(no next epic auto-detected on the parent milestone — pick one manually).`,
+    );
+    stepNum += 1;
+  }
+  lines.push('');
+
+  if (reviewCandidates.length > 0) {
+    lines.push(
+      `${stepNum}. **Start clearing the review queue** with \`/hs-review\` — candidates:`,
+    );
+    for (const id of reviewCandidates) {
+      lines.push(`   - \`${id}\``);
+    }
+    stepNum += 1;
+    lines.push('');
+    lines.push(
+      `${stepNum}. **Backfill the epic** once all children close: \`heyspex_backfill_epic({ id: "${epicId}" })\`.`,
+    );
+  } else {
+    lines.push(
+      `${stepNum}. **Backfill the epic**: \`heyspex_backfill_epic({ id: "${epicId}" })\`.`,
+    );
+  }
+  lines.push('');
+  lines.push(
+    `_Pinned via \`.heyspex/focus.yaml\` (\`${focusSpecPath}\`). No actionable child task — ` +
+      `surfacing epic-boundary choices instead of a body excerpt._`,
+  );
+  return lines.join('\n');
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// computeClaimTarget — the vault invariant "a spec is claimable iff it is its
+// own current ClaimTarget" (T2 of [[HS-EPIC-VQZ8]]). Both the /hs-next brief
+// and the console claim endpoint consult this primitive; the endpoint blocks
+// any POST whose target.spec_id !== params.id.
+//
+// Reads ONLY from disk via the injected `loadRef` (SSOT — never an index).
+// Recursion ends at the first claimable descendant or the original node when
+// it has no open descendants.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const CLAIM_TERMINAL_STATUSES = new Set([
+  'closed',
+  'shipped',
+  'in_review',
+  // review_pending = build-complete, awaiting batched review ([[HS-EPIC-SSTM]]).
+  'review_pending',
+  'archived',
+  'cancelled',
+  'duplicate',
+  'hibernated',
+  'superseded',
+  // [[HS-DIAG-YMN3]]: `parked` = indefinite park; not claimable. Mirror of the
+  // TS CLAIM_TERMINAL_STATUSES in lib/scheduler/claim-eligibility.ts.
+  'parked',
+]);
+
+const REVIEW_AWAITING_STATUSES = new Set(['in_review', 'review_pending']);
+
+const ROLLUP_INTENT_VERB = {
+  reviewer_blocked: 'wait for reviewer',
+  ready_for_close: 'flip to in_review',
+};
+
+const ROLLUP_NEXT_ACTION_HINT = {
+  reviewer_blocked: 'wait_for_reviewer',
+  ready_for_close: 'flip_to_in_review',
+};
+
+const TERMINAL_LEAF_INTENT = {
+  awaiting_review: 'wait for reviewer',
+  parked: 'parked — not claimable',
+  done: 'already closed',
+};
+
+const TERMINAL_LEAF_NEXT_ACTION = {
+  awaiting_review: 'wait_for_reviewer',
+  parked: 'not_claimable',
+  done: 'not_claimable',
+};
+
+// [[HS-DIAG-YMN3]] mirror of TS terminalLeafKind / levelForType.
+function terminalLeafKind(status) {
+  if (REVIEW_AWAITING_STATUSES.has(status)) return 'awaiting_review';
+  if (status === 'parked') return 'parked';
+  return 'done';
+}
+
+function levelForType(type) {
+  return type === 'epic' || type === 'milestone' ? type : 'task';
+}
+
+const INTENT_VERB_BY_LEVEL = {
+  task: 'implement it',
+  epic: 'break it into Tasks',
+  milestone: 'break it into Epics',
+};
+
+const TONE_TOKEN_BY_LEVEL = {
+  task: '--status-neutral',
+  epic: '--status-ready',
+  milestone: '--status-pending',
+};
+
+function specStatus(spec) {
+  return String(spec?.status || spec?.frontmatter?.status || '').toLowerCase();
+}
+
+function specType(spec) {
+  return String(spec?.type || spec?.frontmatter?.type || '').toLowerCase();
+}
+
+function specId(spec) {
+  return spec?.id || spec?.frontmatter?.id || null;
+}
+
+function specTitle(spec) {
+  const fm = spec?.frontmatter || {};
+  return spec?.name || fm.name || specId(spec);
+}
+
+/**
+ * Walk parent pointers root-ward, reading each link from disk via `loadRef`.
+ * Returns the chain root → leaf as `[{id, type, title}]`. For a task: includes
+ * the epic and milestone above it. For an epic: includes its milestone. For a
+ * milestone: just the milestone itself. The leaf is always `spec`.
+ */
+export function resolveHierarchy(spec, loadRef) {
+  if (!spec) return [];
+  const chain = [];
+  const visited = new Set();
+  let current = spec;
+  while (current) {
+    const id = specId(current);
+    if (!id || visited.has(id)) break;
+    visited.add(id);
+    chain.unshift({ id, type: specType(current) || 'spec', title: specTitle(current) });
+    const fm = current.frontmatter || {};
+    const parentRef =
+      wikilinkTarget(fm.parent) ||
+      wikilinkTarget(fm.parent_epic) ||
+      wikilinkTarget(fm.milestone);
+    if (!parentRef || typeof loadRef !== 'function') break;
+    current = loadRef(parentRef);
+  }
+  return chain;
+}
+
+function buildClaimTarget(node, level, alignmentState, breadcrumb) {
+  return {
+    level,
+    spec_id: specId(node),
+    title: specTitle(node),
+    intent_verb: INTENT_VERB_BY_LEVEL[level] || 'work on it',
+    tone_token: TONE_TOKEN_BY_LEVEL[level] || '--status-neutral',
+    hierarchy_breadcrumb: breadcrumb || [],
+    alignment_state: alignmentState || 'unknown',
+    // The on-deck claim brief surfaces the leaf's authored summary, and falls
+    // back to an author-then-claim prompt (which needs the file path) when it is
+    // missing. Both come straight from the resolved leaf node's frontmatter/path.
+    summary: node?.frontmatter?.summary || null,
+    relPath: node?.specPath || node?.spec_path || node?.relPath || null,
+  };
+}
+
+function buildRollupClaimTarget(node, level, alignmentState, breadcrumb, rollup) {
+  const kind = rollup.kind;
+  return {
+    ...buildClaimTarget(node, level, alignmentState, breadcrumb),
+    intent_verb: ROLLUP_INTENT_VERB[kind] || 'work on it',
+    tone_token: '--status-paused',
+    rollup_state: kind,
+    next_action_hint: ROLLUP_NEXT_ACTION_HINT[kind] || null,
+    rollup_detail:
+      kind === 'reviewer_blocked'
+        ? { in_review: rollup.in_review ?? 0 }
+        : kind === 'ready_for_close'
+          ? { closed: rollup.closed ?? 0 }
+          : null,
+  };
+}
+
+/** Terminal leaf task/diagnose — not open for implementation ([[HS-DIAG-BVKC]]). */
+function buildTerminalLeafClaimTarget(node, alignmentState, breadcrumb, level = 'task') {
+  const status = specStatus(node);
+  const kind = terminalLeafKind(status);
+  return {
+    ...buildClaimTarget(node, level, alignmentState, breadcrumb),
+    intent_verb: TERMINAL_LEAF_INTENT[kind],
+    tone_token: '--status-paused',
+    rollup_state: 'terminal_leaf',
+    next_action_hint: TERMINAL_LEAF_NEXT_ACTION[kind],
+    terminal_status: status,
+  };
+}
+
+/**
+ * Classify an epic's children into rollup kinds ([[HS-TASK-CRTR]]). Returns
+ * `{ kind: 'has_claimable', ref, child }` when a non-terminal child exists so
+ * the caller can recurse without re-walking.
+ */
+export function classifyEpicChildRollup(epic, loadRef, schedulerOrderIds = [], reviewLevel = 'task') {
+  const fm = epic?.frontmatter || {};
+  const childRefs = rankRefsBySchedulerOrder(
+    Array.isArray(fm.children) ? fm.children.map(wikilinkTarget).filter(Boolean) : [],
+    schedulerOrderIds,
+  );
+  if (childRefs.length === 0) return { kind: 'no_children' };
+
+  let loadedCount = 0;
+  let inReviewCount = 0;
+  const statuses = [];
+  for (const ref of childRefs) {
+    if (typeof loadRef !== 'function') break;
+    const child = loadRef(ref);
+    if (!child) continue;
+    loadedCount += 1;
+    const status = specStatus(child);
+    statuses.push(status);
+    if (!CLAIM_TERMINAL_STATUSES.has(status)) {
+      return { kind: 'has_claimable', ref, child };
+    }
+    if (REVIEW_AWAITING_STATUSES.has(status)) inReviewCount += 1;
+  }
+
+  if (loadedCount === 0) return { kind: 'no_children' };
+  const rollupKind = classifyParentRollup(statuses, 'task', reviewLevel);
+  if (rollupKind === 'reviewer_blocked') {
+    return { kind: 'reviewer_blocked', in_review: inReviewCount };
+  }
+  return { kind: 'ready_for_close', closed: loadedCount };
+}
+
+/** Milestone-level rollup when every child epic is terminal ([[HS-TASK-CRTR]]). */
+export function classifyMilestoneChildRollup(milestone, loadRef, schedulerOrderIds = [], reviewLevel = 'task') {
+  const fm = milestone?.frontmatter || {};
+  const epicRefs = rankRefsBySchedulerOrder(
+    Array.isArray(fm.epics) ? fm.epics.map(wikilinkTarget).filter(Boolean) : [],
+    schedulerOrderIds,
+  );
+  if (epicRefs.length === 0) return { kind: 'no_children' };
+
+  let loadedCount = 0;
+  let inReviewCount = 0;
+  const statuses = [];
+  for (const ref of epicRefs) {
+    if (typeof loadRef !== 'function') break;
+    const epic = loadRef(ref);
+    if (!epic) continue;
+    loadedCount += 1;
+    const status = specStatus(epic);
+    statuses.push(status);
+    if (REVIEW_AWAITING_STATUSES.has(status)) inReviewCount += 1;
+  }
+
+  if (loadedCount === 0) return { kind: 'no_children' };
+  const rollupKind = classifyParentRollup(statuses, 'epic', reviewLevel);
+  if (rollupKind === 'reviewer_blocked') {
+    return { kind: 'reviewer_blocked', in_review: inReviewCount };
+  }
+  return { kind: 'ready_for_close', closed: loadedCount };
+}
+
+/**
+ * Resolve the current claimable node under `spec`. Returns a ClaimTarget with
+ * the 7-field shape T2 AC #7 pins.
+ *
+ *   - Task → returns itself at level: 'task'.
+ *   - Epic with no open children → itself at level: 'epic' (break it into Tasks).
+ *   - Epic with open children → recurses into the first non-terminal child.
+ *   - Milestone with no open epics → itself at level: 'milestone' (break it
+ *     into Epics).
+ *   - Milestone with open epics → recurses into the first non-terminal epic.
+ *
+ * `breadcrumb` is the carried hierarchy chain (computed once at the entry
+ * point, threaded so deep recursion doesn't re-walk from each child).
+ */
+export function computeClaimTarget(
+  spec,
+  vaultRoot,
+  alignmentState,
+  loadRef,
+  schedulerOrderIds = [],
+  rollupOpts,
+) {
+  if (!spec) return null;
+  void vaultRoot;
+  const resolvedRollup =
+    rollupOpts ?? rollupOptsFromMvpState(vaultRoot ? readMvpModeState(vaultRoot) : null);
+  const reviewLevel = resolvedRollup.reviewLevel ?? 'task';
+
+  const breadcrumb = resolveHierarchy(spec, loadRef).map((h) => h.id);
+  return resolveClaimTargetRecursive(
+    spec,
+    alignmentState,
+    loadRef,
+    breadcrumb,
+    new Set(),
+    schedulerOrderIds,
+    reviewLevel,
+  );
+}
+
+function resolveClaimTargetRecursive(
+  spec,
+  alignmentState,
+  loadRef,
+  breadcrumb,
+  visited,
+  schedulerOrderIds = [],
+  reviewLevel = 'task',
+) {
+  if (!spec) return null;
+  const id = specId(spec);
+  if (!id || visited.has(id)) return null;
+  visited.add(id);
+  const type = specType(spec) || 'task';
+
+  // Own-status terminal gate ([[HS-DIAG-YMN3]]) — mirror of the TS resolver. Runs
+  // before the type switch so a directly-claimed terminal node (incl. a `parked`
+  // epic/milestone) reports not-claimable instead of falling through. Only fires
+  // on the root spec — descent recurses into non-terminal children only.
+  if (CLAIM_TERMINAL_STATUSES.has(specStatus(spec))) {
+    return buildTerminalLeafClaimTarget(spec, alignmentState, breadcrumb, levelForType(type));
+  }
+
+  // A diagnose ([[HS-MIL-BFIX]]) is a claimable leaf like a task when open.
+  if (type === 'task' || type === 'diagnose') {
+    return buildClaimTarget(spec, 'task', alignmentState, breadcrumb);
+  }
+
+  if (type === 'epic') {
+    const rollup = classifyEpicChildRollup(spec, loadRef, schedulerOrderIds, reviewLevel);
+    if (rollup.kind === 'has_claimable') {
+      const child = rollup.child;
+      const childBreadcrumb = [...breadcrumb, specId(child)].filter(Boolean);
+      const childTarget = resolveClaimTargetRecursive(
+        child,
+        alignmentState,
+        loadRef,
+        childBreadcrumb,
+        visited,
+        schedulerOrderIds,
+        reviewLevel,
+      );
+      if (childTarget) return childTarget;
+    }
+    if (rollup.kind === 'no_children') {
+      return buildClaimTarget(spec, 'epic', alignmentState, breadcrumb);
+    }
+    if (rollup.kind === 'reviewer_blocked' || rollup.kind === 'ready_for_close') {
+      return buildRollupClaimTarget(spec, 'epic', alignmentState, breadcrumb, rollup);
+    }
+    return buildClaimTarget(spec, 'epic', alignmentState, breadcrumb);
+  }
+
+  if (type === 'milestone') {
+    const fm = spec.frontmatter || {};
+    const epicRefs = rankRefsBySchedulerOrder(
+      Array.isArray(fm.epics) ? fm.epics.map(wikilinkTarget).filter(Boolean) : [],
+      schedulerOrderIds,
+    );
+    for (const ref of epicRefs) {
+      if (typeof loadRef !== 'function') break;
+      const epic = loadRef(ref);
+      if (!epic) continue;
+      if (CLAIM_TERMINAL_STATUSES.has(specStatus(epic))) continue;
+      const childBreadcrumb = [...breadcrumb, specId(epic)].filter(Boolean);
+      const childTarget = resolveClaimTargetRecursive(
+        epic,
+        alignmentState,
+        loadRef,
+        childBreadcrumb,
+        visited,
+        schedulerOrderIds,
+        reviewLevel,
+      );
+      if (childTarget) return childTarget;
+    }
+    const rollup = classifyMilestoneChildRollup(spec, loadRef, schedulerOrderIds, reviewLevel);
+    if (rollup.kind === 'no_children') {
+      return buildClaimTarget(spec, 'milestone', alignmentState, breadcrumb);
+    }
+    if (rollup.kind === 'reviewer_blocked' || rollup.kind === 'ready_for_close') {
+      return buildRollupClaimTarget(spec, 'milestone', alignmentState, breadcrumb, rollup);
+    }
+    return buildClaimTarget(spec, 'milestone', alignmentState, breadcrumb);
+  }
+
+  // Unknown type → return at the spec's own level with a neutral verb.
+  return {
+    level: type || 'spec',
+    spec_id: id,
+    title: specTitle(spec),
+    intent_verb: 'work on it',
+    tone_token: '--status-neutral',
+    hierarchy_breadcrumb: breadcrumb,
+    alignment_state: alignmentState || 'unknown',
+    summary: spec?.frontmatter?.summary || null,
+    relPath: spec?.specPath || spec?.spec_path || spec?.relPath || null,
+  };
+}
+
+export {
+  STATUS_SEVERITY,
+  SEVERITY_RANK,
+  combineSeverity,
+  wikilinkTarget,
+  computeUnmetBlockers,
+  resolveEpicChildTask,
+  resolveMilestoneNextEpics,
+  resolveMilestoneState,
+  mapStateToHint,
+  buildBlockerBanner,
+  buildEpicBoundaryPromptMarkdown,
+  CLAIM_TERMINAL_STATUSES,
+  INTENT_VERB_BY_LEVEL,
+  TONE_TOKEN_BY_LEVEL,
+  ROLLUP_INTENT_VERB,
+  ROLLUP_NEXT_ACTION_HINT,
+};